Karar API'si

Bir olayı bir senaryoya karşı değerlendirir ve sonucu gerekçesiyle döndürür.

POST /api/decisions
X-API-KEY: <anahtar>
Content-Type: application/json

İstek

string

gerekli

Değerlendirmeyi yapacak senaryonun kimliği. Senaryonun canlı sürümü kullanılır.

string

gerekli

Veri modelinizdeki tablo adı — trigger_object bu şemaya göre doğrulanır.

object

gerekli

Değerlendirilecek olayın kendisi. object_id ve updated_at zorunludur.

boolean

varsayılan:"false"

Açıksa her kuralın sonucu ve puanı yanıta eklenir.

boolean

varsayılan:"false"

Açıksa karar ayrıca decision.created webhook’u olarak yayınlanır.

{
  "scenario_id": "019fd100-0000-7000-9000-000000000001",
  "object_type": "sanal_pos",
  "with_rule_execution_details": true,
  "trigger_object": {
    "object_id": "tx-88214",
    "updated_at": "2026-08-06 10:00:00",
    "musteri_no": "M10471",
    "sepet_tutari": 12500.00,
    "client_ip": "203.0.113.45"
  }
}

Yanıt

{
  "decision": {
    "outcome": "BlockAndReview",
    "score": 92,
    "scenario_name": "E-ticaret ödeme riski",
    "scenario_version": 3,
    "review_status": "pending",
    "case_id": "019fd100-0000-7000-a000-000000500001"
  },
  "rule_executions": [
    { "rule_name": "Geçici e-posta sağlayıcı", "outcome": "hit", "score": 40 },
    { "rule_name": "Datacenter / VPN çıkışı", "outcome": "hit", "score": 30 },
    { "rule_name": "Sepet tutarı olağan dışı", "outcome": "hit", "score": 25 },
    { "rule_name": "Yaptırım listesi eşleşmesi", "outcome": "no_hit", "score": 0 }
  ],
  "execution_time_ms": 34
}

Sonuçlar

`outcome`	Anlamı	Ne yapmalısınız
`Approve`	Puan inceleme eşiğinin altında	İşleme devam edin
`Review`	Eşiği geçti ama durdurulmadı	İşleme devam edin; vaka açıldı
`BlockAndReview`	Durdurun, insan karar versin	İşlemi askıya alın
`Decline`	Reddedin	İşlemi reddedin
`Unknown`	Senaryonun tetikleme koşulu sağlanmadı	Kendi varsayılanınızı uygulayın

Unknown bir hata değildir: senaryo o olayla hiç ilgilenmedi demektir. Kodunuzda bu durumu ayrıca ele alın — Approve ile aynı kefeye koymak, tetikleme koşulunuz daraldığında tüm trafiği sessizce onaylatır.

Kural sonuçları

outcome alanı hit ise kural tetiklenmiş ve puanını eklemiştir; no_hit ise değerlendirilmiş ama tetiklenmemiştir. Tetiklenmeyen kuralların da yanıtta yer alması kasıtlıdır — “bu kural neden hiç çalışmıyor” sorusunun cevabı çoğu zaman buradadır.

Gecikme

execution_time_ms o kararın motorda geçirdiği süredir. Ağ süresini içermez. Tipik bir senaryoda onlarca milisaniyedir; süreyi esas olarak kural sayısı ve hız kurallarının pencere genişliği belirler.

Süre dökümü

Tek bir toplam, kararın yavaş olduğunu söyler ama hangi kısmının yavaş olduğunu söylemez — ve o kısımlar birbirinden bağımsız nedenlerle yavaşlar: kurallar pahalılaşmıştır, bir agregat eskisinden çok satır tarıyordur, veritabanı yük altındadır, ya da mesaj kuyruğu geç onaylıyordur. with_rule_execution_details isteyen bir çağrıda yanıt stage_timings taşır: her aşama, kaç kez çalıştığı ve toplam süresi.

"stage_timings": [
  { "stage": "aggregation_query", "count": 18, "milliseconds": 240.118 },
  { "stage": "rule_eval", "count": 1, "milliseconds": 251.4 }
]

Yanıtta görülebilecek aşamalar:

aşama	ne ölçüyor
`rule_eval`	Senaryonun kurallarının değerlendirilmesi
`aggregation_query`	Tek bir agregasyon sorgusu. Karar, kurallarının sorduğu her agregat için bir kez çalıştırır ve bu süre `rule_eval` içinde geçer
`decision_publish`	Kararın mesaj kuyruğuna verilip onayının beklenmesi

Kararın veritabanına yazılması listede yoktur ve olmaması doğrudur: yazma, siz cevabı aldıktan sonra ayrı bir tüketicide gerçekleşir. Aşama dökümü yalnızca sizi bekletmiş olan işi sayar.

Tekrarlayan aşamalar listelenmek yerine toplanır, çünkü asıl okunacak cümle onlardadır: “18 sorgu, 240 ms” yavaş kararı açıklar; on sekiz satır dört milisaniye kimsenin toplamadığı aynı bilgidir.

Aşamalar toplamı execution_time_ms etmez. İç içe geçerler ve üst üste binerler; ölçülmemiş bir boşluk da boşta geçen zaman değil, henüz adı konmamış iştir. Bunu bir pasta grafiğine dönüştürmeyin.

Dün gerçekleşmiş tek bir yavaş ödemeyi elinde yalnızca bir korelasyon kimliğiyle soran entegratörün cevabı budur — yüzdelik dilim panolarına tek bir işlem sorulamaz.

Başlangıç

Platform

Kararlar

Veri ve olaylar

Sinyaller ve tarama

Yapay zeka

Kendi sunucunuzda

Karar API'si

İstek

Yanıt

Sonuçlar

Kural sonuçları

Gecikme

Süre dökümü

​İstek

​Yanıt

​Sonuçlar

​Kural sonuçları

​Gecikme

​Süre dökümü

İstek

Yanıt

Sonuçlar

Kural sonuçları

Gecikme

Süre dökümü