Yönlendirme Kuralları

Yönlendirme kuralları, bir ödeme isteğine hangi konnektörün yanıt vereceğini belirler. Her kural bir filtre kümesi + bir hedef konnektör + opsiyonel fallback konnektör tanımlar. Engine kuralları priority sırasında değerlendirir; ilk eşleşen kural seçilir.

Endpoint’ler

GET    /api/v1/routing-rules                      # Liste
GET    /api/v1/routing-rules/{id}                 # Tek kural
POST   /api/v1/routing-rules                      # Yeni kural
PUT    /api/v1/routing-rules/{id}                 # Güncelleme
DELETE /api/v1/routing-rules/{id}                 # Silme
POST   /api/v1/routing-rules/bulk-delete          # Toplu silme
POST   /api/v1/routing-rules/{id}/activate
POST   /api/v1/routing-rules/{id}/deactivate
PATCH  /api/v1/routing-rules/{id}/score           # Skor güncelleme

Kural oluşturma

curl -X POST https://vpos.payven.com.tr/api/v1/routing-rules \
  -H "Authorization: Bearer $PAYVEN_TOKEN" \
  -H "Idempotency-Key: routing-rule-bonus-garanti" \
  -H "Content-Type: application/json" \
  -d '{
    "name":                       "Bonus 1-12 taksit Garanti",
    "priority":                   10,
    "is_active":                  true,
    "card_bin":                   "454671",
    "card_bin_end":               "454699",
    "installment_count":          null,
    "min_amount":                 100,
    "max_amount":                 20000000,
    "currency":                   "TRY",
    "card_brand_filter":          "bonus",
    "card_type_filter":           "credit",
    "target_connector_config_id": "cfg_garanti_prod-001",
    "fallback_connector_config_id":"cfg_akbank_prod-001",
    "weight":                     70,
    "success_rate":               99.2,
    "average_response_time_ms":   850,
    "cost_score":                 80,
    "daily_transaction_limit":    100000
  }'

Alan referansı

Alan	Tip	Zorunluluk	Açıklama
`name`	string	Zorunlu	İnsan-okur ad (raporlamada görünür)
`priority`	short	Zorunlu	Değerlendirme sırası (düşük sayı = önce). 0-32767.
`is_active`	bool	Opsiyonel	Varsayılan `true`
`card_bin`	string	Opsiyonel	BIN başlangıcı (1-6 hane). Tek BIN için `card_bin_end` ile aynı verin.
`card_bin_end`	string	Opsiyonel	BIN aralığı sonu — `card_bin`–`card_bin_end` aralığı eşleşir
`installment_count`	short	Opsiyonel	Spesifik taksit sayısı (boş = her taksit)
`min_amount`, `max_amount`	long (kuruş)	Zorunlu	Tutar aralığı
`currency`	string	Opsiyonel	Para birimi filtresi (boş = her para birimi). Şu an üretimde yalnız `TRY` aktif.
`card_brand_filter`	enum	Opsiyonel	`bonus`, `maximum`, `axess`, `world`, `paraf`, `cardfinans`, `wings`
`card_type_filter`	enum	Opsiyonel	`credit`, `debit`, `prepaid`
`target_connector_config_id`	UUID	Zorunlu	Birinci tercih — hangi konnektör konfigürasyonu yanıtlayacak
`fallback_connector_config_id`	UUID	Opsiyonel	Birinci başarısız olursa Smart Retry hangisini denesin
`weight`	short	Opsiyonel	0-100 — A/B trafik dağılımı veya skoring katkısı
`success_rate`	decimal	Opsiyonel	Son ölçülen başarı oranı (0-100) — score motoruna girer
`average_response_time_ms`	int	Opsiyonel	Son ortalama yanıt süresi — skor motoruna girer
`cost_score`	short	Opsiyonel	0-100 (yüksek = daha ucuz). Skor motoruna girer.
`daily_transaction_limit`	int	Opsiyonel	Günlük işlem limiti — aşılırsa kural pas geçilir

Skor formülü

Engine kuralı eşleşen aday konnektörler için bileşik skor üretir:

score = (weight × 0.30) + (success_rate × 0.30) + ((1000 − response_ms) × 0.20) + (cost_score × 0.20)

