Životní cyklus dokladu a zaúčtování

Vystavit doklad a zaúčtovat ho jsou v API dvě různá volání. Mezi nimi doklad existuje, jde ho číst i měnit, ale v účetnictví firmy po něm není stopa.

Vystavení není zaúčtování

POST doklad jen založí. Odpověď 201 vrací kompletní detail včetně dopočtených částek a přiděleného čísla — do účetního deníku se ale nic nezapsalo. U dokladů, které mají pole accounted, je v odpovědi false.

Do účetnictví doklad převede až samostatné volání:

curl -s -X PUT https://online.iucto.cz/api/1.3/invoice_issued/13290/account \
  -H "X-Auth-Key: $IUCTO_API_KEY"

Požadavek nemá tělo. Odpověď 200 vrací detail dokladu, teď už s accounted: true.

Rozdělení na dva kroky je záměrné: mezi vystavením a zaúčtováním má integrace prostor doklad zkontrolovat, doplnit zaúčtování položek nebo ho zase smazat. Po zaúčtování se stejný doklad zaúčtovat podruhé nedá — vrátí 400 s hláškou Již zaúčtovaný doklad.

Jediný doklad, který se do deníku dostane sám, je přímé zaúčtování. Zapisuje se tam rovnou při vytvoření a žádnou akci /account nemá.

Který zdroj má `/account`

Akci /account má osm zdrojů. U pěti z nich se výsledek pozná podle pole accounted, u zbylých tří toto pole neexistuje.

Zdroj	Endpoint	Pole `accounted`
Faktury vydané	`PUT /invoice_issued/{id}/account`	ano
Opravné daňové doklady vydané	`PUT /creditnote_issued/{id}/account`	ano
Faktury přijaté	`PUT /invoice_received/{id}/account`	ano
Opravné daňové doklady přijaté	`PUT /creditnote_received/{id}/account`	ano
Interní předpisy nákladů	`PUT /direct_expense/{id}/account`	ano
Platby vydané	`PUT /payment_issued/{id}/account`	ne
Platby přijaté	`PUT /payment_received/{id}/account`	ne
Bankovní pohyby	`PUT /bank_transaction/{id}/account`	ne

Sedm z nich vrací detail zaúčtovaného dokladu. Výjimkou je bankovní pohyb: tam /account z pohybu vytvoří platbu a vrací přehled plateb, které vznikly. Funguje jen u pohybu spárovaného s dokladem.

Zdroje, které /account nemají:

Objednávky přijaté i vydané — položky objednávky zaúčtování vůbec nenesou.
Zálohové faktury vydané i přijaté — zálohová faktura není daňový doklad a do deníku se nezapisuje. Do účetnictví ji dostane až platba, která ji hradí, viz Zálohové faktury.
Přímé zaúčtování — zapisuje se do deníku rovnou.

Filtr accounted=true nebo accounted=false v seznamu funguje u těch pěti zdrojů, které pole mají. Bez filtru se vrací zaúčtované i nezaúčtované.

Co musí být splněné, aby zaúčtování prošlo

Zaúčtování projde jen tehdy, když každá položka dokladu má vyplněné zaúčtování — jak se zadává, popisuje Zaúčtování položek.

Nad rámec toho platí dvě upřesnění:

U plátce DPH je vattype_id povinné vždy, i když se položka účtuje přes účty.
Když se účtuje přes účty a položka má nenulovou sazbu DPH, musí mít vyplněný i vat_chart_id.

Když některá položka nevyhoví, vrátí se 400 s hláškou Chybějící parametry pro zaúčtování. Doklad zůstane nezaúčtovaný a jde ho opravit přes PUT a zaúčtovat znovu.

Zaúčtování může skončit chybou i z důvodů, které s položkami nesouvisejí:

Kód	Hláška	Příčina
`400`	Doklad je smazaný, nebo účetní období, či období DPH je uzavřeno.	doklad je smazaný nebo mimo otevřené období
`400`	Již zaúčtovaný doklad	doklad je zaúčtovaný
`400`	Zaúčtovat lze pouze doklady z letošního roku…	zkušební tarif, doklad z minulého roku
`402`	(zpráva o limitu dokladů)	vyčerpaný limit dokladů v tarifu

Kód 402 znamená „tohle nemáte zaplacené", ne chybu v požadavku — rozdíl proti 403 vysvětluje 402 vs. 403.

Dva nezávislé zámky: účetní období a období DPH

Otevřenost období hlídají dvě samostatná data na účetním období firmy — datum uzavření účetního období a datum uzávěrky DPH. Doklad se považuje za editovatelný jen tehdy, když jeho date spadá do období, které není uzavřené účetně a zároveň leží za datem uzávěrky DPH. Zavřít se dá jen jedno z nich a doklad je pak stejně zamčený.

Kód odpovědi se liší podle toho, co s dokladem děláte:

Operace	Kód
Vytvoření (`POST`) s datem mimo otevřené období	`400` — Záznam musí spadat do otevřeného účetního, případně DPH období.
Editace (`PUT`) a smazání (`DELETE`)	`403` — Doklad je smazaný, nebo účetní období, či období DPH je uzavřeno.
Zaúčtování (`PUT /…/account`)	`400` — text hlášky stejný jako u `403`

Text hlášky je u editace i zaúčtování stejný, stavový kód a tvar těla ne: 403 nese holý řetězec, 400 u zaúčtování holé pole hlášek — viz Tvary chybového těla. Kód, který uzávěrku ošetřuje, musí počítat s obojím.

Kontrola výsledku v účetním deníku

Účetní deník je jediné místo, kde se dá ověřit, co zaúčtování skutečně vytvořilo. Zápisy k jednomu dokladu vytáhnete filtrem na typ a ID dokladu:

