> ## 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.

# Mutabakat Yaşam Döngüsü

> Bir mutabakat oturumunun başlatılmasından sonlandırılmasına tüm aşamalar.

Bu sayfa bir mutabakat oturumunun her aşamasını ve API çağrılarını detaylandırır. Endpoint listesi ve request/response şekli için: [Mutabakat Genel Bakış](/sanal-pos/reconciliation/overview).

## 1. Başlatma

Mutabakat genellikle **gün sonunda planlı** çalışır (banka raporlarının gelmesinden sonra, tipik olarak 02:00-04:00 arası). Manuel başlatma için:

```bash theme={null}
curl -X POST https://vpos.payven.com.tr/api/v1/reconciliations/start \
  -H "Authorization: Bearer $PAYVEN_TOKEN" \
  -H "Idempotency-Key: recon-garanti-2026-05-03" \
  -H "Content-Type: application/json" \
  -d '{
    "scope":               "connector",
    "connector_config_id": "cfg_garanti_prod-001",
    "period":              "daily",
    "period_start":        "2026-05-03T00:00:00+00:00",
    "bank_transactions":   [...]
  }'
```

`bank_transactions` boş gönderilirse Payven sadece kendi DB tarafında self-reconciliation yapar (banka verisinden bağımsız bir doğrulama). Banka CSV/XLS dosyasını parse edip satırları doldurmak müşteri tarafının sorumluluğundadır — yol haritasında bu adım için Payven tarafında parser/import endpoint'i planlanıyor.

## 2. Karşılaştırma

Payven gün boyu kaydedilen `completed`, `refunded`, `voided` hareketleri banka satırlarıyla eşleştirir. Eşleştirme anahtarları:

* **Birincil:** `provider_transaction_id` ↔ `bank_transaction_id`
* **Yedek:** `auth_code` ↔ `auth_code` (aynı banka içinde)
* **Merchant scope'unda:** `merchant_external_id` ile filtreleme

Karşılaştırma sırasında her satır şu kategorilerden birine düşer:

| Kategori          | Tetikleyici                                                           |
| ----------------- | --------------------------------------------------------------------- |
| `matched`         | İki tarafta var, tutar + durum uyumlu                                 |
| `amount_mismatch` | Tutarlar uyuşmuyor (banka komisyonu kesmişse tipik)                   |
| `status_mismatch` | Tutar aynı ama durum farklı (örn. Payven `completed`, banka `voided`) |
| `orphan_db`       | Sadece Payven'de var                                                  |
| `orphan_bank`     | Sadece bankada var                                                    |

## 3. İnceleme

Mutabakat detayını veya sadece tutarsızlıkları çekin:

```bash theme={null}
# Tüm satırlar (sayfalı)
curl "https://vpos.payven.com.tr/api/v1/reconciliations/8e3f5c12.../details?page=1&page_size=50&detail_status=pending" \
  -H "Authorization: Bearer $PAYVEN_TOKEN"
```

Yanıt — sayfalı `ReconciliationDetailDto` listesi:

```json theme={null}
{
  "items": [
    {
      "id":                  "9f3d2b8e-...",
      "reconciliation_id":   "8e3f5c12-...",
      "transaction_id":      "abc-...",
      "bank_transaction_id": "GAR-AUTH-789-001",
      "db_amount":           15000,
      "bank_amount":         14750,
      "db_status":           "completed",
      "bank_status":         "approved",
      "discrepancy":         "amount_mismatch",
      "detail_status":       "pending",
      "resolution_action":   null,
      "adjusted_amount":     null,
      "applied_status":      null,
      "resolved_at":         null,
      "resolved_by":         null,
      "remarks":             null
    }
  ],
  "page":              1,
  "total_pages":       1,
  "total_count":       12,
  "has_previous_page": false,
  "has_next_page":     false
}
```

## 4. Tutarsızlıkları çözme

### Tek satır

```bash theme={null}
curl -X POST https://vpos.payven.com.tr/api/v1/reconciliations/8e3f5c12.../details/9f3d2b8e.../resolve \
  -H "Authorization: Bearer $PAYVEN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "resolution_action": "accept_bank",
    "adjusted_amount":   14750,
    "applied_status":    "completed",
    "remarks":           "Banka 250 kuruş komisyon kesti, Payven tarafında net tutar revize edildi"
  }'
```

