Fiziksel POS
Ödeme İşlemleri
Fatura, Alıcı ve Mali Belge

Fatura, Alıcı ve Mali Belge

⚠️

Kaynak kod hazır; yayın ve üretici kabulü bekleniyor. Bu sayfa prod'a çıkış duyurusu değildir. Yeni alanlar ancak hedef cihazın uygulama/üretici desteği açıkça doğrulanıp açıldığında kullanılır; aksi durumda tahsilattan önce 422 physical_pos.fiscal_document.unsupported alınır. Özelliği bilinmeyen eski sunucuya düşen çağrı, alanları atarak ödeme başlatmaz.

Ödemeyi başlatan restoran/kafe yazılımı satış uygulaması kimliğini kendi kaydı ve gerçek sürümüyle gönderir. Aşağıdaki mali alanlar bu kimliğin yerine geçmez.

Mevcut fatura tahsilatı

Normal SALE isteğine şu blok eklenir:

{
  "salesData": {
    "invoices": [
      {
        "invoiceNumber": "ABC2026000000001",
        "issuedOn": "2026-11-06",
        "amountMinor": "12500"
      }
    ]
  }
}

Bu, önceden düzenlenmiş faturaya karşı bu ödeme ile tahsil edilen paydır. Yeni fatura kesilmez. En fazla 20 referans; her birinde pozitif kanonik minor tutarı; toplamı ödemenin amountMinor değerine eşit olmalıdır. Para birimi ödeme para birimidir. invoiceUuid isteğe bağlı UUID, issuedOn isteğe bağlı gerçek takvim tarihidir. Numara talep içinde tekrarlanamaz; sonraki kısmi tahsilatlar ayrı ödeme olabilir. Fatura numarası Idempotency-Key yerine geçmez. Faturanın varlığı ve kalan cari bakiyesi bu alanla doğrulanmış sayılmaz.

Yeni belge talebi ve alıcı

{
  "salesData": {
    "fiscal": { "documentType": "E_ARCHIVE" }
  }
}

Yeni belge isteği yalnız kalemli, TRY SALE işleminde ve doğrulanmış yetenekte açılır. Belge türleri E_ARCHIVE, E_INVOICE, INFO_SLIP, OKC_RECEIPT, E_SMM; her cihazın alt kümesi farklıdır. Mevcut fatura listesi ile yeni belge talebi birlikte verilmez. Düzenleyen kaynak yetenekten gelir; belgenin yeni numarası/ETTN'si kullanıcı tarafından başarı sonucu olarak gönderilmez.

Gerekiyorsa salesData.buyer eklenir:

AlanAnlam
partyTypeINDIVIDUAL, BUSINESS, PUBLIC
identityType, identityNumberTCKN (11 rakam), VKN (10 rakam), FOREIGN (3–32 büyük harf/rakam/tire); kimlik/mükellef doğrulaması değildir
givenName, familyNameGerçek kişi veya TCKN için ayrı ayrı zorunlu ad/soyad; serbest unvandan bölünmez
legalNameDiğer alıcılarda zorunlu resmî unvan; kişide isteğe bağlı ticari unvan
taxOffice, emailİsteğe bağlı vergi dairesi ve biçimi doğrulanan e-posta
addressZorunlu countryCode, city, line; isteğe bağlı district, postalCode

E_INVOICE/E_SMM veya yeteneğin alıcı sınırını aşan tutar alıcı bilgisi ister. Limit kodda mevzuat sayısı olarak tahmin edilmez; bilinmeyen limit güvenli biçimde alıcı gerektirir. Adres ülkesi kimlik türünü belirlemez. Satış profili, istisna, kurum/abone/tesisat ve kuyumculuk alanları bu sınırlı sözleşmede açık değildir; bilinmeyen alan veya üreticiye özgü serbest JSON gönderilmez. Alıcı bilgisi şifreli tutulur; komut günlüğüne ve webhook'a açık kopyalanmaz.

Mali sonucu okuma

GET /api/v1/physical-pos/payments/{paymentId}/sales-data için physical_pos:view veya physical_pos:payments gerekir. Yanıttaki salesData eski/verisiz ödemede null'dır; aksi durumda:

  • invoices: gönderilen mevcut fatura tahsilat referansları.
  • buyerProvided: alıcı kaydı var/yok; kimlik/adres yanıtta bulunmaz.
  • fiscalRequested: yeni belge istendi mi.
  • documents[]: belge kimliği, deneme, kaynak/tür, ayrı fiscalStatus, gerekçe, oluşan numara/UUID/tarih/ÖKC referansları, historySeq, rowVersion, actionRequired, outcomeConflict, alarms.

Panelde işlem ayrıntısında aynı kayıt gösterilir. Belge durumları PENDING, ISSUED, FAILED, UNKNOWN, NOT_REQUIRED ve ilgili inceleme/iptal durumlarıdır. Durum bir mali belge durumudur; banka ödeme durumu değildir. Belge kesildi iddiası doğrulanan cihaz sonucu ve yeterli belge kimliği gerektirir; isteğin kabul edilmesi belge kesildi demek değildir.

