Mali Fişleme — fiscal.de ✓ Canlı

POST {RESTOMENUM_BASE}/plugin-api/capabilities/fiscal.de/invoke
Authorization: Bearer <apiKey>
Content-Type: application/json

// tutar alanı YOK — platform türetir
{
  "payload": {
    "sale": { "type": "packet", "id": "pkt_123" },   // ZORUNLU — imzalanacak satış
    "receiptType": "RECEIPT",                         // ops., varsayılan RECEIPT
    "registerId": "kiosk-1",                          // ops., ≤64, OPAK kasa/terminal kimliği
    "idempotencyKey": "close-pkt_123-37"              // ZORUNLU, satış başına SABİT
  }
}

import { RestomenumClient } from '@restomenum/plugin-sdk';

// Tüketici (scope: capability:fiscal.de:consume) — tutarlar CENT (integer):
const r = await client.capabilities.invoke('fiscal.de', {
  sale: { type: 'packet', id: packetId },        // ZORUNLU — hangi satış
  idempotencyKey: `close-${packetId}-${docNo}`,  // ZORUNLU, satış başına SABİT
});
// TUTAR GÖNDERMEZSİN: KDV + ödeme kırılımını platform satış kaydından türetir.

// Mali blok YANITTA gelir → fişi kendi basan eklenti (kiosk) kapanış gate'ini beklemez.
if (r.status === 'signed')  printReceipt(r.receiptExtras);   // tse.qr BYTE-KESİN basılır
if (r.status === 'ausfall') printReceipt(r.receiptExtras);   // HATA DEĞİL — tek öğe: tse.ausfall

{ "success": true, "data": {
    "requestId": "req_9f1c…",
    "status": "signed",                     // accepted | signed | ausfall | failed
    "providerMessageId": "412",             // = Beleg-Nr
    "receiptExtras": [                      // MALİ BLOK — fişe olduğu gibi basılır
      { "key": "tse.qr",       "type": "qr", "value": "V0;…", "verified": true },
      { "key": "tse.txNumber", "value": "412", "label": "Beleg-Nr", "verified": true }
    ]
} }

// Aynı idempotencyKey ile 2. çağrı: sağlayıcıya YENİ istek GİTMEZ, saklanan yanıt döner
{ "success": true, "data": { "requestId": "req_9f1c…", "status": "signed",
    "providerMessageId": "412", "idempotentReplay": true, "receiptExtras": [ … ] } }

POST <sağlayıcının actionUrl / webhookUrl'i>
x-restomenum-signature:   t=…,v1=…
x-restomenum-event:       capability
x-restomenum-capability:  fiscal.de
x-restomenum-request:     req_9f1c…
x-restomenum-environment: production

{
  "type": "capability", "capability": "fiscal.de", "v": 1,
  "environment": "production",              // | sandbox
  "tenantId": "<serverId>", "requestId": "req_9f1c…",
  "consumer": { "pluginId": "hellokiosk" },
  "occurredAt": 1786000000000,
  "payload": {
    "receiptType": "RECEIPT",
    "sale": { "type": "packet", "id": "pkt_123" },
    "amountsPerVatRate":     [ { "vatRate": 19, "amount": 1990 },        // ← platform türetti
                               { "vatRate": 7,  "amount": 700 } ],
    "amountsPerPaymentType": [ { "paymentType": "CASH",     "amount": 1690 },
                               { "paymentType": "NON_CASH", "amount": 1000 } ],
    "lines": [ { "id": "ln_1", "title": "Pizza", "quantity": 1, /* … orders[] ile AYNI şekil */ } ],
                                            // ⏳ satır listesi — YA TAM YA HİÇ (>200 satır → konmaz)
    "sequence": 14,                         // ⏳ satışın kaçıncı durum değişikliği (opsiyonel)
    "sequenceScope": "sq_5776130612ab"      // ⏳ opak satış hattı — karşılaştırma AYNI scope içinde
  }
}

import { verifyAndParseCapability, fiscalResponse, fiscalSaleKey, receiptExtra } from '@restomenum/plugin-sdk';
import type { FiscalDePayload } from '@restomenum/plugin-sdk';