curl -s "https://online.iucto.cz/api/1.3/journal?document_type=FV&document_id=13290" \
  -H "X-Auth-Key: $IUCTO_API_KEY"

Odpověď je pro přehlednost zkrácená — chybí v ní druhý zápis (řádek s daní, chartaccount_dal: 64 a price: 1260.0), vnořená protistrana (customer, supplier) a pole department_id, contract_id, document_variable_symbol, document_maturity_date a item_variable_symbol:

{
  "pageCount": 1,
  "page": 1,
  "pageSize": 2,
  "_embedded": {
    "journal": [
      {
        "_links": { "self": { "href": "/1.3/journal/34717969" } },
        "id": 34717969,
        "document_type": "FV",
        "document_id": 13290,
        "document_sequence_code": "FV20260114",
        "parent_document_type": null,
        "parent_document_id": null,
        "date": "2026-08-13",
        "date_vat": "2026-08-13",
        "date_expense": "2026-08-13",
        "chartaccount_md": 57,
        "chartaccount_dal": 1,
        "text": "Konzultace — srpen 2026",
        "price": 6000.0,
        "vat_type_id": 1,
        "vat": 21
      }
    ]
  }
}

Co v odpovědi hledat:

document_type a document_id ukazují na doklad, ze kterého zápis vznikl. Kódy typů jsou v Datových typech.
parent_document_type a parent_document_id ukazují na navázaný doklad. U zápisů platby je to faktura, kterou platba hradí; u faktury bývají null.
chartaccount_md a chartaccount_dal jsou ID účtů z účtové osnovy, ne čísla účtů. Překlad vrací Účty účetní osnovy.
figure je jen v detailu zápisu a říká, jaká částka se zaúčtovala — vat_base u řádku se základem daně, vat u řádku s daní.

Jeden doklad se do deníku promítne několika řádky — zvlášť základ, zvlášť daň, zvlášť zaokrouhlení. Faktura v ukázce vychází na celé koruny, takže řádek se zaokrouhlením nemá.

Deník je jen pro čtení

GET /journal a GET /journal/{id} jsou jediné operace, které zdroj má. Zápis do deníku přes API nejde — nepodporovaná metoda končí 405 s prázdným tělem. Zápisy tam dostane jen zaúčtování dokladu nebo přímé zaúčtování.

Jak opravit zaúčtovaný doklad

Zaúčtování je jednosměrná operace: žádný endpoint, který by doklad z účetního deníku vyjmul a nechal ho existovat dál, v API není.

Když je zaúčtovaný doklad špatně, jsou dvě cesty:

Věcná oprava — vystavte opravný daňový doklad. Původní doklad zůstane v účetnictví beze změny, oprava je samostatný doklad, který se také zaúčtuje.
Smazání dokladu — DELETE odstraní i jeho zápisy z deníku. Jde to jen dokud je doklad v otevřeném období a nevisí na něm jiný záznam. Pro doklad odeslaný do EET to neplatí vůbec, viz níž.

Smazání a stav `deleted`

DELETE na doklad vrací 204 No Content a tělo nemá. Co se s dokladem stane dál, závisí na jeho pozici v číselné řadě: buď se z databáze odstraní úplně, nebo se jen označí jako smazaný a jde ho dál číst. Integrace nesmí předpokládat ani jedno.

Praktické důsledky:

Ze seznamu smazaný doklad zmizí. Výchozí chování je, že se smazané záznamy nevrací. Najdete je jen s parametrem deleted=true; ten naopak vrátí výhradně smazané.
Detail může, ale nemusí fungovat. U logicky smazaného dokladu vrátí GET /<doklad>/{id} stav 200 a v odpovědi je deleted: true. U fyzicky odstraněného přijde 404.
Smazaný doklad už nejde měnit. Editace i další smazání vrací 403 s hláškou Doklad je smazaný, nebo účetní období, či období DPH je uzavřeno.
Navázaný záznam smazání blokuje. Když na dokladu visí jiný záznam — typicky úhrada nebo faktura, ze které je záloha odečtená —, vrátí se 403 s hláškou Nelze smazat záznam. Nejdřív je potřeba odstranit vazbu.
Doklad odeslaný do EET nejde editovat ani smazat. Odpověď je 403 s hláškou Nelze upravit doklad, který byl odeslán do EET… a jediné řešení je opravný daňový doklad. Podrobnosti popisuje EET.

Shrnutí dráhy dokladu

Fáze	Volání	Stav	Co ještě jde
Vznik	`POST /<doklad>`	`accounted: false`, `deleted: false`	editace, smazání, zaúčtování
Zaúčtováno	`PUT /<doklad>/{id}/account`	`accounted: true`	editace, smazání (zápisy v deníku se přepočítají, resp. zmizí)
Smazáno	`DELETE /<doklad>/{id}`	`deleted: true`, nebo záznam už neexistuje	nanejvýš čtení detailu
Období uzavřeno	—	beze změny	jen čtení

Kam dál

Co platí pro všechny doklady — zaúčtování položek, neplátci DPH, EET, One Stop Shop
Zálohové faktury a jejich odečtení — doklad, který se nezaúčtovává
Chyby a jak je číst — stavové kódy a tvary chybového těla
Účetní deník a Přímé zaúčtování v referenci

Vystavení není zaúčtování​

Který zdroj má /account​

Co musí být splněné, aby zaúčtování prošlo​

Dva nezávislé zámky: účetní období a období DPH​

Kontrola výsledku v účetním deníku​

Jak opravit zaúčtovaný doklad​

Smazání a stav deleted​

Shrnutí dráhy dokladu​

Kam dál​