Pokladny (POS)

Autentizace pokladny

Všechny /api/pos/* endpointy vyžadují hlavičku Authorization: Bearer <token pokladny> – stejný token, jaký zařízení používá pro POST /api/pos/documents (#1016), poznáte ho podle prefixu pos_. Je to jiný jmenný prostor než uživatelský JWT nebo API klíč (ih_…) a funguje výhradně na cestách pod /api/pos – na žádný jiný endpoint API tímhle tokenem nedosáhnete.

Neplatný i deaktivovaný token vrací stejnou hlášku 401 – rozlišení by útočníkovi potvrdilo, že token někdy existoval.

Doklad je navíc vždy scoped na konkrétní zařízení: pokladna vidí a tiskne jen doklady, které sama vystavila (posDeviceId), i kdyby ve stejné firmě byla zařízení další. Cizí doklad – i z jiné pokladny téže firmy – dostane 404, ne 403.

Formát 80mm tiskového výstupu

Odpověď není hotové PDF nebo obrázek k vytištění – je to strukturovaná sada řádků, kterou si klientská aplikace (pokladna, případně budoucí web) sama vyrenderuje na termotiskárně. To je záměr: pokladna musí umět vytisknout doklad i offline, bez spojení s InvoiceHubem, přesně stejně, jako by ho vytiskl server. Popis níž je zdroj pravdy pro tenhle formát – ne jen příklad.

Tisková plocha 80mm pásky je cca 72mm; pro čitelný monospace font počítejte s 42 znaky na řádek. Texty, které by se do 42 znaků nevešly (typicky seznam položek u zjednodušeného dokladu), přicházejí už zalomené na víc řádků – klient text sám nezalamuje.

Odpověď ReceiptOutput

Řádek ReceiptLine

Společná struktura – nezávisle na kind

1. Kopie: je-li copy: true, úplně první i úplně poslední řádek je KOPIE (bold, size: "large", align: "center") – i kdyby obsluha odtrhla horní okraj pásky, kopii nejde vydávat za originál.
2. Hlavička dodavatele (zarovnaná na střed): název (tučně), adresa (ulice, PSČ a město), IČO, a DIČ – DIČ jen je-li vystavitel plátce DPH.
3. Oddělovací čára (rule).
4. Evidenční číslo dokladu a datum vystavení = DUZP, ve formátu d. M. yyyy (např. 3. 9. 2026).
5. Oddělovací čára (rule).
6. Obsah podle kind – viz sekce níž.
7. Zaokrouhlení – je-li na dokladu zapnuté a nenulové, samostatný řádek Zaokrouhlení: {částka}, mimo základ daně.
8. Oddělovací čára (rule).
9. Celková částka k úhradě – jeden řádek, bold a size: "large".
10. Způsob úhrady – jen je-li na dokladu vyplněný (u dokladu na splatnost není). Známé kódy se překládají do češtiny (CASH → Hotově, CARD → Kartou, TRANSFER/BANK_TRANSFER → Převodem); pokladna může poslat i vlastní text – ten se vytiskne přesně tak, jak přišel.
11. Jen u INVOICE (faktura na splatnost, viz níž).
12. Oddělovací čára (rule).
13. Patička: jméno pokladního zařízení, které doklad vystavilo (je-li k dispozici – jinak se řádek vynechá), a poděkování za nákup.
14. Je-li copy: true, poslední řádek znovu KOPIE.

Obsah – zjednodušený doklad (SIMPLIFIED)

Zjednodušený daňový doklad (zákon o DPH) nemá identifikovaného odběratele a neuvádí rozpad základu a daně – jen souhrn sazeb, které se na dokladu vyskytují:

• Předmět plnění – názvy položek, zalomené na řádky do 42 znaků.
• Sazba(y) DPH – jeden řádek se seznamem použitých sazeb, například Sazba DPH: 21 %, 12 % (bez základu a bez výše daně u jednotlivých sazeb).
• Žádný odběratel – blok s odběratelem se u tohoto typu vůbec nevytiskne.

Obsah – zkrácená verze (TAX_DOCUMENT/INVOICE)

Plný daňový doklad uhrazený na místě (TAX_DOCUMENT) a faktura na splatnost (INVOICE) sdílejí stejný „zkrácený“ obsah (isShortVersion: true) – odběratele a rekapitulaci po sazbách místo výpisu jednotlivých položek. Plná faktura se všemi položkami chodí odběrateli e-mailem a je k nahlédnutí v InvoiceHubu – proto výstup na pásce obsahuje poznámku „Plná faktura je součástí e-mailu / k nahlédnutí v InvoiceHubu.“

• Odběratel – jméno, IČO a DIČ (jsou-li vyplněné).
• Rekapitulace po sazbách – jeden řádek na každou sazbu DPH použitou na dokladu: základ daně (suma subtotal položek té sazby), sazba a výše daně (suma vatAmount položek té sazby).

Navíc jen u INVOICE (na rozdíl od TAX_DOCUMENT, který je vždy uhrazený na místě):

• Splatnost – datum, do kdy má být faktura zaplacená.
• Číslo účtu – IBAN vystavitele, případně BBAN, je-li k dispozici.
• Variabilní symbol – u pokladního dokladu je to číslo dokladu.
• Viditelný řádek NEUHRAZENO (tučně) – faktura na splatnost z pokladny se na rozdíl od SIMPLIFIED/TAX_DOCUMENT platí až později, a to musí být na dokladu na první pohled vidět.

Endpointy z pokladny

Všechny vyžadují token pokladny (viz výš).

GET /api/pos/documents/:id/receipt

Náhled tiskového výstupu, bez kopie (copy: false).

GET /api/pos/documents/:id/receipt
Authorization: Bearer pos_…

200 OK
{ "data": { "kind": "SIMPLIFIED", "copy": false, "isShortVersion": false, "documentNumber": "P01-2026-0001", "lines": [ … ] } }

404 – doklad neexistuje, nebo patří jinému zařízení.

POST /api/pos/documents/:id/reprint

Stejný obsah jako GET .../receipt, ale s copy: true – řádek KOPIE na začátku i na konci. Na rozdíl od reprintu z InvoiceHub administrace (viz níž) se tenhle pokus nezapisuje do auditní stopy dokladu – pokladna žádného přihlášeného uživatele nemá, ke kterému by se zápis vázal.

POST /api/pos/documents/:id/reprint
Authorization: Bearer pos_…

200 OK
{ "data": { "kind": "SIMPLIFIED", "copy": true, "isShortVersion": false, "documentNumber": "P01-2026-0001", "lines": [ … ] } }

404 – doklad neexistuje, nebo patří jinému zařízení.

POST /api/pos/documents/:id/email

Odešle doklad e-mailem přímo z pokladny (obsluha zadá adresu na místě, bez přihlášeného uživatele InvoiceHubu) – jde stejnou cestou jako obecné odeslání dokladu z InvoiceHubu: plné PDF v příloze, zápis do historie odesílání i do auditu.

POST /api/pos/documents/:id/email
Authorization: Bearer pos_…
Content-Type: application/json

{ "to": "zakaznik@example.com" }

200 OK
{ "ok": true }

• to – povinná, platná e-mailová adresa. Chybí-li nebo není platná, vrací se 400.

404 – doklad neexistuje, nebo patří jinému zařízení. 503 – odeslání selhalo (SMTP/Resend); důvod je v error odpovědi, stejně jako u obecného e-mailového endpointu.

Reprint z InvoiceHub administrace

Nad dokladem, který vznikl na pokladně (nebo i bez ní – u dokladu bez posDocumentKind se typ výstupu odvodí z toho, jestli má odběratele, splatnost a jaký má stav), jde tiskový výstup vyvolat i z InvoiceHubu jako přihlášený uživatel:

Autentizace je běžný uživatelský JWT (Authorization: Bearer <token> + X-Organization-Id), doklad musí patřit do stejné firmy a rozsahu oddělení jako u ostatních operací nad /documents/:id – jinak 404. Reprint navíc zapisuje do auditní stopy dokladu akci RECEIPT_REPRINTED, ať je v historii dokladu vidět, kdo a kdy ho znovu vytiskl.