// 1) İMZA + şekil doğrula (webhook ile AYNI HMAC şeması). null → 401.
const req = await verifyAndParseCapability<FiscalDePayload>(rawBody, sigHeader, {
  getSecret: (tenantId, environment) => installStore.find(tenantId, environment)?.webhookSecret,
});
if (!req) return res.status(401).json({ error: 'invalid_signature' });

// 2) requestId DEDUPE (ZORUNLU): aynı fişi İKİ KEZ imzalamak TSE'de mükerrer işlem = mali/yasal sorun.
const prior = await store.find(req.requestId);
if (prior) return res.json(fiscalResponse(prior.status, {
  providerMessageId: prior.providerMessageId, receiptExtras: prior.receiptExtras,   // BLOĞU DA sakla
}));

// 3) SATIŞ ANAHTARI (tekleme): tipli referanstan kur — `packet:pkt_123`. Elle string birleştirme
//    YOK (tip öneki atlanırsa adı "5" olan masa ile id'si "5" olan paket aynı Vorgang sanılır).
//    requestId dedupe'u YETMEZ: POS kapanışı aynı satışı FARKLI requestId ile imzalatmaya gelir.
// ⚠️ type:'table' geldiğinde ANAHTAR YETMEZ: tableId kalıcıdır (masa kapanıp aynı id ile yeniden açılır)
//    → anahtara oturum ayracı ekle (`${fiscalSaleKey(sale)}:${isGunu}`), yoksa dünkü Beleg replay olur.
const saleKey = fiscalSaleKey(req.payload.sale);
const priorSale = await store.findBySale(saleKey);
if (priorSale) return res.json(fiscalResponse(priorSale.status, {   // Rechnungsdoppel — yeni Vorgang YOK
  providerMessageId: priorSale.providerMessageId, receiptExtras: priorSale.receiptExtras,
}));

// 4) Denge SAVUNMA KATMANI: platform Σ KDV == Σ tahsilat olmasını GARANTİ eder (dengesizse imza
//    atılmadan 400 plugin.fiscal.amountsInvalid döner) — yine de kendi kapını tut.
const sum = (rows) => rows.reduce((t, r) => t + r.amount, 0);
if (sum(req.payload.amountsPerVatRate) !== sum(req.payload.amountsPerPaymentType))
  return res.json(fiscalResponse('failed', { error: { code: 'unbalanced_receipt' } }));  // blok TAŞIMA

// 5) TSE'ye ulaşılamıyorsa 'ausfall' — 'failed' DÖNME (işlem geçerli, fişe "Ausfall" basılır).
if (!(await tseReachable()))
  return res.json(fiscalResponse('ausfall', {
    receiptExtras: [receiptExtra('tse.ausfall', 'TSE-Ausfall: Beleg ohne TSE-Signatur')],
  }));

// 6) İmzala ve MALİ BLOĞU YANITTA DÖN. providerMessageId = Beleg-Nr.
const { belegNr, qr, sigCounter } = await signAtTse(req.payload);   // CENT tutarlar; negatif olabilir
const receiptExtras = [
  receiptExtra('tse.qr', qr, { type: 'qr' }),                  // BYTE-KESİN: kırpma/escape YOK
  receiptExtra('tse.txNumber', String(belegNr), { label: 'Beleg-Nr' }),
  receiptExtra('tse.signatureCounter', String(sigCounter), { label: 'Sig-Zähler' }),
];
await store.save(req.requestId, { status: 'signed', providerMessageId: String(belegNr), receiptExtras });
await store.saveBySale(saleKey, { status: 'signed', providerMessageId: String(belegNr), receiptExtras });
res.json(fiscalResponse('signed', { providerMessageId: String(belegNr), receiptExtras }));

{ "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" }
  ] }

// Sepet (tüketici gönderir)
[ { "product": "POS-11", "quantity": 1, "taxRate": 19 },   // 10.00 ₺
  { "product": "POS-12", "quantity": 1, "taxRate": 7  } ]  //  5.00 ₺

// Sağlayıcıya giden kırılım (platform türetir)
"amountsPerVatRate": [
  { "vatRate": 19, "amount": 1000 },
  { "vatRate": 7,  "amount": 500  }
]  // kuruş-integer