Ana içeriğe atla

​
Kayıt ve tutar ilişkileri

Banka hareketi onayı ödeme kaydı, fatura aktarımı muhasebe kaydı, pazaryeri aktarımı ise fatura ve gerekirse cari, ürün veya depo kayıtları oluşturabilir. İşlem sonucundaki kimlikleri kendi iş referansınızla birlikte saklayın ve ilgili kayıtlarla doğrulayın. JSON sayı alanlarında 1234.56 kullanın; 1.234,56 gibi görüntü metni göndermeyin. Kur ve yuvarlama işlemleri kaynağa özeldir. İstek değerleriyle oluşan mali kaydın değerlerini mutabakat için birlikte saklayın.

​
Fatura: taslak, gönderim, aktarım ve iptal

  1. Fatura bağlantısını ve kredi durumunu okuyun. Bağlantı durumu anahtar içermez.
  2. POST /apps/invoice/api, type=invoiceInfo ile mükellef/seri/şablon seçeneklerini alın; bu varyant read izniyle çalışır.
  3. type=view için kalıcı bir Idempotency-Key belirleyin. Bu çağrı sağlayıcıda taslak oluşturur; UUID’yi ve işlem makbuzunu saklayın.
  4. type=invoiceapproval ile 1–100 benzersiz UUID seçimini gönderin. Gönderim kabulünden sonra aktarım işareti yazılır; belirsiz sonuçta yeni gönderim başlatılmaz.
  5. GET /apps/invoice/check/{UUID} belgeyi Muhasip muhasebesine aktarır; GET olmasına rağmen write izni gerekir. UUID hedef koruması aynı belgenin ikinci kaydını önler.
  6. GET /apps/invoice/sync Idempotency-Key ile eşitleme başlatır; önce bütün sayfalardan UUID’ler toplanır, her belge tekil aktarımın kullandığı korumadan geçirilir. Alt işlemler operationIds ile izlenir.
Taslak silme (type=invoicecancel) ile düzenlenmiş belge iptali (DELETE /apps/invoice/cancel/{UUID}) farklıdır. Belge iptali, kabul sonrasında Muhasip’teki bağlı muhasebe, ödeme ve stok kayıtlarını günceller. Banka hareketine bağlı veya birden çok faturaya mahsup edilmiş ödeme varsa iptal başlatılmadan 409 döner. Kayıtların güncellenme durumu belirsizse işlem inceleme gerektirir; tekrar iptal etmeyin.

​
Banka: yenileme ve ödeme onayı

Banka liste/detayından firma hesabı ve hareket kimliğini alın. GET /apps/bank/check/{id} verileri yeniler; sorgu devam ediyorsa 409, hizmet başarısızsa 502 döner. Ek query alanı kabul edilmez. Başarı cevabı yalnız mali hareket alanlarını içerir. Hareket onayı contact veya invoice türündedir. Cari türünde mevcut firma carisi seçilebilir veya yeni cari adıyla kayıt oluşturulabilir. Fatura türünde cari, para birimi ve yön fatura/hareket arasında eşleşmelidir. API yalnız açık ve önceden ödeme almamış faturanın tam tutarını mahsup eder; kısmi/önceki ödemeli faturalar 422 ile reddedilir. TRY için kur 1’dir. Döviz hareketinde saklanmış pozitif kur ve faturayla uyum gerekir; kanıtsız kur=1, eksik kur veya kur farkı gerektiren durum API’de işlenmez. IBAN ve varsa vergi bilgisi yalnız çözülen firma carisine yazılır. Onay ödeme kaydı oluşturur; not/durum güncellemesi aynı işlem değildir. Banka fatura otomasyonu tek desteklenen invoice aksiyonu ve TRY hesaplarıyla sınırlıdır. Aktif tanımın hesap, seri/şablon, alıcı adresi ve yüzde100 dağılan satır oranları tamam olmalıdır. GET run write ve Idempotency-Key ister. Bütün satırlar kesin başarılıysa veya işlenecek hareket yoksa başarı kaydedilir. Başarısız satır/belirsizlik 502 review_required olur; log ayrıntısını ve faturaları kontrol etmeden yeniden çalıştırmayın. Tanımdaki saat otomatik çalışma garantisi değildir.

​
POS: başvuru, bağlantı, tahsilat ve iptal

POS hesabının aktif/onaylı olması gerekir. isDefault=true varsayılan, false ek hesapları listeler. Taksit/komisyon seçeneklerini hesaptan okuyun; her POS’ta aynı seçenekleri varsaymayın. POST /apps/pos/link Idempotency-Key ile tahsilat bağlantısı kaydı oluşturur. orderId ve paymentId döner; karttan çekim yapılmaz ve URL dönmez. Tahsilat sonucu işlem detayından okunur. Tahsilat sonucunu işlem listesinden veya ayrıntısından takip edin. Başvuru PUT /apps/pos ile, Idempotency-Key ve altı gerekli yetkili/hesap alanıyla yürür. Sağlayıcının başvuruyu kabulü nihai POS onayı değildir. status=false ile kapatmada başvuru/anahtar gerekmez. Ek hesap silme arşivler; varsayılan hesabı arşivlemek yerine pasifleştirin. Tahsilat iptali yalnız aynı gün onaylanmış başarılı ve henüz iade edilmemiş kayıtta mümkündür. Sağlayıcı iptalinden sonra yerel iade kaydı güncellenir. Onaysız bağlantıyı DELETE ile silmek, gerçekleşmiş tahsilatı iade etmek değildir.

​
e-Arşiv: GİB taslağı, SMS ve imza

e-Arşiv bağlantısı firma GİB hesabıyla kurulur; token dönmez. send taslak oluşturur, imzalamaz; Idempotency-Key zorunludur. Sağlayıcı kesin ETTN sunamazsa inceleme sonucu gelir ve UUID uydurulmaz. query ile gerçek belgeyi doğrulayın. verifyPhoneNumber ayrı anahtarla SMS ister ve oid verir. sign belge ETTN’si, oid ve 4–8 rakamlı kod kullanır; yalnız GİB sonuc=1 kesin başarıdır. Aynı oid farklı kodla tekrar kullanılamaz; kesin yanlış kod reddinde yeni SMS challenge/oid gerekir. HTML/download signed boolean alanını açıkça ister; belge dosya çıktıları bu akışın parçasıdır. İptal öncesi belge hesap ve belge tarihi listesinde doğrulanır. Sağlayıcı iptali ve listeden kalkış kanıtlanmadan yerel e-belge ilişkisi temizlenmez.

​
Belirsiz sonuç ve işlem kilitleri

Aynı firmada devam eden mali işlemler birbiriyle çakışırsa 409 dönebilir. Okuma istekleri kullanılabilir. Sonuç belirsizse yeni mali işlem başlatmadan mevcut işlemi ve ilişkili kayıtları inceleyin. Bağlantı kopması veya zaman aşımı, mali etkinin hiç oluşmadığını kanıtlamaz. İş referansını, hedefleri ve operationId değerini istekten önce/sonra saklayın. İşlem durumunu okuyun; reviewRequired:true veya retryable:false ise otomatik tekrar yapmayın. failed_before_dispatch ve retryable:true dış etki başlamadan kontrollü tekrar olanağıdır.