Python SDK

lunixi-sdk, Lunixi'nin Python istemcisidir. Ed25519 istek imzalama, token alışverişi, yanıt zarfının çözümü, imleçli sayfalama ve tipli hata ailesini taşır; bunun üzerinde fraud karar ve olay API'sini sunar.

Python 3.9 ve üzeri
Tek bağımlılık Ed25519 için cryptography; HTTP standart kütüphaneyle yapılır
py.typed içerir; tüm açık arayüz tip ipuçlarıyla gelir

Python SDK'sı bu sürümde fraud yüzeyini ve webhook doğrulamayı içerir. Diğer uçları aşağıdaki Genişletme bölümündeki gibi aynı imzalı istek katmanıyla ya da SDK'sız REST ile çağırabilirsiniz.

Kurulum

pip install lunixi-sdk

Anahtar çifti

from lunixi import generate_key_pair
 
private_pem, public_pem = generate_key_pair()
# private_pem'i sır kasanıza koyun; public_pem'i panele yükleyin

Anahtarı sır kasanızdan okuyun; kaynak koda ve depodaki bir dosyaya koymayın.

İstemciyi oluşturma

from lunixi import LunixiClient
 
client = LunixiClient(
    base_url="https://api-gateway.lunixi.com",
    key_id=key_id,              # panelden alırsınız
    private_key=private_key_pem,
)

Ortamı anahtar belirler. İstemciyi uygulama açılışında bir kez kurup paylaşın: token önbelleği bu nesnede durur. İsteğe bağlı parametreler: timeout_seconds (varsayılan 30.0), max_retries (varsayılan 2), transport, token_store.

Fraud kararı

from lunixi import Channel
 
decision = client.fraud().evaluate(
    channel=Channel.STANDALONE_API,
    transaction_ref="order-2026-0001",
    payment={"amount": 14990, "currency": "TRY"},
    customer={"id": "cus_88", "email": "[email protected]"},
)
 
if decision.blocked:
    ...  # işlemi reddedin
elif decision.requires_three_d:
    ...  # 3D Secure ile yeniden deneyin
elif decision.requires_review:
    ...  # incelemeye alın

Karar sonuçları allow, review, block, force_3d'dir. force_3d ödemeyi reddetmez; 3D Secure ile yeniden denemenizi ister. Alan adları snake_case'dir; API referansındaki camelCase yazım da kabul edilir. Tanınmayan bir alan, istek gönderilmeden yerelde hata verir. → Fraud

Çağrı	Uç
`fraud().evaluate(...)`	`POST /api/v1/fraud/decisions/evaluate`
`fraud().decisions.list(...)`	`GET /api/v1/fraud/decision-logs`
`fraud().decisions.get(trace_id)`	`GET /api/v1/fraud/decision-logs/{traceId}`
`fraud().events.record(event)`	`POST /api/v1/fraud/events/transactions`
`fraud().events.record_batch(events)`	`POST /api/v1/fraud/events/transactions/batch`

Olay alımı

result = client.fraud().events.record(
    {
        "eventId": "evt-0001",
        "eventType": "card_sale",
        "subjectType": "customer",
        "occurredAt": "2026-10-11T08:29:00Z",
    },
    idempotency_key="evt-0001",
)
if result.deduplicated:
    ...  # bu olay zaten kaydedilmişti

Bir parti en çok 500 olay taşır. Parti kısmen başarılı olabilir; reddedilen olayları failures() ile okuyun ve düzeltip aynı eventId ile yeniden gönderin:

result = client.fraud().events.record_batch(events, idempotency_key="feed-2026-10-11-01")
for failure in result.failures():
    log.warning("olay %s reddedildi: %s", failure.event_id, failure.error)

Sayfalama

from lunixi import Decision
 
for row in client.fraud().decisions.iterate(decision=Decision.REVIEW, limit=50):
    handle(row)

İmleç opaktır: aynen geri gönderin. Bozuk imleç 400 ile reddedilir, sessizce ilk sayfaya dönmez.

Webhook doğrulama

from lunixi import FraudEvents, WebhookVerifier, WebhookVerificationError
 
verifier = WebhookVerifier(endpoint_secret)
 
try:
    event = verifier.verify(raw_body, request.headers)
except WebhookVerificationError:
    return 400  # doğrulanmamış bir yük üzerinde işlem yapmayın
 
if event.type == FraudEvents.FLOW_ASYNC_COMPLETED:
    ...

Ham gövdeyi verin: JSON'u çözüp yeniden üretmek imzayı bozar. Doğrulama fail-closed çalışır ve 300 saniyelik zaman damgası penceresini denetler. Secret döndürülürken gelen iki imzadan birinin doğrulanması yeterlidir.

Hatalar

Sınıf	Ne zaman
`ConfigurationError`	Yerel bir değer kullanılamaz; hiçbir şey gönderilmedi
`SignatureError`	Özel anahtar yüklenemedi
`ValidationError`	`400` — gövde reddedildi
`AuthenticationError`	`401` / `403` — imza, token veya yetki reddedildi
`RateLimitError`	`429` — `retry_after` ve `quota` taşır
`ServiceUnavailableError`	`503` — `retry_after` taşır
`ApiError`	Diğer hata yanıtları ya da hiç yanıt gelmemesi
`WebhookVerificationError`	Gelen webhook doğrulanmadı

GET istekleri ve idempotency_key verdiğiniz istekler taşıma hatası ya da 5xx sonrası yeniden denenir; evaluate kendiliğinden yeniden denenmez.

Genişletme

SDK'nın sarmaladığı uçların dışındaki her uca imzalama, yeniden deneme ve hata işleme hazır olarak erişebilirsiniz:

import lunixi
 
envelope = client.api().request("GET", "/api/v1/payments", query={"limit": 25})
rows = lunixi.items_of(envelope)

İlgili

Fraud — karar modeli ve olay alımı
Kimlik Doğrulama — anahtar, imza ve token ömrü
SDK'sız REST — imzalama akışı

Java SDK'sız REST