Číselníky

Řada polí na dokladech a kontaktech nepřijímá libovolnou hodnotu, ale kód nebo ID z číselníku. Tahle stránka říká, které pole čerpá odkud, které hodnoty jsou dané napevno a které se musí načíst z API.

Pole → endpoint

Tabulka platí pro celé API 1.3. Sloupec Endpoint je odkaz do reference, sloupec Cesta je to, co se skutečně volá.

Pole	Kde se vyskytuje	Endpoint	Cesta
`vattype_id`	položky dokladů, ceníkové karty	Typy DPH	`GET /vat_type?doctype=…`
`chart_account_id`	položky dokladů, ceníkové karty, bankovní účty	Účty účetní osnovy	`GET /chart_account`
`vat_chart_id`	položky dokladů, ceníkové karty	Účty DPH	`GET /vat_chart`
`accountentrytype_id`	položky dokladů	Typy účetních položek	`GET /accountentry_type?doctype=…`
`payment_type`	doklady	Metody plateb	`GET /payment_type`
`bank_account`	doklady	Bankovní účty	`GET /bank_account`
`rounding_type`	doklady	Způsoby zaokrouhlení	`GET /rounding_type`
`currency`	doklady, platby, bankovní účty, ceníkové karty	Měny	`GET /currency`
`country`	adresa zákazníka, dodavatele a firmy	Země	`GET /country`
`preferred_payment_method`	zákazník	Preferované metody platby	`GET /preferred_payment_method`
`vat`	položky dokladů	Sazby DPH	`GET /vat_rates?date=…`
`document_state_id`	doklady	Stavy dokladů	`GET /document_state`

Rozdíl mezi vattype_id/accountentrytype_id a chart_account_id/vat_chart_id je způsob zadání zaúčtování. Jsou to dvě alternativy, které se nemíchají — viz Zaúčtování položek.

Dva z dvanácti nejsou jen ke čtení

Deset číselníků výše umí jen GET. Bankovní účty a Stavy dokladů jsou plnohodnotné zdroje s POST, PUT i DELETE — obsah si tam firma spravuje sama a mění se častěji než zbytek.

Pevné výčty: hodnoty znáte předem

Čtyři pole mají uzavřenou množinu hodnot, kterou aplikace validuje. Nemá smysl na ně volat API — hodnoty jsou tady a v referenci jako enum. Endpoint u nich slouží jen k dotažení českých popisků do vlastního uživatelského rozhraní.

`payment_type` — způsob úhrady dokladu

Hodnota	Popis z API
`transfer`	Bankovním převodem
`cash`	Hotově
`cashondelivery`	Dobírka
`reciprocity`	Reciproce
`creditcard`	Platební kartou

Pro transfer a creditcard je na dokladu povinné pole bank_account; pro cash, cashondelivery a reciprocity může být null.

Na platbách je množina užší

Celý výčet platí jen pro doklady. Na platbách přijatých i vydaných aplikace pouští pouze transfer a cash — cashondelivery, reciprocity i creditcard tam skončí chybou 400. U bankovních pohybů je payment_type docela jiné pole: nese směr platby, tedy in, nebo out.

`rounding_type` — zaokrouhlení částek

Hodnota	Popis z API
`none`	žádné
`round`	zaokrouhlit
`up`	zaokrouhlit nahoru
`down`	zaokrouhlit dolů

Když se rounding_type nevyplní, použije se nastavení firmy.

`preferred_payment_method` — preferovaná platba zákazníka

Hodnota	Popis z API
`transfer`	Bankovním převodem
`cash`	V hotovosti
`proforma`	Proforma
`check`	Šekem
`creditcard`	Platební kartou
`cashondelivery`	Dobírka

Množina se překrývá s payment_type, ale není stejná: proforma a check jsou jen tady, reciprocity jen u payment_type. Popisky se navíc liší (cash je „Hotově" u dokladu, ale „V hotovosti" u zákazníka).

`invoice_language` — jazyk tisku faktury

Hodnoty: cs, en, sk, de, pl. Pole je na zákazníkovi a žádný endpoint pro něj neexistuje — výčet je jen v referenci.

Dynamické číselníky: musí se načíst

Zbylé číselníky se liší firmu od firmy, případně podle data nebo typu dokladu. Hodnoty se do kódu zapsat nedají, musí se přečíst z API.

Číselník	Proč je dynamický
Účty účetní osnovy	osnova je vlastní každé firmě, ID účtů se mezi firmami neshodují
Účty DPH	totéž, jde o podmnožinu osnovy
Typy DPH	výsledek závisí na `doctype` a na příznaku `oss`
Typy účetních položek	výsledek závisí na `doctype`, firma si typy zakládá sama
Sazby DPH	závisí na `date` a `country`, sazby se v čase mění
Stavy dokladů	firma si je zakládá a maže sama
Bankovní účty	vlastní seznam každé firmy
Měny	dostupnost závisí na aktivaci rozšíření Účtování v cizích měnách
Země	seznam podle ISO 3166-1 alfa-2 s českými názvy, přes 200 položek

