Skip to main content
SarrafPro Dış API v1, /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:
Çoğu istemci bunu sizin için üretir:
Anahtar kaydı status: true ve geçerlilik tarihi gelecekte olmalıdır; aksi halde API 401 döner. Şirketiniz Free paketteyse veya pasifleştirildiyse de istek reddedilir.

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:
Destek taleplerinde traceId paylaşmanız yeterlidir; tüm istek/cevap kayıtları bu kimlikle eşleştirilir.

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

Filtreler alan=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 kaynakta q 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ında updatedSince 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:
Zarf eksikse veya data nesne değilse istek 400 ile reddedilir.

Silme uçları

Belge iptalleri DELETE 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 _id hiçbir cevapta görünmez; kimlik her zaman id alanıdır.
  • Şirket içi alanlar (companiesId, userId vb.) ve entegrasyon sırları (örn. banka integrationsData) hiçbir uçta dönmez.
  • Tarihler ISO-8601 metnidir.

OpenAPI tanımı ve canlı deneme

Uçların makine-okunur sözleşmesi OpenAPI 3.0.3 dosyası olarak yayınlanır ve her yeni kaynakla güncellenir. Postman/Insomnia içe aktarımı veya kod üretimi (client SDK, mock) için kullanabilirsiniz; sayfanın sağ üstündeki menüden indirebilirsiniz. API Referansı sekmesinde okuma uçlarını kendi anahtarınızla tarayıcıdan deneyebilirsiniz.
Belge oluşturan uçlar (fatura, gider pusulası) canlı denemeye açılmaz: bu uçlar gerçek mali belge üretir. Bu uçları kendi ortamınızdan, önce preview ve taslak modunda deneyin.