Fişe Ek Alanlar — receiptExtras ⏳ Yakında

Sözleşme

Gate isteği değişmedi (bkz. Action Hook referansı). Yanıta yalnız receiptExtras eklendi:

{
  "decision": "allow",
  "receiptExtras": [
    { "key": "tse.qr",               "type": "qr",   "value": "V0;…" },
    { "key": "tse.txNumber",         "type": "text", "label": "Beleg-Nr",   "value": "366" },
    { "key": "tse.signatureCounter", "type": "text", "label": "Sig-Zähler", "value": "774" },
    { "key": "tse.timeStart",        "type": "text", "label": "TSE-Start",  "value": "1785438065" },
    { "key": "tse.status",           "type": "text", "value": "signed" }
  ]
}

{ "data": { … } } sarmalı da kabul edilir (mevcut hook davranışı).

Öğe şeması

type değerleri:

• text — Metin — fişe düz satır olarak basılır (label varsa başına eklenir)
• qr — QR — fişe QR kodu olarak basılır (ör. TSE doğrulama verisi)

Katman 1 — belgeye yazılan tek anahtar

Gate yanıtındaki diğer alanlar (decision, message, level, display) protokol alanlarıdır: akışı yönetir ve kasiyere bildirim gösterir. Adisyon dokümanına yazılan tek alan receiptExtras'tır.

Adisyon tutarını/kalemlerini gerçekten değiştirmeniz gerekiyorsa tables/update-orders · packets/update-orders ve update-payments uçlarını kullanın — onlar recompute + paid ≤ total doğrulamasından geçer.

Katman 2 — key namespace sahipliği (GÜVENLİK)

Bazı namespace'ler sahiplenilmiştir; onları yalnız o alanın yetkilisi yazabilir:

verified işareti

Sahiplenilmiş namespace'te ve yetki doğrulandıysa platform öğeye verified: true ekler:

{ "key":"tse.txNumber", "type":"text", "label":"Beleg-Nr", "value":"366", "verified":true }

• Sahiplenilmemiş/bilinmeyen key'ler bu işareti asla almaz — onlara mali anlam yüklenemez.
• Fiş şablonu mali bloğu yalnız verified öğelere basar.
• Eklenti verified'ı kendisi gönderemez; platform üretir (gönderilirse yok sayılır).

Yazım kuralları

• Yalnız allow'da yazılır. deny dönerseniz hiçbir şey yazılmaz — ödeme eşlenemediği için deny döndüyseniz fiş de kesilmemiştir, o key'lerin belgeye girmemesi gerekir. pending'de karar henüz yoktur.
• Değiştirilemezlik: bir key bir kez yazıldıysa üzerine yazılmaz. Aynı key'i tekrar göndermek sessizce yok sayılır (platformda frozen olarak loglanır). Düzeltme gerekiyorsa fiscal doğru yol iptal/düzeltme belgesidir — yeni bir key ile gönderin.
• Doküman yoksa yazılmaz: adisyon o arada kapanmış/silinmişse yazım atlanır, gate kararınız etkilenmez.
• Fail-safe: yazım hatası gate kararını bozmaz. allow dediyseniz kapanış devam eder.

Aynı adisyona birden fazla eklenti yazarsa

Kapanış gate'i tenant-genel fan-out yapar (packet.close tüm kayıtlı eklentilere paralel sorulur), bu yüzden eşzamanlı yazım normaldir:

Yani başka bir eklentinin varlığı sizin öğelerinizi ezmez; siz de onunkini ezemezsiniz. 10 eşzamanlı yazımda kayıp gözlenmedi.

Sınırlar

Geliştiricinin bilmesi gerekenler

1. Geri okuma ucu yok. receiptExtras şu an tables/get / packets/get yanıtlarında dönmez. Yazdığınız belge verisini kendi tarafınızda saklayın. Yeniden basım/denetim sorgusu bu mekanizmanın dışındadır: POS bilgisiyle (kasa, belge no, iş günü) sizden çekilir — platform tarafında ek izin gerekmez.
2. Yalnız kapanış gate'lerinde anlamlıdır (table.close, packet.close). Kapanış olmayan bir hook'ta gönderirseniz fişle ilişkilendirilecek bir belge yoktur.
3. Fişe basma frontend'in işidir. Platform veriyi güvenli saklar; şablon tse.qr varsa QR basar, tse.status uyarı durumundaysa uyarı gösterir. Öğe sırası fişteki sırayı garanti etmez — label göndererek anlamı öğenin kendisinde taşıyın.
4. Timeout bütçesi gate isteğindeki timeoutMs'tir (manifest'ten; table.close varsayılanı 10 sn, paket gate'lerinde 5 sn). Mali belge kesimi bu süreye sığmıyorsa failMode politikanızı gözden geçirin; süre aşımında yanıtınız değerlendirilmez.
5. Kapatma yetkisi yok — allow dönmek kapanışa izin vermektir, kapanışı sizin yapmanız değil.

Örnek — TSE mali bloğu

// Gate isteği (platform → eklenti)
{ "type":"hook", "event":"table.close", "target":{ "type":"table", "id":"masa-5" }, "timeoutMs":5000 }

// Yanıt (eklenti → platform) — belge kesildi, fişe basılacak alanlar döndü
{ "decision":"allow",
  "receiptExtras":[
    { "key":"tse.qr",               "type":"qr",   "value":"V0;KassenSN;Kassenbeleg-V1;…" },
    { "key":"tse.txNumber",         "type":"text", "label":"Beleg-Nr",   "value":"366" },
    { "key":"tse.signatureCounter", "type":"text", "label":"Sig-Zähler", "value":"774" },
    { "key":"tse.timeStart",        "type":"text", "label":"TSE-Start",  "value":"1785438065" },
    { "key":"tse.status",           "type":"text", "value":"signed" }
  ] }

// Ödeme eşlenemedi → belge KESİLMEDİ → hiçbir key yazılmamalı
{ "decision":"deny", "message":"Ödeme TSE ile eşlenemedi" }