Akışlar ve Çözümleme

Fraud kararı sabit bir kural kümesiyle değil, yayınladığınız akışlarla verilir. Bir akışı işlem tipine göre kapsamlarsınız (kart ödemesi, havale, cüzdan çekimi…); karar isteği geldiğinde sistem eşleşen yayınlanmış akışların hepsini çözümler, koşar ve sonuçları tek karar altında birleştirir.

Bu sayfa çözümlemenin nasıl işlediğini anlatır — yani "isteğim hangi akışlara düştü?" sorusunun cevabını. Uç sözleşmesi için: Karar API'si.

Kuralları tetikleyen uç

Yayınladığınız akış (ve içindeki kurallar) tek bir çağrıyla tetiklenir:

POST /api/v1/fraud/decisions/evaluate
Authorization: Bearer <access-token>

Token'ı Ed25519 imzanızla POST /api/v1/auth/token'dan alırsınız. Gereken yetki: fraud:view_decisions. Ayrıntı ve tam alan sözlüğü: Karar API'si.

İstekteki hangi alan hangi ekseni sürer

Çözümlemeyi siz yönlendirirsiniz — hangi akışların koşacağı, gövdede gönderdiğiniz şu alanlardan türer:

curl -X POST "https://api-gateway.lunixi.com/api/v1/fraud/decisions/evaluate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "bankTransfer": { "amount": 250000, "currency": "TRY", "iban": "TR33…" },
    "customer": { "id": "cust_84213" },
    "productContext": "direct_api"
  }'

Bu çağrı bank_transfer işlem tipine kapsamlanmış akışlarınızın hepsini bulur, koşar ve birleşik kararı döndürür. Yanıtta hangi akışların koştuğu ve hangi kuralların eşleştiği açıklanabilirlik alanlarında ve multiFlow bloğunda gelir — kararın neden verildiğini oradan okursunuz.

Akış hangi eksenlerde kapsamlanır

Bir akış yayınlanırken aşağıdaki boyutlarla daraltılabilir. Boş bırakılan boyut "hepsi" demektir — o eksende her değere uyar.

subjectType değerleri işlem tipini taşır: card_payment · bank_transfer · eft · fast · crypto_transfer · wallet_deposit · wallet_withdrawal · wallet_payment · wallet_transfer · bill_payment · loan · payout · refund · cash_in · cash_out · international_transfer

Çözümleme: eşleşen akışların hepsi koşar

Kapsam eksenleri değişmedi — merchantId · merchantGroupIds · flowType · subjectType · integrationMode · productContext (boş kolon = hepsine uyar). Değişen şey seçim adımı: sistem artık en dar kapsamlı tek akışı seçmez. Süzgeçten geçen yayınlanmış akışların hepsi çözülür ve executionMode alanına göre iki şeritten birinde koşar: sync akışlar karar yanıtını üretir, async akışlar kararı bekletmeden arka planda koşar.

Sync şerit: bağımsız koşum, tek karar

executionMode='sync' akışların her biri sıfır taban state ile bağımsız koşar: akışların sırası sonucu etkilemez, bir akış diğerinin skorunu ya da reason code'larını görmez. Koşum bitince sonuçlar tek karar altında birleştirilir:

Üç seviyeli zaman sınırı

Süre bütçesi tek katman değildir; iç içe üç sınır vardır ve dıştaki içtekini bağlar:

Bir düğümün kendi timeoutMs ayarı varsa o kullanılır — ama akış deadline'ını aşamaz; kalan süre neyse düğüm onunla sınırlanır.

Açıklanabilirlikteki flowPath artık akış-öneklidir: her adım flow:<akış-adı>/<düğüm-id> biçiminde gelir — hangi düğümün hangi akışa ait olduğunu yanıttan okursunuz.

Async şerit: kararı bekletmez

executionMode='async' akışlar karar yanıtını bekletmez: koşum kuyruğa alınır, yanıtta asyncFlows listesinde queued durumuyla görünür ve arka planda aynı motorla koşar. Sonuç koşum kaydına yazılır — ayrıntı için aşağıdaki Async sonuçların iletimi bölümüne bakın.

Yanıttaki multiFlow bloğu

Karar yanıtına additive bir alan eklendi — mevcut alanlar değişmedi:

{
  "multiFlow": {
    "enabled": true,
    "executedFlows": ["kart-hiz-kurallari", "cihaz-itibari"],
    "skippedFlows": [
      { "name": "agir-analiz", "reason": "budget_exceeded" }
    ],
    "asyncFlows": [
      { "name": "vaka-taramasi", "status": "queued" }
    ]
  }
}