Hata, tekrar ve ters işlem

  • Aynı idempotency anahtarı + aynı mali blok aynı ödemedir; farklı fatura/alıcı/belge isteği 409 uyuşmazlığıdır.
  • Onaylı ödeme + başarısız veya belirsiz belge mümkündür. Belge sorunu nedeniyle yeni çekim başlatmayın. Otomatik yeniden tahsilat, void veya buluta geçiş yapılmaz.
  • Sonuç bekleme süresi dolunca belge UNKNOWN olabilir; bu, kesilmediği kanıtı değildir. NOT_FOUND da yeniden kesme izni değildir.
  • Çelişen sonuç önceki kesin belgeyi değiştirmez; inceleme bayrağı ve mali webhook üretilir. Alıcı/üretici ham yanıtı webhook'a girmez.
  • Otomatik mali sorgu, yeniden belge kesme ve mali iptal yürütücüsü henüz açık değildir. action_required bildirimi inceleme gereğini gösterir; availableActions: [] olmayan bir butonun var olduğu anlamına gelmez.
  • Aktif/başarılı/belirsiz mali belgeye bağlı ters işlem, mali ters işlem desteği gelene kadar reddedilir. Kesin FAILED/NOT_REQUIRED ve çelişkisiz belgede mevcut finansal ters işlem kuralları korunur. originalPaymentId fatura numarası değildir.

Destek durumu ve açık kapsam

Cihaz içeriği ve sürüm uyumu

Protokol paketi 2.4.0'da kayıtlı kaynak snapshot'ı bulunan yeni mali içerik v2'dir; kaynak olmayan tarihsel v1 içerik aynen korunur. İmzalı START komutu v6, B-19 belgesi v2 olarak kalır. Paket sürümü ile komut ve içerik sürümleri ayrı kavramlardır. Kaynak snapshot'ı mali belgenin kesildiği veya SDK'nın sürümünün doğrulandığı anlamına gelmez.

Eski yalnız-v1 okuyucuya v2 içerik gönderilmez; exact cihaz/app için yeni okuyucu ve üretici kabulü tamamlanmadan salesContextProtocol:6 açılmaz. Bu dağıtım şartıdır, prod'da destek açıldığı duyurusu değildir.

Ortak sorgu ve kurtarma — kaynak teslimi

Android, banka sonucu biliniyorsa yalnız belgeyi sorgulayabilir; banka sorgusu veya yeni tahsilat başlatmaz. Mali kanıt özgün START/documentId ve ilk düzenleme denemesine bağlıdır. SDK portundaki UNKNOWN ağda INDETERMINATE kanıtı, sunucuda UNKNOWN belge durumu olur. NOT_FOUND ve zaman aşımı belge düzenlenmedi kanıtı değildir. Geç belirsiz sonuç kesin sonucu geriletmez; çelişen kesin kanıt inceleme gerektirir.

Sorgu hakkı SDK okunmadan kalıcı kaydedilir: ilk 6 okuma en az 60 sn aralıkla, sonraki okumalar en az 1 saat aralıkla sürer; yeniden başlatma hız sınırını sıfırlamaz. Altı okuma sonunda otomatik kontrol tamamen kesilmez. Belge sorgusu yarıda kesilirse önceden öğrenilmiş banka sonucu korunur. Bu altyapı gerçek SDK'ya henüz bağlanmadı; otomatik mali çözüm/yeniden kesme veya üretim desteği duyurusu değildir.

Cihaz protokol paketi 2.5.0, yalnız cihaz kimliğiyle imzalanan POST /api/device/v1/physical-pos/recovery-state okumasını ekler. Merchant API'si değildir. Taze challenge ve özgün cihaz/ödeme/komut/hash/epoch bağı gerekir; endpoint bulunamazsa veya kimlik doğrulanamazsa kilit açılmaz. K-43 yalnız eski rezervasyonu bırakabilir; banka/belge UNKNOWN kalabilir. Çelişkili kanıt ilgili işlemde inceleme işaretidir; cihaz-geneli kalıcı yasak doğurmaz. İnceleme işaretli kayıtta K-43 bırakma ve otomatik sorgu devam edebilir. Backend/gateway önce yayımlanmalıdır; komut v6, içerik v2 ve B-19 v2 aynı kalır.

Ana yol otomatik kontrol ve eksik sonucun tamamlanmasıdır. Manuel inceleme, sağlayıcıdan kesin kanıt alınamayan kayıtlar için son seçenektir. Tekrarlanan NFC bildirimi veya aynı ödeme sonucunun tekrar teslimi tek ödeme olarak işlenir. Farklı sağlayıcı işlem kimlikleri yalnız tutar/saat benziyor diye birleştirilmez. Yeni imza/kimlik, sandbox ve veri bütünlüğü kontrolleri korunur. Paket 2.5.1 bu istemci davranışını düzeltir; HTTP recovery-state sözleşmesi 2.5.0'dan beri aynıdır.