> ## 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 — Genel Bakış
> Banka gün sonu hareketlerini Payven kayıtlarıyla eşleştirin, tutarsızlıkları yönetin.
Mutabakat, bir dönemde yapılan tüm ödeme/iade hareketlerinin **banka kayıtlarıyla eşleştirilmesi** sürecidir. Tutarsızlıkları (eksik kayıt, tutar farkı, durum farkı) tespit edip operatörün karar vermesini bekler; nihai onayla gelir muhasebenize netlik kazandırır.
## Kapsam ve dönem
Bir mutabakat **kapsam** ve **dönem** olarak sınırlanır:
| Boyut | Değerler |
| ---------------------------- | --------------------------------------------------------------------------------- |
| `scope` | `connector` (banka konfigürasyonu bazında) veya `merchant` (alt-merchant bazında) |
| `period` | `daily`, `monthly`, `yearly`, `custom` |
| `period_start`, `period_end` | UTC zaman damgaları (`custom` için zorunlu, diğerleri otomatik hesaplanır) |
## Endpoint'ler
```http theme={null}
POST /api/v1/reconciliations/start # Mutabakat başlat
GET /api/v1/reconciliations # Liste (sayfalı)
GET /api/v1/reconciliations/{id} # Tek mutabakat detayı (özet + tüm satırlar)
GET /api/v1/reconciliations/{id}/details # Sadece satırlar (sayfalı)
POST /api/v1/reconciliations/{id}/details/{detail_id}/resolve # Tek tutarsızlığı çöz
POST /api/v1/reconciliations/{id}/details/bulk-resolve # Toplu çözüm
POST /api/v1/reconciliations/{id}/finalize # Mutabakatı kapat (Settled olarak işaretle)
POST /api/v1/reconciliations/{id}/cancel # Mutabakatı iptal et
```
## Süreç
```mermaid theme={null}
flowchart LR
A[Banka CSV/API] --> B[POST /reconciliations/start
bank_transactions: []]
B --> C[Eşleştirme motoru]
C --> D{Tutarsızlık?}
D -->|Hayır| E[Tüm satırlar matched]
D -->|Evet| F[orphan_db / orphan_bank /
amount_mismatch / status_mismatch]
F --> G[Operatör resolve eder]
G --> H[POST /finalize]
E --> H
H --> I[İlgili işlemler
'settled' olur]
```
## Mutabakat başlatma
```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_transaction_id": "GAR-AUTH-789-001",
"amount": 15000,
"status": "approved",
"transaction_date": "2026-05-03T12:34:58+00:00",
"auth_code": "123456"
}
]
}'
```
| Alan | Tip | Zorunluluk | Açıklama |
| --------------------- | -------- | --------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `scope` | enum | Zorunlu | `connector` veya `merchant` |
| `connector_config_id` | UUID | scope=connector | Hangi konnektör konfigürasyonu için |
| `merchant_id` | UUID | scope=merchant | Hangi alt-merchant için |
| `period` | enum | Zorunlu | `daily`, `monthly`, `yearly`, `custom` |
| `period_start` | datetime | Zorunlu | Dönem başlangıcı (UTC) |
| `period_end` | datetime | period=custom | Dönem sonu — `custom` için zorunlu |
| `bank_transactions[]` | array | Opsiyonel | Banka satır listesi. Boş bırakılırsa sadece DB tarafı ile çalışılır (banka veriden bağımsız Payven self-reconciliation). |
### `bank_transactions[]` satır yapısı
| Alan | Açıklama |
| ---------------------- | ------------------------------------------------------------------------------------------------------------ |
| `bank_transaction_id` | Banka tarafındaki işlem ID (Payven `provider_transaction_id` ile eşleştirilir) |
| `amount` | Tutar (kuruş) |
| `status` | Banka tarafından dönen durum: `approved`, `completed`, `declined`, `failed`, `refunded`, `voided`, `pending` |
| `transaction_date` | Banka tarafı işlem zamanı |
| `merchant_external_id` | Opsiyonel — merchant scope'ta yardımcı eşleştirme |
| `auth_code` | Opsiyonel — fallback eşleştirme anahtarı |
## Yanıt
```json theme={null}
{
"id": "8e3f5c12-9a7b-4c8d-bc4e-2c963f66afa6",
"scope": "connector",
"connector_config_id": "cfg_garanti_prod-001",
"connector_config_name": "Garanti VPOS Production",
"merchant_id": null,
"merchant_name": null,
"bank_code": "GARANTI",
"period": "daily",
"period_start": "2026-05-03T00:00:00.000+00:00",
"period_end": "2026-05-03T23:59:59.999+00:00",
"reconciliation_date": "2026-05-04",
"total_db_transactions": 1247,
"total_bank_transactions": 1245,
"matched_count": 1240,
"amount_mismatch_count": 2,
"status_mismatch_count": 1,
"orphan_db_count": 5,
"orphan_bank_count": 3,
"resolved_count": 0,
"ignored_count": 0,
"total_db_amount": 18705000,
"total_bank_amount": 18675000,
"overall_status": "draft",
"finalized_at": null,
"finalized_by": null,
"notes": null,
"created": "2026-05-04T03:00:00.000+00:00",
"details": [
{
"id": "9f3d2b8e-...",
"reconciliation_id": "8e3f5c12-...",
"transaction_id": "abc-...",
"bank_transaction_id": "GAR-AUTH-789-001",
"db_amount": 15000,
"bank_amount": 14990,
"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
}
]
}
```
## `overall_status` değerleri
| Değer | Anlam |
| --------------------- | ------------------------------------------------------------------------------ |
| `draft` | Başlatıldı, uyuşmazlıklar çıkarıldı, kullanıcı müdahalesi bekleniyor |
| `in_review` | Kısmi çözüm uygulandı ama hâlâ bekleyen uyuşmazlıklar var |
| `completed` | Tüm uyuşmazlıklar çözüldü/ignore edildi, mutabakat tamamlandı |
| `partially_completed` | Kullanıcı eksik veriyle kapattı — bekleyen kayıtlar `ignored` olarak kapatıldı |
| `cancelled` | İptal edildi |
## `detail_status` değerleri (her uyuşmazlık satırı için)
| Değer | Anlam |
| -------------- | ------------------------------------------------------ |
| `pending` | Henüz kullanıcı müdahalesi bekleniyor |
| `resolved` | Kullanıcı çözdü (düzeltme uygulandı veya manuel match) |
| `ignored` | Kullanıcı görmezden geldi |
| `auto_matched` | Otomatik eşleşti — yalnız örnek/log amaçlı tutuluyor |
## `discrepancy` tipleri
| Tip | Anlam |
| ----------------- | -------------------------------------------------------------------------------------------- |
| `matched` | İki tarafta da var, tutar + durum uyumlu — işlem yok |
| `amount_mismatch` | İki tarafta var ama tutarlar farklı |
| `status_mismatch` | İki tarafta var, tutar aynı ama durum farklı (örn. Payven'de `completed`, banka'da `voided`) |
| `orphan_db` | Sadece Payven tarafında — bankada yok |
| `orphan_bank` | Sadece bankada — Payven tarafında yok |
## Yaşam döngüsü ve çözüm akışı
Tutarsızlıkları çözme + finalize için: [Mutabakat Yaşam Döngüsü](/sanal-pos/reconciliation/lifecycle).
## Settlement raporları
Mutabakat finalize olduğunda ilgili işlemler için `settlement_date` doldurulur. Settlement endpoint'leri ile günlük settlement raporlarını çekebilirsiniz:
```http theme={null}
GET /api/v1/settlements # Liste (sayfalı)
GET /api/v1/settlements/{id} # Tek settlement detayı
POST /api/v1/settlements # Yeni settlement (manuel)
GET /api/v1/settlements/{id}/status # Durum sorgusu
```