> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payven.com.tr/llms.txt
> Use this file to discover all available pages before exploring further.

# Yönlendirme Kuralları

> BIN aralığı, tutar, taksit ve kart filtrelerine göre konnektör seçimi.

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

```http theme={null}
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

```bash theme={null}
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.

<Note>
  **`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.
</Note>

## Skor güncelleme (canlı veriyle)

```bash theme={null}
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

```bash theme={null}
# 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

```bash theme={null}
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:

```http theme={null}
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:

```bash theme={null}
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](/resources/changelog).