| Alan                | Açıklama                                                                                                                                                                                                                                                                                                                 |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `resolution_action` | `accept_bank` (banka doğru, DB güncellenir), `accept_db` (DB doğru, banka satırı resolved işaretlenir), `mark_matched` (manuel eşleştirme — tutar/durum dokunulmaz), `adjust_amount` (manuel tutar override — `adjusted_amount` ile), `force_status` (manuel durum override — `applied_status` ile), `ignore` (göz ardı) |
| `adjusted_amount`   | `accept_bank` veya `adjust_amount` için revize tutar (Payven kaydı bu değere çekilir)                                                                                                                                                                                                                                    |
| `applied_status`    | `force_status` için yeni durum (örn. `canceled` ↔ `completed` eşleşmemesi durumunda)                                                                                                                                                                                                                                     |
| `remarks`           | Operatör notu — audit için kalıcı saklanır                                                                                                                                                                                                                                                                               |

### Toplu çözüm

```bash theme={null}
curl -X POST https://vpos.payven.com.tr/api/v1/reconciliations/8e3f5c12.../details/bulk-resolve \
  -H "Authorization: Bearer $PAYVEN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "detail_ids":        ["9f3d2b8e-...", "abc123-...", "def456-..."],
    "resolution_action": "accept_bank",
    "remarks":           "Banka komisyon kesintisi — toplu kabul"
  }'
```

## 5. Finalize

Tüm tutarsızlıklar çözüldükten sonra:

```bash theme={null}
curl -X POST https://vpos.payven.com.tr/api/v1/reconciliations/8e3f5c12.../finalize \
  -H "Authorization: Bearer $PAYVEN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "notes": "Mayıs 3 günü mutabakat tamamlandı" }'
```

Finalize sonrası:

* `overall_status: "completed"` (veya bekleyen kalemler `ignored` ile kapatıldıysa `partially_completed`), `finalized_at` doldurulur
* İlgili işlemlerin `settlement_date` alanı doldurulur — wire `status` enum'u değişmez, `transaction.status` `completed` kalır; settlement durumu ayrı `Settlement` kaynağında izlenir
* Operatör kullanıcı kimliği `finalized_by` alanında saklanır

## 6. İptal

Henüz finalize edilmemiş bir mutabakatı iptal etmek için:

```bash theme={null}
curl -X POST https://vpos.payven.com.tr/api/v1/reconciliations/8e3f5c12.../cancel \
  -H "Authorization: Bearer $PAYVEN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Yanlış konnektör seçildi, yeni session açılacak" }'
```

İptal mutabakat durumunu `cancelled` yapar. İlgili işlemler etkilenmez.

## Tipik süreler

| Aşama                                      | Tipik süre                    |
| ------------------------------------------ | ----------------------------- |
| Başlatma → Karşılaştırma tamamlanma        | 5-30 dk (işlem hacmine bağlı) |
| Otomatik finalize (tüm satırlar `matched`) | Anlık                         |
| Manuel inceleme (tutarsızlıklar varsa)     | Operatör süresine bağlı       |

Tutarsızlık varsa finalize **manuel** olarak yapılır — operatör çözümleri girene kadar `draft` veya `in_review` statüsünde bekler.

## Geriye dönük inceleme

```bash theme={null}
curl "https://vpos.payven.com.tr/api/v1/reconciliations?period_start_from=2026-04-01T00:00:00Z&period_start_to=2026-04-30T23:59:59Z&page=1&page_size=50" \
  -H "Authorization: Bearer $PAYVEN_TOKEN"
```

## Yol haritası

* **Banka CSV import** — Payven tarafında banka raporu dosyasını parse eden endpoint
* **Otomatik scheduled reconciliation** — günlük cron + slack/email bildirimi
* **Reconciliation webhook event'leri** — `reconciliation.discrepancy_detected`, `reconciliation.finalized` (şu an public webhook event listesinde yok)
* **Connector-spesifik banka raporu API entegrasyonları** — manuel CSV upload yerine otomatik fetch

Güncellemeler için: [Changelog](/resources/changelog).