Dokumentet e kuponit

Kuponi PDF ORIGINAL që lëshohet me çdo komandë, lëshimi i një COPY të shënuar, dhe shkarkimi i bajtave.

Një komandë e suksesshme prodhon një kupon — të dhënat fiskale. Kuponi i rendëruar që i jepet klientit është një dokument kuponi. ORIGINAL-i i tij lëshohet nga vetë komanda që e krijoi; ti nuk e kërkon kurrë.

komandë e suksesshme  ->  coupon (të dhëna)  ->  receipt document (ORIGINAL PDF)

Kur është gati

Lëshimi i një shitjeje, kthimi ose anulimi e kthen ORIGINAL-in bashkë me komandën, si receipt_document. Një komandë e refuzuar ka receipt_document: null — nuk ka kupon për të rendëruar.

Fusha receipt_ready e komandës tregon nëse kuponi dhe rrugët e tij janë të disponueshme.

Objekti coupon i komandës mban të dhënat fiskale:

Fusha	Përshkrimi
`coupon_id`	Identifikuesi i kuponit
`daily_receipt_no`	Numri rendor ditor
`reference_no`	Numri i referencës
`verification_no`	Numri i verifikimit
`qr_payload`	Përmbajtja nga e cila vizatohet kodi QR
`transaction_no`	Numri i transaksionit te ATK
`transmitted_at`	Koha e transmetimit

transaction_no është string, jo numër

Numri i ATK-së mbulon gjithë intervalin 64-bit të panënshkruar. Si numër JSON shifrat e fundit humbasin në çdo klient JavaScript, dhe ky është evidencë transmetimi. Trajtoje gjithmonë si string.

Lëshimi i një kopjeje

POST /v1/commands/{command_id}/receipt-documents regjistron një COPY të re, të shënuar dukshëm. Nuk merr asnjë trup — gjuha jepet si parametër query.

copy.sh

curl -X POST "$BASE_URL/v1/commands/$COMMAND_ID/receipt-documents?locale=sq" \
  -H "Authorization: Bearer $FISKALIZA_API_KEY" \
  -H "Idempotency-Key: receipt-$COMMAND_ID-sq"

Gjuhët e mbështetura janë sq, sr-Latn dhe en; parazgjedhja është sq.

ORIGINAL kundrejt COPY

ORIGINAL-i lëshohet automatikisht nga shitja, kthimi ose anulimi dhe nuk mund të krijohet këtu.
Çdo dokument që lëshon kjo rrugë është COPY.
Ripërsëritja e të njëjtit çelës idempotence dhe e së njëjtës gjuhë kthen të njëjtën kopje. Ndryshimi i gjuhës nën atë çelës jep idempotency_conflict.

Nëse i duhet klientit edhe një kopje, dërgo një çelës të ri idempotence. Nëse thjesht po ritenton pas një dështimi rrjeti, ripërdor të njëjtin.

Përgjigja:

{
  "success": true,
  "data": {
    "receipt_document": {
      "id": "…",
      "command_id": "command_123",
      "locale": "sq",
      "kind": "COPY",
      "pdf_url": "/v1/receipt-documents/{id}/pdf",
      "pdf_sha256": "…",
      "issued_at": "2026-08-26T10:00:09Z"
    }
  }
}

Shkarkimi i bajtave

pdf_url tregon gjithmonë te GET /v1/receipt-documents/{document_id}/pdf. PDF-ja është i vetmi rendërim publik — HTML-ja dhe të dhënat e papërpunuara të kuponit qëllimisht nuk ekspozohen.

curl "$BASE_URL/v1/receipt-documents/$DOCUMENT_ID/pdf" \
  -H "Authorization: Bearer $FISKALIZA_API_KEY" \
  -o kupon.pdf

Këto janë bajtat, pdf_sha256-in e të cilëve e regjistroi përgjigja e lëshimit.

Këto URL kërkojnë çelësin tënd

Rruga e shkarkimit autentikohet me çelësin API. Mos ia dërgo URL-në drejtpërdrejt klientit — kjo do të thoshte t'i jepje çelësin. Shkarko bajtat në backend dhe dorëzoji përmes kanalit tënd.

Verifiko pdf_sha256 pas shkarkimit nëse ruan kopje afatgjata: kështu provon që bajtat nuk kanë ndryshuar.

Listimi i lëshimeve

GET /v1/commands/{command_id}/receipt-documents kthen vetëm metadata. Asnjë dokument nuk rendërohet dhe asnjë nuk lëshohet, dhe nuk kërkohet Idempotency-Key.

Renditja: issued_at zbritës, pastaj ID zbritëse.
Përfshihen origjinalet dhe kopjet e dukshme për biznesin dhe aksesin POS të çelësit.
locale filtron si rezultatet ashtu edhe total-in.
limit ka parazgjedhje 50; vlerat mbi 100 kufizohen në 100.
Një komandë e autorizuar pa lëshime kthen listë bosh.
Offset-et përtej rezultatit të fundit kthejnë listë bosh me total-in përkatës.

curl "$BASE_URL/v1/commands/$COMMAND_ID/receipt-documents?locale=sq&limit=20" \
  -H "Authorization: Bearer $FISKALIZA_API_KEY"

Aftësia e kërkuar

Lëshimi i një kopjeje dhe listimi i lëshimeve kërkojnë fiskaliza:receipts:issue. Shkarkimi i PDF-së pranon ose atë, ose fiskaliza:commands:write, që shërbimi i cili lëshoi shitjen të marrë kuponin e vet. Pa një aftësi të mjaftueshme, përgjigja është 403 insufficient_capability.