En yüksek skorlu konnektör seçilir. Eşit skorda priority daha düşük olan kazanır.

success_rate ve average_response_time_ms alanları konsol ve background job’lar tarafından canlı veriden güncellenir — manuel girmenize gerek yok. İlk oluşturmada makul varsayılanları (örn. 100 ve 800) verin.

Skor güncelleme (canlı veriyle)

curl -X PATCH https://vpos.payven.com.tr/api/v1/routing-rules/{id}/score \
  -H "Authorization: Bearer $PAYVEN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "success_rate":            98.5,
    "average_response_time_ms":920
  }'

Skor güncellemesi otomatik agent (background job) tarafından dakikada bir yapılır. Manuel müdahale nadir gereklidir.

Aktif / pasif

# Pasife al
curl -X POST https://vpos.payven.com.tr/api/v1/routing-rules/{id}/deactivate \
  -H "Authorization: Bearer $PAYVEN_TOKEN"

# Aktif et
curl -X POST https://vpos.payven.com.tr/api/v1/routing-rules/{id}/activate \
  -H "Authorization: Bearer $PAYVEN_TOKEN"

Toplu silme

curl -X POST https://vpos.payven.com.tr/api/v1/routing-rules/bulk-delete \
  -H "Authorization: Bearer $PAYVEN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "ids": ["uuid1", "uuid2", "uuid3"] }'

Basit kurallar (`/simple-routing-rules`)

Yeni başlayanlar için Simple Routing Rules alternatifi vardır. Aynı CRUD pattern’iyle çalışır ama skor motoru olmadan, “şu BIN’e şu konnektör” mantığında düz yapı sunar:

GET    /api/v1/simple-routing-rules
POST   /api/v1/simple-routing-rules
PUT    /api/v1/simple-routing-rules/{id}
DELETE /api/v1/simple-routing-rules/{id}
POST   /api/v1/simple-routing-rules/bulk-delete
POST   /api/v1/simple-routing-rules/{id}/activate
POST   /api/v1/simple-routing-rules/{id}/deactivate

Hata response’ları

HTTP	`code`	Anlam
`404`	`connector_not_found`	`target_connector_config_id` veya `fallback_connector_config_id` bulunamadı
`422`	`validation_failed`	`min_amount > max_amount`, BIN format hatası, vb.
`409`	`idempotency_key_in_use`	Aynı `Idempotency-Key` farklı body için kullanılmış

Resolve simülasyonu

Bir koşul setine göre hangi kuralların eşleşeceğini önceden hesaplamak için:

curl -X POST https://vpos.payven.com.tr/api/v1/routing-rules/resolve \
  -H "Authorization: Bearer $PAYVEN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "card_bin":    "454671",
    "amount":      15000,
    "installment": 3,
    "card_brand":  "bonus",
    "card_type":   "credit"
  }'

Yanıtta skor sıralı eşleşen kurallar listesi döner. Production trafiğine etki etmez.

Yol haritası

Conditional rule tree — AND/OR operatörlü ağaç tabanlı koşullar
A/B traffic split — aynı koşula iki konnektör + ağırlık dağıtımı
Rule clone — mevcut kuralı kopyalayıp düzenleme

Güncellemeler için: Changelog.

Genel Bakış

Ödeme Akışları

Sorgulamalar

Akıllı Yönlendirme

Mutabakat

Webhook'lar

Raporlama & İzleme

Test

Hata Kodları

Endpoint’ler

Kural oluşturma

Alan referansı

Skor formülü

Skor güncelleme (canlı veriyle)

Aktif / pasif

Toplu silme

Basit kurallar (`/simple-routing-rules`)

Hata response’ları

Resolve simülasyonu

Yol haritası

​Endpoint’ler

​Kural oluşturma

​Alan referansı

​Skor formülü

​Skor güncelleme (canlı veriyle)

​Aktif / pasif

​Toplu silme

​Basit kurallar (/simple-routing-rules)

​Hata response’ları

​Resolve simülasyonu

​Yol haritası

Endpoint’ler

Kural oluşturma

Alan referansı

Skor formülü

Skor güncelleme (canlı veriyle)

Aktif / pasif

Toplu silme

Basit kurallar (`/simple-routing-rules`)

Hata response’ları

Resolve simülasyonu

Yol haritası