/v1 öneki altında yayınlanan tüm uçlar için tek ve donmuş bir sözleşme kullanır. Bu sayfadaki kurallar her uçta aynen geçerlidir; kaynak sayfalarında yalnızca kaynağa özel alanlar anlatılır.
Ortamlar
Kimlik doğrulama
Tüm uçlar HTTP Basic kimlik doğrulaması gerektirir. Kullanıcı adıapiUserId, parola secretKey değeridir:
Cevap zarfı
Başarılı cevap
Hatalı cevap
Hata kodları
Bazı çakışma ve dış servis hatalarında
details[0] ek işlem bilgisi taşır:
Liste uçları: sayfalama, sıralama, filtreleme
Sayfalama
Sıralama
sort=alan:asc|desc biçimindedir. Her kaynağın izinli alan listesi (whitelist) vardır; liste dışı alan 400 döner. Örnek: sort=createdAt:desc.
Filtreleme
Filtreleralan=değer biçiminde yazılır ve her kaynağın sözleşmesinde açıkça listelenir:
Bilinmeyen filtre alanı
400 VALIDATION_FAILED döner. Bu, sözleşmenin donmasını garanti eder: API sessizce yeni bir filtreyi kabul edip beklenmedik davranmaz.Serbest metin arama
Çoğu kaynaktaq parametresi vardır. Numerik değerler ilgili kimlik alanında (idNo) tam eşleşme, metin değerler ad/ünvan alanında büyük-küçük harf duyarsız arama yapar.
Artımlı senkronizasyon (incremental sync)
Müşteriler, uyum kayıtları, banka hesapları, banka hareketleri ve gider pusulası kaynaklarındaupdatedSince desteklenir: yalnızca verilen ISO-8601 tarihinden sonra güncellenen kayıtlar döner. Muhasebe ve e-ticaret entegrasyonlarında önerilen desen:
Her kaynağın desteklediği filtreler kendi sayfasında listelenir. Desteklenmeyen bir filtre
400 VALIDATION_FAILED döner; sessizce yok sayılmaz.Yazma uçları: gövde zarfı ve durum kodları
POST uçlarında gövde data zarfı zorunludur:
data nesne değilse istek 400 ile reddedilir.
Silme uçları
Belge iptalleriDELETE ile yapılır ve yalnız kesinleşmemiş belgeyi kapsar: gönderilmemiş fatura taslağı, kesinleştirilmemiş gider pusulası. Kesinleşmiş belge 409 döner ve iptali panelden yürütülür.
Mükerrer koruma
Finansal belge oluşturan uçlar mükerrer isteğe karşı korumalıdır. Ağ hatası nedeniyle cevabı alamadığınız bir istekte tekrar denemeden önce ilgili liste ucundan belgenin oluşup oluşmadığını doğrulayın. Fatura cevabıUPSTREAM_RESULT_UNCERTAIN ise aynı banka hareketini otomatik tekrar göndermeyin. details[0].retryable değeri false olur. traceId ve details[0].attemptId değerlerini saklayıp sonucu SarrafPro üzerinden doğrulayın.
source: "bankTransaction" kullanılan fatura ve gider pusulası işlemlerinde bağlı banka hesabı aktif olmalıdır. Bu kontrol önizleme, taslak ve gerçek oluşturma sırasında yeniden yapılır. Salt-okunur banka hareketi geçmişi bu kuraldan etkilenmez.Alan disiplini
- Mongo
_idhiçbir cevapta görünmez; kimlik her zamanidalanıdır. - Şirket içi alanlar (
companiesId,userIdvb.) ve entegrasyon sırları (örn. bankaintegrationsData) hiçbir uçta dönmez. - Tarihler ISO-8601 metnidir.