Formát dat a konvence

Jak API zapisuje částky, měny, datumy a období, jak se posílá tělo požadavku a jak se stránkují seznamy.

Ověřeno 28. září 2026 proti kódu API.

Tělo požadavku

Zápisy přijímají JSON s hlavičkou Content-Type: application/json. Operace, které zakládají nebo upravují záznam, čtou jeho pole z kořenového objektu pojmenovaného podle záznamu, například document, partner, entity, bank_account, employee nebo trip. Reference uvádí kořen v tabulce Tělo požadavku jako první část cesty pole (například document.issue_date). Pole mimo kořen, jako issue: true u dokladu, stojí vedle něj. Ostatní operace čtou parametry přímo, například amount u úhrady.

Kořenový objekt a pole vedle něj

{
  "document": { "kind": "invoice_out", "partner_id": 1, "issue_date": "2026-09-28" },
  "issue": false
}

Soubory se posílají jako multipart/form-data (viz Soubory, importy a opakování). Stejná pole lze poslat i jako formulář. Pravdivostní hodnoty ale spolehlivě přijímá jen JSON: u některých operací se text false z formuláře bere jako zapnuto.

Částky, měny a kurzy

Částky jsou čísla JSON (například 15972.0) zaokrouhlená na haléře, v měně dokladu (pole currency, výchozí CZK).
Pole končící _czk jsou v korunách, přepočtené kurzem dokladu exchange_rate (počet Kč za jednu jednotku měny).
U dokladu v cizí měně posílejte exchange_rate sami. Založení ani úprava dokladu kurz ČNB nedoplní a bez něj uloží kurz 1. Kurz ČNB doplňuje editor v aplikaci, import ISDOC (když ho soubor neuvádí) a opakované faktury.
DPH se počítá z rekapitulace podle sazeb (§ 37 zákona o DPH) a zaokrouhluje se na haléře. Celkovou částku dokladu v Kč zaokrouhlí na celé koruny podle nastavení firmy settings.round_total (always, cash = jen při platbě hotově, never); přijaté doklady jen při platbě hotově. Rozdíl je v poli rounding.

Kurzy ČNB k datu vrací bez přihlášení sdílené API TechTools /cnb-api/rates?date=RRRR-MM-DD, které používá i editor dokladu. Kurz v něm platí za amount jednotek měny (u některých měn za 100), na jednu jednotku ho přepočtěte sami.

Datumy, roky a období

Zápis datumů a období
Údaj	Formát	Příklad
Datum	ISO 8601 `RRRR-MM-DD`	`2026-09-28`
Datum a čas	ISO 8601 v UTC	`2026-09-28T10:00:00.000Z`
Rok	celé číslo; hodnotu mimo 2000–2100 API zarovná na nejbližší mez	`year=2026`
Období DPH	`period` jako měsíc `RRRR-MM` nebo čtvrtletí `RRRR-Qn`, případně `year` s `month` nebo `quarter`	`period=2026-08`, `period=2026-Q3`
Měsíc JMHZ	`year` a `month` (1–12); odpověď vrací `period` jako `RRRR-MM`	`year=2026&month=8`
Rozsah	`from` a `to` jako datum; balíček pro účetní a platby úřadům přijmou i měsíc `RRRR-MM`	`from=2026-01-01&to=2026-06-30`

Bez parametru year pracují sestavy s aktuálním rokem. U firmy s hospodářským rokem znamená year=2026 dvanáct měsíců od měsíce fiscal_year_start roku 2026. Neplatné datum vrátí 400. Neplatné daňové období dnes vrací 500, reference to u daňových operací uvádí.

Stránkování a velké seznamy

Stránkované seznamy přijímají page (od 1) a vracejí total, page, per a rows. Velikost stránky se liší podle seznamu:

Stránky a limity seznamů
Seznam	Velikost stránky	Poznámka
Doklady	`per` 1–500, výchozí 100	vrací i `sums` za celý výběr
Účetní deník	`per` 1–1000, výchozí 200
Bankovní pohyby	pevně 200
Historie změn	pevně 100	bez pole `per` v odpovědi
Žádosti o podklady	bez stránek	nejvýš 500 řádků, pak `truncated`
Fronta úkolů	bez stránek	nejvýš 1000 řádků, pak `truncated`
Klienti	bez stránek	nejvýš 200 firem
Kontakty	bez stránek	nejvýš 500 kontaktů
Cestovní náhrady	bez stránek	nejvýš 500 cest
Podání	bez stránek	nejvýš 200 nejnovějších
Archiv výpisů	bez stránek	nejvýš 120 výpisů

Ostatní seznamy stránky nemají a vracejí celý obsah. Pokud má operace vlastní omezení počtu, uvádí ho reference v řádku Limity.

Jazyk a texty

Chybové zprávy, popisky (například kind_label nebo vat_status_label) a upozornění jsou česky. Texty se mohou měnit. Program by se měl rozhodovat podle stavového kódu HTTP, pole code (pokud ho chyba má) a hodnot jako status nebo kind, ne podle textu.