Veřejné API TAXY

Přes veřejné REST API si vaše systémy (ERP, e-shop, interní nástroje) načtou z TAXY klienty a jejich doklady včetně vytěžených údajů a souborů. Přístup se ověřuje API klíčem, který vytvoří vlastník nebo administrátor účetní kanceláře.

Napojení na účetní programy (Pohoda, ABRA Flexi, Money S3 a další) API klíč TAXY nepotřebuje. Nastavíte ho u klienta podle návodů v Integrace.

Co API umí

• Klienti — seznam klientů kanceláře, ke kterým má klíč přístup, včetně stavu (aktivní, rozpracovaný, archivovaný).
• Složky — strom složek dokumentů klienta. Kód složky slouží jako filtr ve výpisu dokladů.
• Doklady — typ, složka, stavy (vytěžení, kontrola, schválení, přenos do účetního programu), úhrada, štítky, vytěžené údaje s položkami a zaúčtování.
• Soubor dokladu — krátkodobý odkaz ke stažení souboru dokladu (PDF nebo obrázek).

Odpovědi jsou ve formátu JSON, názvy polí jsou anglicky, časy v UTC (ISO 8601) a data ve tvaru YYYY-MM-DD.

Zapnutí modulu

Když modul vypnete, přestanou fungovat všechny klíče kanceláře. Po opětovném zapnutí fungují dál.

Vytvoření API klíče

API klíče může spravovat jen vlastník nebo administrátor kanceláře. Ostatní účetní místo tabulky klíčů uvidí jen upozornění.

Klíč začíná txy_live_. Po zavření okna ho TAXY už znovu nezobrazí, v tabulce uvidíte jen jeho začátek.

Za koho klíč jedná

Klíč jedná jménem účetního, který ho vytvořil:

• vidí jen klienty, které vidí autor, zúžené na rozsah klíče,
• u těchto klientů vidí stejné složky a doklady jako autor, tedy všechny, i složky Trvalých dokumentů s omezeným přístupem („Jen vybraní“, „Jen administrátoři“).

Klíč přestane fungovat, když:

• autor přestane být vlastníkem nebo administrátorem kanceláře. V tabulce má klíč stav Autor bez role a znovu ho oživí vrácení role Administrátor.
• účet autora v kanceláři deaktivujete nebo odeberete. V tabulce má klíč stav Autor neaktivní. Vytvořte nový klíč pod aktivním účtem a starý zneplatněte.
• klíč zneplatníte, nebo vypnete modul API externí přístup.

Klíč pro dlouhodobé napojení proto vytvářejte pod účtem, který v kanceláři zůstane.

Zneplatnění klíče

V tabulce API klíče klikněte u klíče na Zneplatnit a akci potvrďte. Integrace, které klíč používají, přestanou okamžitě fungovat a akci nelze vrátit. Zneplatněné klíče zobrazíte přepínačem Zobrazit zneplatněné klíče.

Kancelář může mít nejvýše 20 aktivních klíčů. Když je limit vyčerpaný, nejdřív některý klíč zneplatněte.

Ztracený klíč

Klíč nejde znovu zobrazit ani obnovit. Pokud jste ho ztratili nebo máte podezření, že ho zná někdo nepovolaný, zneplatněte ho a vytvořte nový. Nový klíč pak vyměňte v systému, který API používá.

Rychlý start

Klíč posílejte v hlavičce Authorization každého požadavku. V ukázkách nahraďte VAS_API_KLIC svým klíčem. Identifikátory klientů a dokladů získáte z odpovědí předchozích dotazů.

Seznam klientů, ke kterým má klíč přístup:

curl -i "https://api.taxy.cz/api/public/v1/clients" \
  -H "Authorization: Bearer VAS_API_KLIC"

Doklady klienta změněné od zadaného okamžiku, včetně dokladů přesunutých do koše:

curl -sS "https://api.taxy.cz/api/public/v1/clients/{client_id}/documents?updated_since=2026-09-01T00:00:00Z&include_trashed=true" \
  -H "Authorization: Bearer VAS_API_KLIC"

Detail dokladu včetně vytěžených údajů:

curl -sS "https://api.taxy.cz/api/public/v1/documents/{document_id}" \
  -H "Authorization: Bearer VAS_API_KLIC"

Odkaz ke stažení souboru dokladu:

curl -sS "https://api.taxy.cz/api/public/v1/documents/{document_id}/file" \
  -H "Authorization: Bearer VAS_API_KLIC"

Odpověď obsahuje odkaz url s krátkou platností. Kdo odkaz zná, soubor stáhne. Soubor proto stáhněte hned a odkaz neukládejte ani nelogujte.

Stránkování a synchronizace dokladů

Výpis dokladů je stránkovaný. Když má odpověď v poli pagination.has_more hodnotu true, načtěte další stránku se stejnými filtry a s parametrem cursor z pole pagination.next_cursor. Stránka má ve výchozím stavu 50 dokladů, parametrem limit nastavíte nejvýš 100.

Pro pravidelné stahování změn doporučujeme u každého klienta tento postup:

1. První průchod udělejte bez updated_since, s parametrem include_trashed=true.
2. Z první stránky každého průchodu si zapamatujte hodnotu meta.server_time.
3. Projděte všechny stránky a doklady u sebe ukládejte podle id. Nový stav vždy přepíše uložený.
4. Další průchod pošlete s updated_since rovným uloženému meta.server_time mínus 5 minut. Překryv pokryje rozdíly hodin mezi servery.
5. Doklad s is_in_trash: true byl přesunutý do koše. U sebe ho smažte nebo označte.
6. Jednou za čas (např. týdně) udělejte plný průchod bez updated_since a doklady, které v něm nepřišly, u sebe odstraňte. Jen tak se projeví trvale smazané doklady a doklady přesunuté k jinému klientovi.

Všechny filtry a pole popisuje dokumentace API.

Limity

• Každý klíč smí poslat nejvýše 100 požadavků za minutu.
• Stav limitu vracejí hlavičky RateLimit-Limit, RateLimit-Remaining a RateLimit-Reset (počet sekund do konce okna). Curl s přepínačem -i je vypíše.
• Po překročení limitu API odpoví kódem 429 a hlavičkou Retry-After s počtem sekund, po kterých lze požadavek zopakovat. Počkejte uvedenou dobu a pokračujte, počet souběžných požadavků nezvyšujte.
• Kancelář může mít nejvýše 20 aktivních API klíčů.

Bezpečnost

• Klíč používejte jen při komunikaci server-server. Nikdy ho nevkládejte do webové stránky, mobilní aplikace ani do repozitáře.
• Klíč posílejte jen v hlavičce Authorization. V adrese požadavku ho API nepřijme.
• Pro každý systém vytvořte samostatný klíč. Když napojení některého systému ukončíte, zneplatníte jeho klíč a ostatní napojení poběží dál.
• Rozsah klíče omezte jen na klienty, které systém opravdu potřebuje.

Podrobná dokumentace pro vývojáře

• Interaktivní dokumentace API: api.taxy.cz/api/public/v1/docs — všechny endpointy, parametry, pole odpovědí a kódy chyb.
• Specifikace OpenAPI 3.1 (JSON): api.taxy.cz/api/public/v1/openapi.json — pro vygenerování klienta nebo import do Postmanu.

Obě najdete i v nastavení modulu, v sekci Veřejné API.

Řešení potíží

Chybová odpověď má vždy tvar { "success": false, "error": "…", "code": "…" }. Příčinu poznáte podle pole code, text v poli error je jen pro člověka.

Související návody

• Integrace
• Obecný princip