API referansı

Bu dosya, dökümanda yer alan her endpoint için Özet / Açıklama alanına kopyalanabilecek Türkçe metinleri ve örnekleri içerir. Tek doğruluk kaynağı şema için API Dökümanı kullanılmalıdır.

Dökümanda yer alan servisler

Metot	Yol	Özet	Açıklama
`POST`	`/payment/initialize`	Doğrudan satış başlat	Peşin veya taksitli satış için kart ile tahsilat başlatır. Tutar kuruş cinsindendir; `currency` zorunludur. Yanıtta işlem numarası ve durum döner; 3DS gerekiyorsa yönlendirme bilgisi üretilebilir.
`POST`	`/payment/preauth`	Ön provizyon başlat	Tutarı tahsil etmeden bloklamak için ön provizyon başlatır. Sonrasında tahsilat için postauth ucu kullanılır.
`POST`	`/payment/pay-by-link`	Ödeme linki oluştur	Müşteriye gönderilecek ödeme bağlantısı üretir; süre ve tutar kuralları istek gövdesinde tanımlanır.
`GET`	`/payment/status/{transaction_id}`	İşlem durumu sorgula	Tek bir işlemin güncel durumunu ve temel alanlarını döner. Entegrasyonda ana doğrulama kaynağı olarak kullanılabilir.
`GET`	`/payment/transactions`	Tarih aralığında işlem listesi	`start_date` ve `end_date` ile aralık sorgusu; sayfalama `limit` ve `offset` ile yapılır.
`POST`	`/payment/postauth/{transaction_id}`	Ön provizyonu tahsilata çevir	Yalnızca uygun durum ve işlem tipinde çalışır; banka tarafı tahsilatı tamamlar.
`POST`	`/payment/refund/{transaction_id}`	İade talebi	Ana satış satırına karşı iade veya banka kurallarına uygun iptal/iade adımlarını tek uçtan başlatır. Kısmi iade için gövdede tutar verilir; tam iade için tutar boş bırakılabilir (sunucu kurallarına göre).

Kimlik doğrulama (OpenAPI güvenlik şeması)

Tüm /payment/* uçları APIKeyHeader ile korunur — pratikte:

Örnek: initialize

Örnek: refund

İade; SALE veya INSTALLMENT_SALE tipinde ve APPROVED veya CAPTURED durumundaki ana satışa uygulanır.

`error.code` (`detail_code`) sözlüğü

Aşağıdaki kodlar transaction_service/routers/payment.py içinde HTTPException ile atanır; yanıtta error.code olarak döner.

İşlem bulunamadı / erişim

Kod	HTTP	Kısa açıklama
`TRANSACTION_NOT_FOUND`	404	İşlem yok veya bu işyerine ait değil

Tarih aralığı listesi

Kod	HTTP	Kısa açıklama
`INVALID_DATE_RANGE`	400	Bitiş başlangıçtan önce

Tahsilat (postauth)

Kod	HTTP	Kısa açıklama
`INVALID_STATUS_FOR_CAPTURE`	400	İşlem tahsilat için uygun durumda değil
`BANK_CLIENT_UNAVAILABLE`	503	Banka istemcisi kullanılamıyor

İade (refund)

Kod	HTTP	Kısa açıklama
`INVALID_TRANSACTION_KIND`	400	İade yalnızca ana satış satırına
`INVALID_TRANSACTION_TYPE_FOR_REFUND`	400	İade için işlem tipi uygun değil
`INVALID_STATUS_FOR_REFUND`	400	İade için durum uygun değil
`REFUND_AMOUNT_EXCEEDS_TX`	400	İade tutarı işlemi aşıyor
`REFUND_CUMULATIVE_EXCEEDS_TX`	400	Toplam iade tutarı limiti aşıyor
`MISSING_BANK_REFERENCE`	400	Banka referansı eksik
`BANK_CLIENT_UNAVAILABLE`	503	Banka istemcisi kullanılamıyor

Bankanın reddettiği durumlarda kod bankanın döndürdüğü hataya göre değişebilir.

Ön provizyon iptali

Kod	HTTP	Kısa açıklama
`INVALID_TRANSACTION_TYPE_FOR_PREAUTH_CANCEL`	400	Yalnızca PREAUTH
`INVALID_STATUS_FOR_PREAUTH_CANCEL`	400	Durum uygun değil

Doğrulama

Kod	HTTP	Kısa açıklama
`VALIDATION_ERROR`	422	İstek gövdesi veya parametre şemaya uymuyor

Dökümanda yer alan servisler#

Kimlik doğrulama (OpenAPI güvenlik şeması)#

Örnek: initialize#

Örnek: refund#

error.code (detail_code) sözlüğü#

İşlem bulunamadı / erişim#

Tarih aralığı listesi#

Tahsilat (postauth)#

İade (refund)#

Ön provizyon iptali#

Doğrulama#