EET API pro vývojáře
Odesílejte tržby do EET 2.0 z rezervačního systému, hotelového PMS nebo fakturace přes REST API. Podpis, certifikát, komunikaci s Finanční správou, frontu a opakované odeslání při výpadku řešíme my – na stejné evidenci, jakou používá naše pokladna. Tržba odchází s EIČ, evidenční jednotkou a certifikátem podnikatele; jsme technický zprostředkovatel, ne pověřený poplatník.
Začínáme (5 kroků)
- Podnikatel (váš zákazník) si založí účet EvidujZdarma, přidá evidenční jednotky s číslem z DIS+ a nahraje pokladní certifikát – nejdřív testovací pro Playground.
- Ve svém účtu otevře stránku Integrace (
/pokladna/integrace) → Nová integrace, zvolí prostředí, jednotky a oprávnění a token vám předá. Token se zobrazí jen jednou. - Ověřte token:
GET /v1/accountaGET /v1/units(jednotky, u kterých jeready: true). - Na každou platbu přijatou na místě pošlete
POST /v1/saless vaším uuid platby jakoid. V odpovědi je stav, POK a data na doklad. - Stav dohledejte
GET /v1/sales?ids=…neboGET /v1/sales/{id}; vratku pošlete na/v1/sales/{id}/refund.
Specifikace OpenAPI 3.1: /api/v1/openapi.json (otevře se v novém okně). Částky jsou v haléřích (celá čísla), čas ISO 8601 s posunem, např. 2027-01-02T08:10:00+01:00.
Autentizace
Každý požadavek nese hlavičku Authorization: Bearer ezk_…. Token ezk_test_… odesílá do Playgroundu Finanční správy, token ezk_live_… do ostrého provozu. Prostředí určuje token, ne tělo požadavku. Token pokladny na API nefunguje a token API nefunguje v pokladně.
Oprávnění tokenu volí vlastník účtu:
sales:write– odesílat tržby;sales:read– číst jejich stav;refunds:write– vracet tržby bez PINu vlastníka;units:read,closings:read,webhooks:manage.
Token vidí jen jednotky, které mu vlastník přidělil, a jen tržby, které sám poslal. Cizí jednotka nebo tržba vrací 404. Když vlastník integraci odpojí, další požadavek dostane 401 token_revoked; tržby, které už API přijalo, se do EET odešlou.
Připojení jedním klikem (OAuth)
Místo kopírování tokenu může váš systém použít OAuth 2.0 (authorization code + PKCE S256). Aplikaci partnera s adresami pro návrat (redirect_uri) u nás zaregistrujeme a dostanete client_id a client_secret.
- Přesměrujte vlastníka na
https://evidujzdarma.cz/pripojit?client_id=…&redirect_uri=…&state=…&code_challenge=…&code_challenge_method=S256&scope=sales:write sales:read&environment=test. - Vlastník se přihlásí, vybere účet a jednotky a klikne „Povolit“. Vrátíme ho na redirect_uri s parametry code a state (při „Zrušit“ error=access_denied).
- Kód (platí 10 minut, jednou) vyměňte na serveru:
POST /api/v1/oauth/tokens grant_type=authorization_code, code, redirect_uri, client_id, client_secret a code_verifier. Odpověď: access_token (token integrace bez expirace), scope, unit_ids, environment, integration_id.
redirect_uri musí přesně odpovídat registraci, jinak připojení zastavíme bez přesměrování. Opakované použití kódu vrátí invalid_grant a token vydaný tímto kódem odvoláme.
Tržby
POST /v1/sales přijme 1–100 tržeb. id je klíč idempotence: stejné id se stejným tělem vrátí stejný výsledek a do FS nejde dvakrát; jiné tělo vrátí 409 idempotency_conflict. Pořadové číslo (sequence) můžete poslat vlastní (nejvýš 25 znaků), jinak ho přidělí server.
Nové tržby odešleme do FS hned, nejvýš 2.5 s na celý požadavek. Co se do té doby nestihne, má stav queued nebo sending a odešle se z fronty – výsledek zjistíte dotazem na stav. Bez POK vytiskněte na doklad poznámku z receipt.note: „Tržba bude odeslána nejpozději do 48 hodin.“
Druh položky kind: goods (výchozí) nebo credit_topup – dobití kreditu či hotelové karty k pozdějšímu čerpání. Záloha na ubytování je běžná tržba (goods). Platba převodem (transfer) se neeviduje: tržba jen z převodu má stav not_evidenced a do FS nejde.
curl -X POST https://evidujzdarma.cz/api/v1/sales \
-H "Authorization: Bearer $EZ_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "sales": [{ "id": "6f1c2a9e-8b1d-4c33-9f0e-2a7b5d4c1e01", "externalRef": "ALI-2026-000123", "unitId": "<id jednotky z GET /v1/units>", "soldAt": "2027-01-02T08:10:00+01:00", "lines": [{ "name": "Ubytování 2 noci", "qty": 1, "unitPrice": 320000, "vatRate": 12 }], "payments": [{ "method": "card", "amount": 320000 }] }] }'const res = await fetch("https://evidujzdarma.cz/api/v1/sales", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.EZ_TOKEN}`, "Content-Type": "application/json" },
body: JSON.stringify({ sales: [sale] }),
});
const { results } = await res.json();
// results[0].status: confirmed | queued | sending | rejected | quarantined | not_evidenced
// results[0].pok a results[0].receipt vytiskněte na svůj doklad$ch = curl_init("https://evidujzdarma.cz/api/v1/sales");
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("EZ_TOKEN"), "Content-Type: application/json"],
CURLOPT_POSTFIELDS => json_encode(["sales" => [$sale]]),
CURLOPT_TIMEOUT => 10,
]);
$results = json_decode(curl_exec($ch), true)["results"];Vratky
POST /v1/sales/{id}/refund vytvoří zápornou tržbu na jednotce původní tržby. Bez lines vrátí vše, co z tržby zbývá; s lines jen uvedené položky (musí být v původní tržbě). Platby vratky odpovídají platbám původní tržby. Dohromady nelze vrátit víc, než se prodalo – 422 refund_exceeds_original. Vratku lze poslat i k tržbě, která ještě čeká na POK; obě se odešlou z fronty.
# celá vratka
curl -X POST https://evidujzdarma.cz/api/v1/sales/<id původní tržby>/refund \
-H "Authorization: Bearer $EZ_TOKEN" -H "Content-Type: application/json" \
-d '{ "id": "<nové uuid vratky>", "externalRef": "ALI-STORNO-17" }'
# částečná vratka – jen položky z původní tržby, kladné množství
-d '{ "id": "<nové uuid>", "lines": [{ "name": "Minibar", "qty": 1, "unitPrice": 5000, "vatRate": 21 }] }'Webhooky
Endpoint zaregistrujete přes POST /v1/webhooks (oprávnění webhooks:manage) – adresa jen https, ne privátní ani interní (ověřujeme po DNS a přesměrování nesledujeme). Tajemství pro podpis dostanete jen v odpovědi na registraci. Události:
sale.confirmed– přišel POK;sale.rejected– FS tržbu definitivně odmítla nebo skončila v karanténě vlastníka;sale.deadline_soon– tržba stále nemá POK a do lhůty 48 hodin zbývá nejvýš 24 hodin (jednou na tržbu);certificate.expiring(31, 14 a 3 dny před koncem platnosti),certificate.expired;integration.revoked– vlastník integraci odpojil;webhook.testzPOST /v1/webhooks/{id}/test.
Tělo: { "id", "type", "createdAt", "data" }, u tržeb je data stejný objekt jako v odpovědi API. Pořadí událostí nezaručujeme a jednu událost můžete dostat víckrát – deduplikujte podle id. Odpovězte 2xx do 5 sekund; jinak zkusíme znovu po 1 min, 5 min, 30 min, 2 h, 6 h a 24 h. Když endpoint nefunguje 3 dny v kuse, vypneme ho a napíšeme vlastníkovi účtu; tržby se evidují dál.
Každý požadavek nese hlavičku EZ-Signature: t=<unix čas>,v1=<hex HMAC-SHA256(tajemství, t + "." + tělo)>. Počítejte z nezměněného těla a odmítněte podpis starší než 5 minut:
import { createHmac, timingSafeEqual } from "node:crypto";
export function verifyWebhookSignature(rawBody, header, secret, toleranceSeconds = 300) {
const t = /(?:^|,)t=(\d+)/.exec(header)?.[1];
const v1 = /(?:^|,)v1=([0-9a-f]{64})/.exec(header)?.[1];
if (!t || !v1) return false;
if (Math.abs(Date.now() / 1000 - Number(t)) > toleranceSeconds) return false;
const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest();
const given = Buffer.from(v1, "hex");
return given.length === expected.length && timingSafeEqual(given, expected);
}function ez_verify(string $rawBody, string $header, string $secret): bool {
if (!preg_match('/t=(\d+)/', $header, $t) || !preg_match('/v1=([0-9a-f]{64})/', $header, $v)) return false;
if (abs(time() - (int) $t[1]) > 300) return false;
$expected = hash_hmac('sha256', $t[1] . '.' . $rawBody, $secret);
return hash_equals($expected, $v[1]);
}Chyby
Chyba celého požadavku má tvar { "error": { "code", "message", "field", "requestId" } }; message je anglicky. Chyba jedné tržby je v results[].error a požadavek sám je 200. Kódy se bez nové verze API nemění.
| HTTP | code | Kdy |
|---|---|---|
| 400 | invalid_request | Invalid JSON, batch size or a field (see `field`). |
| 401 | invalid_token | Missing or unknown token, or a token that is not an integration token. |
| 401 | token_revoked | The integration was disconnected by the owner. |
| 403 | insufficient_scope | The token lacks the scope this route needs. |
| 403 | account_closed | The account is closed: new sales are refused, reading works for 30 days. |
| 403 | environment_not_ready | A live token while the account is not in production mode. |
| 404 | unit_not_found | The unit does not exist, belongs to another account or is outside the token's units. |
| 404 | sale_not_found | The sale does not exist or was not created by this integration. |
| 404 | original_not_found | Refund: the original sale does not exist or was not created by this integration. |
| 404 | webhook_not_found | The webhook does not exist or belongs to another integration. |
| 409 | idempotency_conflict | A sale with this id exists with a different body. |
| 409 | external_ref_conflict | The externalRef is already used by another sale of this integration. |
| 413 | payload_too_large | The body is larger than 1 MB. |
| 422 | refund_exceeds_original | Refund: more than is left of the original (quantity, amount, evidenced amount or credit). |
| 422 | original_is_refund | Refund: the original is itself a refund. |
| 429 | rate_limited | More than 120 requests per minute per token; see Retry-After. |
| 500 | internal_error | Unexpected server error; retry with the same ids – the API is idempotent. |
| 422 | sale_in_future | results[].error: soldAt is more than 10 minutes in the future. |
| 422 | sale_too_old | results[].error: soldAt is older than 45 days. |
| 422 | amount_out_of_range | results[].error: an amount exceeds the EET limit 99 999 999.99 CZK. |
| 422 | unit_not_ready | results[].error: the unit has no FS unit number (id_provozovny) yet. |
| 422 | certificate_missing | results[].error: no valid certificate for the environment; the sale waits in the queue. |
| 422 | certificate_expired | results[].error: the certificate expired; the sale waits in the queue. |
| 422 | sequence_conflict | results[].error: the client-supplied sequence is already used by another sale. |
| 422 | sale_blocked | results[].error: the sale waits for the owner (account data); it is kept and sent once fixed. |
| 422 | fs_rejected | results[].error: FS rejected the sale (see fsCode). |
| 503 | fs_unavailable | results[].error with retryable: true; FS did not answer, the queue retries – the request itself is 200. |
Limity
- 120 požadavků za minutu na token; nad limit
429 rate_limiteds hlavičkouRetry-After(sekundy) a hlavičkamiRateLimit-Limit,RateLimit-Remaining,RateLimit-Reset. - 100 tržeb v jednom požadavku, tělo nejvýš 1 MB (
413). - Každá odpověď má hlavičku
X-Request-Id– uveďte ji, když nám píšete o problému.
Playground
Playground je testovací prostředí Finanční správy (oznámení FS (otevře se v novém okně), eet.gov.cz pro vývojáře (otevře se v novém okně)). Tržby z něj se nikam nezapočítávají. První POK:
- V účtu EvidujZdarma nahrajte testovací certifikát pro Playground (Nastavení pokladny → Certifikát → Testovací certifikát (Playground)).
- Jednotka musí mít číslo evidenční jednotky.
- Vytvořte integraci s prostředím Testovací (Playground) a tokenem
ezk_test_…pošlete tržbu podle příkladu výše. - Potvrzená tržba má
status: "confirmed"a POK z Playgroundu, který končí na „ff“ – podle toho poznáte testovací odpověď. Ostrý POK takto nekončí. - Pošlete stejnou tržbu znovu: dostanete stejný výsledek. Pak zkuste vratku.
Co se eviduje
Evidují se platby přijaté při osobním kontaktu nebo v provozovně: hotovost, platební karta, QR kód, poukázka, šek i virtuální aktiva. Neevidují se vzdálené platby – platební brána e-shopu, QR kód na webu, bankovní převod na základě faktury. Záloha i doplatek zaplacené při osobním kontaktu se evidují jako dvě samostatné běžné platby. Dobití kreditu (např. čipu nebo předplacené karty) a jeho pozdější čerpání se evidují obě – datová zpráva pak obsahuje i částku určenou k následnému čerpání, resp. částku čerpání. Jinak je to u dárkového poukazu na konkrétní zboží nebo službu: eviduje se jen jeho prodej, samotné uplatnění poukazu není platbou a neeviduje se. Platba stravenkou nebo poukázkou vydanou jinou firmou je běžná evidovaná platba. Podrobně v návodech: Co je kontaktní platba, EET v ubytování, Storno a vrácení peněz, Spropitné. Rozhodnutí, co evidovat, zůstává na podnikateli – API odešle to, co pošlete.
Hotel a PMS
Které platby z hotelového PMS poslat do API – podle návodu EET u ubytování. Co evidovat, rozhoduje podnikatel; API odešle to, co PMS pošle.
| Událost v PMS | Volat API? | Jak |
|---|---|---|
| Záloha převodem / platební bránou / přes Booking, Airbnb online | Ne | Vzdálená platba – neeviduje se. |
| Záloha zaplacená na recepci (hotovost, karta, QR) | Ano | Běžná tržba, kind: goods, řádek např. „Záloha – rezervace …“. |
| Doplatek na recepci | Ano | Samostatná tržba; záloha a doplatek se v datové zprávě nepropojují. |
| Doplatek převodem na fakturu | Ne | Neeviduje se. Chce-li PMS mít vše na jednom místě, může poslat transfer – tržba bude not_evidenced a do FS nepůjde. |
| Minibar, wellness, parkování placené na místě | Ano | Běžná tržba. |
| Vratná kauce – složení / vrácení | Ne | Při složení ani při vrácení se neeviduje (ani stornem). |
| Část kauce složené na místě, kterou si ponecháte | Ano | Tržba jen na ponechanou (použitou) částku. |
| Kauce poslaná převodem, část ponechána | Ne | Nejde o kontaktní platbu. |
| Storno / vrácení peněz na místě | Ano | POST /v1/sales/{id}/refund. |
| Místní poplatek z pobytu | Otevřené | Finanční správa zatím nezveřejnila, zda se zahrnuje do evidované tržby (návod, oddíl „Místní poplatek“). V PMS jako nastavení na úrovni hotelu – rozhodnutí podnikatele a jeho účetní, bez výchozí hodnoty. |
| Dobití kreditu / hotelové karty k pozdějšímu čerpání | Ano | kind: credit_topup; čerpání kreditu method: credit. |
{
"sales": [
{
"id": "0b6f3f1e-2a51-4c8e-9a4e-6a1d2f0c7a11",
"externalRef": "ALI-PAY-1001",
"unitId": "3f2a9c7e-5b1d-4e8f-a2c4-9d6e1b0f3a22",
"soldAt": "2027-01-05T15:20:00+01:00",
"lines": [
{
"name": "Záloha – rezervace R-2027-0042",
"qty": 1,
"unitPrice": 200000,
"vatRate": 12,
"kind": "goods"
}
],
"payments": [
{
"method": "card",
"amount": 200000
}
]
},
{
"id": "6c1d8a42-9e3b-4f70-b5a1-2e8c7d4f9b33",
"externalRef": "ALI-PAY-1002",
"unitId": "3f2a9c7e-5b1d-4e8f-a2c4-9d6e1b0f3a22",
"soldAt": "2027-01-08T10:05:00+01:00",
"lines": [
{
"name": "Doplatek – rezervace R-2027-0042",
"qty": 1,
"unitPrice": 340000,
"vatRate": 12,
"kind": "goods"
},
{
"name": "Minibar",
"qty": 2,
"unitPrice": 6000,
"vatRate": 21,
"kind": "goods"
}
],
"payments": [
{
"method": "card",
"amount": 352000
}
]
}
]
}{
"sales": [
{
"id": "9a4e2b17-3c6d-4f8a-8b1e-5d2c7f0a6e44",
"externalRef": "ALI-KAUCE-77",
"unitId": "3f2a9c7e-5b1d-4e8f-a2c4-9d6e1b0f3a22",
"soldAt": "2027-01-08T10:10:00+01:00",
"lines": [
{
"name": "Úhrada škody z kauce (poškozené povlečení)",
"qty": 1,
"unitPrice": 30000,
"vatRate": 21,
"kind": "goods"
}
],
"payments": [
{
"method": "cash",
"amount": 30000
}
]
}
]
}Reference (OpenAPI)
Vygenerováno ze stejných schémat, kterými API kontroluje požadavky. Kliknutím rozbalíte.
get/v1/accountToken environment, masked EIČ, certificate state and the integration's scopes (any scope).
- 200 – OK
- 401 – invalid_token / token_revoked
- 403 – insufficient_scope / account_closed / environment_not_ready
- 429 – rate_limited (Retry-After)
get/v1/unitsUnits the token may use, and whether they are ready (units:read).
- 200 – OK
- 401 – invalid_token / token_revoked
- 403 – insufficient_scope / account_closed / environment_not_ready
- 429 – rate_limited (Retry-After)
post/v1/salesSubmit 1–100 sales (sales:write). Idempotent by id; new sales are sent to FS synchronously within 2.5 s, the rest by the queue.
- 200 – Results in request order (also when some sales are quarantined).
- 400 – invalid_request
- 401 – invalid_token / token_revoked
- 403 – insufficient_scope / account_closed / environment_not_ready
- 404 – unit_not_found
- 409 – idempotency_conflict / external_ref_conflict
- 413 – payload_too_large
- 429 – rate_limited (Retry-After)
get/v1/salesSales of this integration (sales:read). Order soldAt desc, id.
| Parametr | Kde | Popis |
|---|---|---|
| ids | query | Up to 200 ids, comma separated (includes quarantined sales). |
| externalRef | query | Exact externalRef. |
| status | query | confirmed | queued | sending | rejected | quarantined | not_evidenced |
| unitId | query | Unit id. |
| since | query | soldAt ≥ (ISO 8601). |
| until | query | soldAt < (ISO 8601). |
| limit | query | 1–200, default 50. |
| cursor | query | nextCursor from the previous page. |
- 200 – OK
- 400 – invalid_request
- 401 – invalid_token / token_revoked
- 403 – insufficient_scope / account_closed / environment_not_ready
- 429 – rate_limited (Retry-After)
get/v1/sales/{id}One sale of this integration (sales:read).
| Parametr | Kde | Popis |
|---|---|---|
| id * | path | Sale id |
- 200 – OK
- 401 – invalid_token / token_revoked
- 403 – insufficient_scope / account_closed / environment_not_ready
- 404 – sale_not_found
- 429 – rate_limited (Retry-After)
post/v1/sales/{id}/refundFull refund (no lines) or partial refund of a sale of this integration (refunds:write). The refund is a new negative sale on the original's unit.
| Parametr | Kde | Popis |
|---|---|---|
| id * | path | Original sale id |
- 200 – The refund sale
- 400 – invalid_request
- 401 – invalid_token / token_revoked
- 403 – insufficient_scope / account_closed / environment_not_ready
- 404 – original_not_found / unit_not_found
- 409 – idempotency_conflict / external_ref_conflict
- 422 – refund_exceeds_original / original_is_refund
- 429 – rate_limited (Retry-After)
post/v1/webhooksRegister a webhook endpoint (webhooks:manage). Deliveries are signed: EZ-Signature: t=<unix>,v1=<hex hmac_sha256(secret, t + "." + rawBody)>; retries after 1 min, 5 min, 30 min, 2 h, 6 h, 24 h.
- 201 – Created – the secret is returned only here
- 400 – invalid_request
- 401 – invalid_token / token_revoked
- 403 – insufficient_scope / account_closed / environment_not_ready
- 429 – rate_limited (Retry-After)
get/v1/webhooksWebhook endpoints of this integration (webhooks:manage).
- 200 – OK
- 401 – invalid_token / token_revoked
- 403 – insufficient_scope / account_closed / environment_not_ready
- 429 – rate_limited (Retry-After)
delete/v1/webhooks/{id}Delete a webhook endpoint (webhooks:manage).
| Parametr | Kde | Popis |
|---|---|---|
| id * | path | Webhook id |
- 200 – Deleted
- 401 – invalid_token / token_revoked
- 403 – insufficient_scope / account_closed / environment_not_ready
- 404 – webhook_not_found
- 429 – rate_limited (Retry-After)
post/v1/webhooks/{id}/testQueue a webhook.test event (webhooks:manage).
| Parametr | Kde | Popis |
|---|---|---|
| id * | path | Webhook id |
- 202 – Queued
- 401 – invalid_token / token_revoked
- 403 – insufficient_scope / account_closed / environment_not_ready
- 404 – webhook_not_found
- 429 – rate_limited (Retry-After)
post/v1/oauth/tokenOAuth 2.0 authorization code + PKCE (S256): exchange the code from /pripojit for an integration token. Client authentication with client_secret. A reused code returns invalid_grant and revokes the token issued with it.
- 200 – Token
- 400 – invalid_request / invalid_grant / unsupported_grant_type (RFC 6749 error object)
- 401 – invalid_client
get/v1/closingsDaily totals of this integration's sales (closings:read). Day = calendar day in Europe/Prague by soldAt.
| Parametr | Kde | Popis |
|---|---|---|
| unitId | query | Unit id. |
| from | query | YYYY-MM-DD (default today). |
| to | query | YYYY-MM-DD (default = from, at most 62 days). |
- 200 – OK
- 400 – invalid_request
- 401 – invalid_token / token_revoked
- 403 – insufficient_scope / account_closed / environment_not_ready
- 404 – unit_not_found
- 429 – rate_limited (Retry-After)
Schémata
SaleV1
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"externalRef": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"unitId": {
"type": "string",
"format": "uuid"
},
"soldAt": {
"type": "string",
"format": "date-time"
},
"sequence": {
"type": "string",
"minLength": 1,
"maxLength": 25
},
"lines": {
"minItems": 1,
"maxItems": 300,
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
"qty": {
"type": "number"
},
"unitPrice": {
"type": "integer",
"minimum": -10000000000,
"maximum": 10000000000
},
"vatRate": {
"type": "integer",
"minimum": 0,
"maximum": 30
},
"kind": {
"type": "string",
"enum": [
"goods",
"credit_topup"
]
}
},
"required": [
"name",
"qty",
"unitPrice",
"vatRate"
]
}
},
"payments": {
"minItems": 1,
"maxItems": 5,
"type": "array",
"items": {
"type": "object",
"properties": {
"method": {
"type": "string",
"enum": [
"cash",
"card",
"qr",
"transfer",
"meal_voucher",
"credit",
"gift_voucher",
"voucher"
]
},
"amount": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": [
"method",
"amount"
]
}
},
"tip": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"discount": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"refundOf": {},
"approval": {}
},
"required": [
"id",
"unitId",
"soldAt",
"lines",
"payments"
]
}SalesRequest
{
"type": "object",
"properties": {
"sales": {
"minItems": 1,
"maxItems": 100,
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"externalRef": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"unitId": {
"type": "string",
"format": "uuid"
},
"soldAt": {
"type": "string",
"format": "date-time"
},
"sequence": {
"type": "string",
"minLength": 1,
"maxLength": 25
},
"lines": {
"minItems": 1,
"maxItems": 300,
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
"qty": {
"type": "number"
},
"unitPrice": {
"type": "integer",
"minimum": -10000000000,
"maximum": 10000000000
},
"vatRate": {
"type": "integer",
"minimum": 0,
"maximum": 30
},
"kind": {
"type": "string",
"enum": [
"goods",
"credit_topup"
]
}
},
"required": [
"name",
"qty",
"unitPrice",
"vatRate"
]
}
},
"payments": {
"minItems": 1,
"maxItems": 5,
"type": "array",
"items": {
"type": "object",
"properties": {
"method": {
"type": "string",
"enum": [
"cash",
"card",
"qr",
"transfer",
"meal_voucher",
"credit",
"gift_voucher",
"voucher"
]
},
"amount": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": [
"method",
"amount"
]
}
},
"tip": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"discount": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"refundOf": {},
"approval": {}
},
"required": [
"id",
"unitId",
"soldAt",
"lines",
"payments"
]
}
}
},
"required": [
"sales"
]
}RefundRequest
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"externalRef": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"soldAt": {
"type": "string",
"format": "date-time"
},
"lines": {
"minItems": 1,
"maxItems": 300,
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
"qty": {
"type": "number",
"exclusiveMinimum": 0,
"maximum": 10000
},
"unitPrice": {
"type": "integer",
"minimum": -10000000000,
"maximum": 10000000000
},
"vatRate": {
"type": "integer",
"minimum": 0,
"maximum": 30
},
"kind": {
"type": "string",
"enum": [
"goods",
"credit_topup"
]
}
},
"required": [
"name",
"qty",
"unitPrice",
"vatRate"
]
}
},
"reason": {
"type": "string",
"maxLength": 200
}
},
"required": [
"id"
]
}SaleStatusV1
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"externalRef": {
"type": [
"string",
"null"
]
},
"status": {
"type": "string",
"enum": [
"confirmed",
"queued",
"sending",
"rejected",
"quarantined",
"not_evidenced"
]
},
"pok": {
"type": [
"string",
"null"
]
},
"evidencedAmount": {
"anyOf": [
{
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
{
"type": "null"
}
]
},
"notEvidencedAmount": {
"anyOf": [
{
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
{
"type": "null"
}
]
},
"sentAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"deadlineAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "soldAt + 48 h"
},
"attempts": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"warnings": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"text": {
"type": "string"
}
},
"required": [
"code",
"text"
],
"additionalProperties": false
}
},
"error": {
"anyOf": [
{
"type": "object",
"properties": {
"code": {
"type": "string",
"enum": [
"invalid_request",
"invalid_token",
"token_revoked",
"insufficient_scope",
"account_closed",
"environment_not_ready",
"unit_not_found",
"sale_not_found",
"original_not_found",
"webhook_not_found",
"idempotency_conflict",
"external_ref_conflict",
"payload_too_large",
"refund_exceeds_original",
"original_is_refund",
"rate_limited",
"internal_error",
"sale_in_future",
"sale_too_old",
"amount_out_of_range",
"unit_not_ready",
"certificate_missing",
"certificate_expired",
"sequence_conflict",
"sale_blocked",
"fs_rejected",
"fs_unavailable"
]
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"field": {
"type": "string"
},
"fsCode": {
"description": "Chyba code from FS (Popis rozhraní EET 2.0, 3.5.4)",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": [
"code",
"message",
"retryable"
],
"additionalProperties": false
},
{
"type": "null"
}
]
},
"receipt": {
"anyOf": [
{
"type": "object",
"properties": {
"seller": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"ico": {
"type": [
"string",
"null"
]
},
"dic": {
"type": [
"string",
"null"
]
},
"address": {
"type": [
"string",
"null"
]
}
},
"required": [
"name",
"ico",
"dic",
"address"
],
"additionalProperties": false
},
"unit": {
"type": "object",
"properties": {
"fsUnitId": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"label": {
"type": "string"
}
},
"required": [
"fsUnitId",
"label"
],
"additionalProperties": false
},
"registerId": {
"type": "string",
"description": "id_pokl"
},
"sequence": {
"type": "string",
"description": "porad_cis"
},
"soldAt": {
"type": "string",
"format": "date-time"
},
"total": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991,
"description": "haléře"
},
"evidencedAmount": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991,
"description": "celk_trzba in haléře"
},
"vatBreakdown": {
"anyOf": [
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "object",
"properties": {
"base": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"vat": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": [
"base",
"vat"
],
"additionalProperties": false
}
},
{
"type": "null"
}
]
},
"pok": {
"type": [
"string",
"null"
]
},
"mode": {
"type": "string",
"enum": [
"production",
"playground"
]
},
"offline": {
"type": "boolean",
"description": "true when the POK is not there yet at the time of the response"
},
"note": {
"description": "Print on the receipt when offline: “Tržba bude odeslána nejpozději do 48 hodin.”",
"type": "string"
}
},
"required": [
"seller",
"unit",
"registerId",
"sequence",
"soldAt",
"total",
"evidencedAmount",
"vatBreakdown",
"pok",
"mode",
"offline"
],
"additionalProperties": false
},
{
"type": "null"
}
]
},
"receiptUrl": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"externalRef",
"status",
"pok",
"evidencedAmount",
"notEvidencedAmount",
"sentAt",
"deadlineAt",
"attempts",
"warnings",
"error",
"receipt",
"receiptUrl"
],
"additionalProperties": false
}ReceiptFiscalV1
{
"type": "object",
"properties": {
"seller": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"ico": {
"type": [
"string",
"null"
]
},
"dic": {
"type": [
"string",
"null"
]
},
"address": {
"type": [
"string",
"null"
]
}
},
"required": [
"name",
"ico",
"dic",
"address"
],
"additionalProperties": false
},
"unit": {
"type": "object",
"properties": {
"fsUnitId": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"label": {
"type": "string"
}
},
"required": [
"fsUnitId",
"label"
],
"additionalProperties": false
},
"registerId": {
"type": "string",
"description": "id_pokl"
},
"sequence": {
"type": "string",
"description": "porad_cis"
},
"soldAt": {
"type": "string",
"format": "date-time"
},
"total": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991,
"description": "haléře"
},
"evidencedAmount": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991,
"description": "celk_trzba in haléře"
},
"vatBreakdown": {
"anyOf": [
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "object",
"properties": {
"base": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"vat": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": [
"base",
"vat"
],
"additionalProperties": false
}
},
{
"type": "null"
}
]
},
"pok": {
"type": [
"string",
"null"
]
},
"mode": {
"type": "string",
"enum": [
"production",
"playground"
]
},
"offline": {
"type": "boolean",
"description": "true when the POK is not there yet at the time of the response"
},
"note": {
"description": "Print on the receipt when offline: “Tržba bude odeslána nejpozději do 48 hodin.”",
"type": "string"
}
},
"required": [
"seller",
"unit",
"registerId",
"sequence",
"soldAt",
"total",
"evidencedAmount",
"vatBreakdown",
"pok",
"mode",
"offline"
],
"additionalProperties": false
}SalesResult
{
"type": "object",
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"externalRef": {
"type": [
"string",
"null"
]
},
"status": {
"type": "string",
"enum": [
"confirmed",
"queued",
"sending",
"rejected",
"quarantined",
"not_evidenced"
]
},
"pok": {
"type": [
"string",
"null"
]
},
"evidencedAmount": {
"anyOf": [
{
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
{
"type": "null"
}
]
},
"notEvidencedAmount": {
"anyOf": [
{
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
{
"type": "null"
}
]
},
"sentAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"deadlineAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "soldAt + 48 h"
},
"attempts": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"warnings": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"text": {
"type": "string"
}
},
"required": [
"code",
"text"
],
"additionalProperties": false
}
},
"error": {
"anyOf": [
{
"type": "object",
"properties": {
"code": {
"type": "string",
"enum": [
"invalid_request",
"invalid_token",
"token_revoked",
"insufficient_scope",
"account_closed",
"environment_not_ready",
"unit_not_found",
"sale_not_found",
"original_not_found",
"webhook_not_found",
"idempotency_conflict",
"external_ref_conflict",
"payload_too_large",
"refund_exceeds_original",
"original_is_refund",
"rate_limited",
"internal_error",
"sale_in_future",
"sale_too_old",
"amount_out_of_range",
"unit_not_ready",
"certificate_missing",
"certificate_expired",
"sequence_conflict",
"sale_blocked",
"fs_rejected",
"fs_unavailable"
]
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"field": {
"type": "string"
},
"fsCode": {
"description": "Chyba code from FS (Popis rozhraní EET 2.0, 3.5.4)",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": [
"code",
"message",
"retryable"
],
"additionalProperties": false
},
{
"type": "null"
}
]
},
"receipt": {
"anyOf": [
{
"type": "object",
"properties": {
"seller": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"ico": {
"type": [
"string",
"null"
]
},
"dic": {
"type": [
"string",
"null"
]
},
"address": {
"type": [
"string",
"null"
]
}
},
"required": [
"name",
"ico",
"dic",
"address"
],
"additionalProperties": false
},
"unit": {
"type": "object",
"properties": {
"fsUnitId": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"label": {
"type": "string"
}
},
"required": [
"fsUnitId",
"label"
],
"additionalProperties": false
},
"registerId": {
"type": "string",
"description": "id_pokl"
},
"sequence": {
"type": "string",
"description": "porad_cis"
},
"soldAt": {
"type": "string",
"format": "date-time"
},
"total": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991,
"description": "haléře"
},
"evidencedAmount": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991,
"description": "celk_trzba in haléře"
},
"vatBreakdown": {
"anyOf": [
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "object",
"properties": {
"base": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"vat": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": [
"base",
"vat"
],
"additionalProperties": false
}
},
{
"type": "null"
}
]
},
"pok": {
"type": [
"string",
"null"
]
},
"mode": {
"type": "string",
"enum": [
"production",
"playground"
]
},
"offline": {
"type": "boolean",
"description": "true when the POK is not there yet at the time of the response"
},
"note": {
"description": "Print on the receipt when offline: “Tržba bude odeslána nejpozději do 48 hodin.”",
"type": "string"
}
},
"required": [
"seller",
"unit",
"registerId",
"sequence",
"soldAt",
"total",
"evidencedAmount",
"vatBreakdown",
"pok",
"mode",
"offline"
],
"additionalProperties": false
},
{
"type": "null"
}
]
},
"receiptUrl": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"externalRef",
"status",
"pok",
"evidencedAmount",
"notEvidencedAmount",
"sentAt",
"deadlineAt",
"attempts",
"warnings",
"error",
"receipt",
"receiptUrl"
],
"additionalProperties": false
}
}
},
"required": [
"results"
],
"additionalProperties": false
}SalesList
{
"type": "object",
"properties": {
"sales": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"externalRef": {
"type": [
"string",
"null"
]
},
"status": {
"type": "string",
"enum": [
"confirmed",
"queued",
"sending",
"rejected",
"quarantined",
"not_evidenced"
]
},
"pok": {
"type": [
"string",
"null"
]
},
"evidencedAmount": {
"anyOf": [
{
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
{
"type": "null"
}
]
},
"notEvidencedAmount": {
"anyOf": [
{
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
{
"type": "null"
}
]
},
"sentAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"deadlineAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "soldAt + 48 h"
},
"attempts": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"warnings": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"text": {
"type": "string"
}
},
"required": [
"code",
"text"
],
"additionalProperties": false
}
},
"error": {
"anyOf": [
{
"type": "object",
"properties": {
"code": {
"type": "string",
"enum": [
"invalid_request",
"invalid_token",
"token_revoked",
"insufficient_scope",
"account_closed",
"environment_not_ready",
"unit_not_found",
"sale_not_found",
"original_not_found",
"webhook_not_found",
"idempotency_conflict",
"external_ref_conflict",
"payload_too_large",
"refund_exceeds_original",
"original_is_refund",
"rate_limited",
"internal_error",
"sale_in_future",
"sale_too_old",
"amount_out_of_range",
"unit_not_ready",
"certificate_missing",
"certificate_expired",
"sequence_conflict",
"sale_blocked",
"fs_rejected",
"fs_unavailable"
]
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"field": {
"type": "string"
},
"fsCode": {
"description": "Chyba code from FS (Popis rozhraní EET 2.0, 3.5.4)",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": [
"code",
"message",
"retryable"
],
"additionalProperties": false
},
{
"type": "null"
}
]
},
"receipt": {
"anyOf": [
{
"type": "object",
"properties": {
"seller": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"ico": {
"type": [
"string",
"null"
]
},
"dic": {
"type": [
"string",
"null"
]
},
"address": {
"type": [
"string",
"null"
]
}
},
"required": [
"name",
"ico",
"dic",
"address"
],
"additionalProperties": false
},
"unit": {
"type": "object",
"properties": {
"fsUnitId": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"label": {
"type": "string"
}
},
"required": [
"fsUnitId",
"label"
],
"additionalProperties": false
},
"registerId": {
"type": "string",
"description": "id_pokl"
},
"sequence": {
"type": "string",
"description": "porad_cis"
},
"soldAt": {
"type": "string",
"format": "date-time"
},
"total": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991,
"description": "haléře"
},
"evidencedAmount": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991,
"description": "celk_trzba in haléře"
},
"vatBreakdown": {
"anyOf": [
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "object",
"properties": {
"base": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"vat": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": [
"base",
"vat"
],
"additionalProperties": false
}
},
{
"type": "null"
}
]
},
"pok": {
"type": [
"string",
"null"
]
},
"mode": {
"type": "string",
"enum": [
"production",
"playground"
]
},
"offline": {
"type": "boolean",
"description": "true when the POK is not there yet at the time of the response"
},
"note": {
"description": "Print on the receipt when offline: “Tržba bude odeslána nejpozději do 48 hodin.”",
"type": "string"
}
},
"required": [
"seller",
"unit",
"registerId",
"sequence",
"soldAt",
"total",
"evidencedAmount",
"vatBreakdown",
"pok",
"mode",
"offline"
],
"additionalProperties": false
},
{
"type": "null"
}
]
},
"receiptUrl": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"externalRef",
"status",
"pok",
"evidencedAmount",
"notEvidencedAmount",
"sentAt",
"deadlineAt",
"attempts",
"warnings",
"error",
"receipt",
"receiptUrl"
],
"additionalProperties": false
}
},
"nextCursor": {
"type": [
"string",
"null"
]
}
},
"required": [
"sales",
"nextCursor"
],
"additionalProperties": false
}Account
{
"type": "object",
"properties": {
"environment": {
"type": "string",
"enum": [
"test",
"live"
]
},
"eetMode": {
"type": "string",
"enum": [
"playground",
"production"
]
},
"eicMasked": {
"type": [
"string",
"null"
]
},
"certificate": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"valid",
"expired",
"missing",
"not_verified"
]
},
"validTo": {
"type": [
"string",
"null"
]
},
"daysLeft": {
"anyOf": [
{
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
{
"type": "null"
}
]
}
},
"required": [
"status",
"validTo",
"daysLeft"
],
"additionalProperties": false
},
"integration": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"scopes": {
"type": "array",
"items": {
"type": "string",
"enum": [
"sales:write",
"sales:read",
"refunds:write",
"units:read",
"closings:read",
"webhooks:manage"
]
}
},
"unitIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid"
}
}
},
"required": [
"id",
"name",
"scopes",
"unitIds"
],
"additionalProperties": false
}
},
"required": [
"environment",
"eetMode",
"eicMasked",
"certificate",
"integration"
],
"additionalProperties": false
}Units
{
"type": "object",
"properties": {
"units": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"label": {
"type": "string"
},
"type": {
"type": "string"
},
"fsUnitId": {
"anyOf": [
{
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
{
"type": "null"
}
]
},
"active": {
"type": "boolean"
},
"ready": {
"type": "boolean"
},
"notReadyReason": {
"anyOf": [
{
"type": "string",
"enum": [
"unit_missing_fs_id",
"certificate_missing",
"certificate_expired",
"account_closed"
]
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"label",
"type",
"fsUnitId",
"active",
"ready",
"notReadyReason"
],
"additionalProperties": false
}
}
},
"required": [
"units"
],
"additionalProperties": false
}Closings
{
"type": "object",
"properties": {
"closings": {
"type": "array",
"items": {
"type": "object",
"properties": {
"date": {
"type": "string",
"description": "YYYY-MM-DD, Europe/Prague"
},
"unitId": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"count": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"total": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"evidenced": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"notEvidenced": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"byPaymentMethod": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"byVat": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "object",
"properties": {
"base": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"vat": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": [
"base",
"vat"
],
"additionalProperties": false
}
},
"pending": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991,
"description": "sales without POK yet"
}
},
"required": [
"date",
"unitId",
"count",
"total",
"evidenced",
"notEvidenced",
"byPaymentMethod",
"byVat",
"pending"
],
"additionalProperties": false
}
}
},
"required": [
"closings"
],
"additionalProperties": false
}Error
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"enum": [
"invalid_request",
"invalid_token",
"token_revoked",
"insufficient_scope",
"account_closed",
"environment_not_ready",
"unit_not_found",
"sale_not_found",
"original_not_found",
"webhook_not_found",
"idempotency_conflict",
"external_ref_conflict",
"payload_too_large",
"refund_exceeds_original",
"original_is_refund",
"rate_limited",
"internal_error",
"sale_in_future",
"sale_too_old",
"amount_out_of_range",
"unit_not_ready",
"certificate_missing",
"certificate_expired",
"sequence_conflict",
"sale_blocked",
"fs_rejected",
"fs_unavailable"
]
},
"message": {
"type": "string"
},
"field": {
"type": "string"
},
"requestId": {
"type": "string",
"format": "uuid"
}
},
"required": [
"code",
"message",
"requestId"
],
"additionalProperties": false
}
},
"required": [
"error"
],
"additionalProperties": false
}WebhookCreate
{
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "uri",
"description": "https only; private, loopback and link-local addresses are refused"
},
"events": {
"description": "Omitted or empty = all events",
"type": "array",
"items": {
"type": "string",
"enum": [
"sale.confirmed",
"sale.rejected",
"sale.deadline_soon",
"certificate.expiring",
"certificate.expired",
"integration.revoked"
]
}
}
},
"required": [
"url"
]
}Webhook
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"url": {
"type": "string"
},
"events": {
"type": "array",
"items": {
"type": "string"
}
},
"active": {
"type": "boolean"
},
"failingSince": {
"type": [
"string",
"null"
]
},
"createdAt": {
"type": "string"
}
},
"required": [
"id",
"url",
"events",
"active",
"failingSince",
"createdAt"
],
"additionalProperties": false
}WebhookCreated
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"url": {
"type": "string"
},
"events": {
"type": "array",
"items": {
"type": "string"
}
},
"active": {
"type": "boolean"
},
"failingSince": {
"type": [
"string",
"null"
]
},
"createdAt": {
"type": "string"
},
"secret": {
"type": "string",
"description": "Signing secret, returned only once"
}
},
"required": [
"id",
"url",
"events",
"active",
"failingSince",
"createdAt",
"secret"
],
"additionalProperties": false
}WebhookEvent
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Event id – deduplicate by it; order is not guaranteed"
},
"type": {
"type": "string",
"enum": [
"sale.confirmed",
"sale.rejected",
"sale.deadline_soon",
"certificate.expiring",
"certificate.expired",
"integration.revoked",
"webhook.test"
]
},
"createdAt": {
"type": "string"
},
"data": {
"anyOf": [
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"externalRef": {
"type": [
"string",
"null"
]
},
"status": {
"type": "string",
"enum": [
"confirmed",
"queued",
"sending",
"rejected",
"quarantined",
"not_evidenced"
]
},
"pok": {
"type": [
"string",
"null"
]
},
"evidencedAmount": {
"anyOf": [
{
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
{
"type": "null"
}
]
},
"notEvidencedAmount": {
"anyOf": [
{
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
{
"type": "null"
}
]
},
"sentAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"deadlineAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "soldAt + 48 h"
},
"attempts": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"warnings": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"text": {
"type": "string"
}
},
"required": [
"code",
"text"
],
"additionalProperties": false
}
},
"error": {
"anyOf": [
{
"type": "object",
"properties": {
"code": {
"type": "string",
"enum": [
"invalid_request",
"invalid_token",
"token_revoked",
"insufficient_scope",
"account_closed",
"environment_not_ready",
"unit_not_found",
"sale_not_found",
"original_not_found",
"webhook_not_found",
"idempotency_conflict",
"external_ref_conflict",
"payload_too_large",
"refund_exceeds_original",
"original_is_refund",
"rate_limited",
"internal_error",
"sale_in_future",
"sale_too_old",
"amount_out_of_range",
"unit_not_ready",
"certificate_missing",
"certificate_expired",
"sequence_conflict",
"sale_blocked",
"fs_rejected",
"fs_unavailable"
]
},
"message": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"field": {
"type": "string"
},
"fsCode": {
"description": "Chyba code from FS (Popis rozhraní EET 2.0, 3.5.4)",
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": [
"code",
"message",
"retryable"
],
"additionalProperties": false
},
{
"type": "null"
}
]
},
"receipt": {
"anyOf": [
{
"type": "object",
"properties": {
"seller": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"ico": {
"type": [
"string",
"null"
]
},
"dic": {
"type": [
"string",
"null"
]
},
"address": {
"type": [
"string",
"null"
]
}
},
"required": [
"name",
"ico",
"dic",
"address"
],
"additionalProperties": false
},
"unit": {
"type": "object",
"properties": {
"fsUnitId": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"label": {
"type": "string"
}
},
"required": [
"fsUnitId",
"label"
],
"additionalProperties": false
},
"registerId": {
"type": "string",
"description": "id_pokl"
},
"sequence": {
"type": "string",
"description": "porad_cis"
},
"soldAt": {
"type": "string",
"format": "date-time"
},
"total": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991,
"description": "haléře"
},
"evidencedAmount": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991,
"description": "celk_trzba in haléře"
},
"vatBreakdown": {
"anyOf": [
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "object",
"properties": {
"base": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"vat": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": [
"base",
"vat"
],
"additionalProperties": false
}
},
{
"type": "null"
}
]
},
"pok": {
"type": [
"string",
"null"
]
},
"mode": {
"type": "string",
"enum": [
"production",
"playground"
]
},
"offline": {
"type": "boolean",
"description": "true when the POK is not there yet at the time of the response"
},
"note": {
"description": "Print on the receipt when offline: “Tržba bude odeslána nejpozději do 48 hodin.”",
"type": "string"
}
},
"required": [
"seller",
"unit",
"registerId",
"sequence",
"soldAt",
"total",
"evidencedAmount",
"vatBreakdown",
"pok",
"mode",
"offline"
],
"additionalProperties": false
},
{
"type": "null"
}
]
},
"receiptUrl": {
"anyOf": [
{
"type": "string",
"format": "uri"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"externalRef",
"status",
"pok",
"evidencedAmount",
"notEvidencedAmount",
"sentAt",
"deadlineAt",
"attempts",
"warnings",
"error",
"receipt",
"receiptUrl"
],
"additionalProperties": false
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
],
"description": "SaleStatusV1 for sale.* events; certificate or integration info otherwise"
}
},
"required": [
"id",
"type",
"createdAt",
"data"
],
"additionalProperties": false
}Changelog API
- v1 (30. 10. 2026) – první verze: tržby, stav, vratky, jednotky, denní přehledy, webhooky, připojení přes OAuth, Playground.