Ana içeriğe atla

​
İstekleri hazırlama

İşlem sayfalarındaki istek örneklerini kullanın. API anahtarınızı hazırlamak, erişim koşullarını ve kayıt ilişkilerini öğrenmek için kimlik ve izinler rehberini izleyin.

​
API izinleri ve IP kısıtı

İzin listesi (scope) tanımlanmışsa en az bir geçerli muhasip:<modül>:read veya muhasip:<modül>:write izni gerekir. Liste boş veya tanımlanmamışsa anahtarın erişim yetkileri geçerlidir. Ayrıntılar kimlik ve izinler rehberindedir. read ve write ayrı izinlerdir; yazma izni kendiliğinden okuma izni vermez. API yöneticisi modül işlemi izinlerini geçebilir; firma, ürün erişimi, kayıt sahipliği veya IP denetimini geçemez. İşlem durumunu okumak için işlemin ait olduğu modülde read veya write yeterlidir. İzin kontrolü yalnız HTTP yöntemine dayanmaz. Banka yenileme, fatura kontrol/aktarım ve eşitleme, otomasyon çalıştırma, pazaryeri özet/sipariş sorgusu GET olsa da write ister. Fatura işlem ucunda type=invoiceInfo; e-Arşiv işlem ucunda func=getUserData|query|html|download okuma izniyle kullanılabilir. Diğer belgelenmiş varyantlar yazma izni ister. Yan etkili GET işlemleri HEAD ile çalıştırılmaz; 405 döner. IP listesi boşsa adres kısıtı uygulanmaz. Dolu listede doğrulanmış istemci adresi, normalize edilmiş IPv4/IPv6 adreslerinden biriyle birebir eşleşmelidir. CIDR/aralık tanımı desteklenmez. Geçersiz liste, belirlenemeyen istemci adresi veya eşleşmeyen IP 403 API_IP_FORBIDDEN üretir. API yöneticileri de bu denetime tabidir.

​
Cevaplar ve kimlikler

İşlemler çoğunlukla HTTP 200 döndürür; oluşturma için genel bir 201 standardı yoktur. result, resultData, total, paginate, createData gibi üst alanlar kaynak bazında farklıdır. İç içe hizmet durumu ile dış status aynı anlamı taşımaz. Kimlikler de kaynak bazında id, _id, UUID, paymentId veya operationId olabilir; birbirinin yerine kullanılmaz.
Belgelenen hassas bağlantı cevaplarında parolalar ve gizli anahtarlar açık döndürülmez. GİB belge içeriği, cari/ödeme bilgileri gibi iş verilerini ayrıca koruyun; ham istek/cevapları genel uygulama loglarına yazmayın. Bu belgelerdeki bütün kimlikler, kişi alanları ve sır yer tutucuları temsilîdir.

​
Hatalar

Bazı alan doğrulama cevapları result:[{type,joiType,path,label}], diğerleri code/message içerir. Bütün hatalarda aynı alanları beklemeyin. Bağlantı kopması veya JSON olmayan hata, mali işlemin hiç yapılmadığını kanıtlamaz. İşlem takibi belgesindeki durumları değerlendirin.

​
Sayfalama ve filtreler

Her işlemin kendi sayfalama, sıralama ve filtre alanlarını kullanın. Belgelenmemiş bir parametre 400 ile reddedilebilir. Kimlik filtreleri metin olarak gönderilse de sunucu firma kapsamını ve kimlik türünü doğrular. Tarih-saat için açık saat dilimi olan ISO 8601, gün filtreleri için YYYY-MM-DD kullanın.

​
Hız ve gövde sınırları

İstek sınırı istemci IP’si başına 6 saniyede 100 istektir. Sınır aşıldığında 429 döner; varsa Retry-After başlığına göre bekleyin.
Retry-After varsa değerlendirin. Finansal çağrıyı yalnız 429 veya zaman aşımı nedeniyle kendiliğinden yeniden göndermeyin. JSON/form istek gövdesi sınırı 10 MiB’dir; belge işlemleri daha dar sınırlar uygulayabilir.

​
Mali işlemler ve tekrar çağrı

Korunan mali işlemlerde kalıcı işlem kimliği, hedef kilidi ve gerektiğinde Idempotency-Key kullanılır. Bu başlık bütün CRUD isteklerinde genel bir zorunluluk değildir; ilgili kaynak ve işlem takibi hangi çağrılarda gerektiğini açıklar. Tekrar cevapları güvenli makbuz ve sonuç kimlikleriyle sınırlıdır; ilk HTML/PDF veya bütün mali yanıtın birebir tekrarı vaat edilmez. Mali işlemin sonucunu işlem kimliğiyle takip edin; sonucu belirsiz bir isteği otomatik tekrarlamayın. Tutar, vergi ve kayıt ilişkileri için muhasebesel işlem rehberini okuyun.