API: napojení účetnictví, e-shopu a dalších programů
Modul API v EET kasa (149 Kč měsíčně ke každému plánu, v Max Plus v ceně): REST rozhraní s API klíčem pro zálohování účtenek, napojení účetnictví, e-shopu nebo skladového systému. Čtení prodejů a účtenek, katalogu, směn a souhrnů tržeb, z modulů Sklad, Zákaznické účty, Kupony a Cenové akce; zápis produktů, kategorií, příjemek, odpisů, kuponů a akcí. Popis všech funkcí, limity, chyby, příklady.
Modul API zpřístupní data firmy jiným programům přes webové rozhraní (REST, JSON). Typické použití: automatická záloha účtenek mimo pokladnu, napojení účetnictví (stažení dokladů a souhrnů za období bez ručního exportu), synchronizace katalogu a skladu s e-shopem nebo skladovým systémem, vlastní přehledy a tabulky. Program se prokazuje API klíčem, který vytvoříte v administraci; klíč může být jen pro čtení, nebo i pro zápis.
Modul stojí 149 Kč měsíčně ke každému plánu, v plánu Max Plus je v ceně; do 1. 2. 2027 je zdarma (viz Ceník). Zapíná se v menu Moduly a nevyžaduje žádný jiný modul.
Co API umí a co ne#
Základ (bez dalších modulů): údaje o firmě, pokladny, obsluha, sazby DPH, platební metody, kategorie a produkty, prodeje a účtenky včetně položek, plateb a stavu EET, účtenka jako HTML (úzká i A4), směny s pohyby hotovosti, souhrn tržeb za období (po pokladnách, platebních metodách, sazbách DPH, dnech a obsluze).
Z modulů (jen když je modul zapnutý, jinak odpoví chybou 403): Sklad (sklady, položky, stavy se šaržemi, pohyby; příjemky, odpisy a korekce), Zákaznické účty (jen čtení), Kupony a Cenové akce (čtení i zápis).
Zápis má jen klíč s oprávněním Čtení a zápis a týká se produktů, kategorií, skladu, kuponů a cenových akcí. Prodeje, směny a zákaznické účty jsou vždy jen ke čtení: doklady vznikají výhradně na pokladně, aby číslování, EET a storna zůstaly konzistentní.
Co API neumí: vytvořit prodej nebo účtenku, odesílat do EET, vystavit fakturu, pracovat se Zákaznickou aplikací, rezervacemi a personalistikou, posílat upozornění (webhooky): změny si program zjišťuje dotazem, typicky přes since_id (viz níže).
Zapnutí a API klíče#
- V administraci otevřete Moduly a u modulu API stiskněte Zapnout (jen majitel účtu).
- V menu přibude API. Ve formuláři Nový klíč zadejte název (k čemu klíč slouží, např. „účetnictví“), zvolte oprávnění (Jen čtení, nebo Čtení a zápis) a případně platnost do. Stiskněte Vytvořit klíč.
- Klíč se zobrazí jen jednou v oranžovém rámečku, tvar
eetk_a 48 znaků. Zkopírujte ho a předejte vývojáři nebo vložte do napojeného programu. Pokladna ukládá pouze jeho otisk, z administrace ho nelze znovu zjistit; ztracený klíč odvolejte a vytvořte nový. - Každý program má mít vlastní klíč, aby šel samostatně odvolat (tlačítko Odvolat v seznamu). Odvolaný klíč okamžitě přestane fungovat (chyba 401). Firma může mít nejvýš 10 platných klíčů.
V seznamu vidíte začátek klíče, oprávnění, platnost, kdo ho vytvořil, poslední použití s IP adresou a počet požadavků. Klíče spravuje majitel i správce firmy; účet s rolí jen pro čtení stránku nevidí. Vytvoření a odvolání klíče se zapisuje do audit logu, stejně jako každý zápis přes API (jako „API klíč název“).
Log požadavků#
Záložka Log požadavků ukazuje každý požadavek: čas, klíč, metodu, adresu, výsledek (stavový kód), kód chyby, trvání a IP adresu. Filtrovat lze podle klíče, výsledku (úspěch, chyba klienta, chyba serveru) a data. Nahoře je souhrn za posledních 24 hodin včetně počtu překročení limitu. Záznamy se uchovávají 90 dní. Log je první místo, kam se podívat, když napojení nefunguje: chyba 401 znamená neplatný nebo odvolaný klíč, 403 klíč jen pro čtení nebo vypnutý modul, 422 neplatná data a 429 překročený limit.
Základy: adresa, ověření, formát#
- Adresa:
https://pokladna.eet-kasa.cz/api/ext/v1/a za ní název funkce, např..../api/ext/v1/sales. - Ověření: hlavička
Authorization: Bearer <klíč>. Doporučujeme posílat iAccept: application/json; u zápisuContent-Type: application/jsona tělo jako JSON objekt. - Odpověď je vždy JSON s
ok. Jeden záznam:{"ok": true, "data": {…}}. Seznam:{"ok": true, "data": […], "page": 1, "per_page": 50, "has_more": true}. Chyba:{"ok": false, "error": "text pro člověka", "code": "strojový_kód", "errors": {"pole": "zpráva"}}(errorsjen u validace). - Časy jsou ve tvaru ISO 8601 s posunem středoevropského času, např.
2026-10-14T09:15:00+02:00. Při zadávání můžete poslat čas s posunem, nebo bez něj (bere se jako čas v ČR). Dny (from,to,valid_to,expires_at) ve tvaruRRRR-MM-DD. - Částky jsou čísla v Kč s DPH (
199.0), množství čísla se třemi desetinnými místy, příznakytrue/false, chybějící hodnotanull. - Metody:
GETčtení,POSTzaložení,PATCHzměna (mění jen zadaná pole, ostatní zůstávají). Jiné metody vrátí 405.
První zkouška z příkazové řádky:
curl -H "Authorization: Bearer eetk_vaš_klíč" https://pokladna.eet-kasa.cz/api/ext/v1/meOdpověď obsahuje firmu, zapnuté moduly, údaje o klíči (oprávnění, platnost) a limity:
{"ok":true,"data":{"company":{"id":12,"name":"Pekárna Na Rohu s.r.o.","ico":"12345678","dic":"CZ12345678","vat_payer":true,…},
"modules":{"stock":true,"recipes":false,"customer_accounts":false,"coupons":true,"promotions":true},
"key":{"id":3,"name":"účetnictví","prefix":"eetk_7f3a9c1","can_write":false,"expires_at":null,…},
"limits":{"per_minute":120,"per_day":20000,"per_page_max":200},"server_time":"2026-10-14T09:15:00+02:00"}}Stránkování a stahování změn#
Seznamy (sales, shifts, products, stock/items, stock/movements, coupons, promotions) vrací nejvýš 200 záznamů najednou: parametr per_page (výchozí 50, nejvýš 200) a page (od 1). Když je has_more true, načtěte další stránku. Záznamy jsou řazené podle id vzestupně; order=desc otočí pořadí (nejnovější první).
Pro průběžné stahování (zálohy, účetnictví) používejte since_id: vrátí jen záznamy s id větším než zadané číslo. Program si zapamatuje nejvyšší id, které už zpracoval, a příště se zeptá na novější. Je to spolehlivější než filtrování podle data: doklady vytvořené offline se na server dostanou až po synchronizaci, ale vždy dostanou vyšší id. U produktů slouží k témuž updated_since (čas poslední změny).
Limity požadavků#
Na jeden klíč platí 120 požadavků za minutu a na firmu 20 000 požadavků za den. Každá odpověď nese hlavičky X-RateLimit-Limit a X-RateLimit-Remaining (kolik v tomto okně zbývá). Po překročení přijde chyba 429 s kódem rate_limited a hlavičkou Retry-After (za kolik sekund to zkusit znovu). Stahujte po stránkách o 200 záznamech a změny přes since_id, ne celou historii znovu a znovu; na denní zálohu účtenek stačí jednotky požadavků.
Chyby#
| Stav | code | Význam |
|---|---|---|
| 400 | invalid_json | Tělo požadavku není platný JSON objekt. |
| 401 | invalid_key | Chybí nebo je neplatný klíč v hlavičce Authorization. |
| 401 | revoked_key | Klíč byl odvolán nebo mu skončila platnost. |
| 403 | module_disabled | Modul API, nebo modul dané části (Sklad, Kupony…), není zapnutý; v module je jeho název. |
| 403 | read_only_key | Klíč je jen pro čtení, zápis vyžaduje klíč s oprávněním Čtení a zápis. |
| 404 | not_found | Záznam nebo funkce neexistuje (nebo patří jiné firmě). |
| 405 | method_not_allowed | Nepodporovaná metoda. |
| 409 | validation | Konflikt, např. kupón s tímto kódem už existuje. |
| 422 | validation | Neplatná data; v errors je zpráva ke každému poli. |
| 429 | rate_limited | Překročený limit; hlavička Retry-After. |
| 500 | server_error | Chyba serveru; zkuste to znovu, trvá‑li, ozvěte se podpoře. |
Přehled funkcí#
Stručný seznam; podrobnosti ke každé funkci (parametry, těla, odpovědi, chyby) jsou v referenční dokumentaci.
| Metoda a adresa | Co vrací nebo dělá | Modul | Zápis |
|---|---|---|---|
GET /me | Firma, zapnuté moduly, údaje o klíči, limity. | – | – |
GET /registers | Pokladny (id, kód, název, sklad, poslední číslo účtenky). | – | – |
GET /users | Obsluha s PINem (bez PINu): id, jméno, role, aktivní. | – | – |
GET /vat-rates | Sazby DPH. | – | – |
GET /payment-methods | Platební metody (kód, název, hotovost, EET, zaokrouhlení). | – | – |
GET /categories | Kategorie s počtem produktů. | – | – |
POST /categories, PATCH /categories/{id} | Založení a změna kategorie. | – | ano |
GET /products, GET /products/{id} | Produkty (updated_since, active, category_id, q). | – | – |
POST /products, PATCH /products/{id} | Založení a změna produktu. | – | ano |
GET /sales, GET /sales/{id} | Doklady (účtenky a storna) s položkami, platbami, EET. | – | – |
GET /sales/{id}/receipt | Účtenka jako HTML (format=thermal nebo a4). | – | – |
GET /shifts, GET /shifts/{id} | Směny; detail s uzávěrkou a pohyby hotovosti. | – | – |
GET /reports/summary | Souhrn tržeb za období. | – | – |
GET /stock/warehouses | Sklady. | Sklad | – |
GET /stock/items | Skladové položky. | Sklad | – |
GET /stock/levels | Stav položek ve skladu se šaržemi a expirací. | Sklad | – |
GET /stock/movements | Skladové pohyby. | Sklad | – |
POST /stock/receipts | Příjemka (více řádků, šarže s expirací). | Sklad | ano |
POST /stock/writeoffs | Odpis (expirace, poškození, spotřeba, ztráta, jiné). | Sklad | ano |
POST /stock/adjustments | Korekce stavu (+/−) s důvodem. | Sklad | ano |
GET /customer-accounts, GET /customer-accounts/{id} | Zákaznické účty s nezaplacenými položkami a historií. | Zákaznické účty | – |
GET /coupons, GET /coupons/{id} | Kupony; detail s použitími na dokladech. | Kupony | – |
POST /coupons, PATCH /coupons/{id} | Založení a změna kupónu. | Kupony | ano |
GET /promotions, GET /promotions/{id} | Cenové akce s produkty a kategoriemi. | Cenové akce | – |
POST /promotions, PATCH /promotions/{id} | Založení a změna cenové akce. | Cenové akce | ano |
Po každém zápisu do katalogu, kuponů nebo akcí si pokladny stáhnou nová data samy (do 30 sekund), stejně jako po změně v administraci.
Prodeje a účtenky#
GET /sales vrací doklady podle id vzestupně. Parametry: from a to (dny podle data vystavení, včetně), register_id, type (sale nebo storno), since_id, order, page, per_page. Bez from/to se vrací celá historie po stránkách.
curl -H "Authorization: Bearer eetk_…" "https://pokladna.eet-kasa.cz/api/ext/v1/sales?from=2026-10-01&to=2026-10-31&per_page=200"Každý doklad obsahuje číslo účtenky, typ (sale/storno) a u storna storno_of_sale_id, čas vystavení, pokladnu a obsluhu, částky (subtotal, discount_total, rounding, tip, total, eet_amount), rozpis DPH (vat_summary: sazba, základ, daň, celkem), zákazníka z dokladu (customer: jméno, IČO, DIČ, adresa, e‑mail; null bez zákazníka), odkaz na zákaznický účet a rezervaci, uplatněný kupón (coupon) a věrnostní kartu (loyalty), poznámku, auth_mode (online/offline), stav EET (eet.state: not_required, pending, sent, failed; eet.pok kód POK, eet.test testovací prostředí) a receipt_url (veřejná e‑účtenka).
GET /sales/{id} přidá items (položky: produkt, název, varianta, modifikátory, množství, jednotka, jednotková cena s DPH, sazba, sleva, celkem řádku, akce), payments (platby: metoda, částka, číslo transakce terminálu) a invoice (číslo a odkaz faktury, pokud k dokladu existuje).
GET /sales/{id}/receipt vrátí účtenku jako HTML stránku, stejnou jako veřejná e‑účtenka; ?format=a4 vrátí daňový doklad na A4. Hodí se k archivaci (uložte HTML, nebo ho v prohlížeči vytiskněte do PDF). Údaje pro vlastní tisk máte v JSON detailu dokladu.
Směny a souhrn tržeb#
GET /shifts (parametry from/to podle otevření, register_id, status=open|closed, since_id) vrací směny s otevřením, uzavřením, počáteční a napočítanou hotovostí, rozdílem, číslem Z‑uzávěrky a počtem a součtem dokladů. GET /shifts/{id} přidá report (uzávěrka tak, jak ji pokladna uzavřela) a cash_movements (vklady a výběry s důvodem).
GET /reports/summary?from=&to= vrátí za období totals (počet dokladů, prodejů a storen, tržba, slevy, spropitné, tržba pro EET a stavy EET), by_register, by_payment_method, by_vat (základ a daň po sazbách), by_day a by_user. Bez zadání posledních 30 dnů.
Katalog: kategorie a produkty#
GET /products vrací produkty s kategorií, PLU, EAN, cenou s DPH, sazbou, jednotkou, desetinnými místy množství, variantami a modifikátory, barvou, odkazem na obrázek (image_url), pořadím, příznakem aktivní a odkazem na skladovou položku (stock_item_id, modul Sklad). Parametry updated_since (jen změněné od času), active=1|0, category_id, q (hledání v názvu, PLU a EAN).
Založení produktu (POST /products, klíč se zápisem):
curl -X POST -H "Authorization: Bearer eetk_…" -H "Content-Type: application/json" \
-d '{"name":"Koláč tvarohový","category_id":4,"plu":"312","ean":"8594001234567","price_incl_vat":32,"vat_rate":12,"unit":"ks","track_stock":true}' \
https://pokladna.eet-kasa.cz/api/ext/v1/productsPole: name (povinné), category_id, plu, ean, price_incl_vat (povinné při založení), price_variable (pokladna se zeptá na částku), vat_rate, unit, qty_decimals (0–3), is_favorite, color (#RRGGBB), sort, is_active, a se zapnutým Skladem track_stock (přímé sledování produktu na skladě). PATCH /products/{id} mění jen zadaná pole. Obrázky, varianty a modifikátory se přes API nemění, nastavíte je v administraci. Kategorie: name, color, sort, is_active a u modulu pro hospody bon_station (kitchen, bar, nebo prázdné).
Sklad#
Vyžaduje modul Sklad. GET /stock/levels?warehouse_id= vrátí všechny aktivní položky ve skladu (bez zadání výchozí sklad) se stavem, šaržemi (batches: datum expirace a množství) a nejbližší expirací. GET /stock/movements (parametry warehouse_id, stock_item_id, type, from/to, since_id) vrací pohyby: prodej, storno, příjem, odpis, úprava, převod, inventura, zákaznický účet; u pohybu z API je actor api.
Příjemka (POST /stock/receipts): warehouse_id (nepovinné), note, a lines s řádky {stock_item_id | product_id | sku, qty, expires_at}. Položku lze zadat číslem skladové položky, číslem produktu, nebo SKU. Řádek s expires_at založí nebo navýší šarži s tímto datem.
{"note":"Dodávka 14. 10.","lines":[{"sku":"MOUKA-25","qty":50},{"product_id":87,"qty":12,"expires_at":"2026-10-20"}]}Odpis (POST /stock/writeoffs): položka, qty, reason (expiry, damage, consumption, theft, other), note, případně batch_id (jen z dané šarže; bez něj se odepisuje nejdřív nejbližší expirace). Korekce (POST /stock/adjustments): položka, delta (kladné přidá, záporné odebere), povinné note s důvodem, u přidání volitelně expires_at. Odpovědi vrací nový stav dotčených položek.
Zákaznické účty, kupony, cenové akce#
Zákaznické účty (modul Zákaznické účty, jen čtení): GET /customer-accounts vrátí účty s nezaplacenou částkou a počtem položek, GET /customer-accounts/{id} navíc open_items (nezaplacené položky) a history (zaplacené a odebrané položky s číslem dokladu).
Kupony (modul Kupony): POST /coupons s poli code (3–40 znaků, písmena, číslice, pomlčka; uloží se velkými písmeny), name, type (amount Kč nebo percent), value, min_total (minimální nákup), max_uses, valid_from, valid_to, note, is_active. Kód musí být v rámci firmy jedinečný (jinak 409). Detail kupónu obsahuje uses (doklady, na kterých byl uplatněn). V odpovědi je navíc kind (general, personal dárek zákazníkovi, birthday) a loyalty_card_id; osobní kupóny se zakládají jen v administraci z karty zákazníka.
Cenové akce (modul Cenové akce): POST /promotions s poli name, type (price akční cena, amount sleva v Kč, percent sleva v %, qty_percent množstevní sleva od min_qty kusů, nplus akce min_qty + free_qty zdarma), value, min_qty, free_qty, qty_scope (product za každý produkt zvlášť, promotion dohromady), loyalty_only (jen pro držitele věrnostní karty), starts_at, ends_at, product_ids, category_ids (alespoň jedno), note, is_active. Při PATCH se seznam produktů a kategorií nahradí celý, když ho pošlete.
Nejčastější otázky#
- Program dostává 401, klíč jsem právě zkopíroval. Zkontrolujte, že posíláte celý klíč (53 znaků, začíná
eetk_) v hlavičceAuthorization: Bearer …a že klíč není odvolaný nebo prošlý (seznam v menu API). V logu požadavků je u řádku kód chyby. - Dostávám 403
module_disabled. Buď je vypnutý modul API (menu Moduly), nebo modul té části, kterou voláte (např. Sklad). V odpovědi je vmodule, který to je. - Potřebuji vytvářet účtenky z e-shopu. API doklady nevytváří; prodej se eviduje na pokladně. E-shop může do pokladny posílat katalog a sklad, pokladna zpět prodeje.
- Jak zjistím nové doklady bez stahování všeho?
GET /sales?since_id=<poslední id>; podrobnosti v části Stránkování a stahování změn. - Může API volat prohlížeč (JavaScript na našem webu)? Ne, klíč by byl veřejně čitelný. Volejte API ze serveru.
- Kde vidím, co program dělal? V menu API → Log požadavků (90 dní). Zápisy jsou i v audit logu jako „API klíč název“.
- Změní se API v budoucnu? Adresa obsahuje verzi (
v1). Nová pole v odpovědích mohou přibývat, stávající se nemění ani neodebírají; nekompatibilní změny přijdou jen jakov2s předstihem oznámeným v administraci.