Odpovědi mají tři tvary a jeden parser na ně nestačí.

Pole hodnot — GET /currency a GET /vat_rates:

["AED", "AFN", "ALL", "AMD"]

Mapa klíč → popisek — většina ostatních číselníků, například GET /chart_account, GET /vat_chart, GET /vat_type, GET /accountentry_type nebo GET /country:

{"64": "343000 - Daň z přidané hodnoty (DPH)"}

U map je klíčem to, co se posílá zpátky do API — ID nebo kód. Popisek je jen pro člověka a může se změnit.

HAL kolekce — GET /bank_account a GET /document_state. Nejsou to jen číselníky, ale plnohodnotné zdroje (viz poznámka výše), takže odpovídají stejně jako doklady: záznamy jsou objekty v _embedded pod klíčem podle názvu zdroje a obálka nese stránkování pageCount, page a pageSize.

{
  "_links": { "self": { "href": "/1.3/document_state" } },
  "pageCount": 1,
  "page": 1,
  "pageSize": 2,
  "_embedded": {
    "document_state": [
      { "id": 136, "name": "Nový", "description": null, "visibility": true }
    ]
  }
}

Sazby DPH: povinné datum, volitelná země

GET /vat_rates vyžaduje parametr date; bez něj vrátí 400. Bez country vrací sazby platné v České republice, s ním sazby zadané země EU. Země mimo EU skončí chybou.

GET /vat_rates?date=2026-08-13            → [21, 12, 0]
GET /vat_rates?date=2026-08-13&country=DE → ["0.00", "7.00", "19.00"]

Jak je z ukázky vidět, tvar prvků se mezi variantami liší: české sazby chodí jako čísla seřazená sestupně, sazby zemí EU jako řetězce vzestupně. Hodnoty si proto před porovnáním převeďte na číslo a na pořadí se nespoléhejte.

Typy DPH a typy účetních položek: jen devět typů dokladů

GET /vat_type i GET /accountentry_type mají povinný parametr doctype a přijímají jen prvních devět kódů z tabulky typů dokladů: FV, FP, ZFV, ZFP, ODV, ODP, PV, PP a IPN. Zbylé čtyři — OP, OV, PZ a UD — odmítnou hláškou Parametr 'doctype' není platný. U objednávek to dává smysl: jejich položky zaúčtování nemají, takže není co vybírat.

Pro režim One Stop Shop je potřeba přidat oss=true (od verze API 1.2) — vrátí se jiná sada typů DPH než bez něj.

GET /vat_type?doctype=FV           → {"1": "Zdanitelné plnění v ČR ", "20": "Bez DPH", …}
GET /vat_type?doctype=FV&oss=true  → {"67": "Dodání služby - OSS", "66": "Dodání zboží - OSS"}

Číselníky si cachujte

Číselníky se mění řádově pomaleji než doklady, ale každé jejich načtení stojí jeden dotaz z denní kvóty. Načtěte je jednou při startu aplikace a držte v paměti; volat /currency nebo /payment_type před každou fakturou je nejčastější příčina vyčerpaného limitu.

Praktické rozdělení:

Nevolat vůbec — payment_type, rounding_type, preferred_payment_method a invoice_language, pokud nepotřebujete české popisky. Výčty jsou výše.
Načíst jednou při startu — currency, country, chart_account, vat_chart, bank_account, document_state a dvojice vat_type s accountentry_type pro typy dokladů, které vaše integrace vystavuje.
Načíst podle potřeby s krátkou platností — vat_rates, protože odpověď závisí na datu a zemi. Klíčem cache ať je dvojice date + country.

Když integrace narazí na 402 s vyčerpanou kvótou, projděte Limity a kvóty — cachování číselníků je tam první doporučení.

Kam dál

Datové typy — formáty hodnot a kompletní tabulka typů dokladů
Co platí pro všechny doklady — zaúčtování položek, neplátci DPH, režim OSS
Limity a kvóty — proč se číselníky vyplatí cachovat
První faktura krok za krokem — číselníky v celém flow

Pole → endpoint​

Pevné výčty: hodnoty znáte předem​

payment_type — způsob úhrady dokladu​

rounding_type — zaokrouhlení částek​

preferred_payment_method — preferovaná platba zákazníka​

invoice_language — jazyk tisku faktury​

Dynamické číselníky: musí se načíst​

Sazby DPH: povinné datum, volitelná země​

Typy DPH a typy účetních položek: jen devět typů dokladů​

Číselníky si cachujte​

Kam dál​