gRPC telinde aynı blok multiFlowJson alanında JSON string olarak taşınır.

Belirli bir akışı adıyla çağırma

İstek metadata içinde akış adı gönderirseniz çözümleme doğrudan o ada kilitlenir — çoklu çözümleme o istekte yalnız adı verilen akışı koşar:

{ "metadata": { "fraudFlowName": "yuksek-riskli-havale" } }

Kabul edilen anahtarlar: liveFraudFlowName, fraudFlowName, flowName. Bu, kanarya/deneme akışlarını sınamanın yoludur — üretimde varsayılanı ezmek için kullanmayın.

Async sonuçların iletimi

executionMode='async' akışların sonucu koşum kaydına yazılır.

Bu sonuçların size iletimi platform webhook olaylarıyla yapılacaktır — çok yakında. Platform webhook'larının kurulumu, imza doğrulaması ve yeniden deneme davranışı için: Webhook kurulumu.

Switch düğümünde eksik/bozuk veri: condition ve op farkı

Switch düğümünde bir case iki biçimde yazılabilir ve ikisinin eksik/bozuk veri (örneğin sayı beklenen alanda metin) davranışı bilinçli olarak farklıdır:

Akış yazarı kuralı: karar-kritik (block yönlü) kontrolü condition ile yazın — fail-closed davranış istersiniz. Yönlendirme amaçlı ucuz eşlemeyi op ile yazın — eksik veri default'a düşsün ve indeterminateCases ile görünür olsun.

Gelen webhook tetiği (triggerType: webhook)

webhook tetikli bir akış, bir event-stream bağlantı profili üzerinden dışarıdan tetiklenir. Zincir:

1. Panelden bir bağlantı profili tanımlanır (kaynak: webhook; imza secret'ı profildedir).
2. Dış sistem şu adrese POST atar: POST /api/v1/fraud/database-events/{connectionProfileId}/webhook/{routingKey} — imza x-event-signature, zaman damgası x-event-timestamp header'ında taşınır.
3. İmza doğrulanır (HMAC + zaman penceresi); ardından triggerType değeri webhook veya event olan ve triggerConfig.webhookPath değeri routingKey ile eşleşen yayınlanmış akışlar koşturulur.

Bu gelen tetik yalnız akışı çalıştırır; imza secret'ı bağlantı profilinde tutulur.

executionMode rehberi

Hiç akış eşleşmezse

Bu bilinçli bir tasarım: önceki davranışta yapılandırılmamış merchant ile açıkça temiz çıkmış bir ödeme birbirinden ayırt edilemiyordu. Entegrasyonunuzu kurarken fraud.decision.unconfigured sebep kodunu izleyin — akışınız yayına girmediyse bunu üretimde görürsünüz.

Capability paketleri

Akışlar tek başına da koşar, ama üzerlerinde bir capability paketi katmanı vardır: paket, bir karar için hangi yeteneklerin hangi sırayla ve hangi hata politikasıyla çalışacağını tarif eder ve gerektiğinde birden çok akışı orkestre eder.

Akış içinde kendi kodunuzu çalıştırmak

Kural düğümleri bir eşiği veya karşılaştırmayı ifade etmeye yeter; ama bazı politikalar kural diliyle yazılamaz — bir skorun kendi formülünüzle hesaplanması, bir dış yanıtın ayrıştırılması, iş kuralına özgü bir dönüşüm. Bunun için akışa script düğümü koyarsınız ve kendi JavaScript'inizi çalıştırırsınız.

Script varlığının yaşam döngüsü

Nasıl çalışır

Kod, fraud servisinin içinde değil, ayrı bir yürütme servisinde koşar: gerçek bir V8 izolatı (isolated-vm) içinde, kendi heap tavanıyla, kendi süre sınırıyla. İzolatlar belirli sayıda işten sonra geri dönüştürülür, çıktı ve log boyutu tavanlanır.

İki mod

Her çalıştırma denetime yazılır: success · failed · timeout. Süre tavanını aşan bir script akışı kilitlemez — hata olarak döner ve akışın fail-closed duruşu devreye girer.

İlgili

• Karar API'si — POST /api/v1/fraud/decisions/evaluate alan sözlüğü
• Karar Kayıtları — GET /api/v1/fraud/decision-logs