Přeskočit na hlavní obsah

Řešení potíží

Kontrolní seznamy k chybám, na které se u integrace naráží nejčastěji. Stavové kódy, tvary chybového těla a přehled hlášek jsou na stránce Chyby a jak je číst.

401 — Unauthorized​

Klíč chybí, je překlepnutý, nebo patří jiné firmě.

  • Hlavička se jmenuje přesně X-Auth-Key (ne Authorization, ne X-Api-Key).
  • Klíč je vázaný na uživatele v konkrétní firmě. Když spravujete víc firem, máte víc klíčů a nedají se zaměňovat.
  • Po odebrání oprávnění uživateli přestane fungovat i jeho klíč.

402 a 403 — operace se neprovede​

Oba kódy znamenají, že požadavek je v pořádku, ale neprovede se: 403 je „tohle nejde udělat" (uzavřené období, vazba na jiný záznam, EET, chybějící oprávnění), 402 je „tohle nemáte zaplacené" (zdroj mimo tarif, vyčerpaná kvóta dotazů). Rozdíl, příčiny obou kódů a past s uzavřeným obdobím, kde zaúčtování vrací 400 místo 403, jsou v sekci 402 vs. 403.

400 — Bad Request​

Chyba ve tvaru nebo obsahu požadavku. Kontrolní seznam:

  1. Tělo požadavku není prázdné. Server čte syrové tělo bez ohledu na Content-Type, ale prázdné tělo odmítne hláškou „Tělo požadavku je prázdné". Hlavičku Content-Type: application/json posílejte tak jako tak.
  2. Datumy ve formátu YYYY-mm-dd. Ne 12.8.2026, ne ISO s časem.
  3. bank_account u převodu. Pro payment_type transfer a creditcard je povinný; pro cash, cashondelivery a reciprocity může být null.
  4. vatid u plátce DPH. Kombinace vat_payer: true bez vatid neprojde.
  5. Čísla účtu ve správném tvaru. account_number1 až 4 u kontaktu projdou jen jako IBAN, nebo ve tvaru předčíslí-číslo/kód banky.

Doklad se vystavil, ale nejde zaúčtovat​

PUT /invoice_issued/{id}/account vyžaduje, aby každá položka měla vyplněné zaúčtování — viz Zaúčtování položek. Když integrace položky posílá bez nich, doklad vznikne, ale zaúčtovat ho půjde až po doplnění.

Odpověď je prázdná / není to JSON​

  • GET /invoice_issued/{id}/pdf vrací binární PDF, ne JSON.
  • DELETE vrací 204 No Content — parsovat tělo nemá smysl.

Vyčerpaná kvóta dotazů​

Po vyčerpání kvóty vrací API 402, bez hlavičky Retry-After a bez kódu 429. Kolik dotazů má který tarif a jak je šetřit, je v Limitech a kvótách.

Komunikace musí probíhat přes HTTPS​

Volání na http:// API odmítne. Přesměrování nespoléhejte — knihovny při redirectu často zahodí hlavičky včetně X-Auth-Key a z chyby se pak stane záhadná 401.

Kam dál​