{"openapi":"3.1.0","info":{"title":"Saldo – TechTools účetnictví API","version":"1.1","description":"Czech bookkeeping for s.r.o. and OSVČ: invoices, bank matching, double-entry ledger or daňová evidence, VAT return + kontrolní hlášení + souhrnné hlášení with EPO XML, income tax (DPFO/DPPO), OSVČ insurance, income tax returns (DPFO/DPPO) as EPO XML, OSVČ insurance, payroll, travel allowances and depreciation, plus shared invoice links, attachments, quotes and orders, Fio bank feeds and insolvency checks. Public calculators need no account; bookkeeping endpoints need a personal API key or the TechTools session cookie.","contact":{"url":"https://techtools.cz/tools/ucetnictvi/"}},"servers":[{"url":"https://techtools.cz/ucetnictvi-api"}],"externalDocs":{"url":"https://techtools.cz/tools/ucetnictvi/dokumentace/api/","description":"Dokumentace API v češtině: rychlý start, oprávnění, chyby, limity a reference s příklady"},"tags":[{"name":"Veřejné kalkulátory a číselníky","description":"Sazby, svátky, lhůty, číselníky, QR Platba, čtení ISDOC, kalkulátory a sdílené faktury bez přihlášení."},{"name":"Účet, firmy a přístupy","description":"API klíče, pozvánky, firmy, jejich nastavení, členové a role, historie změn, vyhledání firmy podle IČO."},{"name":"Kontakty","description":"Odběratelé a dodavatelé, načtení z ARES, kontrola v registru plátců DPH a v insolvenčním rejstříku."},{"name":"Doklady a jejich stavy","description":"Faktury, zálohy, dobropisy, pokladní a obchodní doklady; koncept, vystavení, storno, platby a opakování."},{"name":"Schvalování výdajů","description":"Pravidla schvalování přijatých výdajů a rozhodnutí o jednotlivých dokladech."},{"name":"Přílohy a importy","description":"Přílohy dokladů, import ISDOC a převod dat z jiných programů s náhledem a vrácením."},{"name":"Banka, párování a výpisy","description":"Účty a pokladny, import výpisů, archiv originálů, kontrola zůstatků, párování a bankovní pravidla."},{"name":"Účetní knihy a výkazy","description":"Účtový rozvrh, účetní zápisy, sestavy a výkazy, měsíční a roční uzávěrka."},{"name":"Daně, podání a doručenky","description":"DPH, kontrolní a souhrnné hlášení, daň z příjmů, přehledy OSVČ, XML, EPO, evidence podání a doručenek."},{"name":"Majetek, mzdy a cesty","description":"Dlouhodobý majetek a odpisy, zaměstnanci a výplatní pásky, JMHZ a cestovní náhrady."},{"name":"Automatizace, fronta a podklady","description":"Automatizace, přehled klientů, fronta úkolů účetní a žádosti o chybějící podklady."},{"name":"Exporty a předání účetní","description":"Balíček pro účetní, export do POHODY a Money S3, platební příkazy a export dat firmy do JSON."}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Osobní klíč z Nastavení → API a integrace"},"bearer":{"type":"http","scheme":"bearer","description":"Tentýž klíč jako Bearer token"},"session":{"type":"apiKey","in":"cookie","name":"_techtools4_session","description":"Přihlášení v prohlížeči; zápisy navíc potřebují hlavičku X-Saldo: 1 a stejný původ"}},"parameters":{"entity":{"name":"entity_id","in":"path","required":true,"schema":{"type":"integer"},"description":"Účetní jednotka (GET /entities)"},"id":{"name":"id","in":"path","required":true,"schema":{"type":"integer"}},"year":{"name":"year","in":"query","schema":{"type":"integer","minimum":2000,"maximum":2100}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}},"security":[{"apiKey":[]},{"bearer":[]},{"session":[]}],"paths":{"/docs":{"get":{"operationId":"getApiDocs","tags":["Veřejné kalkulátory a číselníky"],"summary":"Stručný popis API ve formátu JSON","description":"Vrátí statický přehled API Salda: konvence (peníze, data, chyby, přihlášení, ochrana proti CSRF, limity), veřejné endpointy s ukázkovými vstupy a stručný seznam endpointů účetních jednotek. Obsah je napsaný v kódu (Ucetnictvi::ApiDocs), nikoli generovaný z rout. Úplný strojový popis operací je v GET /openapi.json.","parameters":[],"security":[],"responses":{"200":{"description":"Objekt s popisem API.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"verejne","x-saldo-access":"public","x-saldo-side-effects":"Nic nezapisuje.","x-saldo-response-fields":[{"name":"name","description":"Název API"},{"name":"version","description":"Verze popisu"},{"name":"description","description":"Stručný popis API (anglicky)"},{"name":"base_url","description":"Základní adresa https://techtools.cz/ucetnictvi-api"},{"name":"ui","description":"Adresa aplikace Saldo"},{"name":"conventions","description":"Konvence: money, dates, errors, auth, csrf, rate_limits"},{"name":"public_endpoints","description":"Veřejné endpointy s ukázkovými vstupy kalkulaček"},{"name":"account_endpoints","description":"Stručný přehled endpointů, které vyžadují přihlášení"},{"name":"disclaimer","description":"Upozornění, že výpočty nejsou daňovým poradenstvím"}]}},"/openapi.json":{"get":{"operationId":"getOpenApi","tags":["Veřejné kalkulátory a číselníky"],"summary":"Popis API ve formátu OpenAPI 3.1","description":"Vrátí popis API ve formátu OpenAPI 3.1 (JSON) pro generátory klientů a AI agenty. Routa nepřijímá příponu formátu, cesta je vždy přesně /openapi.json.","parameters":[],"security":[],"responses":{"200":{"description":"Dokument OpenAPI 3.1: info, servers, components (securitySchemes apiKey, bearer a session), paths.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"verejne","x-saldo-access":"public","x-saldo-side-effects":"Nic nezapisuje."}},"/rates":{"get":{"operationId":"getRates","tags":["Veřejné kalkulátory a číselníky"],"summary":"Zákonné sazby a konstanty pro rok","description":"Vrátí všechny zákonné sazby a konstanty, se kterými počítají výpočty Salda (DPH, daň z příjmů, pojistné OSVČ, mzdy, paušální daň, cestovní náhrady, odpisy, repo sazby ČNB), sloučené ze společných a ročních souborů, se zdroji a právním základem. Pole years uvádí roky, pro které Saldo sazby má; jiný rok skončí chybou 422. reviewed_on je den poslední kontroly sazeb proti předpisům.","parameters":[{"name":"year","in":"query","required":false,"description":"Rok sazeb, výchozí je aktuální rok. Hodnota mimo 2000–2100 se posune na nejbližší mez, nečíselná hodnota znamená aktuální rok. Sazby existují jen pro roky z pole years (nyní 2024–2026).","schema":{"type":"integer","minimum":2000,"maximum":2100},"example":2026}],"security":[],"responses":{"200":{"description":"Rok, dostupné roky, datum kontroly a strom sazeb podle oblastí.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Pro zadaný rok Saldo sazby nemá (zpráva „Pro rok … nejsou k dispozici zákonné sazby“)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"verejne","x-saldo-access":"public","x-saldo-side-effects":"Nic nezapisuje.","x-saldo-errors":[{"status":422,"when":"Pro zadaný rok Saldo sazby nemá (zpráva „Pro rok … nejsou k dispozici zákonné sazby“)"}],"x-saldo-response-fields":[{"name":"year","description":"Rok, pro který jsou sazby vráceny"},{"name":"years","description":"Roky, pro které Saldo sazby má"},{"name":"reviewed_on","description":"Datum poslední kontroly sazeb proti předpisům (YYYY-MM-DD)"},{"name":"rates","description":"Sazby podle oblastí: general, vat, income_tax, osvc, employees, flat_tax, corporate, travel, foreign_travel, depreciation, repo_rates"}]}},"/holidays":{"get":{"operationId":"getHolidays","tags":["Veřejné kalkulátory a číselníky"],"summary":"Státní svátky v Česku pro rok","description":"Vrátí data státních svátků a ostatních svátků podle zákona č. 245/2000 Sb. v daném roce, seřazená podle data: 11 pevných svátků, Velký pátek a Velikonoční pondělí. Saldo podle nich posouvá lhůty na nejbližší následující pracovní den. Seznam neobsahuje názvy svátků a Velký pátek vrací pro každý rok, i když je svátkem až od roku 2016.","parameters":[{"name":"year","in":"query","required":false,"description":"Rok, výchozí je aktuální. Hodnota mimo 2000–2100 se posune na nejbližší mez, nečíselná hodnota znamená aktuální rok.","schema":{"type":"integer","minimum":2000,"maximum":2100},"example":2026}],"security":[],"responses":{"200":{"description":"Rok a seřazené pole dat svátků.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"verejne","x-saldo-access":"public","x-saldo-side-effects":"Nic nezapisuje.","x-saldo-response-fields":[{"name":"year","description":"Použitý rok"},{"name":"holidays","description":"Data svátků (YYYY-MM-DD) vzestupně"}]}},"/deadlines":{"get":{"operationId":"getDeadlines","tags":["Veřejné kalkulátory a číselníky"],"summary":"Daňové a pojistné lhůty pro zadaný profil","description":"Vrátí kalendář lhůt jednoho poplatníka na kalendářní rok: DPH (přiznání, kontrolní a souhrnné hlášení), daň z příjmů a zálohy, pojistné OSVČ a přehledy, paušální daň, mzdové odvody a roční vyúčtování, daň z nemovitých věcí, silniční daň a účetní závěrka. Lhůta připadající na víkend nebo svátek se posune na nejbližší následující pracovní den (date), zákonný den zůstává v statutory_date. Počítá se vždy s elektronickým podáním; parametr databox jen doplní právní základ. Neznámá hodnota legal_form znamená osvc, neznámá hodnota vat znamená none. Události jsou seřazené podle data, kategorie a klíče.","parameters":[{"name":"year","in":"query","required":false,"description":"Kalendářní rok, výchozí je aktuální. Musí mít sazby (GET /rates → years), jinak 422.","schema":{"type":"integer","minimum":2000,"maximum":2100},"example":2026},{"name":"legal_form","in":"query","required":false,"description":"Právní forma. U sro a as je kontrolní hlášení vždy měsíční, přibudou lhůty účetní závěrky a platí fiscal_year_start.","schema":{"type":"string","enum":["osvc","sro","as"],"default":"osvc"},"example":"osvc"},{"name":"vat","in":"query","required":false,"description":"Vztah k DPH: neplátce, měsíční plátce, čtvrtletní plátce, identifikovaná osoba.","schema":{"type":"string","enum":["none","monthly","quarterly","identified"],"default":"none"},"example":"quarterly"},{"name":"employees","in":"query","required":false,"description":"Má zaměstnance – přidá mzdové odvody, JMHZ a roční vyúčtování.","schema":{"type":"boolean","default":false},"example":true},{"name":"advisor","in":"query","required":false,"description":"Přiznání k dani z příjmů podává daňový poradce (prodloužená lhůta).","schema":{"type":"boolean","default":false}},{"name":"databox","in":"query","required":false,"description":"Má datovou schránku; jen doplní právní základ povinného elektronického podání u přiznání.","schema":{"type":"boolean","default":false}},{"name":"flat_tax","in":"query","required":false,"description":"OSVČ v paušálním režimu – místo přiznání, záloh na daň a pojistného dostane oznámení a měsíční paušální platby. U sro a as se ignoruje.","schema":{"type":"boolean","default":false}},{"name":"recap_statement","in":"query","required":false,"description":"Podává souhrnné hlášení (dodání do jiného státu EU).","schema":{"type":"boolean","default":false}},{"name":"recap_goods","in":"query","required":false,"description":"Čtvrtletní plátce dodává zboží do jiného státu EU – souhrnné hlášení se přidá měsíčně (i bez recap_statement) místo čtvrtletně.","schema":{"type":"boolean","default":false}},{"name":"audit","in":"query","required":false,"description":"Povinný audit (jen sro a as) – prodloužená lhůta přiznání a text lhůty schválení závěrky.","schema":{"type":"boolean","default":false}},{"name":"real_estate","in":"query","required":false,"description":"Přidá přiznání a splátky daně z nemovitých věcí.","schema":{"type":"boolean","default":false}},{"name":"road_tax","in":"query","required":false,"description":"Přidá přiznání a platbu silniční daně.","schema":{"type":"boolean","default":false}},{"name":"fiscal_year_start","in":"query","required":false,"description":"Měsíc začátku hospodářského roku (jen sro a as). Hodnota mimo 1–12 se posune na nejbližší mez.","schema":{"type":"integer","default":1,"minimum":1,"maximum":12}}],"security":[],"responses":{"200":{"description":"Rok, použitý profil (včetně electronic: true) a seřazené události.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Pro zadaný rok Saldo sazby nemá","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"verejne","x-saldo-access":"public","x-saldo-side-effects":"Nic nezapisuje.","x-saldo-errors":[{"status":422,"when":"Pro zadaný rok Saldo sazby nemá"}],"x-saldo-response-fields":[{"name":"year","description":"Kalendářní rok"},{"name":"profile","description":"Použitý profil po doplnění výchozích hodnot"},{"name":"events[].date","description":"Lhůta posunutá na pracovní den"},{"name":"events[].statutory_date","description":"Zákonný den lhůty"},{"name":"events[].shifted","description":"Zda byla lhůta posunuta"},{"name":"events[].key","description":"Stabilní klíč události, např. vat_return_2026_01"},{"name":"events[].title","description":"Název povinnosti"},{"name":"events[].detail","description":"Období, ke kterému se povinnost vztahuje"},{"name":"events[].description","description":"Vysvětlení povinnosti"},{"name":"events[].category","description":"income_tax, vat, insurance, payroll, property, accounts nebo other"},{"name":"events[].basis","description":"Právní základ"}]}},"/codebooks":{"get":{"operationId":"getCodebooks","tags":["Veřejné kalkulátory a číselníky"],"summary":"Číselníky pro formuláře a API","description":"Vrátí všechny číselníky v jednom objektu: druhy a stavy dokladů, režimy DPH, způsoby úhrady, druhy DPH na řádku, nárok na odpočet, právní formy, způsoby vedení účetnictví, vztahy k DPH, výdajové paušály, druhy účtů, role členů, pracovní poměry, zdravotní pojišťovny, invalidity, kategorie a způsoby odpisů majetku, druhy a typy podání, státy EU, měny, jednotky, sazby DPH podle roku, kódy přenesené daňové povinnosti, finanční úřady a odpisové skupiny.","parameters":[],"security":[],"responses":{"200":{"description":"Objekt, jehož klíče jsou názvy číselníků.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"verejne","x-saldo-access":"public","x-saldo-side-effects":"Nic nezapisuje.","x-saldo-response-fields":[{"name":"document_kinds","description":"Druhy dokladů s popisem a klíčem"},{"name":"legal_forms","description":"Právní formy (osvc, sro, as, vos, ks, druzstvo, spolek, other)"},{"name":"bookkeeping_modes","description":"Způsoby vedení (double_entry, tax_records, flat_expenses, flat_tax)"},{"name":"vat_statuses","description":"Vztah k DPH (none, monthly, quarterly, identified)"},{"name":"roles","description":"Role členů (owner, accountant, editor, viewer)"},{"name":"vat_rates","description":"Sazby DPH podle roku"},{"name":"rc_codes","description":"Kódy režimu přenesení daňové povinnosti"},{"name":"tax_offices","description":"Finanční úřady a územní pracoviště"},{"name":"depreciation_groups","description":"Odpisové skupiny s dobou odpisování a sazbami"}]}},"/qr":{"get":{"operationId":"buildQrPayment","tags":["Veřejné kalkulátory a číselníky"],"summary":"Řetězec QR Platby (SPAYD) pro platbu","description":"Sestaví řetězec QR Platby podle standardu SPAYD 1.0 České bankovní asociace, který stačí vykreslit jako QR kód. Ověří IBAN (kontrolní číslice, i zahraniční), měnu, částku, datum a symboly. Text zprávy a jméno příjemce zkrátí na délku podle standardu a znaky mimo ASCII zakóduje.","parameters":[{"name":"iban","in":"query","required":true,"description":"IBAN příjemce; mezery se odstraní a písmena převedou na velká.","schema":{"type":"string"},"example":"CZ6508000000192000145399"},{"name":"amount","in":"query","required":true,"description":"Částka, kladná a nejvýše 9 999 999,99. Přijme i desetinnou čárku a mezery; nečíselná hodnota se bere jako 0 a skončí chybou 422.","schema":{"type":"number"},"example":1210},{"name":"currency","in":"query","required":false,"description":"Kód měny ISO 4217 (tři písmena).","schema":{"type":"string","default":"CZK"},"example":"CZK"},{"name":"vs","in":"query","required":false,"description":"Variabilní symbol, nejvýše 10 číslic.","schema":{"type":"string"},"example":"20260001"},{"name":"ks","in":"query","required":false,"description":"Konstantní symbol, nejvýše 10 číslic.","schema":{"type":"string"}},{"name":"ss","in":"query","required":false,"description":"Specifický symbol, nejvýše 10 číslic.","schema":{"type":"string"}},{"name":"message","in":"query","required":false,"description":"Zpráva pro příjemce; zkrátí se na 60 znaků.","schema":{"type":"string"},"example":"Faktura 20260001"},{"name":"due_date","in":"query","required":false,"description":"Datum splatnosti (YYYY-MM-DD); jiný formát vrátí 400.","schema":{"type":"string","format":"date"},"example":"2026-10-15"},{"name":"name","in":"query","required":false,"description":"Jméno příjemce; zkrátí se na 35 znaků.","schema":{"type":"string"}}],"security":[],"responses":{"200":{"description":"Objekt s řetězcem SPAYD.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Neplatný IBAN („Neplatný IBAN: …“) Částka není kladná („Částka musí být kladná“), a to i když není číslem Částka je vyšší než 9 999 999,99 Neplatný kód měny nebo symbol delší než 10 číslic či s jinými znaky než číslicemi","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"verejne","x-saldo-access":"public","x-saldo-side-effects":"Nic nezapisuje.","x-saldo-errors":[{"status":422,"when":"Neplatný IBAN („Neplatný IBAN: …“)"},{"status":422,"when":"Částka není kladná („Částka musí být kladná“), a to i když není číslem"},{"status":422,"when":"Částka je vyšší než 9 999 999,99"},{"status":422,"when":"Neplatný kód měny nebo symbol delší než 10 číslic či s jinými znaky než číslicemi"}],"x-saldo-response-fields":[{"name":"spayd","description":"Řetězec QR Platby, např. SPD*1.0*ACC:CZ…*AM:1210.00*CC:CZK*X-VS:20260001"}]}},"/isdoc/parse":{"post":{"operationId":"parseIsdoc","tags":["Veřejné kalkulátory a číselníky"],"summary":"Přečte fakturu ve formátu ISDOC","description":"Přečte jeden doklad ISDOC 5.x nebo 6.x a vrátí ho jako JSON: strany, řádky, rekapitulaci DPH, součty a platební údaje. Přijme soubor .isdoc (XML), .isdocx (ZIP s manifestem a přílohami) i PDF s vloženým ISDOC. Soubor lze poslat jako pole file (multipart) nebo přímo jako tělo požadavku. Obsah souboru nikdy nezpůsobí chybu: neplatný soubor vrátí 200 s prázdnými poli a důvodem v prvním prvku warnings. Druh dokladu je vždy z pohledu příjemce (invoice_in, credit_in, proforma_in, advance_in).","parameters":[{"name":"filename","in":"query","required":false,"description":"Název souboru pro hlášení ve warnings, když se soubor posílá jako tělo požadavku.","schema":{"type":"string"}}],"security":[],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"Soubor .isdoc, .isdocx nebo PDF s vloženým ISDOC, nejvýše 10 MB. Místo multipart lze poslat samotný soubor jako tělo (např. Content-Type: application/xml)."}}}}}},"responses":{"200":{"description":"Normalizovaný doklad. U nečitelného souboru jsou pole prázdná a warnings obsahuje důvod.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Nebyl poslán žádný soubor ani tělo požadavku","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"413":{"description":"Soubor je větší než 10 MB","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"verejne","x-saldo-access":"public","x-saldo-side-effects":"Nic nezapisuje.","x-saldo-limits":"Nejvýše 10 MB. ZIP (.isdocx) nejvýše 200 souborů, jeden soubor do 20 MB a celkem do 60 MB po rozbalení; PDF nejvýše 5 000 proudů, 20 MB na proud a 80 MB po dekompresi. Čte vždy jen jeden doklad: z archivu bez manifest.xml vezme první soubor .isdoc (přednostně z kořene archivu), ostatní soubory vrátí jen jako přílohy a do warnings doplní upozornění.","x-saldo-errors":[{"status":400,"when":"Nebyl poslán žádný soubor ani tělo požadavku"},{"status":413,"when":"Soubor je větší než 10 MB"}],"x-saldo-response-fields":[{"name":"format_version","description":"Verze ISDOC ze souboru"},{"name":"document_type","description":"Typ dokladu ISDOC (1 faktura, 2 dobropis, 3 vrubopis, 4 zálohová faktura, 5–6 daňový doklad k záloze, 7 zjednodušený)"},{"name":"kind","description":"Druh dokladu v Saldu z pohledu příjemce"},{"name":"simplified","description":"Zjednodušený daňový doklad (typ 7)"},{"name":"number","description":"Číslo dokladu"},{"name":"uuid","description":"UUID dokladu, je-li platné"},{"name":"issue_date","description":"Datum vystavení"},{"name":"taxable_date","description":"DUZP"},{"name":"due_date","description":"Datum splatnosti"},{"name":"currency","description":"Měna dokladu"},{"name":"exchange_rate","description":"Kurz u cizí měny"},{"name":"vat_applicable","description":"Doklad podléhá DPH (VATApplicable; bez údaje true, u nečitelného souboru null)"},{"name":"note","description":"Poznámka z dokladu"},{"name":"order_reference","description":"Číslo objednávky (ExternalOrderID nebo SalesOrderID)"},{"name":"original","description":"Původní doklad u opravného dokladu (number, uuid, issue_date), jinak null"},{"name":"supplier","description":"Dodavatel: name, ico, dic, street, house_number, city, zip, country, email, phone, register_note"},{"name":"customer","description":"Odběratel ve stejném tvaru"},{"name":"lines","description":"Řádky: description, quantity, unit, unit_price, net, vat, gross, vat_rate, net_czk, vat_czk, reverse_charge"},{"name":"totals","description":"Součty: net, vat, gross, rounding, payable, paid_deposits, by_rate a částky v Kč"},{"name":"payment","description":"method, variable_symbol, constant_symbol, specific_symbol, account_number, bank_code, iban, bic, due_date"},{"name":"attachments","description":"Přílohy z .isdocx (filename, content_type, size), bez obsahu"},{"name":"warnings","description":"Upozornění a důvody, proč něco nešlo přečíst"}]}},"/calc/{calculator}":{"post":{"operationId":"runCalculator","tags":["Veřejné kalkulátory a číselníky"],"summary":"Veřejná kalkulačka daní, pojistného, mezd a náhrad","description":"Spustí jednu z bezstavových kalkulaček podle cesty: DPH, OSVČ, porovnání režimů, paušální daň, daň právnické osoby, mzda, cestovní náhrady, odpisy a úrok z prodlení. Vstupy se posílají jako JSON objekt (Content-Type: application/json) nebo jako formulářová pole. Výsledky počítají se sazbami roku, který kalkulačka použije; pro rok bez sazeb vrátí 422. Nečíselné hodnoty a čísla s více než 15 číslicemi se u částek berou jako 0, nevrátí chybu.","parameters":[{"name":"calculator","in":"path","required":true,"description":"Název kalkulačky. Pomlčky se převádějí na podtržítka, takže fungují i late-interest a flat-tax.","schema":{"type":"string","enum":["vat","osvc","regime","flat_tax","corporate","payroll","travel","depreciation","late_interest"]},"example":"osvc"}],"security":[],"responses":{"200":{"description":"Výsledek výpočtu; tvar podle kalkulačky (viz varianty).","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"description":"Neznámá kalkulačka; zpráva vyjmenuje dostupné názvy","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"422":{"description":"Chybí povinné pole nebo má neplatnou hodnotu, včetně neplatného data; zpráva začíná „Chybí nebo je neplatný parametr:“ Pole má jiný tvar, než kalkulačka čeká (např. objekt místo čísla); zpráva „Parametry mají neplatný tvar – popis vstupů je v /ucetnictvi-api/docs“ Pro rok výpočtu Saldo sazby nemá („Pro rok … nejsou k dispozici zákonné sazby“)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"400":{"description":"Tělo není platný JSON; odpověď sestaví Rails (HTML stránka, s Accept: application/json objekt {status, error}), ne tvar {error} Salda","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"verejne","x-saldo-access":"public","x-saldo-side-effects":"Nic nezapisuje.","x-saldo-limits":"Částky mají nejvýše 15 číslic před desetinnou čárkou, jinak se berou jako 0. Roky jen z GET /rates → years (nyní 2024–2026). Aplikace sama volání bez API klíče neomezuje; s API klíčem platí limit 600 požadavků za minutu na klíč, počítaný zvlášť pro každou skupinu cest.","x-saldo-repeat":"Stejný vstup dává stejný výsledek. Výchozí hodnoty (rok, měsíc, den úhrady) se berou z dnešního data, takže se mohou mezi dny lišit.","x-saldo-errors":[{"status":404,"when":"Neznámá kalkulačka; zpráva vyjmenuje dostupné názvy"},{"status":422,"when":"Chybí povinné pole nebo má neplatnou hodnotu, včetně neplatného data; zpráva začíná „Chybí nebo je neplatný parametr:“"},{"status":422,"when":"Pole má jiný tvar, než kalkulačka čeká (např. objekt místo čísla); zpráva „Parametry mají neplatný tvar – popis vstupů je v /ucetnictvi-api/docs“"},{"status":422,"when":"Pro rok výpočtu Saldo sazby nemá („Pro rok … nejsou k dispozici zákonné sazby“)"},{"status":400,"when":"Tělo není platný JSON; odpověď sestaví Rails (HTML stránka, s Accept: application/json objekt {status, error}), ne tvar {error} Salda"}],"x-saldo-variants":[{"param":"calculator","value":"vat","summary":"DPH ze základu nebo z částky s daní","description":"Spočítá DPH zdola ze základu (net, § 37 písm. a) ZDPH), nebo shora z částky včetně daně (gross, § 37 písm. b) ZDPH). Když je zadané gross, net se ignoruje. Daň se zaokrouhlí na haléře. Sazba se neověřuje; nečíselná sazba znamená 0 %.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"net":{"type":"number","description":"Základ daně; povinný, pokud není zadané gross.","example":1000},"gross":{"type":"number","description":"Částka včetně DPH; když je zadaná, počítá se shora."},"rate":{"type":"number","description":"Sazba DPH v procentech.","default":21,"example":21}}},"example":{"net":1000,"rate":21}}}},"response-fields":[{"name":"rate","description":"Použitá sazba"},{"name":"net","description":"Základ"},{"name":"vat","description":"Daň"},{"name":"gross","description":"Částka s daní"},{"name":"method","description":"Způsob výpočtu (zdola nebo shora) s paragrafem"}],"errors":[{"status":422,"when":"Chybí net i gross"}]},{"param":"calculator","value":"osvc","summary":"Daň a pojistné OSVČ za rok","description":"Spočítá rok OSVČ: daň z příjmů fyzických osob se slevami a daňovým zvýhodněním na děti, sociální a zdravotní pojištění podle přehledů, doplatky, zálohy na další rok, čistý příjem a řádky přiznání DPFO. Výdaje zadejte buď skutečné (expenses), nebo jako výdajový paušál (flat_rate) – právě jedno z nich. Sleva na manžela se přes tuto kalkulačku neuplatní (spouse se bere jen jako ano/ne a sleva vyžaduje příjem manžela a dítě do 3 let; vrátí se jen upozornění). Počet měsíců u dětí se neomezuje.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["income"],"properties":{"year":{"type":"integer","description":"Rok, výchozí je aktuální; musí mít sazby.","example":2026},"income":{"type":"number","description":"Příjmy ze samostatné činnosti za rok.","example":900000},"expenses":{"type":"number","description":"Skutečné výdaje; nezadávejte současně s flat_rate."},"flat_rate":{"type":"integer","description":"Výdajový paušál v procentech; nezadávejte současně s expenses.","enum":[80,60,40,30],"example":60},"months":{"type":"integer","description":"Počet měsíců činnosti v roce.","default":12,"minimum":1,"maximum":12},"main_activity":{"type":"boolean","description":"Hlavní (true) nebo vedlejší (false) samostatná činnost.","default":true},"sickness_insurance":{"type":"boolean","description":"Platí dobrovolné nemocenské pojištění.","default":false},"spouse":{"type":"boolean","description":"Uplatnění slevy na manžela; v této kalkulačce jen vyvolá upozornění, slevu neuplatní.","default":false},"children":{"type":"array","description":"Vyživované děti pro daňové zvýhodnění.","items":{"type":"object","properties":{"order":{"type":"integer","description":"Pořadí dítěte; 3 a vyšší mají sazbu třetího dítěte.","default":1},"months":{"type":"integer","description":"Počet měsíců nároku; hodnota se neověřuje.","default":12},"ztpp":{"type":"boolean","description":"Dítě je držitelem průkazu ZTP/P.","default":false}}}},"disability":{"type":"string","description":"Stupeň invalidity poplatníka pro slevu.","enum":["1","2","3","i","ii","iii","first","second","third"]},"ztpp":{"type":"boolean","description":"Poplatník je držitelem průkazu ZTP/P.","default":false},"deductions":{"type":"object","description":"Nezdanitelné části základu daně: gifts, blood_donations (počet odběrů), mortgage_interest, mortgage_before_2021, mortgage_months, pension, life_insurance, dip, long_term_care. Neznámý klíč vrátí upozornění."},"employment_income":{"type":"number","description":"Příjmy ze závislé činnosti (§ 6 ZDP).","default":0},"paid_advances":{"type":"object","description":"Již zaplacené částky: tax (zálohy na daň), withheld (sražená daň), bonuses (vyplacené měsíční daňové bonusy), sp (zálohy na sociální pojištění), zp (zálohy na zdravotní pojištění)."}}},"example":{"year":2026,"income":900000,"flat_rate":60,"children":[{"order":1}]}}}},"response-fields":[{"name":"expenses","description":"Uplatněné výdaje"},{"name":"expense_method","description":"Způsob výdajů a u paušálu jeho části se stropem"},{"name":"profit","description":"Dílčí základ ze samostatné činnosti"},{"name":"tax_base","description":"Základ daně"},{"name":"deductions","description":"Uplatněné odpočty"},{"name":"tax_before_credits","description":"Daň před slevami"},{"name":"credits","description":"Slevy na dani"},{"name":"child_benefit","description":"Daňové zvýhodnění na děti: celkem, uplatněno jako sleva, bonus"},{"name":"tax","description":"Daň po slevách"},{"name":"bonus","description":"Daňový bonus"},{"name":"tax_withheld","description":"Sražená daň (paid_advances.withheld)"},{"name":"tax_advances_paid","description":"Zaplacené zálohy na daň (paid_advances.tax)"},{"name":"tax_balance","description":"Doplatek (kladný) nebo přeplatek daně"},{"name":"tax_advances","description":"Zálohy na daň na další období"},{"name":"sp","description":"Sociální pojištění: základy, pojistné, sleva, doplatek, nová záloha, nemocenské"},{"name":"zp","description":"Zdravotní pojištění: základy, pojistné, doplatek, nová záloha"},{"name":"total_levies","description":"Daň a pojistné celkem"},{"name":"net_income","description":"Příjmy po výdajích a odvodech"},{"name":"effective_rate","description":"Podíl odvodů na příjmech"},{"name":"form_rows","description":"Hodnoty řádků přiznání DPFO"},{"name":"warnings","description":"Upozornění k výpočtu"}],"errors":[{"status":422,"when":"Chybí income"},{"status":422,"when":"Není zadán právě jeden z expenses a flat_rate („Zadejte buď skutečné výdaje, nebo výdajový paušál“)"},{"status":422,"when":"flat_rate není 80, 60, 40 ani 30 („Neznámý výdajový paušál“)"},{"status":422,"when":"months mimo 1–12 nebo neznámý stupeň invalidity"}]},{"param":"calculator","value":"regime","summary":"Porovnání skutečných výdajů, paušálů a paušální daně","description":"Porovná roční odvody OSVČ (daň, sociální a zdravotní pojištění, případně nemocenské) při skutečných výdajích, při výdajových paušálech a v paušálním režimu, seřadí způsobilé varianty od nejlevnější, označí doporučenou a spočítá úsporu proti současnému režimu. Paušál neodpovídající druhu příjmů a nedostupný paušální režim jsou uvedeny s důvody. Osobní údaje se předávají v objektu profile; main_activity, vat_payer, children a spouse lze poslat i na nejvyšší úrovni a mají přednost. Na rozdíl od kalkulačky osvc lze v profile.spouse poslat objekt s příjmem manžela a slevu tak uplatnit.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["income"],"properties":{"year":{"type":"integer","description":"Rok, výchozí je aktuální; musí mít sazby.","example":2026},"income":{"type":"number","description":"Příjmy ze samostatné činnosti.","example":900000},"expenses":{"type":"number","description":"Skutečné výdaje.","default":0,"example":250000},"main_activity":{"type":"boolean","description":"Hlavní činnost; přepíše profile.main_activity."},"vat_payer":{"type":"boolean","description":"Plátce DPH (vylučuje paušální režim); přepíše profile.vat_payer."},"children":{"type":"array","description":"Děti jako u kalkulačky osvc; přepíše profile.children.","items":{"type":"object"}},"spouse":{"description":"true/false, nebo objekt { income, child_under_three, months, ztpp }; přepíše profile.spouse."},"profile":{"type":"object","description":"Další údaje: income_kind (crafts, trade, other, rental nebo 80/60/40/30, případně objekt { druh: částka } pro smíšené příjmy; výchozí trade s upozorněním), flat_rate (totéž, když chybí income_kind), current_regime (klíč varianty), bookkeeping (tax_records, double_entry, flat_expenses, flat_tax – určí současný režim), employment_income, other_income, partner, insolvency, months, sickness_insurance, disability, ztpp, deductions, starting_business."}}},"example":{"year":2026,"income":900000,"expenses":250000,"profile":{"income_kind":"trade"}}}}},"response-fields":[{"name":"income_kind","description":"Použitý druh příjmů"},{"name":"current","description":"Klíč současného režimu"},{"name":"recommended","description":"Klíč nejlevnější způsobilé varianty"},{"name":"savings","description":"Úspora doporučené varianty proti současné (null, když současná není způsobilá)"},{"name":"options","description":"Varianty (actual_expenses, flat_rate_80/60/40/30 nebo flat_rate_mixed, flat_tax): eligible, rank, total_levies, tax, sp, zp, net_income, reasons, notes, savings_vs_current"},{"name":"summary","description":"Shrnutí doporučení česky"},{"name":"warnings","description":"Upozornění"}],"errors":[{"status":422,"when":"Chybí income nebo je neznámý druh příjmů (income_kind, flat_rate)"}]},{"param":"calculator","value":"flat_tax","summary":"Nárok na paušální daň a pásmo","description":"Ověří, zda poplatník může být v paušálním režimu, a vrátí pásmo s měsíční paušální zálohou rozdělenou na daň, sociální a zdravotní pojištění. Nesplněné podmínky vrátí v reasons. Pro smíšené příjmy lze poslat income_kind jako objekt s částkami podle druhu.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["income"],"properties":{"year":{"type":"integer","description":"Rok, výchozí je aktuální; musí mít sazby.","example":2026},"income":{"type":"number","description":"Roční příjmy ze samostatné činnosti.","example":800000},"income_kind":{"type":"string","description":"Druh příjmů: crafts, trade, other, rental nebo sazba paušálu 80, 60, 40, 30; případně objekt { druh: částka }.","default":"trade","example":"trade"},"vat_payer":{"type":"boolean","description":"Plátce DPH (vylučuje paušální režim).","default":false},"employment":{"type":"boolean","description":"Má příjmy ze závislé činnosti nezdaněné srážkovou daní (vylučuje režim).","default":false},"other_income":{"type":"number","description":"Příjmy z kapitálu, nájmu a ostatní příjmy (nad limit vylučují režim).","default":0}}},"example":{"year":2026,"income":800000,"income_kind":"trade","vat_payer":false}}}},"response-fields":[{"name":"eligible","description":"Zda může být v paušálním režimu"},{"name":"band","description":"Číslo pásma (null, když nesplní limit)"},{"name":"monthly","description":"Měsíční paušální záloha"},{"name":"annual","description":"Roční částka (12 měsíců)"},{"name":"split","description":"Rozdělení měsíční zálohy: tax, social, health"},{"name":"reasons","description":"Důvody, proč režim nelze použít"},{"name":"notes","description":"Poznámky k režimu"},{"name":"basis","description":"Právní základ"}],"errors":[{"status":422,"when":"Chybí income nebo je neznámý druh příjmů („Neznámý výdajový paušál: …“)"}]},{"param":"calculator","value":"corporate","summary":"Daň z příjmů právnické osoby","description":"Spočítá daň z příjmů právnických osob z účetního výsledku hospodaření: připočte daňově neuznatelné náklady, odečte nezdanitelné výnosy, uplatní ztrátu z minulých let, odpočet na výzkum a dary (jen jednotlivé dary od zákonného minima, nejvýše podíl základu), zaokrouhlí základ, vrátí daň, zálohy na další období, doplatek a řádky přiznání DPPO. Úpravy se zařadí na výchozí řádky přiznání.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["accounting_profit"],"properties":{"year":{"type":"integer","description":"Rok, výchozí je aktuální (zdaňovací období končí 31. 12.); musí mít sazby.","example":2026},"accounting_profit":{"type":"number","description":"Účetní výsledek hospodaření před zdaněním (ztráta záporně).","example":1250000},"non_deductible":{"type":"array","description":"Připočitatelné položky.","items":{"type":"object","properties":{"label":{"type":"string","description":"Popis"},"amount":{"type":"number","description":"Částka"}}}},"non_taxable":{"type":"array","description":"Odečitatelné položky.","items":{"type":"object","properties":{"label":{"type":"string","description":"Popis"},"amount":{"type":"number","description":"Částka"}}}},"loss_carryforward":{"type":"number","description":"Daňová ztráta z minulých let k uplatnění.","default":0},"gifts":{"type":"array","description":"Částky jednotlivých darů (lze poslat i jedno číslo).","items":{"type":"number"}},"rd_deduction":{"type":"number","description":"Odpočet na výzkum a vývoj.","default":0},"paid_advances":{"type":"number","description":"Zaplacené zálohy na daň.","default":0},"last_known_tax":{"type":"number","description":"Poslední známá daň pro výpočet záloh; bez ní se použije vypočtená daň."}}},"example":{"year":2026,"accounting_profit":1250000,"non_deductible":[{"label":"Reprezentace","amount":18000}],"gifts":[5000]}}}},"response-fields":[{"name":"increases","description":"Připočtené položky s řádkem přiznání"},{"name":"decreases","description":"Odečtené položky s řádkem přiznání"},{"name":"tax_base","description":"Základ daně před odpočty"},{"name":"loss","description":"Daňová ztráta běžného roku"},{"name":"loss_applied","description":"Uplatněná ztráta z minulých let"},{"name":"rd_applied","description":"Uplatněný odpočet na výzkum a vývoj"},{"name":"base_after_deductions","description":"Základ po odečtení ztráty a odpočtu na výzkum"},{"name":"gifts_applied","description":"Odečtené dary"},{"name":"tax_base_rounded","description":"Zaokrouhlený základ"},{"name":"rate","description":"Sazba daně"},{"name":"tax","description":"Daň"},{"name":"advances","description":"Zálohy: frequency, amount, period, schedule"},{"name":"balance","description":"Daň minus zaplacené zálohy"},{"name":"form_rows","description":"Nenulové řádky přiznání DPPO"},{"name":"warnings","description":"Upozornění (ztráta, malé dary, strop darů)"}],"errors":[{"status":422,"when":"Chybí accounting_profit"}]},{"param":"calculator","value":"payroll","summary":"Výplatní páska zaměstnance za měsíc","description":"Spočítá měsíční mzdu zaměstnance v pracovním poměru (hpp), na dohodu o pracovní činnosti (dpc) nebo o provedení práce (dpp): účast na pojištění, pojistné zaměstnance i zaměstnavatele, zálohu nebo srážkovou daň se slevami a zvýhodněním na děti, čistou mzdu, výplatu s bonusem, náklady zaměstnavatele a předkontace mzdových zápisů.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["gross"],"properties":{"year":{"type":"integer","description":"Rok, výchozí je aktuální; musí mít sazby.","example":2026},"month":{"type":"integer","description":"Měsíc, výchozí je aktuální.","minimum":1,"maximum":12,"example":9},"contract":{"type":"string","description":"Pracovněprávní vztah.","enum":["hpp","dpc","dpp"],"default":"hpp","example":"hpp"},"gross":{"type":"number","description":"Hrubá mzda za měsíc.","minimum":0,"example":52000},"declaration":{"type":"boolean","description":"Zaměstnanec podepsal prohlášení poplatníka.","default":true},"children":{"type":"array","description":"Děti pro daňové zvýhodnění.","items":{"type":"object","properties":{"order":{"type":"integer","description":"Pořadí dítěte"},"ztpp":{"type":"boolean","description":"Dítě s průkazem ZTP/P"},"months":{"type":"array","description":"Čísla měsíců nároku; bez nich se dítě uplatní v každém měsíci","items":{"type":"integer"}}}}},"disability":{"type":"string","description":"Stupeň invalidity zaměstnance (0 = žádná).","enum":["0","1","2","3","first","second","third"]},"ztpp":{"type":"boolean","description":"Zaměstnanec je držitelem průkazu ZTP/P.","default":false},"student":{"type":"boolean","description":"Student (bez minimálního vyměřovacího základu zdravotního pojištění).","default":false},"pensioner_discount":{"type":"boolean","description":"Pracující důchodce se slevou na pojistném.","default":false},"health_minimum_exempt":{"type":"boolean","description":"Neuplatní se minimální vyměřovací základ zdravotního pojištění.","default":false},"agreed_wage":{"type":"number","description":"Sjednaná mzda (pro účast na pojištění u zaměstnání malého rozsahu)."},"ytd_social_base":{"type":"number","description":"Dosavadní roční vyměřovací základ sociálního pojištění (kvůli ročnímu maximu).","default":0}}},"example":{"year":2026,"month":9,"contract":"hpp","gross":52000,"children":[{"order":1}]}}}},"response-fields":[{"name":"insured","description":"Účast na sociálním a zdravotním pojištění"},{"name":"assessment_base","description":"Vyměřovací základy"},{"name":"employee","description":"Pojistné zaměstnance: social, health, total"},{"name":"employer","description":"Pojistné zaměstnavatele: social, health, total"},{"name":"health_min_base_topup","description":"Doplatek do minimálního základu zdravotního pojištění"},{"name":"tax","description":"Daň: základ, sazby, slevy, zvýhodnění na děti, advance, withholding, kind"},{"name":"net","description":"Čistá mzda"},{"name":"payout","description":"K výplatě včetně daňového bonusu"},{"name":"employer_cost","description":"Náklady zaměstnavatele"},{"name":"postings","description":"Předkontace: debit, credit, amount, text"},{"name":"warnings","description":"Upozornění"}],"errors":[{"status":422,"when":"Chybí gross, gross je záporná, neznámý contract, měsíc mimo 1–12 nebo neplatný stupeň invalidity"}]},{"param":"calculator","value":"travel","summary":"Cestovní náhrady za jednu tuzemskou nebo zahraniční cestu","description":"Spočítá cestovní náhrady jedné cesty ze sídla do cíle a zpět: stravné po kalendářních dnech s krácením za poskytnuté jídlo, základní náhradu za použití vozidla, náhradu za pohonné hmoty (bez ceny paliva se použije průměrná cena z vyhlášky), ubytování a ostatní výdaje. U zaměstnance se použije minimální sazba stravného, u OSVČ maximální. Zahraniční stravné se vrátí v cizí měně; do celkové částky se nezapočte, protože kalkulačka nemá kurz. Rok sazeb se bere z data odjezdu; časy bez časového pásma se berou tak, jak jsou zadané.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["departure","arrival"],"properties":{"departure":{"type":"string","format":"date-time","description":"Odjezd, např. 2026-09-21T06:30.","example":"2026-09-21T06:30"},"arrival":{"type":"string","format":"date-time","description":"Návrat; musí být po odjezdu a nejvýše 366 dní od něj.","example":"2026-09-21T19:10"},"destination":{"type":"string","description":"Cíl cesty.","example":"Brno"},"traveller":{"type":"string","description":"Zaměstnanec, nebo OSVČ.","enum":["employee","self_employed"],"default":"employee"},"km":{"type":"number","description":"Ujeté kilometry soukromým vozidlem; bez nich se náhrady za vozidlo nepočítají.","example":420},"vehicle_kind":{"type":"string","description":"Druh vozidla.","enum":["car","motorcycle","truck","electric"],"default":"car"},"consumption":{"type":"number","description":"Spotřeba v litrech (nebo kWh) na 100 km podle technického průkazu.","example":6.1},"fuel":{"type":"string","description":"Palivo; u elektromobilu vždy electricity.","enum":["petrol95","petrol98","diesel","lpg","electricity"],"default":"petrol95","example":"diesel"},"fuel_price":{"type":"number","description":"Doložená cena paliva za jednotku; bez ní průměrná cena z vyhlášky."},"meals":{"type":"array","description":"Poskytnutá jídla, která krátí stravné.","items":{"type":"object","properties":{"date":{"type":"string","format":"date","description":"Den"},"count":{"type":"integer","description":"Počet jídel"}}}},"accommodation":{"type":"number","description":"Výdaje za ubytování.","default":0},"other":{"type":"number","description":"Ostatní nutné výdaje.","default":0},"foreign_country":{"type":"string","description":"Kód cílového státu (ISO 3166-1 alpha-2) u zahraniční cesty; CZ vrátí chybu."},"hours_abroad":{"type":"number","description":"Počet hodin v zahraničí u zahraniční cesty."}}},"example":{"destination":"Brno","departure":"2026-09-21T06:30","arrival":"2026-09-21T19:10","km":420,"vehicle_kind":"car","consumption":6.1,"fuel":"diesel"}}}},"response-fields":[{"name":"duration_hours","description":"Délka cesty v hodinách"},{"name":"per_diem","description":"Tuzemské stravné: band, rate, reductions, amount, days"},{"name":"foreign_per_diem","description":"Zahraniční stravné v cizí měně (amount_czk je null) nebo null"},{"name":"mileage","description":"Základní náhrada: base_rate, km, amount"},{"name":"fuel","description":"Náhrada za pohonné hmoty: type, price, consumption, amount"},{"name":"accommodation","description":"Výdaje za ubytování ze vstupu"},{"name":"other","description":"Ostatní nutné výdaje ze vstupu"},{"name":"total","description":"Celkem v Kč bez zahraničního stravného; u zaměstnance zaokrouhleno"},{"name":"basis","description":"Právní základ"},{"name":"warnings","description":"Upozornění"}],"errors":[{"status":422,"when":"Chybí odjezd nebo návrat, návrat není po odjezdu, nebo cesta trvá déle než 366 dní; tyto zprávy („Zadejte odjezd i návrat“, „Návrat musí být po odjezdu“, „Cesta smí trvat nejvýš 366 dní“) nemají předponu „Chybí nebo je neplatný parametr:“"},{"status":422,"when":"Neznámý druh vozidla, palivo, záporné kilometry nebo náhrady, u zahraniční cesty stát CZ"}]},{"param":"calculator","value":"depreciation","summary":"Daňové a účetní odpisy majetku","description":"Vrátí odpisový plán hmotného majetku. S group spočítá daňové odpisy rovnoměrné nebo zrychlené po letech (§ 30 až 32 ZDP); s useful_life_months účetní odpisy po měsících sečtené po letech, od měsíce po zařazení. Lze zadat obojí; alespoň jedno je povinné.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["price"],"properties":{"price":{"type":"number","description":"Vstupní (pořizovací) cena, kladná.","example":850000},"group":{"type":"integer","description":"Odpisová skupina pro daňové odpisy.","minimum":1,"maximum":6,"example":2},"method":{"type":"string","description":"Rovnoměrné nebo zrychlené daňové odpisy.","enum":["straight","accelerated"],"default":"straight","example":"straight"},"start_year":{"type":"integer","description":"Rok zahájení daňového odpisování, výchozí je aktuální.","example":2026},"disposal_year":{"type":"integer","description":"Rok vyřazení (polovina ročního odpisu); nesmí předcházet start_year."},"useful_life_months":{"type":"integer","description":"Doba použitelnosti v měsících pro účetní odpisy.","minimum":1,"maximum":1200},"in_use_from":{"type":"string","format":"date","description":"Datum zařazení do užívání; povinné s useful_life_months."},"residual":{"type":"number","description":"Zbytková hodnota (0 až cena).","default":0}}},"example":{"price":850000,"group":2,"method":"straight","start_year":2026}}}},"response-fields":[{"name":"tax","description":"Daňové odpisy po letech: year, rate_or_coefficient, kind, amount, deductible, accumulated, remaining"},{"name":"accounting","description":"Účetní odpisy po letech: year, amount, accumulated, remaining"}],"errors":[{"status":422,"when":"Chybí price, nebo group i useful_life_months"},{"status":422,"when":"Neznámá skupina nebo způsob, cena není kladná, rok vyřazení před zahájením"},{"status":422,"when":"useful_life_months mimo 1–1200, chybí nebo je neplatné in_use_from, zbytková hodnota mimo 0 až cenu"}]},{"param":"calculator","value":"late_interest","summary":"Úrok z prodlení a náklady spojené s uplatněním pohledávky","description":"Spočítá zákonný úrok z prodlení podle nařízení vlády č. 351/2013 Sb.: repo sazba ČNB platná první den kalendářního pololetí, v němž prodlení začalo, plus 8 procentních bodů, po celou dobu prodlení; výsledek je rozdělený po pololetích. Mezi podnikateli přidá paušál 1 200 Kč. Zaplaceno do splatnosti znamená nulový úrok. Částka je vždy v Kč.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["principal","due_date"],"properties":{"principal":{"type":"number","description":"Dlužná jistina.","minimum":0,"example":48400},"due_date":{"type":"string","format":"date","description":"Den splatnosti; prodlení začíná následujícím dnem. Nejdříve 31. 12. 2013.","example":"2026-05-15"},"paid_on":{"type":"string","format":"date","description":"Den úhrady, výchozí je dnešek.","example":"2026-09-26"},"business":{"type":"boolean","description":"Závazek mezi podnikateli nebo vůči veřejnému zadavateli (nárok na paušál 1 200 Kč).","default":true}}},"example":{"principal":48400,"due_date":"2026-05-15","paid_on":"2026-09-26"}}}},"response-fields":[{"name":"delay_from","description":"První den prodlení (null bez prodlení)"},{"name":"days","description":"Počet dní prodlení"},{"name":"reference_date","description":"Rozhodný den pro repo sazbu"},{"name":"repo_rate","description":"Repo sazba ČNB"},{"name":"rate","description":"Roční sazba úroku z prodlení"},{"name":"periods","description":"Pololetí: from, to, days, rate, interest"},{"name":"interest","description":"Úrok celkem"},{"name":"recovery_cost","description":"Paušální náklady 1 200 Kč nebo 0"},{"name":"basis","description":"Právní základ"}],"errors":[{"status":422,"when":"Chybí principal nebo due_date, datum je neplatné nebo jistina záporná"},{"status":422,"when":"Data mimo roky 2000–2100 nebo od sebe víc než 30 let"},{"status":422,"when":"Splatnost před 31. 12. 2013 (prodlení podle nařízení č. 142/1994 Sb. Saldo nepočítá)"}]}]}},"/share/{token}":{"get":{"operationId":"getSharedDocument","tags":["Veřejné kalkulátory a číselníky"],"summary":"Veřejný náhled sdílené faktury","description":"Vrátí to, co vidí zákazník na veřejném odkazu faktury (stránka /tools/ucetnictvi/faktura/#\u003ctoken\u003e): údaje dokladu s řádky a rekapitulací DPH, odběratele, dodavatele včetně loga a vzhledu faktury, bankovní účet a řetězec QR Platby. Sdílet lze jen vystavenou fakturu, zálohovou fakturu, daňový doklad k přijaté platbě nebo dobropis; interní poznámka ani účetní účty řádků se nevracejí. Odpověď má hlavičku X-Robots-Tag: noindex, nofollow.","parameters":[{"name":"token","in":"path","required":true,"description":"Token z odkazu (32 znaků A–Z, a–z, 0–9, _ a -). Jiný tvar routa nepřijme a vrátí 404 od Rails.","schema":{"type":"string"},"example":"UC2gSmTAa-8xk0Q9yrAGCAQE1471pxZS"}],"security":[],"responses":{"200":{"description":"Doklad, dodavatel, bankovní účet a QR Platba.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"description":"Token neexistuje, sdílení bylo zrušeno nebo doklad už není vystavený (JSON „Záznam nebyl nalezen“); token jiného tvaru vrátí 404 od Rails bez JSON","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"verejne","x-saldo-access":"public","x-saldo-side-effects":"Když odkaz neotevře přihlášený člen firmy, zvýší počítadlo zobrazení a při prvním zobrazení uloží jeho čas. Jinak nic nezapisuje.","x-saldo-repeat":"Každé zobrazení mimo členy firmy se započítá znovu.","x-saldo-errors":[{"status":404,"when":"Token neexistuje, sdílení bylo zrušeno nebo doklad už není vystavený (JSON „Záznam nebyl nalezen“); token jiného tvaru vrátí 404 od Rails bez JSON"}],"x-saldo-response-fields":[{"name":"document","description":"Druh, stav, číslo, symboly, data, měna, součty, úhrady, zbývá uhradit, stav splatnosti, řádky, rekapitulace DPH, odběratel, související doklad"},{"name":"entity","description":"Dodavatel: název, adresa, IČO, DIČ, kontakty, vztah k DPH, patička, logo (data URI), barva a vzhled faktury v settings, vat_payer"},{"name":"bank_account","description":"Účet pro platbu (number, bank_code, iban, bic, currency) nebo null"},{"name":"spayd","description":"QR Platba jen u neuhrazeného dokladu v CZK nebo EUR, jinak null"}]}},"/share/{token}/isdoc":{"get":{"operationId":"getSharedDocumentIsdoc","tags":["Veřejné kalkulátory a číselníky"],"summary":"ISDOC sdílené faktury ke stažení","description":"Vrátí sdílený doklad jako soubor ISDOC 6.0.2 (XML) ke stažení s názvem \u003cčíslo dokladu\u003e.isdoc, aby ho zákazník mohl načíst do svého účetnictví. Počítadlo zobrazení nemění. Odpověď má hlavičku X-Robots-Tag: noindex, nofollow.","parameters":[{"name":"token","in":"path","required":true,"description":"Token z odkazu (32 znaků A–Z, a–z, 0–9, _ a -).","schema":{"type":"string"},"example":"UC2gSmTAa-8xk0Q9yrAGCAQE1471pxZS"}],"security":[],"responses":{"200":{"description":"Soubor ISDOC (Content-Disposition: attachment).","content":{"application/xml":{"schema":{"type":"string","format":"binary"}}}},"404":{"description":"Token neexistuje, sdílení bylo zrušeno nebo doklad už není vystavený","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"422":{"description":"Z dokladu nelze sestavit ISDOC (např. chybí číslo, položky nebo název dodavatele)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"verejne","x-saldo-access":"public","x-saldo-side-effects":"Nic nezapisuje.","x-saldo-errors":[{"status":404,"when":"Token neexistuje, sdílení bylo zrušeno nebo doklad už není vystavený"},{"status":422,"when":"Z dokladu nelze sestavit ISDOC (např. chybí číslo, položky nebo název dodavatele)"}]}},"/api_keys":{"get":{"operationId":"listApiKeys","tags":["Účet, firmy a přístupy"],"summary":"Seznam vlastních API klíčů","description":"Vrátí všechny API klíče přihlášeného uživatele od nejnovějšího, včetně zrušených. Token se po vytvoření už nikdy nevrací, jen jeho poslední čtyři znaky v hint. Čas posledního použití se při ověření klíče ukládá nejvýše jednou za 5 minut.","parameters":[],"security":[{"session":[]}],"responses":{"200":{"description":"Objekt s polem keys.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"403":{"description":"Požadavek s API klíčem místo přihlášení v prohlížeči","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"ucet-a-firmy","x-saldo-access":"session","x-saldo-access-note":"Jen s přihlášením v prohlížeči (cookie _techtools4_session). Požadavek s API klíčem v X-API-Key nebo Authorization: Bearer vrátí 403 „API klíče se spravují jen po přihlášení v prohlížeči“.","x-saldo-side-effects":"Nic nezapisuje.","x-saldo-errors":[{"status":403,"when":"Požadavek s API klíčem místo přihlášení v prohlížeči"}],"x-saldo-response-fields":[{"name":"keys[].id","description":"ID klíče"},{"name":"keys[].name","description":"Název klíče"},{"name":"keys[].hint","description":"Konec tokenu ve tvaru …abcd"},{"name":"keys[].read_only","description":"Klíč smí jen číst (GET a HEAD)"},{"name":"keys[].created_at","description":"Vytvoření"},{"name":"keys[].last_used_at","description":"Poslední použití (s přesností na 5 minut) nebo null"},{"name":"keys[].revoked_at","description":"Čas zrušení nebo null"},{"name":"keys[].active","description":"Klíč není zrušený"}],"x-saldo-example":{"note":"Volá se s přihlášením v prohlížeči, ne s API klíčem."}},"post":{"operationId":"createApiKey","tags":["Účet, firmy a přístupy"],"summary":"Vytvoří API klíč","description":"Vytvoří osobní API klíč pro skripty a AI agenty a jednou vrátí jeho token (saldo_ a 40 znaků). Klíč jedná s právy svého uživatele ve všech firmách, kde je uživatel přijatým členem. Klíč jen pro čtení odmítne každý požadavek kromě GET a HEAD. Token se posílá v hlavičce X-API-Key nebo jako Authorization: Bearer.","parameters":[],"security":[{"session":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Název klíče; prázdný nebo chybějící název se uloží jako „API klíč“.","maxLength":80,"example":"Účetní agent"},"read_only":{"type":"boolean","description":"Klíč smí jen číst.","default":false,"example":true}}},"example":{"name":"Účetní agent","read_only":true}}}},"responses":{"201":{"description":"Vytvořený klíč ve stejném tvaru jako v seznamu a navíc token. Token už znovu získat nelze.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Uživatel už má 20 aktivních klíčů („Můžete mít nejvýš 20 aktivních klíčů“)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"403":{"description":"Požadavek s API klíčem místo přihlášení v prohlížeči","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"ucet-a-firmy","x-saldo-access":"session","x-saldo-access-note":"Jen s přihlášením v prohlížeči; zápis navíc potřebuje hlavičku X-Saldo: 1. Požadavek s API klíčem vrátí 403.","x-saldo-side-effects":"Vytvoří API klíč. Uloží jen otisk SHA-256 tokenu a jeho poslední čtyři znaky, samotný token neukládá. Záznam do historie změn nevzniká.","x-saldo-limits":"Nejvýše 20 aktivních (nezrušených) klíčů na uživatele.","x-saldo-repeat":"Každé volání vytvoří nový klíč s novým tokenem.","x-saldo-errors":[{"status":422,"when":"Uživatel už má 20 aktivních klíčů („Můžete mít nejvýš 20 aktivních klíčů“)"},{"status":403,"when":"Požadavek s API klíčem místo přihlášení v prohlížeči"}],"x-saldo-response-fields":[{"name":"token","description":"Celý token klíče; vrací se jen v této odpovědi"},{"name":"id","description":"ID klíče"},{"name":"hint","description":"Poslední čtyři znaky tokenu ve tvaru …abcd"},{"name":"read_only","description":"Klíč smí jen číst"},{"name":"active","description":"true"}],"x-saldo-example":{"note":"Volá se s přihlášením v prohlížeči a hlavičkou X-Saldo: 1."}}},"/api_keys/{id}":{"delete":{"operationId":"revokeApiKey","tags":["Účet, firmy a přístupy"],"summary":"Zruší API klíč","description":"Zruší vlastní API klíč. Klíč okamžitě přestane platit (požadavky s ním vrátí 401 INVALID_API_KEY), ale v seznamu zůstane se stavem active: false. Klíč jiného uživatele vrátí 404.","parameters":[{"name":"id","in":"path","required":true,"description":"ID klíče ze seznamu GET /api_keys.","schema":{"type":"integer"},"example":3}],"security":[{"session":[]}],"responses":{"200":{"description":"Zrušený klíč ve stejném tvaru jako v seznamu (active: false, revoked_at).","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"403":{"description":"Požadavek s API klíčem místo přihlášení v prohlížeči","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"ucet-a-firmy","x-saldo-access":"session","x-saldo-access-note":"Jen s přihlášením v prohlížeči a hlavičkou X-Saldo: 1. Klíč nelze zrušit jím samým ani jiným API klíčem (403).","x-saldo-side-effects":"Nastaví čas zrušení klíče; klíč se nemaže.","x-saldo-repeat":"Opakované zrušení téhož klíče vrátí znovu 200 a přepíše čas zrušení na čas posledního volání.","x-saldo-errors":[{"status":403,"when":"Požadavek s API klíčem místo přihlášení v prohlížeči"}],"x-saldo-example":{"note":"Volá se s přihlášením v prohlížeči a hlavičkou X-Saldo: 1."}}},"/invitations":{"get":{"operationId":"listInvitations","tags":["Účet, firmy a přístupy"],"summary":"Pozvánky do firem čekající na přijetí","description":"Vrátí pozvánky přihlášeného uživatele do cizích firem, které ještě nepřijal, od nejstarší. Dokud pozvánku nepřijme, firma se mu v GET /entities nezobrazí a k jejím datům nemá přístup.","parameters":[],"responses":{"200":{"description":"Pole pozvánek.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"ucet-a-firmy","x-saldo-access":"user","x-saldo-side-effects":"Nic nezapisuje.","x-saldo-response-fields":[{"name":"id","description":"ID pozvánky (členství) pro přijetí nebo odmítnutí"},{"name":"entity_id","description":"ID firmy"},{"name":"entity_name","description":"Název firmy"},{"name":"legal_form","description":"Právní forma"},{"name":"legal_form_label","description":"Název právní formy"},{"name":"role","description":"Nabízená role: accountant, editor nebo viewer"},{"name":"role_label","description":"Název role"},{"name":"invited_by","description":"Uživatelské jméno toho, kdo pozval"},{"name":"invited_at","description":"Čas pozvání"}]}},"/invitations/{id}/accept":{"post":{"operationId":"acceptInvitation","tags":["Účet, firmy a přístupy"],"summary":"Přijme pozvánku do firmy","description":"Přijme pozvánku a uživatel tím získá přístup k firmě s rolí z pozvánky. Vrátí firmu ve stejném tvaru jako GET /entities.","parameters":[{"name":"id","in":"path","required":true,"description":"ID pozvánky z GET /invitations.","schema":{"type":"integer"},"example":5}],"responses":{"200":{"description":"Firma s rolí volajícího (role, can_write, can_manage).","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"ucet-a-firmy","x-saldo-access":"user","x-saldo-access-note":"Jen pozvánka adresovaná volajícímu. Cizí, už přijatá nebo neexistující pozvánka vrátí 404.","x-saldo-side-effects":"Označí členství jako přijaté. Do historie změn firmy zapíše událost member.accepted.","x-saldo-repeat":"Druhé přijetí téže pozvánky vrátí 404."}},"/invitations/{id}":{"delete":{"operationId":"declineInvitation","tags":["Účet, firmy a přístupy"],"summary":"Odmítne pozvánku do firmy","description":"Odmítne pozvánku a smaže ji. Firma pak může uživatele pozvat znovu.","parameters":[{"name":"id","in":"path","required":true,"description":"ID pozvánky z GET /invitations.","schema":{"type":"integer"},"example":5}],"responses":{"204":{"description":"Bez obsahu."},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"ucet-a-firmy","x-saldo-access":"user","x-saldo-access-note":"Jen pozvánka adresovaná volajícímu. Cizí, už přijatá nebo neexistující pozvánka vrátí 404; z přijatého členství se odchází přes DELETE /entities/{entity_id}/members/{id}.","x-saldo-side-effects":"Smaže pozvánku. Do historie změn firmy zapíše událost member.declined.","x-saldo-repeat":"Druhé odmítnutí téže pozvánky vrátí 404.","x-saldo-example":{"note":"Potřebuje vlastní čekající pozvánku; přijetí a odmítnutí spotřebují tutéž."}}},"/lookup/banks":{"get":{"operationId":"listBanks","tags":["Účet, firmy a přístupy"],"summary":"Číselník českých bank s kódy a BIC","description":"Vrátí kódy bank platebního styku v ČR s názvem banky a BIC podle číselníku ČNB (stav uvedený v kódu: 24. 8. 2026). Některé banky BIC nemají.","parameters":[],"responses":{"200":{"description":"Pole bank seřazené podle kódu.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"ucet-a-firmy","x-saldo-access":"user","x-saldo-side-effects":"Nic nezapisuje.","x-saldo-response-fields":[{"name":"code","description":"Čtyřmístný kód banky"},{"name":"name","description":"Název banky"},{"name":"bic","description":"BIC (SWIFT) nebo null"}]}},"/lookup/statement_formats":{"get":{"operationId":"listStatementFormats","tags":["Účet, firmy a přístupy"],"summary":"Formáty bankovních výpisů, které umí import","description":"Vrátí formáty datových exportů výpisů, které import čte přesně (GPC/ABO, XML camt.053, MT940, CSV), a údaje o čtení PDF výpisů: je v betě a banks vyjmenovává banky, jejichž rozvržení PDF je ověřené. PDF jiných bank se čtou také, ale bez ověření.","parameters":[],"responses":{"200":{"description":"Objekt s exports a pdf.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"ucet-a-firmy","x-saldo-access":"user","x-saldo-side-effects":"Nic nezapisuje.","x-saldo-response-fields":[{"name":"exports","description":"Názvy datových formátů"},{"name":"pdf.beta","description":"Čtení PDF je v betě (true)"},{"name":"pdf.banks[]","description":"Banky s ověřeným PDF výpisem: code, name"}]}},"/lookup/{ico}":{"get":{"operationId":"lookupCompany","tags":["Účet, firmy a přístupy"],"summary":"Firma podle IČO s návrhem nastavení Salda","description":"Najde subjekt podle IČO v ARES, doplní statistiky ARES RES (počet zaměstnanců, převažující činnost) a stav v registru plátců DPH a navrhne nastavení firmy v Saldu: segment, právní formu, způsob vedení (OSVČ daňová evidence, ostatní podvojné účetnictví), vztah k DPH, finanční úřad a pracoviště, CZ-NACE, u OSVČ výdajový paušál a tipy na moduly. Neznámé IČO není chyba: vrátí 200 s found: false a code NOT_FOUND. Když ARES RES nebo registr plátců neodpoví, návrh se vrátí bez nich a důvod je ve warnings.","parameters":[{"name":"ico","in":"path","required":true,"description":"IČO, 1 až 8 číslic; kratší se doplní nulami zleva. Musí mít platnou kontrolní číslici. Jiné znaky nebo víc než 8 číslic routa nepřijme (404).","schema":{"type":"string"},"example":"99999994"}],"responses":{"200":{"description":"Karta firmy a návrh nastavení, nebo { ico, found: false, code: NOT_FOUND, error }.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"IČO nemá platnou kontrolní číslici","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"502":{"description":"ARES neodpovídá nebo vrátil chybu","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"429":{"description":"Víc než 40 hledání za minutu jedním uživatelem („Příliš mnoho hledání – zkuste to za minutu znovu“)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"ucet-a-firmy","x-saldo-access":"user","x-saldo-side-effects":"Nic nezapisuje. Volá ARES (ekonomické subjekty, RES, případně číselník CZ-NACE) a registr plátců DPH Ministerstva financí. Výsledek na 5 minut uloží do mezipaměti.","x-saldo-limits":"40 hledání za minutu na uživatele. Odpověď pro stejné IČO je 5 minut z mezipaměti. Časový limit dotazu do ARES je 8 s.","x-saldo-errors":[{"status":422,"code":"INVALID_ICO","when":"IČO nemá platnou kontrolní číslici"},{"status":502,"code":"ARES_UNAVAILABLE","when":"ARES neodpovídá nebo vrátil chybu"},{"status":429,"code":"RATE_LIMITED","when":"Víc než 40 hledání za minutu jedním uživatelem („Příliš mnoho hledání – zkuste to za minutu znovu“)"}],"x-saldo-response-fields":[{"name":"found","description":"Subjekt byl nalezen"},{"name":"looked_up_at","description":"Čas dotazu (odpověď může být z mezipaměti)"},{"name":"company","description":"Název, DIČ, právní forma, vznik a zánik, adresa, u OSVČ jméno, plátce DPH, nespolehlivost, velikost, CZ-NACE (nejvýše 8), společníci (nejvýše 10)"},{"name":"bank_accounts","description":"Účty zveřejněné v registru plátců DPH (nejvýše 5): number, bank_code, bank_name, display"},{"name":"suggestion","description":"Návrh: segment, legal_form, bookkeeping, vat_status, employees, tax_office_code, tax_office_workplace, tax_office_label, nace, nace_code, nace_name, u OSVČ income_kind, flat_rate, flat_rate_reason, hints"},{"name":"sources","description":"Které zdroje odpověděly: ares, res, vat_registry"},{"name":"warnings","description":"Upozornění (zaniklý subjekt, nedostupný zdroj)"}],"x-saldo-example":{"note":"ARES, ARES RES a registr plátců DPH jsou v příkladu nahrazené testovacími daty."}}},"/entities":{"get":{"operationId":"listEntities","tags":["Účet, firmy a přístupy"],"summary":"Firmy, ke kterým má uživatel přístup","description":"Vrátí všechny účetní jednotky, kde je volající přijatým členem, nejdřív aktivní a potom archivované, v obou skupinách podle názvu. Každá firma obsahuje své údaje, nastavení doplněné o výchozí hodnoty a roli volajícího. Logo se tu nevrací, jen příznak has_logo.","parameters":[],"responses":{"200":{"description":"Pole firem.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"ucet-a-firmy","x-saldo-access":"user","x-saldo-side-effects":"Nic nezapisuje.","x-saldo-response-fields":[{"name":"id","description":"ID firmy (entity_id v dalších cestách)"},{"name":"name","description":"Název"},{"name":"legal_form","description":"Právní forma a legal_form_label"},{"name":"bookkeeping","description":"Způsob vedení a bookkeeping_label"},{"name":"vat_status","description":"Vztah k DPH a vat_status_label"},{"name":"locked_until","description":"Období uzamčené do tohoto dne včetně, nebo null"},{"name":"settings","description":"Nastavení doplněné o výchozí hodnoty"},{"name":"has_logo","description":"Firma má logo"},{"name":"vat_payer","description":"Plátce DPH (měsíční nebo čtvrtletní)"},{"name":"double_entry","description":"Vede podvojné účetnictví"},{"name":"role","description":"Role volajícího: owner, accountant, editor nebo viewer"},{"name":"can_write","description":"Volající smí zapisovat"},{"name":"can_manage","description":"Volající je vlastník nebo účetní"},{"name":"member_user_id","description":"ID uživatele volajícího"}]},"post":{"operationId":"createEntity","tags":["Účet, firmy a přístupy"],"summary":"Založí novou firmu","description":"Založí účetní jednotku, volajícího z ní udělá vlastníka a připraví ji k použití: účtový rozvrh, pokladnu a volitelně bankovní účet s počátečním stavem. Právnická osoba (každá forma kromě osvc) musí vést podvojné účetnictví; jiný způsob vedení Saldo odmítne, nepřepne ho samo. Výdajový paušál se uloží jen při vedení flat_expenses. Při vyplněném settings.profile (průvodce založením) doplní čas dokončení průvodce, chybí-li, a podle osvc_activity zapíše hlavní nebo vedlejší činnost do daňového profilu, pokud tax_profile.main_activity nepřišlo. Stejné IČO lze založit vícekrát.","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["entity"],"properties":{"entity":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"Název firmy nebo jméno OSVČ; řídicí znaky se nahradí mezerou.","maxLength":200,"example":"Nová firma s.r.o."},"legal_form":{"type":"string","description":"Právní forma.","enum":["osvc","sro","as","vos","ks","druzstvo","spolek","other"],"default":"sro","example":"sro"},"ico":{"type":"string","description":"IČO; nečíselné znaky se odstraní a kratší číslo doplní nulami na 8 číslic. Kontrolní číslice se neověřuje.","example":"12345679"},"dic":{"type":"string","description":"DIČ; převede se na velká písmena bez mezer a k 8–10 číslicím se doplní CZ.","example":"CZ12345679"},"title":{"type":"string","description":"Titul (OSVČ)."},"first_name":{"type":"string","description":"Jméno (OSVČ)."},"last_name":{"type":"string","description":"Příjmení (OSVČ)."},"street":{"type":"string","description":"Ulice."},"house_number":{"type":"string","description":"Číslo popisné."},"orientation_number":{"type":"string","description":"Číslo orientační."},"city":{"type":"string","description":"Obec."},"zip":{"type":"string","description":"PSČ."},"country":{"type":"string","description":"Stát.","default":"CZ"},"email":{"type":"string","description":"E-mail na dokladech."},"phone":{"type":"string","description":"Telefon."},"web":{"type":"string","description":"Web."},"databox":{"type":"string","description":"ID datové schránky."},"register_note":{"type":"string","description":"Zápis v rejstříku, tiskne se na doklady."},"bookkeeping":{"type":"string","description":"Způsob vedení; jiný než double_entry jen pro osvc.","enum":["double_entry","tax_records","flat_expenses","flat_tax"],"default":"double_entry","example":"double_entry"},"flat_expense_rate":{"type":"integer","description":"Výdajový paušál v procentech; uloží se jen s bookkeeping flat_expenses.","enum":[80,60,40,30]},"vat_status":{"type":"string","description":"Vztah k DPH.","enum":["none","monthly","quarterly","identified"],"default":"none","example":"quarterly"},"vat_registered_on":{"type":"string","format":"date","description":"Datum registrace k DPH."},"tax_office_code":{"type":"string","description":"Kód finančního úřadu (číselník tax_offices z GET /codebooks)."},"tax_office_workplace":{"type":"string","description":"Kód územního pracoviště."},"nace":{"type":"string","description":"Převažující činnost CZ-NACE (pro přiznání)."},"fiscal_year_start":{"type":"integer","description":"Měsíc začátku účetního období.","default":1,"minimum":1,"maximum":12},"currency":{"type":"string","description":"Účetní měna, tři velká písmena.","default":"CZK"},"default_due_days":{"type":"integer","description":"Výchozí splatnost vydaných faktur ve dnech.","default":14,"minimum":0,"maximum":365},"invoice_footer":{"type":"string","description":"Patička dokladů."},"accent_color":{"type":"string","description":"Barva dokladů ve tvaru #RRGGBB.","example":"#0f766e"},"archived":{"type":"boolean","description":"Firma je archivovaná (v seznamech až na konci).","default":false},"settings":{"type":"object","description":"Nastavení. Chybou 422 se kontrolují jen odpovědi průvodce (profile) a vzhled faktury; modules a přepínače vzhledu se převedou na true/false, ostatní povolené klíče se uloží, jak přijdou, a nepovolené se zahodí.","properties":{"round_total":{"type":"string","description":"Zaokrouhlení vydaných dokladů na celé koruny – always vždy, cash jen při platbě v hotovosti, jiná hodnota nikdy.","default":"cash"},"invoice_language":{"type":"string","description":"Jazyk nových dokladů; doklady přijmou jen cs nebo en.","default":"cs"},"number_format":{"type":"string","description":"Maska čísla dokladu se značkami {prefix}, {yyyy}, {yy}, {mm} a {n…} (počet n = počet číslic pořadí).","default":"{prefix}{yyyy}{nnnn}"},"show_qr":{"type":"boolean","description":"Tisknout QR Platbu.","default":true},"invoice_style":{"type":"string","description":"Vzhled faktury.","enum":["plain","linka","summary","sidebar","swiss","block","studio","nordic","classic","mono","executive","corporate","modern","elegant","technical","edge","duo","poster","letter","outline","soft","bigtotal","night","glanceink","sideright","sideink","heritage","frame","geometric","atelier","serifclean","ledger","compact","dense","wholesale","guilloche"],"default":"plain"},"invoice_font":{"type":"string","description":"Písmo faktury (auto = podle vzhledu).","enum":["auto","inter","plex","manrope","dm","franklin","serif","lora"],"default":"auto"},"invoice_density":{"type":"string","description":"Hustota faktury.","enum":["normal","compact","airy"],"default":"normal"},"invoice_table":{"type":"string","description":"Styl tabulky položek.","enum":["auto","lines","zebra","grid","minimal","headfill","headline"],"default":"auto"},"invoice_corners":{"type":"string","description":"Rohy prvků faktury.","enum":["auto","sharp","round"],"default":"auto"},"invoice_logo_size":{"type":"string","description":"Velikost loga.","enum":["s","m","l"],"default":"m"},"invoice_logo_name":{"type":"boolean","description":"Tisknout název firmy vedle loga.","default":false},"invoice_row_numbers":{"type":"boolean","description":"Číslovat řádky.","default":false},"invoice_paid_stamp":{"type":"boolean","description":"Razítko Zaplaceno na uhrazených dokladech.","default":true},"invoice_contacts":{"type":"boolean","description":"Tisknout kontakty firmy.","default":true},"invoice_credit":{"type":"boolean","description":"Tisknout odkaz na Saldo.","default":true},"statement_category":{"type":"string","description":"Kategorie účetní jednotky pro výkazy (mikro, mala, stredni, velka); výchozí mikro."},"signature":{"type":"string","description":"Podpis na dokladech."},"vat_coefficient":{"type":"number","description":"Koeficient krácení nároku na odpočet DPH."},"tax_advisor":{"type":"boolean","description":"Přiznání podává daňový poradce."},"audit":{"type":"boolean","description":"Povinný audit."},"real_estate":{"type":"boolean","description":"Platí daň z nemovitých věcí (kalendář lhůt)."},"road_tax":{"type":"boolean","description":"Platí silniční daň (kalendář lhůt)."},"income_kind":{"type":"string","description":"Druh příjmů OSVČ pro výdajový paušál (crafts, trade, other, rental)."},"cssz_variable_symbol":{"type":"string","description":"Variabilní symbol plateb ČSSZ."},"ossz_code":{"type":"string","description":"Kód okresní správy sociálního zabezpečení."},"flat_tax_band":{"type":"integer","description":"Pásmo paušální daně."},"reminder_days":{"type":"array","description":"Po kolika dnech po splatnosti připomínat.","default":[3,14,30],"items":{"type":"integer"}},"jmhz_ownership_form":{"type":"string","description":"Forma vlastnictví pro JMHZ."},"jmhz_collective_agreements":{"type":"array","description":"Kolektivní smlouvy pro JMHZ.","items":{"type":"string"}},"jmhz_workplace":{"type":"object","description":"Pracoviště pro JMHZ – municipality, municipality_code, country."},"jmhz_disabled_quota":{"type":"object","description":"Povinný podíl OZP pro JMHZ – employees, disabled, share."},"submitter":{"type":"object","description":"Osoba podávající přiznání – first_name, last_name, phone, relation."},"corporate_profile":{"type":"object","description":"Údaje pro daň právnické osoby – loss_carryforward, gifts, paid_advances, last_known_tax."},"tax_profile":{"type":"object","description":"Daňový profil OSVČ (měsíce činnosti, hlavní činnost, manžel(ka), děti, invalidita, rodné číslo, OSSZ, zdravotní pojišťovna, odpočty, zálohy, způsob vrácení přeplatku a další údaje pro přiznání a přehledy)."},"profile":{"type":"object","description":"Odpovědi průvodce založením: segment (osvc, startup, small, growing, accountant), osvc_activity (main, secondary), employees (none, small, many), keeper (self, accountant, is_accountant), příznaky cash, assets, travel, projects, advances, commercial (boolean), foreign (pole z eu, non_eu; jiné hodnoty se zahodí), completed_at. Neznámá hodnota výčtu vrátí 422."},"modules":{"type":"object","description":"Zapnuté moduly: advances, cash, commercial, internal, payroll, assets, trips, projects, closing, multi_currency, forecast (boolean). Chybějící modul je zapnutý, neznámé klíče se zahodí."},"checklist":{"type":"object","description":"Stav prvních kroků – hidden (boolean) a dismissed (pole klíčů)."}}}}},"bank":{"type":"object","description":"Volitelný bankovní účet: name, number, bank_code, iban, bic, currency, opening_balance, opening_date. Založí se jen s number nebo iban.","properties":{"name":{"type":"string","description":"Název účtu; výchozí „Bankovní účet“"},"number":{"type":"string","description":"Číslo účtu bez kódu banky"},"bank_code":{"type":"string","description":"Kód banky (4 číslice)"},"iban":{"type":"string","description":"IBAN"},"bic":{"type":"string","description":"BIC"},"currency":{"type":"string","description":"Měna účtu; výchozí CZK"},"opening_balance":{"type":"number","description":"Počáteční stav"},"opening_date":{"type":"string","format":"date","description":"Datum počátečního stavu; výchozí začátek účetního roku"}}}}},"example":{"entity":{"name":"Nová firma s.r.o.","legal_form":"sro","ico":"12345679","dic":"CZ12345679","vat_status":"quarterly","settings":{"invoice_style":"technical","modules":{"payroll":false}}},"bank":{"name":"Provozní účet","number":"2900001227","bank_code":"2010","opening_balance":50000,"opening_date":"2026-01-01"}}}}},"responses":{"201":{"description":"Založená firma ve stejném tvaru jako v GET /entities (role owner).","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Právnická osoba s jiným vedením než double_entry (chyba u bookkeeping: „právnická osoba vede podvojné účetnictví“) Neznámá odpověď průvodce v settings.profile („profil: … musí být jedno z …“) Neznámá hodnota vzhledu faktury („vzhled faktury: … musí být jedno z …“) Kurz ČNB pro počáteční stav bankovního účtu v cizí měně se nepodařilo načíst","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"ucet-a-firmy","x-saldo-access":"user","x-saldo-access-note":"Firmu může založit kterýkoli přihlášený uživatel nebo API klíč; stane se jejím vlastníkem.","x-saldo-side-effects":"Vytvoří firmu, členství vlastníka, účtový rozvrh (u daňové evidence kategorie příjmů a výdajů), pokladnu s analytickým účtem 211xxx a s údaji banky bankovní účet s analytickým účtem 221xxx. U podvojného účetnictví zaúčtuje nenulový počáteční stav bankovního účtu k datu počátečního stavu; u cizí měny přepočte kurzem ČNB (volá ČNB). Do historie změn zapíše událost entity.created.","x-saldo-repeat":"Každé volání založí novou firmu.","x-saldo-errors":[{"status":422,"when":"Právnická osoba s jiným vedením než double_entry (chyba u bookkeeping: „právnická osoba vede podvojné účetnictví“)"},{"status":422,"when":"Neznámá odpověď průvodce v settings.profile („profil: … musí být jedno z …“)"},{"status":422,"when":"Neznámá hodnota vzhledu faktury („vzhled faktury: … musí být jedno z …“)"},{"status":422,"when":"Kurz ČNB pro počáteční stav bankovního účtu v cizí měně se nepodařilo načíst"}]}},"/entities/demo":{"post":{"operationId":"createDemoEntity","tags":["Účet, firmy a přístupy"],"summary":"Založí ukázkovou firmu s daty od začátku roku","description":"Založí ukázkovou firmu označenou jako ukázka (settings.demo), ve které si lze Saldo vyzkoušet, s daty od začátku letošního roku do dneška: kontakty, vydané a přijaté doklady včetně dobropisu a zálohové faktury (u plátce DPH i s daňovým dokladem k přijaté platbě), pokladní doklady, bankovní účet s pohyby (většina spárovaná s doklady, několik čeká na spárování), pokladnu, majetek, platby úřadům s bankovními pravidly, opakovanou fakturu, projekty a střediska; u varianty sro také zaměstnance, výplatní pásky a cestovní příkaz. Doklady jsou vystavené a zaúčtované jako skutečné. Varianta sro je měsíční plátce DPH s podvojným účetnictvím, varianta osvc neplátce s daňovou evidencí. První kroky jsou u ukázky skryté.","parameters":[{"name":"variant","in":"query","required":false,"description":"Druh ukázkové firmy; jiná hodnota znamená sro. Lze poslat i v těle požadavku.","schema":{"type":"string","enum":["sro","osvc"],"default":"sro"},"example":"osvc"}],"responses":{"201":{"description":"Založená ukázková firma ve stejném tvaru jako v GET /entities (role owner).","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Uživatel už vlastní 3 ukázkové firmy („Ukázkové firmy můžete mít nejvýš 3 – nejprve některou smažte“)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"ucet-a-firmy","x-saldo-access":"user","x-saldo-side-effects":"Vytvoří firmu se členstvím vlastníka a s daty od začátku roku; vystavené doklady, úhrady a výplatní pásky zaúčtuje. Nic neposílá mimo Saldo.","x-saldo-limits":"Nejvýše 3 ukázkové firmy na vlastníka.","x-saldo-repeat":"Každé volání založí další ukázkovou firmu až do limitu.","x-saldo-errors":[{"status":422,"when":"Uživatel už vlastní 3 ukázkové firmy („Ukázkové firmy můžete mít nejvýš 3 – nejprve některou smažte“)"}],"x-saldo-example":{"note":"Volající smí mít nejvýš dvě ukázkové firmy předem."}}},"/entities/{id}":{"get":{"operationId":"getEntity","tags":["Účet, firmy a přístupy"],"summary":"Detail firmy s nastavením a logem","description":"Vrátí jednu firmu ve stejném tvaru jako GET /entities a navíc logo jako data URI v logo_data.","parameters":[{"name":"id","in":"path","required":true,"description":"ID firmy.","schema":{"type":"integer"},"example":1}],"responses":{"200":{"description":"Firma, nastavení s výchozími hodnotami, role volajícího a logo.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"ucet-a-firmy","x-saldo-access":"member","x-saldo-side-effects":"Nic nezapisuje.","x-saldo-response-fields":[{"name":"logo_data","description":"Logo jako data:image/…;base64, nebo null"},{"name":"settings","description":"Nastavení doplněné o výchozí hodnoty"},{"name":"role","description":"Role volajícího"}]},"patch":{"operationId":"updateEntity","tags":["Účet, firmy a přístupy"],"summary":"Změní údaje a nastavení firmy","description":"Změní údaje firmy, nastavení a logo. Pole jsou stejná jako při založení, navíc logo_data; uzamčení období se mění jen přes POST /entities/{id}/lock. Poslané settings se sloučí s dosavadním nastavením jen na nejvyšší úrovni: vnořený objekt (tax_profile, profile, modules, submitter, corporate_profile, jmhz_*) se nahradí celý. Vzhled faktury se ověřuje jen u změněných hodnot, takže dříve uložená neznámá hodnota uložení nebrání. Pravidlo podvojného účetnictví pro právnické osoby platí i při změně.","parameters":[{"name":"id","in":"path","required":true,"description":"ID firmy.","schema":{"type":"integer"},"example":1}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["entity"],"properties":{"entity":{"type":"object","properties":{"name":{"type":"string","description":"Název","maxLength":200},"legal_form":{"type":"string","description":"Právní forma","enum":["osvc","sro","as","vos","ks","druzstvo","spolek","other"]},"ico":{"type":"string","description":"IČO (normalizuje se na 8 číslic)"},"dic":{"type":"string","description":"DIČ"},"title":{"type":"string","description":"Titul"},"first_name":{"type":"string","description":"Jméno"},"last_name":{"type":"string","description":"Příjmení"},"street":{"type":"string","description":"Ulice"},"house_number":{"type":"string","description":"Číslo popisné"},"orientation_number":{"type":"string","description":"Číslo orientační"},"city":{"type":"string","description":"Obec"},"zip":{"type":"string","description":"PSČ"},"country":{"type":"string","description":"Stát"},"email":{"type":"string","description":"E-mail"},"phone":{"type":"string","description":"Telefon"},"web":{"type":"string","description":"Web"},"databox":{"type":"string","description":"ID datové schránky"},"register_note":{"type":"string","description":"Zápis v rejstříku"},"bookkeeping":{"type":"string","description":"Způsob vedení; jiný než double_entry jen pro osvc","enum":["double_entry","tax_records","flat_expenses","flat_tax"]},"flat_expense_rate":{"type":"integer","description":"Výdajový paušál; uloží se jen s flat_expenses","enum":[80,60,40,30]},"vat_status":{"type":"string","description":"Vztah k DPH","enum":["none","monthly","quarterly","identified"]},"vat_registered_on":{"type":"string","format":"date","description":"Datum registrace k DPH"},"tax_office_code":{"type":"string","description":"Kód finančního úřadu"},"tax_office_workplace":{"type":"string","description":"Kód územního pracoviště"},"nace":{"type":"string","description":"CZ-NACE"},"fiscal_year_start":{"type":"integer","description":"Měsíc začátku účetního období","minimum":1,"maximum":12},"currency":{"type":"string","description":"Účetní měna"},"default_due_days":{"type":"integer","description":"Výchozí splatnost","minimum":0,"maximum":365},"invoice_footer":{"type":"string","description":"Patička dokladů"},"accent_color":{"type":"string","description":"Barva #RRGGBB","example":"#0f766e"},"archived":{"type":"boolean","description":"Archivovat firmu"},"logo_data":{"type":"string","description":"Logo jako data:image/png, jpeg, webp nebo gif;base64,…; prázdný řetězec logo odstraní.","maxLength":400000},"settings":{"type":"object","description":"Stejné klíče jako při založení (POST /entities). Sloučí se jen na nejvyšší úrovni a výchozí hodnoty se při tom uloží do záznamu."}}}}},"example":{"entity":{"accent_color":"#0f766e","settings":{"invoice_style":"technical","invoice_font":"plex","invoice_row_numbers":true}}}}}},"responses":{"200":{"description":"Uložená firma jako v GET /entities/{id}, včetně logo_data.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"403":{"description":"Volající není vlastník ani účetní („Nastavení smí měnit jen vlastník nebo účetní“)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"422":{"description":"Právnická osoba s jiným vedením než double_entry Logo není obrázek PNG, JPEG, WebP nebo GIF v data URI nebo je delší než 400 000 znaků Neznámá nová hodnota vzhledu faktury nebo odpovědi průvodce","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"ucet-a-firmy","x-saldo-access":"manager","x-saldo-side-effects":"Uloží firmu. Do historie změn zapíše událost entity.updated, i když se nic nezměnilo.","x-saldo-repeat":"Stejný požadavek vede ke stejnému stavu; každé volání přidá do historie změn nový záznam.","x-saldo-errors":[{"status":403,"when":"Volající není vlastník ani účetní („Nastavení smí měnit jen vlastník nebo účetní“)"},{"status":422,"when":"Právnická osoba s jiným vedením než double_entry"},{"status":422,"when":"Logo není obrázek PNG, JPEG, WebP nebo GIF v data URI nebo je delší než 400 000 znaků"},{"status":422,"when":"Neznámá nová hodnota vzhledu faktury nebo odpovědi průvodce"}]},"delete":{"operationId":"deleteEntity","tags":["Účet, firmy a přístupy"],"summary":"Trvale smaže firmu se všemi daty","description":"Trvale smaže účetní jednotku a všechna její data. Pro potvrzení je nutné poslat přesný název firmy. Firmu, u jejíchž podání jsou uložené doručenky nebo jiné důkazní soubory, touto cestou smazat nelze. Na tom, zda jde o ukázkovou firmu, nezáleží.","parameters":[{"name":"id","in":"path","required":true,"description":"ID firmy.","schema":{"type":"integer"},"example":2}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["confirm"],"properties":{"confirm":{"type":"string","description":"Přesný název firmy (mezery na začátku a na konci se ignorují). Lze poslat i jako parametr v URL.","example":"Jan Ukázka – grafické studio (ukázka)"}}},"example":{"confirm":"Jan Ukázka – grafické studio (ukázka)"}}}},"responses":{"204":{"description":"Bez obsahu."},"403":{"description":"Volající není vlastník („Smazat účetní jednotku smí jen vlastník“)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"422":{"description":"confirm neodpovídá názvu firmy („Pro potvrzení zadejte přesný název účetní jednotky“) Firma má důkazní soubory k podáním (doručenky); smazat ji tímto postupem nelze","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"ucet-a-firmy","x-saldo-access":"owner","x-saldo-side-effects":"Smaže firmu i všechna data: doklady s přílohami, kontakty, bankovní účty a pohyby, archiv výpisů (soubory se mažou na pozadí), účtový rozvrh, číselné řady, účetní zápisy, majetek, zaměstnance, výplatní pásky, cesty, opakované faktury, podání, žádosti o podklady, frontu úkolů, bankovní pravidla, členství a historii změn. Nelze vrátit.","x-saldo-repeat":"Druhé volání vrátí 404.","x-saldo-errors":[{"status":403,"when":"Volající není vlastník („Smazat účetní jednotku smí jen vlastník“)"},{"status":422,"when":"confirm neodpovídá názvu firmy („Pro potvrzení zadejte přesný název účetní jednotky“)"},{"status":422,"when":"Firma má důkazní soubory k podáním (doručenky); smazat ji tímto postupem nelze"}],"x-saldo-example":{"note":"Smaže ukázkovou OSVČ; příklad potřebuje firmu, kterou lze smazat."}}},"/entities/{id}/lock":{"post":{"operationId":"lockEntityPeriod","tags":["Účet, firmy a přístupy"],"summary":"Uzamkne nebo odemkne účetní období","description":"Nastaví den, do kterého je období uzamčené (včetně), nebo zámek zruší. V uzamčeném období Saldo odmítne (422) vystavení, změnu a storno dokladů podle jejich data zdanitelného plnění, data pro DPH, data vystavení nebo účetního data, účetní zápisy, úhrady, párování bankovních pohybů, zůstatky a kontrolu výpisů, výplatní pásky, odpisy, kurzové rozdíly, importy a změnu počátečních stavů; koncepty lze dál upravovat. Samotný zámek nic nekontroluje: přijme i datum v budoucnu a nezkoumá, zda v období zbývají koncepty nebo nespárované pohyby.","parameters":[{"name":"id","in":"path","required":true,"description":"ID firmy.","schema":{"type":"integer"},"example":1}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"locked_until":{"type":"string","format":"date","description":"Poslední uzamčený den jako řetězec YYYY-MM-DD; prázdná hodnota nebo chybějící pole zámek zruší. Neplatné datum vrátí 400, číslo nebo jiná hodnota než řetězec skončí chybou 500.","example":"2025-12-31"}}},"example":{"locked_until":"2025-12-31"}}}},"responses":{"200":{"description":"Firma ve stejném tvaru jako v GET /entities s novým locked_until.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"403":{"description":"Volající není vlastník ani účetní („Období smí uzamknout jen vlastník nebo účetní“)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"ucet-a-firmy","x-saldo-access":"manager","x-saldo-side-effects":"Uloží locked_until. Do historie změn zapíše událost entity.locked (Uzamčeno období do … nebo Zámek období zrušen).","x-saldo-repeat":"Stejné datum vede ke stejnému stavu; každé volání přidá do historie změn nový záznam.","x-saldo-errors":[{"status":403,"when":"Volající není vlastník ani účetní („Období smí uzamknout jen vlastník nebo účetní“)"}]}},"/entities/{id}/getting_started":{"get":{"operationId":"getGettingStarted","tags":["Účet, firmy a přístupy"],"summary":"První kroky s firmou a jejich splnění","description":"Vrátí seznam prvních kroků podle skutečných dat firmy a odpovědí průvodce: import z jiného programu (ne pro segment startup), banka, první vydaná faktura, přijaté doklady, vzhled faktury (logo), pravidelná faktura, bankovní pravidla, pozvání účetní (jen když průvodce uvádí, že účetnictví vede účetní) a údaje pro přiznání. Krok je splněný podle dat, ne podle kliknutí. U ukázkové firmy je celý seznam skrytý (hidden: true).","parameters":[{"name":"id","in":"path","required":true,"description":"ID firmy.","schema":{"type":"integer"},"example":1}],"responses":{"200":{"description":"Kroky a souhrn.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"ucet-a-firmy","x-saldo-access":"member","x-saldo-side-effects":"Nic nezapisuje.","x-saldo-response-fields":[{"name":"items[].key","description":"Klíč kroku: import, bank, first_invoice, received, invoice_look, recurring, bank_rules, accountant, tax_data"},{"name":"items[].done","description":"Krok je splněný"},{"name":"items[].dismissed","description":"Uživatel krok skryl"},{"name":"items[].title","description":"Název kroku"},{"name":"items[].text","description":"Vysvětlení"},{"name":"items[].href","description":"Adresa obrazovky v aplikaci"},{"name":"items[].action","description":"Popisek tlačítka"},{"name":"items[].icon","description":"Ikona Font Awesome"},{"name":"done","description":"Počet splněných neskrytých kroků"},{"name":"total","description":"Počet neskrytých kroků"},{"name":"complete","description":"Všechny neskryté kroky jsou splněné"},{"name":"hidden","description":"Seznam je skrytý (uživatelem nebo u ukázkové firmy)"}]}},"/entities/{id}/getting_started/dismiss":{"post":{"operationId":"dismissGettingStarted","tags":["Účet, firmy a přístupy"],"summary":"Skryje jeden první krok nebo celý seznam","description":"Skryje jeden krok (key), nebo s all: true celý seznam prvních kroků. Stav se ukládá u firmy, platí tedy pro všechny její členy.","parameters":[{"name":"id","in":"path","required":true,"description":"ID firmy.","schema":{"type":"integer"},"example":1}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string","description":"Krok ke skrytí; musí být v aktuálním seznamu firmy.","enum":["import","bank","first_invoice","received","invoice_look","recurring","bank_rules","accountant","tax_data"],"example":"import"},"all":{"type":"boolean","description":"Skrýt celý seznam; má přednost před key.","default":false}}},"example":{"key":"import"}}}},"responses":{"200":{"description":"Seznam prvních kroků po změně, stejně jako GET /entities/{id}/getting_started.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Chybí key nebo krok v seznamu firmy není („Neznámý krok … – obnovte stránku a zkuste to znovu“)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"ucet-a-firmy","x-saldo-access":"writer","x-saldo-side-effects":"Uloží stav seznamu do nastavení firmy (settings.checklist). Do historie změn nezapisuje.","x-saldo-repeat":"Opakované skrytí téhož kroku nic dalšího nezmění.","x-saldo-errors":[{"status":422,"when":"Chybí key nebo krok v seznamu firmy není („Neznámý krok … – obnovte stránku a zkuste to znovu“)"}]},"delete":{"operationId":"resetGettingStarted","tags":["Účet, firmy a přístupy"],"summary":"Znovu zobrazí všechny první kroky","description":"Zruší skrytí jednotlivých kroků i celého seznamu. U ukázkové firmy zůstane seznam skrytý (hidden: true).","parameters":[{"name":"id","in":"path","required":true,"description":"ID firmy.","schema":{"type":"integer"},"example":1}],"responses":{"200":{"description":"Seznam prvních kroků po změně, stejně jako GET /entities/{id}/getting_started.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"ucet-a-firmy","x-saldo-access":"writer","x-saldo-side-effects":"Vynuluje stav seznamu v nastavení firmy (settings.checklist). Do historie změn nezapisuje.","x-saldo-repeat":"Opakování nic dalšího nezmění."}},"/entities/{entity_id}/members":{"get":{"operationId":"listMembers","tags":["Účet, firmy a přístupy"],"summary":"Členové firmy a čekající pozvánky","description":"Vrátí všechny členy firmy včetně pozvánek, které pozvaný ještě nepřijal, v pořadí přidání. E-mail se vrací jen u volajícího samotného.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID firmy.","schema":{"type":"integer"},"example":1}],"responses":{"200":{"description":"Pole členů.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"ucet-a-firmy","x-saldo-access":"member","x-saldo-side-effects":"Nic nezapisuje.","x-saldo-response-fields":[{"name":"id","description":"ID členství (pro změnu role a odebrání)"},{"name":"user_id","description":"ID uživatele"},{"name":"username","description":"Uživatelské jméno"},{"name":"display_name","description":"Zobrazované jméno"},{"name":"email","description":"E-mail, jen u volajícího; jinak null"},{"name":"role","description":"owner, accountant, editor nebo viewer"},{"name":"role_label","description":"Název role"},{"name":"pending","description":"Pozvánka zatím nebyla přijata"},{"name":"accepted_at","description":"Čas přijetí"},{"name":"invited_by","description":"Kdo pozval"},{"name":"is_self","description":"Jde o volajícího"}]},"post":{"operationId":"inviteMember","tags":["Účet, firmy a přístupy"],"summary":"Pozve uživatele TechTools do firmy","description":"Pozve existující účet TechTools podle uživatelského jména nebo e-mailu účtu (bez ohledu na velikost písmen, jen celá hodnota). Vznikne čekající pozvánka: pozvaný získá přístup, až ji přijme přes POST /invitations/{id}/accept. E-mail se pozvanému neposílá. Roli owner nelze přidělit; neznámá nebo chybějící role znamená viewer. Odpověď nikdy neobsahuje e-mail pozvaného.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID firmy.","schema":{"type":"integer"},"example":1}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["login"],"properties":{"login":{"type":"string","description":"Uživatelské jméno, nebo e-mail účtu (hodnota se zavináčem); mezery okolo se ignorují.","example":"jana.novakova"},"role":{"type":"string","description":"Role; jiná hodnota včetně owner znamená viewer.","enum":["accountant","editor","viewer"],"default":"viewer","example":"editor"}}},"example":{"login":"kolegyne_ukazka","role":"editor"}}}},"responses":{"201":{"description":"Nové členství ve stejném tvaru jako v GET /entities/{entity_id}/members, s pending: true.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"description":"Na TechTools není účet s tímto uživatelským jménem ani e-mailem","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"422":{"description":"Uživatel už je členem firmy nebo je pozvaný","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"ucet-a-firmy","x-saldo-access":"manager","x-saldo-side-effects":"Vytvoří čekající pozvánku (členství bez přijetí). Do historie změn zapíše událost member.invited.","x-saldo-repeat":"Druhé pozvání téhož uživatele vrátí 422.","x-saldo-errors":[{"status":404,"when":"Na TechTools není účet s tímto uživatelským jménem ani e-mailem"},{"status":422,"when":"Uživatel už je členem firmy nebo je pozvaný"}],"x-saldo-example":{"note":"Potřebuje uživatele TechTools, který ve firmě ještě není."}}},"/entities/{entity_id}/members/{id}":{"patch":{"operationId":"updateMember","tags":["Účet, firmy a přístupy"],"summary":"Změní roli člena nebo pozvánky","description":"Změní roli člena nebo čekající pozvánky. Roli vlastníka změnit nelze a nikoho nelze povýšit na vlastníka. Neznámá nebo chybějící role znamená viewer. Účetní může změnit i vlastní roli, a tím přijít o správu firmy; vlastník svou roli změnit nemůže (jeho členství má roli owner).","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID firmy.","schema":{"type":"integer"},"example":1},{"name":"id","in":"path","required":true,"description":"ID členství z GET /entities/{entity_id}/members.","schema":{"type":"integer"},"example":3}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"role":{"type":"string","description":"Nová role; jiná hodnota znamená viewer.","enum":["accountant","editor","viewer"],"default":"viewer","example":"editor"}}},"example":{"role":"editor"}}}},"responses":{"200":{"description":"Členství ve stejném tvaru jako v GET /entities/{entity_id}/members.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Členství patří vlastníkovi („Roli vlastníka nelze změnit“)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"ucet-a-firmy","x-saldo-access":"manager","x-saldo-side-effects":"Uloží roli. Do historie změn zapíše událost member.updated.","x-saldo-repeat":"Stejná role vede ke stejnému stavu; každé volání přidá do historie změn nový záznam.","x-saldo-errors":[{"status":422,"when":"Členství patří vlastníkovi („Roli vlastníka nelze změnit“)"}]},"delete":{"operationId":"removeMember","tags":["Účet, firmy a přístupy"],"summary":"Odebere člena, zruší pozvánku nebo opustí firmu","description":"Smaže členství. Vlastní členství znamená opuštění firmy; cizí členství odebere člena nebo zruší čekající pozvánku. Vlastníka nelze odebrat a poslední vlastník nemůže firmu opustit.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID firmy.","schema":{"type":"integer"},"example":1},{"name":"id","in":"path","required":true,"description":"ID členství z GET /entities/{entity_id}/members.","schema":{"type":"integer"},"example":3}],"responses":{"204":{"description":"Bez obsahu."},"403":{"description":"Cizí členství se pokouší odebrat člen, který není vlastník ani účetní","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"422":{"description":"Poslední vlastník chce firmu opustit („Poslední vlastník nemůže firmu opustit“) Odebírané členství patří vlastníkovi („Vlastníka nelze odebrat“)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"ucet-a-firmy","x-saldo-access":"special","x-saldo-access-note":"Vlastní členství může zrušit každý člen včetně role viewer. Cizí členství nebo pozvánku jen vlastník nebo účetní; ostatní dostanou 403 „Tuto akci smí provést jen vlastník nebo účetní“.","x-saldo-side-effects":"Smaže členství. Do historie změn zapíše událost member.left (opuštění) nebo member.removed (odebrání člena nebo zrušení pozvánky).","x-saldo-repeat":"Druhé volání vrátí 404.","x-saldo-errors":[{"status":403,"when":"Cizí členství se pokouší odebrat člen, který není vlastník ani účetní"},{"status":422,"when":"Poslední vlastník chce firmu opustit („Poslední vlastník nemůže firmu opustit“)"},{"status":422,"when":"Odebírané členství patří vlastníkovi („Vlastníka nelze odebrat“)"}]}},"/entities/{entity_id}/events":{"get":{"operationId":"listEvents","tags":["Účet, firmy a přístupy"],"summary":"Historie změn firmy","description":"Vrátí historii změn firmy (kdo co udělal) od nejnovější, po 100 záznamech na stránku, s celkovým počtem. Podrobnosti (details) se vracejí jen u událostí podání (action začínající filing.).","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID firmy.","schema":{"type":"integer"},"example":1},{"name":"page","in":"query","required":false,"description":"Stránka po 100 záznamech; hodnota menší než 1 znamená 1.","schema":{"type":"integer","default":1,"minimum":1},"example":1}],"responses":{"200":{"description":"Stránka historie.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"ucet-a-firmy","x-saldo-access":"member","x-saldo-side-effects":"Nic nezapisuje.","x-saldo-limits":"100 záznamů na stránku.","x-saldo-response-fields":[{"name":"total","description":"Celkový počet událostí"},{"name":"page","description":"Vrácená stránka"},{"name":"rows[].id","description":"ID události"},{"name":"rows[].action","description":"Druh události, např. entity.updated, member.invited, partner.created"},{"name":"rows[].subject_type","description":"Typ dotčeného záznamu, např. Entity, Partner, Document"},{"name":"rows[].subject_id","description":"ID dotčeného záznamu"},{"name":"rows[].summary","description":"Popis (nejvýše 250 znaků)"},{"name":"rows[].user","description":"Uživatelské jméno autora"},{"name":"rows[].created_at","description":"Čas"},{"name":"rows[].details","description":"Podrobnosti, jen u událostí filing.*"}]}},"/entities/{entity_id}/partners":{"get":{"operationId":"listPartners","tags":["Kontakty"],"summary":"Kontakty firmy s obraty","description":"Vrátí kontakty firmy (odběratele i dodavatele) seřazené podle názvu bez ohledu na velikost písmen, nejvýše 500. Ke každému kontaktu připojí obraty: součet základu vystavených faktur a dobropisů v Kč zvlášť za prodej a za nákup a počet neuhrazených vystavených faktur, zálohových faktur a dobropisů; kontakt bez takových dokladů má stats null. Hledání q najde část názvu, IČO, DIČ, IBAN nebo čísla účtu.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID firmy.","schema":{"type":"integer"},"example":1},{"name":"q","in":"query","required":false,"description":"Hledaný text (část názvu, IČO, DIČ, IBAN nebo čísla účtu), bez ohledu na velikost písmen.","schema":{"type":"string"},"example":"Nordwood"}],"responses":{"200":{"description":"Pole kontaktů.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"kontakty","x-saldo-access":"member","x-saldo-side-effects":"Nic nezapisuje.","x-saldo-limits":"Nejvýše 500 kontaktů, bez stránkování.","x-saldo-response-fields":[{"name":"id","description":"ID kontaktu"},{"name":"name","description":"Název"},{"name":"ico","description":"IČO (8 číslic)"},{"name":"dic","description":"DIČ"},{"name":"street","description":"Ulice"},{"name":"city","description":"Obec"},{"name":"zip","description":"PSČ"},{"name":"country","description":"Stát (ISO kód)"},{"name":"email","description":"E-mail"},{"name":"phone","description":"Telefon"},{"name":"web","description":"Web"},{"name":"bank_account","description":"Číslo účtu"},{"name":"iban","description":"IBAN"},{"name":"bic","description":"BIC"},{"name":"due_days","description":"Splatnost ve dnech pro nové doklady"},{"name":"default_account_code","description":"Výchozí účet pro doklady"},{"name":"note","description":"Poznámka"},{"name":"company_id","description":"Propojení s firmou v registru firem TechTools"},{"name":"vat_payer","description":"Plátce DPH podle poslední kontroly registru (null = neověřeno)"},{"name":"unreliable","description":"Nespolehlivý plátce podle poslední kontroly"},{"name":"checked_at","description":"Čas poslední kontroly v registru plátců DPH"},{"name":"insolvent","description":"V insolvenčním rejstříku podle poslední kontroly"},{"name":"insolvency_note","description":"Spisové značky a stavy řízení"},{"name":"insolvency_checked_at","description":"Čas poslední kontroly v insolvenčním rejstříku"},{"name":"stats","description":"sales, purchases (základ v Kč) a open_documents, nebo null"}]},"post":{"operationId":"createPartner","tags":["Kontakty"],"summary":"Založí kontakt","description":"Založí odběratele nebo dodavatele. IČO se doplní nulami na 8 číslic, DIČ převede na velká písmena bez mezer (k 8–10 číslicím se doplní CZ), stát na velká písmena. Duplicitu IČO Saldo nekontroluje. company_id se uloží jen u firmy z vlastního registru firem TechTools volajícího, jinak se tiše zahodí.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID firmy.","schema":{"type":"integer"},"example":1}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["partner"],"properties":{"partner":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"Název nebo jméno","maxLength":200,"example":"Kavárna Modrý pták s.r.o."},"ico":{"type":"string","description":"IČO; nečíselné znaky se odstraní a doplní se nulami na 8 číslic","example":"90000102"},"dic":{"type":"string","description":"DIČ ve tvaru dvou písmen státu a 2–12 znaků","example":"CZ90000102"},"street":{"type":"string","description":"Ulice a číslo"},"city":{"type":"string","description":"Obec"},"zip":{"type":"string","description":"PSČ"},"country":{"type":"string","description":"Stát, dvoupísmenný kód","default":"CZ"},"email":{"type":"string","description":"E-mail"},"phone":{"type":"string","description":"Telefon"},"web":{"type":"string","description":"Web"},"bank_account":{"type":"string","description":"Číslo účtu ve tvaru předčíslí-číslo/kód banky (tvar se neověřuje)"},"iban":{"type":"string","description":"IBAN"},"bic":{"type":"string","description":"BIC"},"due_days":{"type":"integer","description":"Splatnost ve dnech pro nové doklady","minimum":0,"maximum":365},"default_account_code":{"type":"string","description":"Výchozí účet pro řádky dokladů"},"note":{"type":"string","description":"Poznámka"},"company_id":{"type":"integer","description":"ID firmy z registru firem TechTools volajícího"}}}}},"example":{"partner":{"name":"Kavárna Modrý pták s.r.o.","ico":"90000102","dic":"CZ90000102","street":"Jugoslávská 12","city":"Praha 2","zip":"12000","country":"CZ","email":"ucetni@modry-ptak.example","due_days":14}}}}},"responses":{"201":{"description":"Založený kontakt ve stejném tvaru jako v seznamu (stats null).","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"kontakty","x-saldo-access":"writer","x-saldo-side-effects":"Vytvoří kontakt. Do historie změn zapíše událost partner.created.","x-saldo-repeat":"Každé volání založí nový kontakt, i se stejným IČO."}},"/entities/{entity_id}/partners/{id}":{"get":{"operationId":"getPartner","tags":["Kontakty"],"summary":"Detail kontaktu s posledními doklady","description":"Vrátí kontakt s obraty a posledními 100 doklady firmy s tímto kontaktem (od nejnovějšího data vystavení) ve zkráceném tvaru jako v seznamu dokladů.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID firmy.","schema":{"type":"integer"},"example":1},{"name":"id","in":"path","required":true,"description":"ID kontaktu.","schema":{"type":"integer"},"example":1}],"responses":{"200":{"description":"Kontakt jako v seznamu a pole documents.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"kontakty","x-saldo-access":"member","x-saldo-side-effects":"Nic nezapisuje.","x-saldo-limits":"Nejvýše 100 dokladů.","x-saldo-response-fields":[{"name":"stats","description":"sales, purchases a open_documents, nebo null"},{"name":"documents","description":"Nejvýše 100 dokladů: id, kind, status, number, data, měna, částky, stav úhrady a další údaje přehledu"}]},"patch":{"operationId":"updatePartner","tags":["Kontakty"],"summary":"Změní kontakt","description":"Změní údaje kontaktu; pole a jejich úpravy jsou stejné jako při založení. Vystavené doklady si ponechávají údaje kontaktu z doby vystavení, koncepty převezmou nové. Když má firma zapnuté schvalování přijatých výdajů, přepočítá schválené přijaté faktury, pokladní výdaje a dobropisy tohoto dodavatele: změna názvu, IČO nebo účtu pro platbu u nich zruší schválení, případně je rovnou schválí znovu, smí-li je volající schválit.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID firmy.","schema":{"type":"integer"},"example":1},{"name":"id","in":"path","required":true,"description":"ID kontaktu.","schema":{"type":"integer"},"example":1}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["partner"],"properties":{"partner":{"type":"object","properties":{"name":{"type":"string","description":"Název nebo jméno","maxLength":200},"ico":{"type":"string","description":"IČO"},"dic":{"type":"string","description":"DIČ"},"street":{"type":"string","description":"Ulice a číslo"},"city":{"type":"string","description":"Obec"},"zip":{"type":"string","description":"PSČ"},"country":{"type":"string","description":"Stát, dvoupísmenný kód"},"email":{"type":"string","description":"E-mail"},"phone":{"type":"string","description":"Telefon"},"web":{"type":"string","description":"Web"},"bank_account":{"type":"string","description":"Číslo účtu"},"iban":{"type":"string","description":"IBAN"},"bic":{"type":"string","description":"BIC"},"due_days":{"type":"integer","description":"Splatnost ve dnech","minimum":0,"maximum":365},"default_account_code":{"type":"string","description":"Výchozí účet"},"note":{"type":"string","description":"Poznámka"},"company_id":{"type":"integer","description":"ID firmy z vlastního registru firem TechTools; cizí ID se ignoruje"}}}}},"example":{"partner":{"email":"fakturace@nordwood.example","due_days":21}}}}},"responses":{"200":{"description":"Uložený kontakt (stats null).","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"kontakty","x-saldo-access":"writer","x-saldo-side-effects":"Uloží kontakt; samotná změna kontaktu se do historie změn nezapisuje. Při zapnutém schvalování může schváleným přijatým výdajům tohoto dodavatele zrušit schválení (událost document.approval_changed) nebo je znovu schválit.","x-saldo-repeat":"Stejný požadavek vede ke stejnému stavu."},"delete":{"operationId":"deletePartner","tags":["Kontakty"],"summary":"Smaže kontakt bez dokladů","description":"Smaže kontakt, který nemá žádný doklad (ani koncept).","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID firmy.","schema":{"type":"integer"},"example":1},{"name":"id","in":"path","required":true,"description":"ID kontaktu.","schema":{"type":"integer"},"example":24}],"responses":{"204":{"description":"Bez obsahu."},"422":{"description":"Kontakt má doklady („Kontakt má doklady – nelze ho smazat“)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"kontakty","x-saldo-access":"writer","x-saldo-side-effects":"Smaže kontakt. Do historie změn nezapisuje.","x-saldo-repeat":"Druhé volání vrátí 404.","x-saldo-errors":[{"status":422,"when":"Kontakt má doklady („Kontakt má doklady – nelze ho smazat“)"}],"x-saldo-example":{"note":"Potřebuje kontakt bez dokladů."}}},"/entities/{entity_id}/partners/lookup":{"get":{"operationId":"lookupPartnerIco","tags":["Kontakty"],"summary":"Údaje subjektu z ARES pro nový kontakt","description":"Načte subjekt podle IČO z ARES (název, DIČ, právní forma, adresa) a zjistí, zda je podle ARES plátcem DPH. Nic neukládá. Neznámé IČO není chyba: vrátí 200 s found: false a code NOT_FOUND. IČO se nedoplňuje nulami, musí mít přesně 8 číslic; jinak (i když chybí) vrátí 502 s chybou „Neplatné IČO“.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID firmy.","schema":{"type":"integer"},"example":1},{"name":"ico","in":"query","required":true,"description":"IČO; nečíselné znaky se odstraní a zbýt musí přesně 8 číslic.","schema":{"type":"string"},"example":"99999994"}],"responses":{"200":{"description":"Údaje subjektu s found: true, nebo { ico, found: false, code: NOT_FOUND, error }.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"502":{"description":"ARES neodpovídá nebo vrátil chybu; také když IČO nemá přesně 8 číslic nebo chybí („Neplatné IČO“)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"kontakty","x-saldo-access":"user","x-saldo-access-note":"Stačí přihlášení nebo API klíč. Členství ve firmě z cesty se neověřuje, entity_id nemusí patřit volajícímu.","x-saldo-side-effects":"Nic nezapisuje. Volá ARES dvakrát (údaje subjektu a stav DPH).","x-saldo-limits":"Časový limit dotazu do ARES je 8 s. Vlastní omezení počtu dotazů ani mezipaměť tato cesta nemá.","x-saldo-errors":[{"status":502,"when":"ARES neodpovídá nebo vrátil chybu; také když IČO nemá přesně 8 číslic nebo chybí („Neplatné IČO“)"}],"x-saldo-response-fields":[{"name":"ico","description":"IČO"},{"name":"name","description":"Obchodní firma nebo jméno"},{"name":"dic","description":"DIČ z ARES"},{"name":"legal_form","description":"Kód právní formy ARES"},{"name":"company_type","description":"sro nebo as, u jiných forem null"},{"name":"address","description":"Adresa sídla jedním řádkem"},{"name":"street","description":"Ulice s čísly"},{"name":"city","description":"Obec"},{"name":"zip","description":"PSČ"},{"name":"found","description":"Subjekt byl nalezen"},{"name":"vat","description":"Údaje z ARES včetně vat_payer, legal_form_name a founded, nebo null, když druhý dotaz selže"}],"x-saldo-example":{"note":"ARES je v příkladu nahrazený testovacími daty."}}},"/entities/{entity_id}/partners/vat_registry_all":{"post":{"operationId":"checkPartnersVatRegistry","tags":["Kontakty"],"summary":"Ověří všechna česká DIČ v registru plátců DPH","description":"Ověří v registru plátců DPH Ministerstva financí všechny kontakty firmy s DIČ začínajícím CZ a u každého uloží, zda je plátcem a zda je nespolehlivý plátce. Vrátí počet ověřených a seznam nespolehlivých. Kontakt, kterého registr v odpovědi neuvede, dostane oba příznaky prázdné, ale čas kontroly se mu uloží.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID firmy.","schema":{"type":"integer"},"example":1}],"responses":{"200":{"description":"Souhrn kontroly.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"502":{"description":"Registr plátců DPH je nedostupný nebo vrátil chybu","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"kontakty","x-saldo-access":"writer","x-saldo-side-effects":"U každého kontaktu s českým DIČ uloží vat_payer, unreliable a checked_at. Do historie změn zapíše událost partner.vat_checked, i když firma žádný takový kontakt nemá. Volá registr plátců DPH.","x-saldo-limits":"Bez omezení počtu kontaktů; registr se volá po 100 DIČ, každý dotaz s limitem 8 s na spojení a 20 s na odpověď.","x-saldo-repeat":"Každé volání ověří kontakty znovu a přidá do historie změn nový záznam.","x-saldo-errors":[{"status":502,"when":"Registr plátců DPH je nedostupný nebo vrátil chybu"}],"x-saldo-response-fields":[{"name":"checked","description":"Počet ověřených kontaktů s českým DIČ"},{"name":"unreliable","description":"Počet nespolehlivých plátců"},{"name":"partners","description":"Nespolehliví plátci: id, name, dic"}],"x-saldo-example":{"note":"Registr plátců DPH je v příkladu nahrazený testovacími daty."}}},"/entities/{entity_id}/partners/insolvency_all":{"post":{"operationId":"checkPartnersInsolvency","tags":["Kontakty"],"summary":"Ověří další várku kontaktů v insolvenčním rejstříku","description":"Ověří v insolvenčním rejstříku (ISIR) nejvýše 15 kontaktů s IČO, které nebyly ověřené posledních 24 hodin: nejdřív ty s neuhrazenými doklady, pak ty nejdéle neověřené. Odpověď rejstříku se pro každé IČO drží 12 hodin v mezipaměti. Kontakt s neplatným IČO se jen označí jako ověřený. První chyba rejstříku várku ukončí a její text je v poli error, odpověď má přesto stav 200. Opakovaným voláním se ověří další kontakty.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID firmy.","schema":{"type":"integer"},"example":1}],"responses":{"200":{"description":"Souhrn várky.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"kontakty","x-saldo-access":"writer","x-saldo-side-effects":"U ověřených kontaktů uloží insolvent, insolvency_note (spisové značky a stavy, nejvýše 250 znaků) a insolvency_checked_at; u kontaktů s neplatným IČO jen insolvency_checked_at. Když ověří aspoň jeden kontakt, zapíše do historie změn událost partner.isir_checked. Volá ISIR.","x-saldo-limits":"15 kontaktů na volání. Dotazy do ISIR server rozkládá (asi 45 za minutu a 2 500 za den); na volné místo čeká nejvýše 10 s, jinak várku ukončí s chybou v poli error. Časový limit dotazu 5 s na spojení a 15 s na odpověď.","x-saldo-repeat":"Každé volání pokračuje dalšími kontakty, dokud remaining neklesne na 0.","x-saldo-response-fields":[{"name":"checked","description":"Počet ověřených kontaktů"},{"name":"remaining","description":"Kolik kontaktů zbývá (počítá i kontakty s neplatným IČO z této várky)"},{"name":"error","description":"Chyba rejstříku, která várku ukončila, nebo null"},{"name":"insolvent","description":"Ověřené kontakty v insolvenci: id, name, note"}],"x-saldo-example":{"note":"Insolvenční rejstřík je v příkladu nahrazený testovacími daty."}}},"/entities/{entity_id}/partners/{id}/vat_registry":{"get":{"operationId":"checkPartnerVatRegistry","tags":["Kontakty"],"summary":"Ověří DIČ kontaktu v registru plátců DPH","description":"Ověří DIČ jednoho kontaktu v registru plátců DPH Ministerstva financí, uloží výsledek ke kontaktu a vrátí stav plátce a to, zda je účet kontaktu (číslo účtu, jinak IBAN) mezi účty zveřejněnými v registru. Přestože jde o GET, zapisuje, a proto vyžaduje právo zápisu. Kvůli chybě v kódu teď vrací 500, kdykoli registr DIČ ve své odpovědi uvede; výsledek se ke kontaktu přesto uloží.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID firmy.","schema":{"type":"integer"},"example":1},{"name":"id","in":"path","required":true,"description":"ID kontaktu.","schema":{"type":"integer"},"example":1}],"responses":{"200":{"description":"Zamýšlený tvar je { status, account, account_published }. Skutečně se 200 vrátí jen tehdy, když registr DIČ neuvede, a to bez klíče status.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Kontakt nemá DIČ začínající CZ („Kontakt nemá české DIČ“)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"502":{"description":"Registr plátců DPH je nedostupný nebo vrátil chybu","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"500":{"description":"Registr DIČ ve své odpovědi uvedl (chyba aplikace: odpověď registru se omylem použije jako HTTP stav; stav plátce se přesto uloží)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"kontakty","x-saldo-access":"writer","x-saldo-access-note":"Vyžaduje právo zápisu (vlastník, účetní, editor). Protože jde o GET, projde i s API klíčem jen pro čtení a výsledek ke kontaktu uloží.","x-saldo-side-effects":"Uloží ke kontaktu vat_payer, unreliable a checked_at. Do historie změn nezapisuje. Volá registr plátců DPH.","x-saldo-repeat":"Každé volání ověří DIČ znovu.","x-saldo-errors":[{"status":422,"when":"Kontakt nemá DIČ začínající CZ („Kontakt nemá české DIČ“)"},{"status":502,"when":"Registr plátců DPH je nedostupný nebo vrátil chybu"},{"status":500,"when":"Registr DIČ ve své odpovědi uvedl (chyba aplikace: odpověď registru se omylem použije jako HTTP stav; stav plátce se přesto uloží)"}],"x-saldo-response-fields":[{"name":"status","description":"Stav z registru: dic, found, kind, payer, unreliable, tax_office, name, since, accounts"},{"name":"account","description":"Účet kontaktu, který se porovnával"},{"name":"account_published","description":"Účet je mezi zveřejněnými účty plátce"}],"x-saldo-example":{"skip":"Ukázka odpovědi chybí: operace teď při nalezeném DIČ končí chybou 500 (chyba aplikace), takže skutečnou odpověď nešlo zaznamenat. Stav plátce se přitom u kontaktu uloží."}}},"/entities/{entity_id}/partners/{id}/insolvency":{"post":{"operationId":"checkPartnerInsolvency","tags":["Kontakty"],"summary":"Ověří kontakt v insolvenčním rejstříku","description":"Ověří IČO kontaktu v insolvenčním rejstříku (ISIR) a vrátí probíhající řízení, ve kterých je kontakt dlužníkem (nejvýše 50), s odkazem na detail řízení. Výsledek uloží ke kontaktu. Odpověď rejstříku se pro IČO drží 12 hodin v mezipaměti; refresh vynutí nový dotaz.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID firmy.","schema":{"type":"integer"},"example":1},{"name":"id","in":"path","required":true,"description":"ID kontaktu.","schema":{"type":"integer"},"example":1},{"name":"refresh","in":"query","required":false,"description":"Nepoužít výsledek z mezipaměti a zeptat se rejstříku znovu.","schema":{"type":"boolean","default":false},"example":true}],"responses":{"200":{"description":"Výsledek kontroly a uložený kontakt.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Kontakt nemá IČO („Kontakt nemá IČO“) IČO kontaktu nemá platnou kontrolní číslici","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"502":{"description":"ISIR je nedostupný, odmítl dotaz, vrátil nečitelnou odpověď nebo byl překročen limit dotazů","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"kontakty","x-saldo-access":"writer","x-saldo-side-effects":"Uloží ke kontaktu insolvent, insolvency_note (nejvýše 250 znaků) a insolvency_checked_at. Do historie změn nezapisuje. Volá ISIR, pokud výsledek není v mezipaměti nebo je zadán refresh.","x-saldo-limits":"Mezipaměť 12 hodin na IČO. Dotazy do ISIR server rozkládá (asi 45 za minutu a 2 500 za den) a na volné místo čeká nejvýše 10 s, jinak vrátí 502.","x-saldo-repeat":"Bez refresh vrací 12 hodin stejný výsledek z mezipaměti; čas kontroly u kontaktu se přesto přepíše.","x-saldo-errors":[{"status":422,"when":"Kontakt nemá IČO („Kontakt nemá IČO“)"},{"status":422,"when":"IČO kontaktu nemá platnou kontrolní číslici"},{"status":502,"when":"ISIR je nedostupný, odmítl dotaz, vrátil nečitelnou odpověď nebo byl překročen limit dotazů"}],"x-saldo-response-fields":[{"name":"ico","description":"Ověřené IČO"},{"name":"insolvent","description":"Kontakt je v probíhajícím insolvenčním řízení"},{"name":"proceedings","description":"Řízení: file_mark, court, state, state_label, started_on, ended_on, url"},{"name":"checked_at","description":"Čas dotazu do rejstříku (při výsledku z mezipaměti starší)"},{"name":"partner","description":"Kontakt po uložení výsledku"}],"x-saldo-example":{"note":"Insolvenční rejstřík je v příkladu nahrazený testovacími daty."}}},"/entities/{entity_id}/documents":{"get":{"operationId":"listDocuments","tags":["Doklady a jejich stavy"],"summary":"Seznam dokladů","description":"Vrátí stránkovaný seznam dokladů firmy všech druhů a stavů (koncepty, vystavené i stornované), pokud je filtry nevyloučí. Řazení je pevné: od nejnovějšího data vystavení, při shodě od nejvyššího ID. Filtry se kombinují; hledání q prochází číslo dokladu, údaje kontaktu uložené na dokladu (jméno, IČO, DIČ, adresa, e-mail, telefon), jméno kontaktu v adresáři, variabilní symbol, popis a číslo dokladu dodavatele. Součty sums jsou za celý vyfiltrovaný výběr (všechny stránky, všechny druhy a směry dohromady, včetně konceptů a stornovaných dokladů, pokud je filtr status nevyloučí), ne jen za vrácenou stránku.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":7},{"name":"kind","in":"query","required":false,"description":"Druhy dokladů oddělené čárkou. Hodnoty: invoice_out, invoice_in, proforma_out, proforma_in, advance_out, advance_in, credit_out, credit_in, cash_in, cash_out, internal, quote_out, order_out, delivery_out. Pole kind[] se nepodporuje; neznámá hodnota nic nenajde.","schema":{"type":"string"},"example":"invoice_out,credit_out"},{"name":"status","in":"query","required":false,"description":"Stav dokladu – koncept, vystavený, stornovaný; jiná hodnota nic nenajde","schema":{"type":"string","enum":["draft","issued","cancelled"]},"example":"issued"},{"name":"state","in":"query","required":false,"description":"Stav úhrady; vybírá jen vystavené doklady s úhradou (faktury, zálohové faktury, dobropisy). unpaid = zbývá něco uhradit (i částečně uhrazené a po splatnosti), overdue = zbývá uhradit a splatnost už uplynula, paid = nic nezbývá (i přeplacené a doklady s nulovou částkou). Jiná hodnota se ignoruje.","schema":{"type":"string","enum":["unpaid","overdue","paid"]},"example":"unpaid"},{"name":"approval","in":"query","required":false,"description":"waiting = přijaté výdaje ve schvalování (odeslané, vrácené k opravě nebo změněné po schválení), bez stornovaných; mine = doklady čekající na schválení (odeslané nebo změněné po schválení), které smí schválit volající. Jiná hodnota se ignoruje.","schema":{"type":"string","enum":["waiting","mine"]},"example":"waiting"},{"name":"partner_id","in":"query","required":false,"description":"Jen doklady tohoto kontaktu","schema":{"type":"integer"},"example":118},{"name":"from","in":"query","required":false,"description":"Datum vystavení od (včetně), ISO YYYY-MM-DD","schema":{"type":"string","format":"date"},"example":"2026-09-01"},{"name":"to","in":"query","required":false,"description":"Datum vystavení do (včetně), ISO YYYY-MM-DD","schema":{"type":"string","format":"date"},"example":"2026-09-30"},{"name":"year","in":"query","required":false,"description":"Hospodářský rok firmy podle data vystavení (začíná měsícem fiscal_year_start firmy). Hodnota mimo rozsah se ořízne, nečíselná znamená aktuální rok.","schema":{"type":"integer","minimum":2000,"maximum":2100},"example":2026},{"name":"q","in":"query","required":false,"description":"Hledaný text (část čísla, údajů kontaktu včetně IČO a adresy, variabilního symbolu, popisu nebo čísla dokladu dodavatele). Velikost písmen se nerozlišuje; u písmen s diakritikou ale jen tehdy, když jsou v uloženém textu malá.","schema":{"type":"string"},"example":"nordwood"},{"name":"page","in":"query","required":false,"description":"Číslo stránky; hodnota menší než 1 znamená 1","schema":{"type":"integer","default":1,"minimum":1},"example":1},{"name":"per","in":"query","required":false,"description":"Počet řádků na stránce; 0 nebo prázdná hodnota znamená 100, jiné hodnoty se ořežou do rozsahu 1–500","schema":{"type":"integer","default":100,"minimum":1,"maximum":500},"example":50}],"responses":{"200":{"description":"Objekt s počtem, stránkováním, součty v Kč a řádky dokladů (souhrnná podoba, bez položek a úhrad).","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"doklady","x-saldo-access":"member","x-saldo-side-effects":"Nic nezapisuje.","x-saldo-limits":"Nejvýše 500 řádků na stránku (výchozí 100).","x-saldo-response-fields":[{"name":"total","description":"Počet dokladů odpovídajících filtrům (všechny stránky)"},{"name":"page","description":"Vrácená stránka"},{"name":"per","description":"Použitý počet řádků na stránce"},{"name":"sums.net_czk","description":"Součet základů v Kč za celý výběr"},{"name":"sums.vat_czk","description":"Součet DPH v Kč za celý výběr"},{"name":"sums.gross_czk","description":"Součet částek s DPH v Kč za celý výběr"},{"name":"rows[].id","description":"ID dokladu"},{"name":"rows[].kind","description":"Druh dokladu (invoice_out, invoice_in, …)"},{"name":"rows[].kind_label","description":"Český název druhu, např. Faktura vydaná"},{"name":"rows[].status","description":"draft (koncept), issued (vystavený), cancelled (stornovaný)"},{"name":"rows[].number","description":"Číslo z číselné řady; null u konceptu, který ještě nebyl vystaven"},{"name":"rows[].variable_symbol","description":"Variabilní symbol"},{"name":"rows[].original_number","description":"Číslo dokladu dodavatele (u přijatých dokladů)"},{"name":"rows[].partner_id","description":"ID kontaktu"},{"name":"rows[].partner_name","description":"Jméno kontaktu – u vystaveného dokladu ze snímku při vystavení"},{"name":"rows[].partner_ico","description":"IČO kontaktu"},{"name":"rows[].issue_date","description":"Datum vystavení"},{"name":"rows[].taxable_date","description":"Datum uskutečnění zdanitelného plnění (DUZP)"},{"name":"rows[].due_date","description":"Datum splatnosti"},{"name":"rows[].currency","description":"Měna dokladu (ISO 4217)"},{"name":"rows[].total_net","description":"Základ v měně dokladu"},{"name":"rows[].total_vat","description":"DPH v měně dokladu"},{"name":"rows[].total_payable","description":"Částka k úhradě v měně dokladu (včetně zaokrouhlení)"},{"name":"rows[].total_gross_czk","description":"Částka s DPH přepočtená kurzem dokladu na Kč"},{"name":"rows[].paid_amount","description":"Uhrazeno v měně dokladu"},{"name":"rows[].remaining","description":"Zbývá uhradit (total_payable − paid_amount)"},{"name":"rows[].payment_state","description":"na (nevystavený doklad nebo druh bez úhrad), unpaid, partial, overdue, paid"},{"name":"rows[].days_overdue","description":"Počet dní po splatnosti (0, není-li overdue)"},{"name":"rows[].description","description":"Popis dokladu"},{"name":"rows[].vat_mode","description":"Režim DPH"},{"name":"rows[].source","description":"Původ dokladu: manual, recurring, isdoc, pohoda, import"},{"name":"rows[].tags","description":"Štítky (text)"},{"name":"rows[].related_document_id","description":"ID souvisejícího dokladu (např. faktura u dobropisu)"},{"name":"rows[].reminders_sent","description":"Počet zaznamenaných upomínek"},{"name":"rows[].outcome","description":"Výsledek nabídky: accepted, rejected nebo null"},{"name":"rows[].attachments_count","description":"Počet příloh"},{"name":"rows[].approval_state","description":"Uložený stav schvalování (pending, approved, returned, changed) nebo null"}]},"post":{"operationId":"createDocument","tags":["Doklady a jejich stavy"],"summary":"Založení dokladu, volitelně s vystavením","description":"Uloží nový doklad jako koncept: dopočítá částky řádků a součty podle sazeb DPH (DPH z rekapitulace po sazbách; u dokladu v Kč zaokrouhlí částku k úhradě – u prodeje podle nastavení firmy, u nákupu jen hotovostní), datum pro DPH a u dokladu v Kč kurz 1. Kontakt, bankovní účet, související doklad a odečítaná záloha, které firmě nepatří, se tiše vynechají (uloží se prázdné). S issue: true se doklad hned vystaví jako v issueDocument; přijatý výdaj, na který se vztahuje pravidlo schvalování a volající ho nesmí schválit, zůstane konceptem a odešle se ke schválení. Kurz cizí měny server nedoplňuje – bez exchange_rate se uloží kurz 1.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":7}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["document"],"properties":{"document":{"type":"object","required":["kind","issue_date"],"properties":{"kind":{"type":"string","description":"Druh dokladu (nelze později změnit). invoice_out/invoice_in – faktura vydaná/přijatá (řada FV/FP); proforma_out/proforma_in – zálohová faktura vydaná/přijatá (ZV/ZP, není daňový doklad; při vystavení se nezaúčtuje, její úhrady ano); advance_out/advance_in – daňový doklad k přijaté/poskytnuté platbě zálohy (DZ/DP); credit_out/ credit_in – opravný daňový doklad (dobropis) vydaný/přijatý (OV/OP); cash_in/cash_out – příjmový/ výdajový pokladní doklad (PP/VP); internal – interní doklad (ID, bez DPH, nezaúčtuje se; ruční účetní zápisy jsou /entries); quote_out – cenová nabídka (NA), order_out – objednávka vydaná (OB), delivery_out – dodací list (DL): obchodní doklady, nikdy se neúčtují ani nevstupují do DPH.","enum":["invoice_out","invoice_in","proforma_out","proforma_in","advance_out","advance_in","credit_out","credit_in","cash_in","cash_out","internal","quote_out","order_out","delivery_out"]},"partner_id":{"type":"integer","description":"ID kontaktu (odběratel nebo dodavatel); ID, které firmě nepatří, se uloží jako prázdné"},"issue_date":{"type":"string","format":"date","description":"Datum vystavení; určuje rok číselné řady"},"taxable_date":{"type":"string","format":"date","description":"DUZP; u daňových dokladů se při vystavení doplní datem vystavení, pokud chybí"},"due_date":{"type":"string","format":"date","description":"Datum splatnosti; nesmí být dříve než datum vystavení"},"received_date":{"type":"string","format":"date","description":"Datum přijetí dokladu (u přijatých dokladů)"},"vat_date":{"type":"string","format":"date","description":"Datum pro DPH. U prodeje se vždy přepíše na DUZP (jinak datum vystavení). U nákupu se bez hodnoty nastaví na pozdější z DUZP a data přijetí (jinak datum vystavení); zadané dřívější datum se posune na tuto hodnotu."},"currency":{"type":"string","description":"Kód měny ze tří písmen (převede se na velká); výchozí CZK","example":"EUR"},"exchange_rate":{"type":"number","description":"Kurz CZK za 1 jednotku měny (\u003e 0, 6 desetinných míst). U CZK se vždy nastaví 1. Server kurz ČNB nedoplňuje – bez hodnoty zůstane 1 i u cizí měny."},"rate_date":{"type":"string","format":"date","description":"Datum, ke kterému je kurz (informativní; posouzení limitu schvalování podle něj hledá kurz ČNB)"},"vat_mode":{"type":"string","description":"Režim DPH: domestic – tuzemské plnění (výchozí), reverse_charge – přenesená daňová povinnost (§ 92a), eu_goods – dodání/pořízení zboží v EU, eu_services – služby v rámci EU, import – dovoz ze třetí země, export – vývoz do třetí země, exempt – osvobozené plnění, non_vat – mimo DPH, triangular – třístranný obchod. DPH se počítá jen v režimu domestic a jen na řádcích druhu standard (u prodeje jen u plátce DPH, u interního dokladu nikdy); u přijatých dokladů plátce DPH nebo identifikované osoby v režimech reverse_charge, eu_goods, eu_services, import a triangular se daň vyměří samovyměřením.","enum":["domestic","reverse_charge","eu_goods","eu_services","import","export","exempt","non_vat","triangular"]},"rc_code":{"type":"string","description":"Kód předmětu plnění u přenesené daňové povinnosti (číselník rc_codes v /codebooks; hodnota se neověřuje)"},"prices_include_vat":{"type":"boolean","description":"Ceny řádků jsou včetně DPH (výchozí false)"},"simplified":{"type":"boolean","description":"Zjednodušený daňový doklad (výchozí false)"},"regime_44":{"type":"boolean","description":"Oprava v režimu § 44 ZDPH (výchozí false)"},"payment_method":{"type":"string","description":"Způsob úhrady – převodem, hotově, kartou, dobírka, zápočet, uhrazeno zálohou, jinak (výchozí bank)","enum":["bank","cash","card","cod","offset","advance","other"]},"bank_account_id":{"type":"integer","description":"ID bankovního účtu nebo pokladny firmy pro úhradu; cizí ID se uloží jako prázdné"},"variable_symbol":{"type":"string","description":"Variabilní symbol; nečíselné znaky se odstraní, nejvýše 10 číslic. U prodeje se při vystavení doplní z čísla dokladu"},"constant_symbol":{"type":"string","description":"Konstantní symbol, nejvýše 10 číslic"},"specific_symbol":{"type":"string","description":"Specifický symbol, nejvýše 10 číslic"},"original_number":{"type":"string","description":"Číslo dokladu dodavatele (u přijatých dokladů); používá se ke kontrole duplicit"},"description":{"type":"string","description":"Popis dokladu"},"note":{"type":"string","description":"Text na dokladu (vidí ho i zákazník)"},"internal_note":{"type":"string","description":"Interní poznámka; na sdílené stránce dokladu se nezobrazí"},"language":{"type":"string","description":"Jazyk dokladu (výchozí cs)","enum":["cs","en"]},"kh_section":{"type":"string","description":"Oddíl kontrolního hlášení; jen se uloží, výpočty ho nečtou"},"cost_center":{"type":"string","description":"Středisko (podmínka pravidel schvalování)"},"project":{"type":"string","description":"Projekt / zakázka"},"tags":{"type":"string","description":"Štítky jako text"},"related_document_id":{"type":"integer","description":"ID souvisejícího dokladu firmy (např. původní faktura dobropisu); cizí ID se uloží jako prázdné"},"lines_attributes":{"type":"array","description":"Řádky dokladu v pořadí, v jakém se mají zobrazit","items":{"type":"object","properties":{"description":{"type":"string","description":"Text položky, nejvýše 500 znaků"},"quantity":{"type":"number","description":"Množství, nesmí být 0 (záporné u dobropisu nebo odpočtu); výchozí 1"},"unit":{"type":"string","description":"Jednotka, např. ks, hod"},"unit_price":{"type":"number","description":"Jednotková cena (bez DPH, nebo s DPH při prices_include_vat), 4 desetinná místa"},"discount_percent":{"type":"number","description":"Sleva v procentech 0–100"},"vat_rate":{"type":"number","description":"Sazba DPH v procentech 0–100; bez hodnoty 0"},"vat_kind":{"type":"string","description":"Druh plnění – zdanitelné, osvobozené s nárokem, osvobozené bez nároku na odpočet, není předmětem daně (výchozí standard)","enum":["standard","exempt_with_credit","exempt_without_credit","not_subject"]},"account_code":{"type":"string","description":"Účet (podvojné účetnictví) nebo kategorie daňové evidence; prázdný se při zaúčtování nahradí 602/518 (daňová evidence P02/V05); nejvýše 12 znaků: číslice, velká písmena, tečka, pomlčka"},"asset":{"type":"boolean","description":"Pořízení majetku"},"deduction":{"type":"string","description":"Nárok na odpočet DPH u nákupu – plný, krácený koeficientem, žádný (výchozí full)","enum":["full","proportional","none"]},"advance_document_id":{"type":"integer","description":"Odpočet zálohy – ID daňového dokladu k záloze (advance_out/advance_in); jiné ID se uloží jako prázdné"}}}}}},"issue":{"type":"boolean","description":"true = po uložení doklad vystavit (nebo odeslat ke schválení)"},"capture_key":{"type":"string","description":"Volitelný klíč idempotence (UUID). Opakovaný požadavek se stejným klíčem ve stejné firmě vrátí už uložený doklad místo nového.","example":"3f2b8c1e-8a4d-4c1b-9f6e-2d7a5b9c0e14"}}},"example":{"issue":true,"document":{"kind":"invoice_out","partner_id":1,"issue_date":"2026-09-28","taxable_date":"2026-09-28","due_date":"2026-10-12","payment_method":"bank","bank_account_id":2,"description":"Konzultace – září","lines_attributes":[{"description":"Konzultace – digitální strategie","quantity":6,"unit":"hod","unit_price":2200,"vat_rate":21,"account_code":"602"}]}}}}},"responses":{"201":{"description":"Detail založeného dokladu jako v getDocument (včetně approval). Při opakování se stejným capture_key odpověď 200 s detailem dříve uloženého dokladu bez klíče approval.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"capture_key není UUID: „Neplatný identifikátor nahrání“ S issue: true doklad bez řádků: „Doklad nemá žádnou položku“ S issue: true faktura, zálohová faktura, dobropis, daňový doklad k záloze nebo obchodní doklad bez kontaktu: „Doplňte odběratele nebo dodavatele“ S issue: true řádek odečítá neexistující nebo nevystavený daňový doklad k záloze: „Odečítaná záloha neexistuje“ S issue: true je daňový doklad k záloze už odečtený na jiném vystaveném dokladu: „Daňový doklad … je už odečtený na dokladu …“ S issue: true datum dokladu v uzamčeném období: „Období do … je uzamčeno – doklad nelze měnit“ (tvar { error, errors }); se zadaným capture_key se místo této chyby vrátí 200 s uloženým konceptem","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"doklady","x-saldo-access":"writer","x-saldo-access-note":"S issue: true platí pro přijaté výdaje (invoice_in, cash_out, credit_in) pravidla schvalování: kdo doklad nesmí schválit, ten ho jen odešle ke schválení.","x-saldo-side-effects":"Vytvoří doklad se zdrojem manual a jeho řádky a zapíše do historie document.created. S issue: true navíc totéž co issueDocument (číslo z řady, účetní zápisy v podvojném účetnictví, document.issued), případně odeslání ke schválení (document.approval_submitted). U přijatého výdaje v cizí měně se při zapnutém schvalování může dotázat kurz ČNB (jen pro posouzení limitu). Když vystavení selže (422), koncept už zůstane uložený.","x-saldo-limits":"Popis řádku nejvýše 500 znaků; variabilní, konstantní a specifický symbol nejvýše 10 číslic.","x-saldo-repeat":"Bez capture_key vytvoří každé volání nový doklad (i po chybě vystavení, kdy už koncept existuje). Se stejným capture_key (bez ohledu na velikost písmen, jedinečný v rámci firmy) vrátí opakované volání dříve uložený doklad se stavem 200, tělo ignoruje a nic nevystavuje; souběžné opakování se ošetří stejně.","x-saldo-errors":[{"status":422,"when":"capture_key není UUID: „Neplatný identifikátor nahrání“"},{"status":422,"when":"S issue: true doklad bez řádků: „Doklad nemá žádnou položku“"},{"status":422,"when":"S issue: true faktura, zálohová faktura, dobropis, daňový doklad k záloze nebo obchodní doklad bez kontaktu: „Doplňte odběratele nebo dodavatele“"},{"status":422,"when":"S issue: true řádek odečítá neexistující nebo nevystavený daňový doklad k záloze: „Odečítaná záloha neexistuje“"},{"status":422,"when":"S issue: true je daňový doklad k záloze už odečtený na jiném vystaveném dokladu: „Daňový doklad … je už odečtený na dokladu …“"},{"status":422,"when":"S issue: true datum dokladu v uzamčeném období: „Období do … je uzamčeno – doklad nelze měnit“ (tvar { error, errors }); se zadaným capture_key se místo této chyby vrátí 200 s uloženým konceptem"}],"x-saldo-example":{"note":"Vystaví fakturu vydanou; odpověď obsahuje číslo z řady FV a stav issued."}}},"/entities/{entity_id}/documents/{id}":{"get":{"operationId":"getDocument","tags":["Doklady a jejich stavy"],"summary":"Detail dokladu","description":"Vrátí úplný doklad: souhrnné údaje jako v seznamu, všechny údaje dokladu, kontakt (uložený snímek – u vystaveného dokladu z okamžiku vystavení –, jinak aktuální údaje z adresáře), řádky s dopočítanými částkami, rekapitulaci DPH podle sazeb, úhrady, metadata příloh, stav sdíleného odkazu, bankovní účet, související doklad, aktivní opakování a stav schvalování.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":7},{"name":"id","in":"path","required":true,"description":"ID dokladu","schema":{"type":"integer"},"example":1532}],"responses":{"200":{"description":"Všechna pole řádku ze seznamu dokladů (listDocuments) a navíc údaje níže. Peníze jsou čísla v měně dokladu, pole *_czk v Kč.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"doklady","x-saldo-access":"member","x-saldo-side-effects":"Nic nezapisuje.","x-saldo-response-fields":[{"name":"uuid","description":"UUID dokladu (u importu z ISDOC), jinak null"},{"name":"constant_symbol","description":"Konstantní symbol"},{"name":"specific_symbol","description":"Specifický symbol"},{"name":"received_date","description":"Datum přijetí"},{"name":"vat_date","description":"Datum pro DPH"},{"name":"exchange_rate","description":"Kurz CZK za jednotku měny"},{"name":"rate_date","description":"Datum kurzu"},{"name":"rc_code","description":"Kód předmětu plnění PDP"},{"name":"prices_include_vat","description":"Ceny včetně DPH"},{"name":"simplified","description":"Zjednodušený daňový doklad"},{"name":"regime_44","description":"Oprava podle § 44 ZDPH"},{"name":"payment_method","description":"Způsob úhrady"},{"name":"bank_account_id","description":"ID účtu pro úhradu"},{"name":"rounding","description":"Zaokrouhlení částky k úhradě"},{"name":"total_gross","description":"Částka s DPH v měně dokladu (před zaokrouhlením)"},{"name":"total_net_czk","description":"Základ v Kč"},{"name":"total_vat_czk","description":"DPH v Kč"},{"name":"note","description":"Text na dokladu"},{"name":"internal_note","description":"Interní poznámka"},{"name":"language","description":"cs nebo en"},{"name":"kh_section","description":"Uložený oddíl kontrolního hlášení"},{"name":"cost_center","description":"Středisko"},{"name":"project","description":"Projekt"},{"name":"paid_on","description":"Datum poslední úhrady, když je doklad plně uhrazen (u pokladního dokladu datum vystavení), jinak null"},{"name":"created_at","description":"Založeno"},{"name":"updated_at","description":"Naposledy změněno"},{"name":"partner","description":"Kontakt { name, ico, dic, street, city, zip, country, email, phone }"},{"name":"lines[]","description":"Řádky { id, position, description, quantity, unit, unit_price, discount_percent, vat_rate, vat_kind, account_code, asset, deduction, advance_document_id, net, vat, gross, net_czk, vat_czk }"},{"name":"attachments[]","description":"Přílohy { id, filename, content_type, byte_size, inline, created_at }"},{"name":"share","description":"Veřejný odkaz { token, shared_at, viewed_at, views } nebo null"},{"name":"payments[]","description":"Úhrady podle data { id, document_id, bank_transaction_id, bank_account_id, paid_on, amount, amount_czk, exchange_rate, payment_method, note }"},{"name":"vat_recap[]","description":"Rekapitulace DPH po sazbách sestupně { rate, net, vat, gross, net_czk, vat_czk }"},{"name":"bank_account","description":"Bankovní účet nebo pokladna dokladu (údaje účtu, display_number) nebo null"},{"name":"related_document","description":"{ id, number, kind } souvisejícího dokladu nebo null"},{"name":"recurrence","description":"Aktivní pravidlo opakování, kde je doklad vzorem (bez template), nebo null"},{"name":"approval","description":"Stav schvalování { state, label, required, rule, approvers, fingerprint, can_submit, can_approve, can_return, history[] } nebo null, když doklad nemá historii schvalování a schvalování se ho netýká (nebo byl vystaven dřív, než ho pravidlo pokrylo)"}]},"patch":{"operationId":"updateDocument","tags":["Doklady a jejich stavy"],"summary":"Úprava dokladu","description":"Změní údaje dokladu a jeho řádků; kind se ignoruje (druh nelze změnit). Řádek s id se upraví, řádek s id a _destroy: true se odebere, řádek bez id se přidá; řádky, které v požadavku nejsou, zůstanou beze změny. Upravit lze i vystavený doklad (a také stornovaný): u vystaveného se účetní zápisy smažou a zaúčtují znovu a při změně kontaktu se obnoví snímek kontaktu. Změna vystaveného nebo stornovaného dokladu, jehož data leží v uzamčeném období, se odmítne; u konceptu se uzamčení nekontroluje. S issue: true se koncept po uložení vystaví (nebo odešle ke schválení); u nekonceptu se issue ignoruje.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":7},{"name":"id","in":"path","required":true,"description":"ID dokladu","schema":{"type":"integer"},"example":1532}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["document"],"properties":{"document":{"type":"object","properties":{"partner_id":{"type":"integer","description":"ID kontaktu; cizí ID se uloží jako prázdné"},"issue_date":{"type":"string","format":"date","description":"Datum vystavení"},"taxable_date":{"type":"string","format":"date","description":"DUZP"},"due_date":{"type":"string","format":"date","description":"Datum splatnosti; nesmí být dříve než datum vystavení"},"received_date":{"type":"string","format":"date","description":"Datum přijetí"},"vat_date":{"type":"string","format":"date","description":"Datum pro DPH (u prodeje se přepíše na DUZP, u nákupu nejdřív DUZP / datum přijetí)"},"currency":{"type":"string","description":"Kód měny"},"exchange_rate":{"type":"number","description":"Kurz CZK za jednotku měny (\u003e 0); u CZK vždy 1"},"rate_date":{"type":"string","format":"date","description":"Datum kurzu"},"vat_mode":{"type":"string","description":"Režim DPH (viz createDocument)","enum":["domestic","reverse_charge","eu_goods","eu_services","import","export","exempt","non_vat","triangular"]},"rc_code":{"type":"string","description":"Kód předmětu plnění PDP"},"prices_include_vat":{"type":"boolean","description":"Ceny včetně DPH"},"simplified":{"type":"boolean","description":"Zjednodušený daňový doklad"},"regime_44":{"type":"boolean","description":"Oprava podle § 44 ZDPH"},"payment_method":{"type":"string","description":"Způsob úhrady","enum":["bank","cash","card","cod","offset","advance","other"]},"bank_account_id":{"type":"integer","description":"ID bankovního účtu nebo pokladny; cizí ID se uloží jako prázdné"},"variable_symbol":{"type":"string","description":"Variabilní symbol (jen číslice, nejvýše 10)"},"constant_symbol":{"type":"string","description":"Konstantní symbol, nejvýše 10 číslic"},"specific_symbol":{"type":"string","description":"Specifický symbol, nejvýše 10 číslic"},"original_number":{"type":"string","description":"Číslo dokladu dodavatele"},"description":{"type":"string","description":"Popis"},"note":{"type":"string","description":"Text na dokladu"},"internal_note":{"type":"string","description":"Interní poznámka"},"language":{"type":"string","description":"Jazyk dokladu","enum":["cs","en"]},"kh_section":{"type":"string","description":"Oddíl kontrolního hlášení (jen se uloží)"},"cost_center":{"type":"string","description":"Středisko"},"project":{"type":"string","description":"Projekt"},"tags":{"type":"string","description":"Štítky"},"related_document_id":{"type":"integer","description":"ID souvisejícího dokladu; cizí ID se uloží jako prázdné"},"lines_attributes":{"type":"array","description":"Změny řádků – s id úprava, s id a _destroy smazání, bez id nový řádek","items":{"type":"object","properties":{"id":{"type":"integer","description":"ID existujícího řádku dokladu"},"_destroy":{"type":"boolean","description":"true = řádek odebrat"},"description":{"type":"string","description":"Text položky, nejvýše 500 znaků"},"quantity":{"type":"number","description":"Množství, nesmí být 0"},"unit":{"type":"string","description":"Jednotka"},"unit_price":{"type":"number","description":"Jednotková cena"},"discount_percent":{"type":"number","description":"Sleva 0–100 %"},"vat_rate":{"type":"number","description":"Sazba DPH 0–100 %"},"vat_kind":{"type":"string","description":"Druh plnění","enum":["standard","exempt_with_credit","exempt_without_credit","not_subject"]},"account_code":{"type":"string","description":"Účet nebo kategorie daňové evidence"},"asset":{"type":"boolean","description":"Pořízení majetku"},"deduction":{"type":"string","description":"Nárok na odpočet","enum":["full","proportional","none"]},"advance_document_id":{"type":"integer","description":"ID odečítaného daňového dokladu k záloze"}}}}}},"issue":{"type":"boolean","description":"true = koncept po uložení vystavit (nebo odeslat ke schválení)"}}},"example":{"document":{"due_date":"2026-10-20","note":"Děkujeme za spolupráci."}}}}},"responses":{"200":{"description":"Detail upraveného dokladu jako v getDocument (včetně approval).","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Data dokladu v uzamčeném období (u nekonceptu): „Období do … je uzamčeno – doklad nelze měnit“ (tvar { error, errors }) Účetní zápisy vystaveného dokladu leží v uzamčeném období: „Období do … je uzamčeno – zaúčtování nelze změnit“ Nepovolená změna zaúčtovaného výdaje ve schvalování: „Změnu částky, kurzu, dodavatele, střediska nebo účtů u zaúčtovaného dokladu musí schválit … – vraťte doklad do konceptu a odešlete ho ke schválení“ S issue: true stejné chyby jako issueDocument (bez řádků, bez kontaktu, odečítaná záloha)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"doklady","x-saldo-access":"writer","x-saldo-access-note":"Změnu částky, kurzu, dodavatele (včetně jeho účtu), střediska nebo účtů zaúčtovaného přijatého výdaje, na který se vztahuje pravidlo schvalování, smí uložit jen jeho schvalovatel; ostatním vrátí 422.","x-saldo-side-effects":"Uloží změny a zapíše document.updated; u vystaveného dokladu v podvojném účetnictví přeúčtuje jeho účetní zápisy. Při zapnutém schvalování změnu schvalovaných údajů schvalovatelem rovnou znovu schválí, změnu jiného člena u schváleného dokladu označí „Změněno po schválení“. S issue: true navíc jako issueDocument; když vystavení selže, změny už zůstanou uložené.","x-saldo-repeat":"Opakování se stejným tělem dá stejný výsledek, kromě řádků bez id – ty se při každém volání přidají znovu; každé volání zapíše další document.updated.","x-saldo-errors":[{"status":422,"when":"Data dokladu v uzamčeném období (u nekonceptu): „Období do … je uzamčeno – doklad nelze měnit“ (tvar { error, errors })"},{"status":422,"when":"Účetní zápisy vystaveného dokladu leží v uzamčeném období: „Období do … je uzamčeno – zaúčtování nelze změnit“"},{"status":422,"when":"Nepovolená změna zaúčtovaného výdaje ve schvalování: „Změnu částky, kurzu, dodavatele, střediska nebo účtů u zaúčtovaného dokladu musí schválit … – vraťte doklad do konceptu a odešlete ho ke schválení“"},{"status":422,"when":"S issue: true stejné chyby jako issueDocument (bez řádků, bez kontaktu, odečítaná záloha)"}]},"delete":{"operationId":"deleteDocument","tags":["Doklady a jejich stavy"],"summary":"Smazání konceptu","description":"Smaže koncept, který ještě nemá číslo (nikdy nebyl vystaven), s jeho řádky, přílohami a historií schvalování a zruší otevřené žádosti o podklad k dokladu. Vystavený ani stornovaný doklad a ani koncept vrácený z vystaveného dokladu (má číslo) smazat nelze – aby v číselné řadě nevznikla mezera, stornuje se.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":7},{"name":"id","in":"path","required":true,"description":"ID dokladu","schema":{"type":"integer"},"example":1540}],"responses":{"204":{"description":"Prázdná odpověď."},"422":{"description":"Doklad není koncept (vystavený nebo stornovaný): „Vystavený doklad nelze smazat – stornujte ho“ Koncept už má číslo z řady: „Doklad už má číslo z číselné řady – aby v ní nevznikla mezera, stornujte ho“","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"doklady","x-saldo-access":"writer","x-saldo-side-effects":"Smaže doklad, řádky, přílohy a záznamy schvalování; otevřené žádosti o podklad k dokladu zruší (zpráva a událost document_request.cancelled) a zapíše document.deleted. Pravidlo opakování, jehož je doklad vzorem, se nesmaže.","x-saldo-repeat":"Druhé volání vrátí 404.","x-saldo-errors":[{"status":422,"when":"Doklad není koncept (vystavený nebo stornovaný): „Vystavený doklad nelze smazat – stornujte ho“"},{"status":422,"when":"Koncept už má číslo z řady: „Doklad už má číslo z číselné řady – aby v ní nevznikla mezera, stornujte ho“"}]}},"/entities/{entity_id}/documents/template":{"get":{"operationId":"getDocumentTemplate","tags":["Doklady a jejich stavy"],"summary":"Předvyplněný nový doklad","description":"Vrátí neuložený koncept zvoleného druhu s výchozími hodnotami firmy: datum vystavení dnes, DUZP dnes u daňových dokladů, datum přijetí dnes u nákupních, u faktur, zálohových faktur a dobropisů splatnost podle výchozí splatnosti firmy (u nabídky 30 dní, jinde žádná), jazyk z nastavení faktur, u pokladních dokladů hotově a první aktivní pokladna, jinak převodem a výchozí (nebo první) aktivní bankovní účet, tuzemské plnění a jeden řádek 1 ks s cenou 0, sazbou 21 % (u prodeje neplátce DPH 0 %) a výchozím účtem. Přidá number_preview – číslo, které by doklad dostal při vystavení dnes. Nic neukládá; doklad se založí přes createDocument.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":7},{"name":"kind","in":"query","required":false,"description":"Druh dokladu; neznámá hodnota znamená invoice_out","schema":{"type":"string","enum":["invoice_out","invoice_in","proforma_out","proforma_in","advance_out","advance_in","credit_out","credit_in","cash_in","cash_out","internal","quote_out","order_out","delivery_out"],"default":"invoice_out"},"example":"invoice_in"}],"responses":{"200":{"description":"Doklad ve tvaru getDocument (id null, status draft, částky 0, přílohy a úhrady prázdné, approval chybí) a navíc number_preview.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"doklady","x-saldo-access":"member","x-saldo-side-effects":"Nic nezapisuje.","x-saldo-response-fields":[{"name":"number_preview","description":"Náhled čísla z číselné řady k dnešnímu dni"},{"name":"lines[]","description":"Jeden výchozí řádek bez id"}]}},"/entities/{entity_id}/documents/next_number":{"get":{"operationId":"previewDocumentNumber","tags":["Doklady a jejich stavy"],"summary":"Náhled dalšího čísla dokladu","description":"Vrátí číslo, které by dostal doklad druhu kind vystavený k datu date, podle formátu čísel firmy (výchozí {prefix}{yyyy}{nnnn}, např. FV20260001; další zástupné znaky {yy}, {mm}). Každý druh má vlastní řadu pro každý kalendářní rok data vystavení. Jde jen o náhled: číslo se nerezervuje a při vystavení se přeskočí čísla, která už nějaký doklad téhož druhu používá (např. z importu).","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":7},{"name":"kind","in":"query","required":false,"description":"Druh dokladu; neznámá hodnota znamená invoice_out","schema":{"type":"string","enum":["invoice_out","invoice_in","proforma_out","proforma_in","advance_out","advance_in","credit_out","credit_in","cash_in","cash_out","internal","quote_out","order_out","delivery_out"],"default":"invoice_out"},"example":"invoice_out"},{"name":"date","in":"query","required":false,"description":"Datum vystavení, ke kterému se číslo počítá (výchozí dnes)","schema":{"type":"string","format":"date"},"example":"2026-09-28"}],"responses":{"200":{"description":"Objekt s náhledem čísla.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"doklady","x-saldo-access":"member","x-saldo-side-effects":"Nic nezapisuje.","x-saldo-response-fields":[{"name":"number","description":"Číslo, např. FV20260042"}]}},"/entities/{entity_id}/documents/items":{"get":{"operationId":"listItemSuggestions","tags":["Doklady a jejich stavy"],"summary":"Našeptávač položek z dřívějších dokladů","description":"Vrátí nejvýše 8 položek, které firma použila na dokladech stejného směru jako kind (prodej, nákup, nebo interní), jejichž text obsahuje všechna slova dotazu (bez ohledu na velikost písmen a diakritiku); prázdný dotaz vrátí nejčastější položky. Prochází posledních 3 000 řádků nestornovaných dokladů s kladným množstvím a neprázdným textem, bez odpočtů záloh. Položky se stejným textem se sloučí a hodnoty jsou z posledního použití. Pořadí: skóre (četnost, text nebo slovo začíná dotazem, použití za posledních 45 a 180 dní), pak novější použití.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":7},{"name":"q","in":"query","required":false,"description":"Hledaná slova","schema":{"type":"string"},"example":"konzultace"},{"name":"kind","in":"query","required":false,"description":"Druh editovaného dokladu; určuje směr (prodej / nákup / interní)","schema":{"type":"string","enum":["invoice_out","invoice_in","proforma_out","proforma_in","advance_out","advance_in","credit_out","credit_in","cash_in","cash_out","internal","quote_out","order_out","delivery_out"],"default":"invoice_out"},"example":"invoice_out"}],"responses":{"200":{"description":"Návrhy položek.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"doklady","x-saldo-access":"member","x-saldo-side-effects":"Nic nezapisuje.","x-saldo-limits":"Nejvýše 8 návrhů; prohledá posledních 3 000 řádků.","x-saldo-response-fields":[{"name":"rows[].description","description":"Text položky"},{"name":"rows[].unit","description":"Jednotka"},{"name":"rows[].unit_price","description":"Jednotková cena z posledního použití"},{"name":"rows[].vat_rate","description":"Sazba DPH"},{"name":"rows[].vat_kind","description":"Druh plnění"},{"name":"rows[].account_code","description":"Účet / kategorie"},{"name":"rows[].discount_percent","description":"Sleva"},{"name":"rows[].currency","description":"Měna dokladu, kde byla položka naposledy"},{"name":"rows[].prices_include_vat","description":"Zda byla cena včetně DPH"},{"name":"rows[].count","description":"Kolikrát byla položka použita"},{"name":"rows[].last_used","description":"Datum vystavení posledního dokladu s položkou"},{"name":"rows[].score","description":"Skóre pořadí"}]}},"/entities/{entity_id}/documents/partner_defaults":{"get":{"operationId":"getPartnerDefaults","tags":["Doklady a jejich stavy"],"summary":"Výchozí údaje dokladu podle kontaktu","description":"Pro kontakt vrátí údaje z jeho posledního nestornovaného dokladu (i konceptu) stejného směru jako kind (přednostně stejného druhu): měnu, způsob úhrady, jazyk, režim DPH, kód PDP, ceny s DPH, konstantní symbol, bankovní účet (jen je-li stále aktivní) a splatnost ve dnech (z kontaktu, jinak z posledního dokladu s úhradou, 0–365). U nákupu navrhne účet řádku. last_document nese řádky posledního dokladu stejného druhu (bez odpočtů záloh) pro „Stejné jako minule“.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":7},{"name":"partner_id","in":"query","required":true,"description":"ID kontaktu firmy","schema":{"type":"integer"},"example":118},{"name":"kind","in":"query","required":false,"description":"Druh editovaného dokladu","schema":{"type":"string","enum":["invoice_out","invoice_in","proforma_out","proforma_in","advance_out","advance_in","credit_out","credit_in","cash_in","cash_out","internal","quote_out","order_out","delivery_out"],"default":"invoice_out"},"example":"invoice_in"}],"responses":{"200":{"description":"Výchozí hodnoty; bez předchozího dokladu jsou údaje dokladu null.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"doklady","x-saldo-access":"member","x-saldo-side-effects":"Nic nezapisuje.","x-saldo-response-fields":[{"name":"partner_id","description":"ID kontaktu"},{"name":"based_on","description":"{ id, number, kind, issue_date } dokladu, ze kterého hodnoty pocházejí (number u konceptu je text Koncept), nebo null"},{"name":"currency","description":"Měna"},{"name":"payment_method","description":"Způsob úhrady"},{"name":"language","description":"Jazyk"},{"name":"vat_mode","description":"Režim DPH"},{"name":"rc_code","description":"Kód PDP"},{"name":"prices_include_vat","description":"Ceny s DPH"},{"name":"constant_symbol","description":"Konstantní symbol"},{"name":"bank_account_id","description":"Aktivní bankovní účet posledního dokladu nebo null"},{"name":"due_days","description":"Splatnost ve dnech nebo null"},{"name":"account_code","description":"U nákupu nejčastější účet řádků vystavených nákupních dokladů kontaktu, jinak výchozí účet kontaktu, jinak 518 (daňová evidence V05); u prodeje a interního dokladu null"},{"name":"last_document","description":"{ id, number, issue_date, total_payable, currency, prices_include_vat, lines[] } posledního dokladu stejného druhu, nebo null"}]}},"/entities/{entity_id}/documents/duplicates":{"get":{"operationId":"findDuplicateDocument","tags":["Doklady a jejich stavy"],"summary":"Kontrola duplicity přijatého dokladu","description":"Zjistí, zda firma už nemá stejný přijatý doklad. Kontroluje jen nákupní druhy (invoice_in, proforma_in, advance_in, credit_in, cash_out) se známým kontaktem firmy a porovnává s nestornovanými nákupními doklady téhož dodavatele (stejný kontakt nebo stejné IČO): nejdřív shodné číslo dokladu dodavatele (bez ohledu na velikost písmen a mezery na krajích), jinak stejná měna a částka k úhradě (±0,005) s datem vystavení nejvýše 3 dny od zadaného. Vrátí nejstarší takový doklad s větou pro uživatele, jinak null. Ukládání dokladu tuto kontrolu neprovádí; hromadné vystavení ano.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":7},{"name":"kind","in":"query","required":false,"description":"Druh kontrolovaného dokladu; u jiného než nákupního druhu (včetně internal a order_out) je výsledek vždy null","schema":{"type":"string","enum":["invoice_out","invoice_in","proforma_out","proforma_in","advance_out","advance_in","credit_out","credit_in","cash_in","cash_out","internal","quote_out","order_out","delivery_out"],"default":"invoice_out"},"example":"invoice_in"},{"name":"partner_id","in":"query","required":false,"description":"ID dodavatele; bez něj (nebo s cizím ID) je výsledek null","schema":{"type":"integer"},"example":131},{"name":"original_number","in":"query","required":false,"description":"Číslo dokladu dodavatele","schema":{"type":"string"},"example":"2026090815"},{"name":"issue_date","in":"query","required":false,"description":"Datum vystavení (pro shodu podle částky)","schema":{"type":"string","format":"date"},"example":"2026-09-20"},{"name":"total","in":"query","required":false,"description":"Částka k úhradě v měně dokladu (pro shodu podle částky; 0 nebo prázdná shodu podle částky vypne)","schema":{"type":"number"},"example":17545},{"name":"currency","in":"query","required":false,"description":"Kód měny dokladu velkými písmeny (pro shodu podle částky); hodnota se nepřevádí, takže s eur se shoda podle částky nenajde","schema":{"type":"string","default":"CZK"},"example":"CZK"},{"name":"id","in":"query","required":false,"description":"ID právě upravovaného dokladu, který se má z porovnání vynechat","schema":{"type":"integer"},"example":1540}],"responses":{"200":{"description":"Pravděpodobná duplicita nebo null.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"doklady","x-saldo-access":"member","x-saldo-side-effects":"Nic nezapisuje.","x-saldo-response-fields":[{"name":"duplicate_of","description":"null, nebo { id, number, kind, status, original_number, issue_date, total_payable, currency, partner, reason, message }"},{"name":"duplicate_of.reason","description":"number (stejné číslo dokladu dodavatele) nebo amount (stejná částka do 3 dnů)"},{"name":"duplicate_of.message","description":"Česká věta pro uživatele"}]}},"/entities/{entity_id}/documents/reminders":{"get":{"operationId":"listReminderCandidates","tags":["Doklady a jejich stavy"],"summary":"Doklady k upomenutí s úroky z prodlení","description":"Bez ids vrátí vydané faktury (invoice_out) po splatnosti, u nichž od splatnosti i od poslední upomínky uplynulo aspoň tolik dní, kolik je v nastavení automatizace (reminder_days, výchozí 7), seřazené podle splatnosti. S ids vrátí z uvedených dokladů firmy jen vydané faktury a vydané zálohové faktury po splatnosti; ostatní započte do skipped. U každého dokladu spočítá úrok z prodlení k dnešku podle NV č. 351/2013 Sb. (a u kontaktu s IČO náklady uplatnění pohledávky 1 200 Kč). Nic nezaznamenává – upomínku zapíše recordDocumentReminder nebo hromadná akce remind.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":7},{"name":"ids","in":"query","required":false,"description":"ID dokladů oddělená čárkou (nebo opakovaný parametr ids[]); použije se prvních 100","schema":{"type":"string"},"example":15321533}],"responses":{"200":{"description":"Doklady s úrokem a pořadím příští upomínky.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"doklady","x-saldo-access":"member","x-saldo-side-effects":"Nic nezapisuje.","x-saldo-limits":"Nejvýše 100 ID v parametru ids.","x-saldo-response-fields":[{"name":"days","description":"Počet dní po splatnosti z nastavení automatizace (reminder_days)"},{"name":"entity","description":"Údaje firmy pro hlavičku upomínky"},{"name":"skipped","description":"S ids počet uvedených ID, které nejsou vydanou fakturou nebo zálohovou fakturou po splatnosti (i cizí ID); bez ids 0"},{"name":"rows[].document","description":"Detail dokladu (bez approval)"},{"name":"rows[].interest","description":"Výpočet úroku jako v getDocumentReminder, nebo null, když výpočet nejde"},{"name":"rows[].next_level","description":"Pořadí příští upomínky (zaznamenané upomínky + 1)"}]}},"/entities/{entity_id}/documents/bulk":{"post":{"operationId":"runBulkDocumentAction","tags":["Doklady a jejich stavy"],"summary":"Hromadná akce s doklady","description":"Provede jednu akci s každým vybraným dokladem zvlášť – odmítnutí jednoho dokladu nezastaví ostatní a odpověď říká, co se povedlo a proč zbytek ne. issue vystaví koncepty jako issueDocument, ale nikdy neschvaluje (přijatý výdaj, který schválení potřebuje a nemá ho, odmítne) a nevystaví koncept přijatého dokladu, který vypadá jako duplicita (viz findDuplicateDocument). pay zaznamená úhradu zbývající částky k paid_on na bank_account_id (hotově, je-li to pokladna, jinak převodem). remind zaznamená upomínku u vydané faktury nebo zálohové faktury po splatnosti. delete smaže koncepty bez čísla. Parametr se jmenuje operation, protože název action je v Rails vyhrazený.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":7}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["operation","ids"],"properties":{"operation":{"type":"string","description":"Hromadná akce","enum":["issue","pay","remind","delete"]},"ids":{"type":"array","description":"ID dokladů firmy (lze i jeden řetězec s ID oddělenými čárkou); ID jiných firem se tiše vynechají","items":{"type":"integer"}},"paid_on":{"type":"string","format":"date","description":"Jen pay – datum úhrady (výchozí dnes)"},"bank_account_id":{"type":"integer","description":"Jen pay – bankovní účet nebo pokladna, na kterou se úhrada zaznamená; ID, které firmě nepatří, vrátí 404 u každé akce"}}},"example":{"operation":"pay","ids":[143],"paid_on":"2026-09-28","bank_account_id":2}}}},"responses":{"200":{"description":"Výsledek akce po dokladech.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Neznámá hodnota operation: „Neznámá hromadná akce – použijte issue, pay, remind nebo delete“ Žádné z ids nepatří dokladu firmy: „Vyberte alespoň jeden doklad“","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"doklady","x-saldo-access":"writer","x-saldo-side-effects":"issue: jako issueDocument u každého úspěšného dokladu (číslo, účetní zápisy, document.issued). pay: úhrada s poznámkou „Hromadně označeno jako zaplacené“, v podvojném účetnictví i její účetní zápis (payment.recorded). remind: počítadlo upomínek +1, datum poslední upomínky dnes, document.reminded. delete: smazání konceptu jako deleteDocument (document.deleted). Každý doklad se zpracuje samostatně; akce nad celou dávkou není atomická.","x-saldo-limits":"Použije prvních 300 ID z ids (další se ignorují); doklady zpracuje v pořadí podle data vystavení.","x-saldo-repeat":"Opakovaná akce issue nebo pay vrátí doklady ve failed („Doklad už je vystavený“, „Doklad je už uhrazený“); remind zaznamená při každém volání další upomínku; delete nenajde smazané doklady.","x-saldo-errors":[{"status":422,"when":"Neznámá hodnota operation: „Neznámá hromadná akce – použijte issue, pay, remind nebo delete“"},{"status":422,"when":"Žádné z ids nepatří dokladu firmy: „Vyberte alespoň jeden doklad“"}],"x-saldo-response-fields":[{"name":"operation","description":"Provedená akce"},{"name":"done","description":"Počet dokladů, u kterých akce proběhla"},{"name":"failed[]","description":"{ id, number, error } – doklady, u kterých akce neproběhla, s důvodem v češtině"},{"name":"documents[]","description":"{ id, number, partner } – doklady, u kterých akce proběhla"}]}},"/entities/{entity_id}/documents/{id}/issue":{"post":{"operationId":"issueDocument","tags":["Doklady a jejich stavy"],"summary":"Vystavení dokladu","description":"Vystaví koncept: ověří, že má aspoň jeden řádek a že faktura, zálohová faktura, dobropis, daňový doklad k záloze a obchodní doklad má kontakt. Přidělí číslo z řady druhu a roku data vystavení (koncept vrácený z vystaveného dokladu si číslo ponechá), u prodeje doplní prázdný variabilní symbol z číslic čísla, u daňových dokladů doplní chybějící DUZP datem vystavení, uloží snímek kontaktu, přepočítá částky a nastaví stav issued. V podvojném účetnictví zaúčtuje předkontaci (prodej MD 311 / D výnosové účty a 343, nákup MD nákladové účty a 343 / D 321, pokladní doklad proti účtu pokladny, daňový doklad k záloze 324/343 nebo 343/314); zálohové faktury, interní a obchodní doklady ani daňová evidence se neúčtují. Pokladní doklad se označí za uhrazený; faktura nebo zálohová faktura vytvořená z nabídky označí nabídku, která ještě nemá výsledek, jako přijatou.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":7},{"name":"id","in":"path","required":true,"description":"ID konceptu","schema":{"type":"integer"},"example":1540}],"responses":{"200":{"description":"Detail vystaveného dokladu jako v getDocument (včetně approval).","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Doklad není koncept (i stornovaný): „Doklad už je vystavený“ Doklad nemá řádky: „Doklad nemá žádnou položku“ Chybí kontakt: „Doplňte odběratele nebo dodavatele“ Řádek odečítá neexistující nebo nevystavený daňový doklad k záloze: „Odečítaná záloha neexistuje“ Daňový doklad k záloze už je odečtený jinde: „Daňový doklad … je už odečtený na dokladu …“ Výdaj ve schvalování, volající ho nesmí schválit: „Doklad musí před zaúčtováním schválit … – odešlete ho ke schválení“, „Doklad čeká na schválení – schvaluje …“, „Doklad se po schválení změnil – odešlete ho znovu ke schválení (schvaluje …)“ nebo „Doklad byl vrácen k opravě – upravte ho a odešlete znovu ke schválení“ Datum dokladu v uzamčeném období: „Období do … je uzamčeno – doklad nelze měnit“ (tvar { error, errors })","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"doklady","x-saldo-access":"writer","x-saldo-access-note":"Přijatý výdaj (invoice_in, cash_out, credit_in), na který se vztahuje pravidlo schvalování a který není schválený, smí vystavit jen jeho schvalovatel – vystavení se pak zaznamená jako schválení („Schváleno při vystavení“); ostatním vrátí 422.","x-saldo-side-effects":"Přidělí číslo (posune číselnou řadu), uloží stav issued a snímek kontaktu, v podvojném účetnictví vytvoří účetní zápisy, u pokladního dokladu nastaví uhrazenou částku a datum úhrady, u zdrojové nabídky nastaví výsledek accepted, zapíše document.issued (a případně document.approved se záznamem schválení). U přijatého výdaje v cizí měně se při zapnutém schvalování může dotázat kurz ČNB (jen pro posouzení limitu).","x-saldo-repeat":"Druhé volání vrátí 422 „Doklad už je vystavený“.","x-saldo-errors":[{"status":422,"when":"Doklad není koncept (i stornovaný): „Doklad už je vystavený“"},{"status":422,"when":"Doklad nemá řádky: „Doklad nemá žádnou položku“"},{"status":422,"when":"Chybí kontakt: „Doplňte odběratele nebo dodavatele“"},{"status":422,"when":"Řádek odečítá neexistující nebo nevystavený daňový doklad k záloze: „Odečítaná záloha neexistuje“"},{"status":422,"when":"Daňový doklad k záloze už je odečtený jinde: „Daňový doklad … je už odečtený na dokladu …“"},{"status":422,"when":"Výdaj ve schvalování, volající ho nesmí schválit: „Doklad musí před zaúčtováním schválit … – odešlete ho ke schválení“, „Doklad čeká na schválení – schvaluje …“, „Doklad se po schválení změnil – odešlete ho znovu ke schválení (schvaluje …)“ nebo „Doklad byl vrácen k opravě – upravte ho a odešlete znovu ke schválení“"},{"status":422,"when":"Datum dokladu v uzamčeném období: „Období do … je uzamčeno – doklad nelze měnit“ (tvar { error, errors })"}]}},"/entities/{entity_id}/documents/{id}/cancel":{"post":{"operationId":"cancelDocument","tags":["Doklady a jejich stavy"],"summary":"Storno dokladu","description":"Stornuje doklad: smaže jeho účetní zápisy a nastaví stav cancelled; číslo zůstává obsazené, takže v řadě nevznikne mezera. Nejde, pokud má doklad s úhradou zaznamenané úhrady, pokud k němu existuje vystavený opravný doklad (nejdřív se stornuje ten) nebo pokud je daňový doklad k záloze odečtený na jiném dokladu. Stav se nekontroluje – stornovat lze i koncept. Veřejný odkaz stornovaného dokladu vrací 404. Zpět do konceptu ho vrátí reopenDocument.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":7},{"name":"id","in":"path","required":true,"description":"ID dokladu","schema":{"type":"integer"},"example":1532}],"responses":{"200":{"description":"Detail stornovaného dokladu jako v getDocument.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Doklad s úhradou má zaznamenané úhrady: „Nejprve zrušte úhrady dokladu“ K dokladu existuje vystavený dobropis: „K dokladu je vystavený opravný doklad … – nejdřív stornujte ten“ Daňový doklad k záloze je odečtený na jiném dokladu: „Záloha je odečtená na dokladu … – nejdřív upravte ten“ Účetní zápisy v uzamčeném období: „Období do … je uzamčeno – zaúčtování nelze změnit“; nebo datum dokladu v uzamčeném období: „Období do … je uzamčeno – doklad nelze měnit“","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"doklady","x-saldo-access":"writer","x-saldo-side-effects":"Smaže účetní zápisy dokladu, nastaví stav cancelled a zapíše document.cancelled.","x-saldo-repeat":"Opakované volání na stornovaný doklad znovu uspěje a zapíše další událost.","x-saldo-errors":[{"status":422,"when":"Doklad s úhradou má zaznamenané úhrady: „Nejprve zrušte úhrady dokladu“"},{"status":422,"when":"K dokladu existuje vystavený dobropis: „K dokladu je vystavený opravný doklad … – nejdřív stornujte ten“"},{"status":422,"when":"Daňový doklad k záloze je odečtený na jiném dokladu: „Záloha je odečtená na dokladu … – nejdřív upravte ten“"},{"status":422,"when":"Účetní zápisy v uzamčeném období: „Období do … je uzamčeno – zaúčtování nelze změnit“; nebo datum dokladu v uzamčeném období: „Období do … je uzamčeno – doklad nelze měnit“"}]}},"/entities/{entity_id}/documents/{id}/reopen":{"post":{"operationId":"reopenDocument","tags":["Doklady a jejich stavy"],"summary":"Vrácení dokladu do konceptu","description":"Vrátí vystavený (nebo stornovaný) doklad do stavu koncept: smaže jeho účetní zápisy a číslo ponechá. Doklad pak lze upravit a znovu vystavit se stejným číslem; koncept s číslem smazat nelze. Podmínky jsou stejné jako u storna: žádné úhrady, žádný vystavený opravný doklad, daňový doklad k záloze neodečtený jinde a neuzamčené období.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":7},{"name":"id","in":"path","required":true,"description":"ID dokladu","schema":{"type":"integer"},"example":1532}],"responses":{"200":{"description":"Detail dokladu ve stavu draft jako v getDocument.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Doklad s úhradou má úhrady: „Doklad s úhradami nelze vrátit do konceptu“ K dokladu existuje vystavený dobropis: „K dokladu je vystavený opravný doklad … – nejdřív stornujte ten“ Daňový doklad k záloze je odečtený jinde: „Záloha je odečtená na dokladu … – nejdřív upravte ten“ Uzamčené období: „Období do … je uzamčeno – zaúčtování nelze změnit“ nebo „Období do … je uzamčeno – doklad nelze měnit“","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"doklady","x-saldo-access":"writer","x-saldo-side-effects":"Smaže účetní zápisy dokladu, nastaví stav draft a zapíše document.reopened.","x-saldo-repeat":"Opakované volání na koncept uspěje bez další změny (zapíše další událost).","x-saldo-errors":[{"status":422,"when":"Doklad s úhradou má úhrady: „Doklad s úhradami nelze vrátit do konceptu“"},{"status":422,"when":"K dokladu existuje vystavený dobropis: „K dokladu je vystavený opravný doklad … – nejdřív stornujte ten“"},{"status":422,"when":"Daňový doklad k záloze je odečtený jinde: „Záloha je odečtená na dokladu … – nejdřív upravte ten“"},{"status":422,"when":"Uzamčené období: „Období do … je uzamčeno – zaúčtování nelze změnit“ nebo „Období do … je uzamčeno – doklad nelze měnit“"}]}},"/entities/{entity_id}/documents/{id}/remind":{"post":{"operationId":"recordDocumentReminder","tags":["Doklady a jejich stavy"],"summary":"Zaznamenání odeslané upomínky","description":"Zvýší počítadlo upomínek dokladu o 1 a nastaví datum poslední upomínky na dnešek. Upomínku nikam neposílá – jen zaznamená, že ji firma odeslala (podklady vrací getDocumentReminder). Na rozdíl od hromadné akce remind nekontroluje druh, stav ani splatnost dokladu.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":7},{"name":"id","in":"path","required":true,"description":"ID dokladu","schema":{"type":"integer"},"example":1532}],"responses":{"200":{"description":"Detail dokladu jako v getDocument, ale bez approval.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"doklady","x-saldo-access":"writer","x-saldo-side-effects":"Zvýší reminders_sent, nastaví last_reminder_on a zapíše document.reminded.","x-saldo-repeat":"Každé volání zaznamená další upomínku."}},"/entities/{entity_id}/documents/{id}/settle":{"post":{"operationId":"settleAdvanceOnInvoice","tags":["Doklady a jejich stavy"],"summary":"Zúčtování uhrazené zálohy úhradou faktury","description":"Uhradí fakturu z uhrazené zálohové faktury, ke které není vystavený daňový doklad k záloze (typicky u neplátce DPH): k faktuře zaznamená úhradu způsobem „Uhrazeno zálohou“ ve výši menší z uhrazené zálohy a zbývající částky faktury, s datem vystavení faktury a kurzem, za který byla záloha přijata. Existuje-li daňový doklad k záloze, záloha se místo toho odečte řádkem na konečné faktuře (prepareFinalInvoice). Směr, kontakt ani vazba zálohové faktury na fakturu se neporovnávají.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":7},{"name":"id","in":"path","required":true,"description":"ID vystavené faktury (dokladu s úhradou)","schema":{"type":"integer"},"example":1532}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["proforma_id"],"properties":{"proforma_id":{"type":"integer","description":"ID zálohové faktury firmy (proforma_out nebo proforma_in); jiný druh vrátí 404"}}},"example":{"proforma_id":147}}}},"responses":{"200":{"description":"Detail faktury s novou úhradou jako v getDocument, ale bez approval.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Zálohová faktura nemá úhradu: „Zálohová faktura zatím není uhrazená“ Tato záloha už je na faktuře zúčtovaná: „Záloha už byla vyúčtována“ K záloze existuje vystavený daňový doklad: „K záloze je vystavený daňový doklad – odečtěte ji na konečné faktuře“ Faktura už odečítá zálohu řádkem: „Záloha je už odečtená v položkách faktury“ Na faktuře nic nezbývá: „Faktura už je uhrazená“ Faktura není vystavená nebo nemá úhrady: „Doklad není vystavený“, „K tomuto dokladu se úhrady neevidují“ Datum vystavení faktury v uzamčeném období: „Období do … je uzamčeno – úhradu z … nelze měnit“","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"doklady","x-saldo-access":"writer","x-saldo-side-effects":"Vytvoří úhradu faktury (payment_method advance, poznámka = číslo zálohové faktury), v podvojném účetnictví zaúčtuje MD 324 / D 311 (u přijaté faktury MD 321 / D 314) a případný kurzový rozdíl, přepočte uhrazenou částku faktury a zapíše payment.recorded.","x-saldo-repeat":"Druhé volání se stejnou fakturou a zálohou vrátí 422 „Záloha už byla vyúčtována“.","x-saldo-errors":[{"status":422,"when":"Zálohová faktura nemá úhradu: „Zálohová faktura zatím není uhrazená“"},{"status":422,"when":"Tato záloha už je na faktuře zúčtovaná: „Záloha už byla vyúčtována“"},{"status":422,"when":"K záloze existuje vystavený daňový doklad: „K záloze je vystavený daňový doklad – odečtěte ji na konečné faktuře“"},{"status":422,"when":"Faktura už odečítá zálohu řádkem: „Záloha je už odečtená v položkách faktury“"},{"status":422,"when":"Na faktuře nic nezbývá: „Faktura už je uhrazená“"},{"status":422,"when":"Faktura není vystavená nebo nemá úhrady: „Doklad není vystavený“, „K tomuto dokladu se úhrady neevidují“"},{"status":422,"when":"Datum vystavení faktury v uzamčeném období: „Období do … je uzamčeno – úhradu z … nelze měnit“"}],"x-saldo-example":{"note":"Ukázková zálohová faktura je uhrazená a nemá vystavený daňový doklad k záloze, takže se faktura uhradí zálohou (úhrada advance s číslem zálohové faktury v poznámce)."}}},"/entities/{entity_id}/documents/{id}/duplicate":{"get":{"operationId":"prepareDocumentCopy","tags":["Doklady a jejich stavy"],"summary":"Kopie dokladu jako nový koncept","description":"Vrátí neuložený koncept stejného druhu: kontakt, měna a kurz (beze změny), režim DPH, kód PDP, ceny s DPH, způsob úhrady, bankovní účet, popis, poznámka, jazyk, středisko, projekt, konstantní symbol a řádky (bez vazby na odečítané zálohy). Datum vystavení a u daňových dokladů DUZP je dnešní, splatnost dnes + splatnost kontaktu (jinak firmy). Částky nejsou přepočítané (součty 0) – dopočítají se při uložení přes createDocument. Připojí number_preview. Nic neukládá.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":7},{"name":"id","in":"path","required":true,"description":"ID kopírovaného dokladu","schema":{"type":"integer"},"example":1532}],"responses":{"200":{"description":"Koncept ve tvaru getDocument (id null, bez approval) a navíc number_preview.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"doklady","x-saldo-access":"member","x-saldo-side-effects":"Nic nezapisuje.","x-saldo-response-fields":[{"name":"number_preview","description":"Náhled čísla z řady druhu k dnešku"}]}},"/entities/{entity_id}/documents/{id}/credit_note":{"get":{"operationId":"prepareCreditNote","tags":["Doklady a jejich stavy"],"summary":"Dobropis k faktuře jako nový koncept","description":"K faktuře vydané (invoice_out) vrátí koncept opravného daňového dokladu vydaného (credit_out), k faktuře přijaté (invoice_in) koncept přijatého (credit_in): kopii faktury jako v prepareDocumentCopy se zápornými množstvími, vazbou related_document na fakturu a poznámkou „Opravný daňový doklad k dokladu č. … ze dne …“. Stav faktury se nekontroluje. Částky nejsou přepočítané. Nic neukládá.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":7},{"name":"id","in":"path","required":true,"description":"ID faktury","schema":{"type":"integer"},"example":1532}],"responses":{"200":{"description":"Koncept dobropisu ve tvaru getDocument (id null, bez approval) a navíc number_preview.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Doklad není invoice_out ani invoice_in: „Dobropis lze vystavit jen k faktuře“","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"doklady","x-saldo-access":"member","x-saldo-side-effects":"Nic nezapisuje.","x-saldo-errors":[{"status":422,"when":"Doklad není invoice_out ani invoice_in: „Dobropis lze vystavit jen k faktuře“"}]}},"/entities/{entity_id}/documents/{id}/final_invoice":{"get":{"operationId":"prepareFinalInvoice","tags":["Doklady a jejich stavy"],"summary":"Konečná faktura k zálohové faktuře jako koncept","description":"K zálohové faktuře vrátí koncept konečné faktury (proforma_out → invoice_out, proforma_in → invoice_in): kopii zálohové faktury s vazbou na ni, poznámkou zálohové faktury doplněnou o větu „Vyúčtování zálohové faktury č. …“ a řádkem odpočtu (množství −1, cena s DPH nebo bez podle prices_include_vat) za každý řádek každého vystaveného daňového dokladu k záloze, který ještě není odečtený na nestornovaném dokladu (ani na konceptu). Odpočet jde v podvojném účetnictví na účet 324 (přijaté zálohy) nebo 314 (poskytnuté zálohy), v daňové evidenci do kategorie hlavního řádku zálohové faktury. Částky nejsou přepočítané. Nic neukládá.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":7},{"name":"id","in":"path","required":true,"description":"ID zálohové faktury","schema":{"type":"integer"},"example":1490}],"responses":{"200":{"description":"Koncept konečné faktury ve tvaru getDocument (id null, bez approval) a navíc number_preview.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Doklad není zálohová faktura: „Vyúčtovat lze jen zálohovou fakturu“ Existuje vystavená konečná faktura a není co dalšího odečíst: „Záloha už je vyúčtovaná dokladem …“","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"doklady","x-saldo-access":"member","x-saldo-side-effects":"Nic nezapisuje.","x-saldo-errors":[{"status":422,"when":"Doklad není zálohová faktura: „Vyúčtovat lze jen zálohovou fakturu“"},{"status":422,"when":"Existuje vystavená konečná faktura a není co dalšího odečíst: „Záloha už je vyúčtovaná dokladem …“"}],"x-saldo-example":{"note":"Ukázková zálohová faktura je uhrazená, ale nemá vystavený daňový doklad k záloze ani konečnou fakturu, takže koncept neobsahuje řádek odpočtu."}}},"/entities/{entity_id}/documents/{id}/advance_document":{"get":{"operationId":"prepareAdvanceDocument","tags":["Doklady a jejich stavy"],"summary":"Daňový doklad k přijaté platbě zálohy jako koncept","description":"K uhrazené zálohové faktuře vrátí koncept daňového dokladu k platbě (advance_out u vydané, advance_in u přijaté) na částku zaplacenou a dosud nepokrytou vystavenými daňovými doklady k této záloze. Datum vystavení i DUZP je datum poslední platby zálohy, ceny jsou včetně DPH a částka se rozdělí do sazeb DPH v poměru řádků zálohové faktury (účet 324, resp. 314). Částky nejsou přepočítané. Nic neukládá.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":7},{"name":"id","in":"path","required":true,"description":"ID zálohové faktury","schema":{"type":"integer"},"example":1490}],"responses":{"200":{"description":"Koncept daňového dokladu k záloze ve tvaru getDocument (id null, bez approval) a navíc number_preview.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Doklad není zálohová faktura nebo nemá úhradu: „Daňový doklad lze vystavit jen k uhrazené zálohové faktuře“ Všechny platby už mají daňový doklad: „Ke všem přijatým platbám zálohy už daňový doklad existuje“","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"doklady","x-saldo-access":"member","x-saldo-side-effects":"Nic nezapisuje.","x-saldo-errors":[{"status":422,"when":"Doklad není zálohová faktura nebo nemá úhradu: „Daňový doklad lze vystavit jen k uhrazené zálohové faktuře“"},{"status":422,"when":"Všechny platby už mají daňový doklad: „Ke všem přijatým platbám zálohy už daňový doklad existuje“"}],"x-saldo-example":{"note":"Vyžaduje uhrazenou zálohovou fakturu, jejíž platby ještě nemají daňový doklad."}}},"/entities/{entity_id}/documents/{id}/reminder":{"get":{"operationId":"getDocumentReminder","tags":["Doklady a jejich stavy"],"summary":"Podklady pro upomínku dokladu","description":"Vrátí doklad, údaje firmy, pořadí příští upomínky a výpočet úroku z prodlení k dnešku ze zbývající částky podle NV č. 351/2013 Sb.: repo sazba ČNB platná první den pololetí, v němž prodlení začalo, + 8 p. b., za dny od dne po splatnosti do dneška; náklady spojené s uplatněním pohledávky 1 200 Kč jen u kontaktu s IČO, a to až po splatnosti. interest je null, když doklad nemá splatnost, nic nezbývá uhradit nebo výpočet nejde (např. splatnost před rokem 2014). Nic nezaznamenává.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":7},{"name":"id","in":"path","required":true,"description":"ID dokladu","schema":{"type":"integer"},"example":1532}],"responses":{"200":{"description":"Podklady pro upomínku.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"doklady","x-saldo-access":"member","x-saldo-side-effects":"Nic nezapisuje.","x-saldo-response-fields":[{"name":"document","description":"Detail dokladu (bez approval)"},{"name":"entity","description":"Údaje firmy"},{"name":"next_level","description":"Pořadí příští upomínky (zaznamenané upomínky + 1)"},{"name":"interest.principal","description":"Jistina = zbývající částka dokladu"},{"name":"interest.currency","description":"Měna výpočtu – vždy CZK (měna dokladu se nepředává)"},{"name":"interest.delay_from","description":"První den prodlení, nebo null, když prodlení ještě nenastalo"},{"name":"interest.days","description":"Počet dní prodlení"},{"name":"interest.reference_date","description":"První den pololetí, podle kterého se bere repo sazba"},{"name":"interest.repo_rate","description":"Repo sazba ČNB v %"},{"name":"interest.rate","description":"Roční sazba úroku v % (repo + 8)"},{"name":"interest.periods[]","description":"{ from, to, days, rate, interest } po kalendářních pololetích"},{"name":"interest.interest","description":"Úrok celkem (2 desetinná místa)"},{"name":"interest.recovery_cost","description":"Náklady uplatnění pohledávky: 1200 u kontaktu s IČO, když prodlení už nastalo, jinak 0"},{"name":"interest.basis[]","description":"Právní podklady výpočtu (texty)"}]}},"/entities/{entity_id}/documents/{id}/qr":{"get":{"operationId":"getDocumentQrPayment","tags":["Doklady a jejich stavy"],"summary":"Řetězec QR Platby k dokladu","description":"Vrátí řetězec QR Platby (SPAYD 1.0) k zaplacení dokladu: účet (IBAN a BIC) bankovního účtu dokladu, u pokladny nebo bez účtu výchozí nebo první aktivní bankovní účet firmy; částka = zbývající částka, a není-li kladná, celková částka k úhradě; dále měna, splatnost, variabilní, konstantní a specifický symbol, jméno firmy a zpráva „druh a číslo dokladu“. Vrátí spayd null, když takto vybraný účet nemá IBAN ani číslo účtu s kódem banky (nebo firma aktivní bankovní účet nemá), měna není CZK ani EUR, nebo částka není kladná (např. dobropis). Stav dokladu se nekontroluje; obrázek QR kódu API nevytváří.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":7},{"name":"id","in":"path","required":true,"description":"ID dokladu","schema":{"type":"integer"},"example":1532}],"responses":{"200":{"description":"Objekt s řetězcem QR Platby.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Neplatný účet firmy: „Neplatný IBAN: …“ nebo „Neplatný BIC: …“ Částka nad limit QR Platby: „Částka pro QR Platbu smí být nejvýše 9 999 999,99“","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"doklady","x-saldo-access":"member","x-saldo-side-effects":"Nic nezapisuje.","x-saldo-errors":[{"status":422,"when":"Neplatný účet firmy: „Neplatný IBAN: …“ nebo „Neplatný BIC: …“"},{"status":422,"when":"Částka nad limit QR Platby: „Částka pro QR Platbu smí být nejvýše 9 999 999,99“"}],"x-saldo-response-fields":[{"name":"spayd","description":"Např. SPD*1.0*ACC:CZ…*AM:15972.00*CC:CZK*…, nebo null"}]}},"/entities/{entity_id}/documents/{id}/isdoc":{"get":{"operationId":"downloadDocumentIsdoc","tags":["Doklady a jejich stavy"],"summary":"Stažení dokladu ve formátu ISDOC","description":"Vrátí vydaný doklad (invoice_out, credit_out, proforma_out, advance_out) jako soubor ISDOC (XML) ke stažení s názvem „číslo.isdoc“. Dodavatel je firma, odběratel kontakt dokladu, platební údaje jsou z bankovního účtu dokladu nebo výchozího účtu firmy. Doklad musí mít číslo (tedy být někdy vystaven) a řádky; dobropis musí odkazovat na původní doklad. Doklad bez uloženého UUID (to má jen doklad importovaný z ISDOC) dostane při každém stažení nové náhodné UUID.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":7},{"name":"id","in":"path","required":true,"description":"ID dokladu","schema":{"type":"integer"},"example":1532}],"responses":{"200":{"description":"Soubor ISDOC (Content-Disposition attachment).","content":{"application/xml":{"schema":{"type":"string","format":"binary"}}}},"422":{"description":"Jiný druh než vydaná faktura, zálohová faktura, dobropis nebo daňový doklad k záloze: „ISDOC lze vytvořit jen pro vydané doklady“ Koncept bez čísla: „Doklad nemá číslo“ „Doklad nemá žádné položky“, „Dodavatel nemá název“, „Opravný doklad musí odkazovat na původní doklad“, „Doklad v cizí měně musí mít kladný kurz“","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"doklady","x-saldo-access":"member","x-saldo-side-effects":"Nic nezapisuje.","x-saldo-errors":[{"status":422,"when":"Jiný druh než vydaná faktura, zálohová faktura, dobropis nebo daňový doklad k záloze: „ISDOC lze vytvořit jen pro vydané doklady“"},{"status":422,"when":"Koncept bez čísla: „Doklad nemá číslo“"},{"status":422,"when":"„Doklad nemá žádné položky“, „Dodavatel nemá název“, „Opravný doklad musí odkazovat na původní doklad“, „Doklad v cizí měně musí mít kladný kurz“"}]}},"/entities/{entity_id}/documents/{id}/payments":{"post":{"operationId":"createDocumentPayment","tags":["Doklady a jejich stavy"],"summary":"Zaznamenání úhrady dokladu","description":"K vystavenému dokladu s úhradou (faktura, zálohová faktura, dobropis – vydané i přijaté) zaznamená úhradu v měně dokladu: záporná částka je vratka, nulová se odmítne, přeplatek se nekontroluje. U dokladu v cizí měně lze v amount_czk zadat skutečně připsanou nebo odepsanou částku v Kč; rozdíl proti kurzu dokladu se v podvojném účetnictví zaúčtuje jako kurzový zisk (663) nebo ztráta (563); u zálohové faktury se celá částka v Kč zaúčtuje proti 324/314 bez kurzového rozdílu. Úhrada není spárovaná s bankovním pohybem. Vrátí celý doklad s přepočtenou uhrazenou částkou.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":7},{"name":"id","in":"path","required":true,"description":"ID dokladu","schema":{"type":"integer"},"example":1532}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount"],"properties":{"amount":{"type":"number","description":"Částka v měně dokladu (2 desetinná místa; nečíselná hodnota se bere jako 0)"},"paid_on":{"type":"string","format":"date","description":"Datum úhrady (výchozí dnes)"},"payment_method":{"type":"string","description":"Způsob úhrady; výchozí cash, je-li bank_account_id pokladna, jinak bank","enum":["bank","cash","card","cod","offset","advance","other"]},"bank_account_id":{"type":"integer","description":"Bankovní účet nebo pokladna firmy; určuje peněžní účet zápisu (jinak 221, u hotovosti 211)"},"amount_czk":{"type":"number","description":"Skutečná částka v Kč, určená pro doklad v cizí měně; bez ní se přepočte kurzem dokladu. Server ji přijme i u dokladu v Kč – odlišná hodnota se pak v podvojném účetnictví zaúčtuje jako kurzový rozdíl."},"note":{"type":"string","description":"Poznámka k úhradě"}}},"example":{"amount":1000,"paid_on":"2026-09-28","bank_account_id":2,"note":"Částečná úhrada"}}}},"responses":{"201":{"description":"Detail dokladu jako v getDocument, ale bez approval (úhrada je v payments[]).","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Doklad není vystavený: „Doklad není vystavený“ Druh bez úhrad (pokladní, interní, obchodní doklad, daňový doklad k záloze): „K tomuto dokladu se úhrady neevidují“ Částka je 0 nebo nečíselná: „Částka úhrady nesmí být nulová“ Datum úhrady v uzamčeném období: „Období do … je uzamčeno – úhradu z … nelze měnit“","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"doklady","x-saldo-access":"writer","x-saldo-side-effects":"Vytvoří úhradu, v podvojném účetnictví její účetní zápis (např. MD 221 / D 311, u vydané zálohové faktury D 324, u přijaté faktury MD 321 / D 221) a případný kurzový rozdíl, přepočte uhrazenou částku a datum úhrady dokladu a zapíše payment.recorded.","x-saldo-repeat":"Každé volání zaznamená další úhradu.","x-saldo-errors":[{"status":422,"when":"Doklad není vystavený: „Doklad není vystavený“"},{"status":422,"when":"Druh bez úhrad (pokladní, interní, obchodní doklad, daňový doklad k záloze): „K tomuto dokladu se úhrady neevidují“"},{"status":422,"when":"Částka je 0 nebo nečíselná: „Částka úhrady nesmí být nulová“"},{"status":422,"when":"Datum úhrady v uzamčeném období: „Období do … je uzamčeno – úhradu z … nelze měnit“"}]}},"/entities/{entity_id}/documents/{id}/payments/{payment_id}":{"delete":{"operationId":"deleteDocumentPayment","tags":["Doklady a jejich stavy"],"summary":"Zrušení úhrady dokladu","description":"Smaže úhradu dokladu s jejími účetními zápisy a přepočte uhrazenou částku. Vznikla-li úhrada spárováním s bankovním pohybem, pohyb se vrátí mezi nespárované, pokud ho jiné úhrady nepokrývají. Úhradu s datem v uzamčeném období zrušit nelze. Vrátí celý doklad.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":7},{"name":"id","in":"path","required":true,"description":"ID dokladu","schema":{"type":"integer"},"example":1532},{"name":"payment_id","in":"path","required":true,"description":"ID úhrady tohoto dokladu (jiná vrátí 404)","schema":{"type":"integer"},"example":884}],"responses":{"200":{"description":"Detail dokladu jako v getDocument, ale bez approval.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Úhrada v uzamčeném období: „Období do … je uzamčeno – úhradu z … nelze měnit“","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"doklady","x-saldo-access":"writer","x-saldo-side-effects":"Smaže úhradu a její účetní zápisy, u spárovaného bankovního pohybu přepočte jeho stav (matched / unmatched), přepočte uhrazenou částku dokladu a zapíše payment.deleted.","x-saldo-repeat":"Druhé volání vrátí 404.","x-saldo-errors":[{"status":422,"when":"Úhrada v uzamčeném období: „Období do … je uzamčeno – úhradu z … nelze měnit“"}]}},"/entities/{entity_id}/documents/{id}/convert":{"get":{"operationId":"prepareConvertedDocument","tags":["Doklady a jejich stavy"],"summary":"Převod dokladu na jiný druh jako koncept","description":"Z vystaveného dokladu vrátí koncept jiného druhu jako kopii (viz prepareDocumentCopy) s vazbou na zdroj a poznámkou „Dle dokladu … č. …“. Povolené převody: cenová nabídka (quote_out) → faktura vydaná, zálohová faktura vydaná nebo dodací list; objednávka (order_out) → faktura přijatá; faktura vydaná → dodací list; dodací list → faktura vydaná. Když se faktura nebo zálohová faktura vytvořená z nabídky vystaví, nabídka se označí jako přijatá (nemá-li ještě výsledek). Nic neukládá.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":7},{"name":"id","in":"path","required":true,"description":"ID zdrojového dokladu","schema":{"type":"integer"},"example":1601},{"name":"kind","in":"query","required":true,"description":"Druh nového dokladu","schema":{"type":"string","enum":["invoice_out","proforma_out","delivery_out","invoice_in"]},"example":"invoice_out"}],"responses":{"200":{"description":"Koncept ve tvaru getDocument (id null, bez approval) a navíc number_preview.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Převod mezi druhy není povolen: „Z tohoto dokladu nelze vytvořit zvolený doklad“ Zdroj není vystavený: „Vytvořit doklad lze jen z vystaveného dokladu“","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"doklady","x-saldo-access":"member","x-saldo-side-effects":"Nic nezapisuje.","x-saldo-errors":[{"status":422,"when":"Převod mezi druhy není povolen: „Z tohoto dokladu nelze vytvořit zvolený doklad“"},{"status":422,"when":"Zdroj není vystavený: „Vytvořit doklad lze jen z vystaveného dokladu“"}]}},"/entities/{entity_id}/documents/{id}/outcome":{"post":{"operationId":"setQuoteOutcome","tags":["Doklady a jejich stavy"],"summary":"Výsledek cenové nabídky","description":"U cenové nabídky (quote_out) zaznamená, zda ji zákazník přijal (accepted) nebo odmítl (rejected); prázdná nebo chybějící hodnota výsledek smaže. Stav nabídky se nekontroluje.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":7},{"name":"id","in":"path","required":true,"description":"ID nabídky","schema":{"type":"integer"},"example":1601}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","description":"accepted = přijato, rejected = odmítnuto, prázdné = bez výsledku","enum":["accepted","rejected",""]}}},"example":{"outcome":"accepted"}}}},"responses":{"200":{"description":"Detail nabídky jako v getDocument, ale bez approval.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Doklad není nabídka: „Výsledek se eviduje jen u nabídek“ Neznámá hodnota: „Neznámý výsledek nabídky“","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"doklady","x-saldo-access":"writer","x-saldo-side-effects":"Změní výsledek nabídky a zapíše document.outcome.","x-saldo-repeat":"Opakování se stejnou hodnotou nic nezmění, jen zapíše další událost.","x-saldo-errors":[{"status":422,"when":"Doklad není nabídka: „Výsledek se eviduje jen u nabídek“"},{"status":422,"when":"Neznámá hodnota: „Neznámý výsledek nabídky“"}]}},"/entities/{entity_id}/documents/{id}/share":{"post":{"operationId":"shareDocument","tags":["Doklady a jejich stavy"],"summary":"Zapnutí veřejného odkazu na doklad","description":"Vytvoří neuhádnutelný token (32 znaků) pro veřejný odkaz na doklad, který lze otevřít bez účtu: zákazník ho vidí na stránce /tools/ucetnictvi/faktura/#\u003ctoken\u003e, data vrací getSharedDocument (/share/{token}; doklad bez interních údajů, firma, bankovní účet a QR Platba) a ISDOC getSharedDocumentIsdoc (/share/{token}/isdoc). Jen u vystaveného dokladu druhu invoice_out, proforma_out, credit_out nebo advance_out. Token nemá omezenou platnost: platí, dokud se odkaz nezruší; dokud doklad není vystavený (storno, vrácení do konceptu), odkaz vrací 404 a po novém vystavení funguje znovu. Už sdílený doklad si token ponechá.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":7},{"name":"id","in":"path","required":true,"description":"ID dokladu","schema":{"type":"integer"},"example":1532}],"responses":{"200":{"description":"Stav sdílení.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Doklad není vystavený nebo je jiného druhu: „Odkaz lze sdílet jen u vystavené faktury, zálohové faktury nebo dobropisu“","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"doklady","x-saldo-access":"writer","x-saldo-side-effects":"Při prvním sdílení uloží token a čas; při každém volání zapíše document.shared.","x-saldo-repeat":"Opakované volání vrátí stejný token a zapíše další událost.","x-saldo-errors":[{"status":422,"when":"Doklad není vystavený nebo je jiného druhu: „Odkaz lze sdílet jen u vystavené faktury, zálohové faktury nebo dobropisu“"}],"x-saldo-response-fields":[{"name":"token","description":"Token veřejného odkazu (32 znaků A–Z, a–z, 0–9, _ a -)"},{"name":"shared_at","description":"Kdy bylo sdílení zapnuto"},{"name":"viewed_at","description":"První zobrazení někým, kdo není členem firmy, nebo null"},{"name":"views","description":"Počet takových zobrazení"}]},"delete":{"operationId":"unshareDocument","tags":["Doklady a jejich stavy"],"summary":"Zrušení veřejného odkazu na doklad","description":"Smaže token – veřejná stránka pak vrací 404 – a vynuluje čas sdílení, první zobrazení a počet zobrazení. Funguje u jakéhokoli dokladu firmy, i nesdíleného. Nové sdílení vytvoří jiný token.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":7},{"name":"id","in":"path","required":true,"description":"ID dokladu","schema":{"type":"integer"},"example":1532}],"responses":{"200":{"description":"Stav sdílení po zrušení – token, shared_at a viewed_at null, views 0.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"doklady","x-saldo-access":"writer","x-saldo-side-effects":"Smaže token a statistiky zobrazení a zapíše document.unshared.","x-saldo-repeat":"Opakované volání vrátí stejnou odpověď a zapíše další událost.","x-saldo-response-fields":[{"name":"token","description":"null"},{"name":"views","description":"0"}]}},"/entities/{entity_id}/recurrences":{"get":{"operationId":"listRecurrences","tags":["Doklady a jejich stavy"],"summary":"Seznam opakovaných faktur","description":"Vrátí všechna pravidla opakování firmy (aktivní i ukončená) seřazená podle data příštího vytvoření. Každé pravidlo nese souhrn vzorového dokladu (template, null, pokud vzor už neexistuje). Odpověď je pole.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":7}],"responses":{"200":{"description":"Pole pravidel opakování.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"doklady","x-saldo-access":"member","x-saldo-side-effects":"Nic nezapisuje.","x-saldo-response-fields":[{"name":"[].id","description":"ID pravidla"},{"name":"[].template_document_id","description":"ID vzorového dokladu"},{"name":"[].frequency","description":"monthly, quarterly, half_yearly, yearly"},{"name":"[].next_on","description":"Datum příštího vytvoření"},{"name":"[].ends_on","description":"Poslední možné datum vytvoření, nebo null"},{"name":"[].auto_issue","description":"Vytvořený doklad rovnou vystavit"},{"name":"[].active","description":"Pravidlo je aktivní"},{"name":"[].last_generated_on","description":"Plánované datum posledního vytvořeného dokladu"},{"name":"[].created_at","description":"Založeno"},{"name":"[].updated_at","description":"Změněno"},{"name":"[].template","description":"Souhrn vzorového dokladu jako řádek listDocuments, nebo null"}]},"post":{"operationId":"createRecurrence","tags":["Doklady a jejich stavy"],"summary":"Založení opakované faktury","description":"Nastaví pravidelné vytváření kopie dokladu template_document_id – monthly (měsíčně), quarterly (čtvrtletně), half_yearly (pololetně), yearly (ročně) – poprvé k datu next_on; doklady vytváří runRecurrences a automatizace. Vzorem může být doklad jakéhokoli druhu a stavu. Jeden doklad smí mít jen jedno aktivní pravidlo. Pole jsou na nejvyšší úrovni těla (bez obalu).","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":7}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["template_document_id","next_on"],"properties":{"template_document_id":{"type":"integer","description":"ID vzorového dokladu firmy (cizí nebo neexistující vrátí 404)"},"frequency":{"type":"string","description":"Frekvence (výchozí monthly)","enum":["monthly","quarterly","half_yearly","yearly"],"default":"monthly"},"next_on":{"type":"string","format":"date","description":"Datum prvního vytvoření, 1. 1. 2000 – 31. 12. 2100"},"ends_on":{"type":"string","format":"date","description":"Poslední možné datum vytvoření (stejný rozsah); po jeho překročení se pravidlo ukončí. Nečitelné datum se bez chyby uloží jako prázdné (pravidlo bez konce)."},"auto_issue":{"type":"boolean","description":"Vytvořený doklad rovnou vystavit (výchozí false = koncept)","default":false},"active":{"type":"boolean","description":"Pravidlo je aktivní (výchozí true)","default":true}}},"example":{"template_document_id":1,"frequency":"monthly","next_on":"2026-11-01","auto_issue":false}}}},"responses":{"201":{"description":"Pravidlo ve tvaru listRecurrences včetně template.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Doklad už má aktivní pravidlo: „Tato faktura už má automatické pravidlo – upravte to stávající“ (tvar { error, errors }) next_on chybí nebo je neplatné či mimo roky 2000–2100 (i ends_on): „… musí ležet v letech 2000 až 2100“ (tvar { error, errors })","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"doklady","x-saldo-access":"writer","x-saldo-side-effects":"Vytvoří pravidlo a zapíše recurrence.created; doklad zatím nevytváří.","x-saldo-repeat":"Druhé volání pro stejný doklad vrátí 422, dokud je první pravidlo aktivní.","x-saldo-errors":[{"status":422,"when":"Doklad už má aktivní pravidlo: „Tato faktura už má automatické pravidlo – upravte to stávající“ (tvar { error, errors })"},{"status":422,"when":"next_on chybí nebo je neplatné či mimo roky 2000–2100 (i ends_on): „… musí ležet v letech 2000 až 2100“ (tvar { error, errors })"}],"x-saldo-example":{"note":"Vzor nesmí mít jiné aktivní pravidlo (ukázková firma už má jedno pro poslední fakturu v Kč)."}}},"/entities/{entity_id}/recurrences/{id}":{"patch":{"operationId":"updateRecurrence","tags":["Doklady a jejich stavy"],"summary":"Úprava opakované faktury","description":"Změní frekvenci, datum příštího vytvoření, konec, automatické vystavení nebo aktivitu pravidla (vzorový doklad změnit nelze). Znovu aktivované pravidlo nesmí kolidovat s jiným aktivním pravidlem téhož dokladu. Pole jsou na nejvyšší úrovni těla.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":7},{"name":"id","in":"path","required":true,"description":"ID pravidla opakování","schema":{"type":"integer"},"example":12}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"frequency":{"type":"string","description":"Frekvence","enum":["monthly","quarterly","half_yearly","yearly"]},"next_on":{"type":"string","format":"date","description":"Datum příštího vytvoření (2000–2100)"},"ends_on":{"type":"string","format":"date","description":"Poslední možné datum vytvoření, nebo null; nečitelné datum se bez chyby uloží jako null"},"auto_issue":{"type":"boolean","description":"Vytvořený doklad rovnou vystavit"},"active":{"type":"boolean","description":"Pravidlo je aktivní"}}},"example":{"frequency":"quarterly","auto_issue":true}}}},"responses":{"200":{"description":"Pravidlo ve tvaru listRecurrences včetně template.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Aktivace při jiném aktivním pravidle téhož dokladu: „Tato faktura už má automatické pravidlo – upravte to stávající“ Datum mimo roky 2000–2100: „… musí ležet v letech 2000 až 2100“","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"doklady","x-saldo-access":"writer","x-saldo-side-effects":"Uloží změny pravidla; do historie firmy nic nezapisuje.","x-saldo-repeat":"Opakování se stejným tělem nic dalšího nezmění.","x-saldo-errors":[{"status":422,"when":"Aktivace při jiném aktivním pravidle téhož dokladu: „Tato faktura už má automatické pravidlo – upravte to stávající“"},{"status":422,"when":"Datum mimo roky 2000–2100: „… musí ležet v letech 2000 až 2100“"}]},"delete":{"operationId":"deleteRecurrence","tags":["Doklady a jejich stavy"],"summary":"Smazání opakované faktury","description":"Smaže pravidlo opakování. Doklady podle něj už vytvořené zůstanou beze změny.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":7},{"name":"id","in":"path","required":true,"description":"ID pravidla opakování","schema":{"type":"integer"},"example":12}],"responses":{"204":{"description":"Prázdná odpověď."},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"doklady","x-saldo-access":"writer","x-saldo-side-effects":"Smaže pravidlo; do historie firmy nic nezapisuje.","x-saldo-repeat":"Druhé volání vrátí 404."}},"/entities/{entity_id}/recurrences/run":{"post":{"operationId":"runRecurrences","tags":["Doklady a jejich stavy"],"summary":"Vytvoření splatných opakovaných faktur","description":"Pro každé aktivní pravidlo s datem příštího vytvoření nejpozději on (výchozí dnes; pozdější datum se zkrátí na dnešek) vytvoří kopii vzorového dokladu (viz prepareDocumentCopy) se zdrojem recurring, datem vystavení (u daňových dokladů i DUZP) = plánované datum a splatností podle kontaktu nebo firmy; u cizí měny načte kurz ČNB k tomuto datu (když není k dispozici, zůstane kurz vzoru). Zmeškaná období dožene, nejvýše 24 dokladů na pravidlo za volání, a posune datum příštího vytvoření; za koncem pravidlo ukončí. S auto_issue doklad hned vystaví, přijatý výdaj, na který se vztahuje schvalování, ale jen odešle ke schválení (běh nikdy neschvaluje); jinak zůstane konceptem.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":7}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"on":{"type":"string","format":"date","description":"Vytvořit, co je splatné do tohoto dne (výchozí dnes, nejvýše dnes)"}}},"example":{"on":"2026-09-28"}}}},"responses":{"200":{"description":"Vytvořené doklady.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"S auto_issue nejde doklad vystavit (např. „Doklad nemá žádnou položku“, „Doplňte odběratele nebo dodavatele“, uzamčené období); běh se zastaví, dříve vytvořené doklady zůstanou","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"doklady","x-saldo-access":"writer","x-saldo-side-effects":"Vytvoří doklady (document.created, s auto_issue i vystavení a zaúčtování jako issueDocument, nebo odeslání ke schválení) a u pravidel posune next_on, last_generated_on a případně je ukončí. Dotazuje kurzy ČNB u vzorů v cizí měně. Každý vytvořený doklad se ukládá samostatně: při chybě zůstanou doklady vytvořené před ní.","x-saldo-limits":"Nejvýše 24 dokladů na jedno pravidlo za volání.","x-saldo-repeat":"Druhé volání se stejným on nic nevytvoří, protože pravidla už mají příští datum později (jen pravidlo, které narazilo na limit 24 dokladů, pokračuje dalšími zmeškanými obdobími); souběžné běhy si totéž období nezdvojí.","x-saldo-errors":[{"status":422,"when":"S auto_issue nejde doklad vystavit (např. „Doklad nemá žádnou položku“, „Doplňte odběratele nebo dodavatele“, uzamčené období); běh se zastaví, dříve vytvořené doklady zůstanou"}],"x-saldo-response-fields":[{"name":"created[]","description":"Souhrny vytvořených dokladů jako řádky listDocuments"},{"name":"count","description":"Počet vytvořených dokladů"},{"name":"failed","description":"Přes API vždy prázdné pole – chyba běh zastaví s 422"}],"x-saldo-example":{"note":"Ukázkové pravidlo má příští datum v příštím měsíci, takže odpověď je prázdná (count 0)."}}},"/entities/{entity_id}/approval_rules":{"get":{"operationId":"getApprovalRules","tags":["Schvalování výdajů"],"summary":"Pravidla schvalování přijatých výdajů","description":"Vrátí nastavení volitelného schvalování přijatých výdajů před zaúčtováním: zda je zapnuté, na které druhy dokladů se vztahuje (faktura přijatá, výdajový pokladní doklad a přijatý dobropis, ten jen když zvyšuje náklady), pravidla s českým popisem a příznakem, že určený schvalovatel už nemá právo zápisu, a členy firmy, kteří mohou být schvalovateli. Pravidla platí, jen když je schvalování zapnuté a existuje aspoň jedno; na doklad se použije první pravidlo, které ho pokrývá.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":7}],"responses":{"200":{"description":"Nastavení schvalování.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"schvalovani","x-saldo-access":"member","x-saldo-side-effects":"Nic nezapisuje.","x-saldo-response-fields":[{"name":"enabled","description":"Schvalování je zapnuté"},{"name":"kinds","description":"Druhy dokladů, na které se schvalování vztahuje: invoice_in, cash_out, credit_in"},{"name":"rules[].min_amount","description":"Minimální částka s DPH v Kč jako text (např. 10000.0), nebo null"},{"name":"rules[].cost_centers","description":"Střediska (pole textů); prázdné = libovolné"},{"name":"rules[].accounts","description":"Začátky čísel účtů nebo kategorií (pole textů); prázdné = libovolné"},{"name":"rules[].approver_id","description":"ID uživatele určeného schvalovatele, nebo null (schvaluje vlastník nebo účetní)"},{"name":"rules[].description","description":"Pravidlo česky, např. „od 10 000 Kč → vlastník nebo účetní“"},{"name":"rules[].approver_missing","description":"true, když určený schvalovatel už nemá právo zápisu (schvaluje pak jen vlastník)"},{"name":"approvers[].id","description":"ID uživatele (použije se jako approver_id)"},{"name":"approvers[].name","description":"Zobrazované jméno nebo uživatelské jméno"},{"name":"approvers[].role","description":"owner, accountant nebo editor"}]},"patch":{"operationId":"updateApprovalRules","tags":["Schvalování výdajů"],"summary":"Nastavení pravidel schvalování","description":"Uloží celé nastavení najednou, nejde o částečnou změnu: chybějící enabled znamená vypnuto a chybějící rules pravidla smaže. Pravidlo pokrývá přijatý výdaj, když platí všechny jeho vyplněné podmínky: částka s DPH v Kč je aspoň min_amount (u cizí měny se při nižším kurzu dokladu bere částka podle kurzu ČNB k datu dokladu), středisko dokladu je jedno z cost_centers (bez ohledu na velikost písmen) a některý řádek má účet začínající některým z accounts. Bez approver_id schvaluje vlastník nebo účetní, s ním určený člen; vlastník smí schválit vždy. Pravidla zůstanou uložená i při vypnutí; doklady ve schvalování, které už žádné pravidlo nepokrývá, se ze schvalování uvolní.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":7}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Zapnout schvalování (chybí-li, uloží se vypnuto); zapnuté vyžaduje aspoň jedno pravidlo"},"rules":{"type":"array","description":"Pravidla v pořadí, v jakém se zkoušejí. Lze poslat i jako objekt s číselnými klíči (formulář rules[0][min_amount]=…), seřadí se podle klíčů.","items":{"type":"object","properties":{"min_amount":{"type":"number","description":"Minimální částka s DPH v Kč (číslo nebo text, mezery a desetinná čárka povoleny); nesmí být záporná; prázdné = bez limitu"},"cost_centers":{"type":"array","description":"Střediska; lze i text oddělený čárkou nebo středníkem","items":{"type":"string"}},"accounts":{"type":"array","description":"Začátky čísel účtů nebo kategorií (1–6 znaků 0–9, A–Z; malá písmena se převedou na velká); lze i text oddělený čárkou, středníkem nebo mezerou","items":{"type":"string"}},"approver_id":{"type":"integer","description":"ID uživatele – člena firmy s právem zápisu (seznam approvers); prázdné = vlastník nebo účetní"}}}}}},"example":{"enabled":true,"rules":[{"min_amount":"10000","cost_centers":[],"accounts":["518"],"approver_id":null}]}}}},"responses":{"200":{"description":"Uložené nastavení ve tvaru getApprovalRules (pravidla normalizovaná, min_amount jako text).","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Víc než 20 pravidel: „Pravidel může být nejvýš 20“ enabled bez pravidel: „Zapnuté schvalování potřebuje aspoň jedno pravidlo“ Pravidlo není objekt: „Pravidlo N musí být objekt s poli min_amount, cost_centers, accounts a approver_id“ „Pravidlo N: částka musí být číslo“ nebo „Pravidlo N: částka nesmí být záporná“ Středisko delší než 80 znaků: „Pravidlo N: středisko „…“ je delší než 80 znaků“ Neplatný účet: „Pravidlo N: „…“ není číslo účtu ani kategorie“ approver_id není člen s právem zápisu (ani dříve uložený schvalovatel): „Pravidlo N: schvalovat může jen člen firmy s právem zápisu“","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"schvalovani","x-saldo-access":"manager","x-saldo-side-effects":"Změní nastavení firmy (settings.approvals), dokladům ve schvalování (odeslaným, vráceným, změněným), které už žádné pravidlo nepokrývá, smaže stav schvalování a zapíše entity.approval_rules s uloženými pravidly. Jiné údaje dokladů ani zaúčtování nemění; u schválených dokladů zůstane uložené schválení.","x-saldo-limits":"Nejvýše 20 pravidel; v pravidle se použije nejvýše 20 středisek a 20 účtů (další se zahodí, duplicity se sloučí); středisko nejvýše 80 znaků.","x-saldo-repeat":"Opakování se stejným tělem nastavení nezmění, jen znovu zapíše událost.","x-saldo-errors":[{"status":422,"when":"Víc než 20 pravidel: „Pravidel může být nejvýš 20“"},{"status":422,"when":"enabled bez pravidel: „Zapnuté schvalování potřebuje aspoň jedno pravidlo“"},{"status":422,"when":"Pravidlo není objekt: „Pravidlo N musí být objekt s poli min_amount, cost_centers, accounts a approver_id“"},{"status":422,"when":"„Pravidlo N: částka musí být číslo“ nebo „Pravidlo N: částka nesmí být záporná“"},{"status":422,"when":"Středisko delší než 80 znaků: „Pravidlo N: středisko „…“ je delší než 80 znaků“"},{"status":422,"when":"Neplatný účet: „Pravidlo N: „…“ není číslo účtu ani kategorie“"},{"status":422,"when":"approver_id není člen s právem zápisu (ani dříve uložený schvalovatel): „Pravidlo N: schvalovat může jen člen firmy s právem zápisu“"}]}},"/entities/{entity_id}/documents/{id}/approval/submit":{"post":{"operationId":"submitDocumentApproval","tags":["Schvalování výdajů"],"summary":"Odeslání přijatého výdaje ke schválení","description":"Odešle doklad, na který se vztahuje pravidlo schvalování, ke schválení (stav pending) – ze stavu „vyžaduje schválení“, „vráceno k opravě“ nebo „změněno po schválení“. Doklad se tím nevystaví ani nezaúčtuje. Tělo se nečte; poznámku k odeslání nelze přes API zadat. Vrátí detail dokladu se stavem schvalování.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":7},{"name":"id","in":"path","required":true,"description":"ID přijatého dokladu","schema":{"type":"integer"},"example":1544}],"responses":{"200":{"description":"Detail dokladu jako v getDocument; approval.state je pending.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Stornovaný doklad: „Stornovaný doklad nelze odeslat ke schválení“ Žádné pravidlo doklad nepokrývá (nebo je schvalování vypnuté): „Tento doklad podle pravidel firmy schválení nepotřebuje“ „Doklad už čeká na schválení“ nebo „Doklad je už schválený“ Doklad byl vystaven dřív, než se na něj pravidlo vztahovalo: „Doklad byl zaúčtovaný dřív, než se začalo schvalovat“","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"schvalovani","x-saldo-access":"writer","x-saldo-side-effects":"Nastaví stav schvalování pending, přidá do historie schvalování záznam submitted s otiskem údajů a zapíše document.approval_submitted.","x-saldo-repeat":"Druhé volání vrátí 422 „Doklad už čeká na schválení“.","x-saldo-errors":[{"status":422,"when":"Stornovaný doklad: „Stornovaný doklad nelze odeslat ke schválení“"},{"status":422,"when":"Žádné pravidlo doklad nepokrývá (nebo je schvalování vypnuté): „Tento doklad podle pravidel firmy schválení nepotřebuje“"},{"status":422,"when":"„Doklad už čeká na schválení“ nebo „Doklad je už schválený“"},{"status":422,"when":"Doklad byl vystaven dřív, než se na něj pravidlo vztahovalo: „Doklad byl zaúčtovaný dřív, než se začalo schvalovat“"}],"x-saldo-response-fields":[{"name":"approval.state","description":"needed, pending, approved, returned, changed nebo not_required"},{"name":"approval.label","description":"Stav česky, např. Čeká na schválení"},{"name":"approval.required","description":"Na doklad se vztahuje pravidlo"},{"name":"approval.rule","description":"Podmínky pravidla česky, např. od 10 000 Kč"},{"name":"approval.approvers","description":"Kdo schvaluje, např. vlastník nebo účetní"},{"name":"approval.fingerprint","description":"Otisk schvalovaných údajů (SHA-256) pro approveDocument"},{"name":"approval.can_submit","description":"Volající může doklad odeslat ke schválení"},{"name":"approval.can_approve","description":"Volající může doklad schválit"},{"name":"approval.can_return","description":"Volající může doklad vrátit"},{"name":"approval.history[]","description":"{ action (submitted, approved, returned, invalidated), label, user, at, note }"}],"x-saldo-example":{"note":"Vyžaduje zapnuté schvalování s pravidlem, které doklad pokrývá (např. updateApprovalRules s min_amount 0); bez něj odpověď 422 „Tento doklad podle pravidel firmy schválení nepotřebuje“."}}},"/entities/{entity_id}/documents/{id}/approval/approve":{"post":{"operationId":"approveDocument","tags":["Schvalování výdajů"],"summary":"Schválení přijatého výdaje","description":"Schválí doklad (stav approved) a uloží otisk schvalovaných údajů: částka, měna, částka v Kč a kurz, dodavatel (jméno, IČO, účet pro platbu), středisko, účty řádků a přílohy. Schválit lze i doklad, který nebyl odeslán ke schválení nebo byl vrácen. Schválení doklad nevystaví – vystaví se pak issueDocument (schválený doklad smí vystavit kterýkoli zapisující člen). S fingerprint (z approval.fingerprint v detailu) se schválení odmítne, pokud se doklad mezitím změnil. Když schválené údaje později změní někdo, kdo doklad nesmí schválit, schválení se zruší (stav changed); změnu schvalovatelem Saldo rovnou znovu schválí.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":7},{"name":"id","in":"path","required":true,"description":"ID přijatého dokladu","schema":{"type":"integer"},"example":1544}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"fingerprint":{"type":"string","description":"Otisk z approval.fingerprint, jak ho schvalovatel viděl; nepovinný"}}}}}},"responses":{"200":{"description":"Detail dokladu jako v getDocument; approval.state je approved a historie končí záznamem approved.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Žádné pravidlo doklad nepokrývá: „Tento doklad podle pravidel firmy schválení nepotřebuje“ Už schválený: „Doklad je už schválený“ Doklad byl vystaven dřív, než se na něj pravidlo vztahovalo: „Doklad byl zaúčtovaný dřív, než se začalo schvalovat“ Volající ho nesmí schválit: „Doklad smí schválit …“ fingerprint neodpovídá aktuálnímu stavu: „Doklad se mezitím změnil – obnovte stránku a zkontrolujte ho znovu“","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"schvalovani","x-saldo-access":"special","x-saldo-access-note":"Zapisující člen (vlastník, účetní, editor), který smí doklad schválit: vlastník vždy; určuje-li pravidlo schvalovatele, jen on (nebo vlastník; když schvalovatel ztratil právo zápisu, jen vlastník); jinak vlastník nebo účetní. Ostatní zapisující členové dostanou 422 „Doklad smí schválit …“, člen jen pro čtení 403.","x-saldo-side-effects":"Nastaví stav schvalování approved a otisk, přidá do historie schvalování záznam approved a zapíše document.approved. Nic nevystavuje ani nezaúčtuje.","x-saldo-repeat":"Druhé volání vrátí 422 „Doklad je už schválený“.","x-saldo-errors":[{"status":422,"when":"Žádné pravidlo doklad nepokrývá: „Tento doklad podle pravidel firmy schválení nepotřebuje“"},{"status":422,"when":"Už schválený: „Doklad je už schválený“"},{"status":422,"when":"Doklad byl vystaven dřív, než se na něj pravidlo vztahovalo: „Doklad byl zaúčtovaný dřív, než se začalo schvalovat“"},{"status":422,"when":"Volající ho nesmí schválit: „Doklad smí schválit …“"},{"status":422,"when":"fingerprint neodpovídá aktuálnímu stavu: „Doklad se mezitím změnil – obnovte stránku a zkontrolujte ho znovu“"}],"x-saldo-example":{"note":"Vyžaduje zapnuté schvalování s pravidlem, které doklad pokrývá; volá vlastník ukázkové firmy."}}},"/entities/{entity_id}/documents/{id}/approval/return":{"post":{"operationId":"returnDocumentApproval","tags":["Schvalování výdajů"],"summary":"Vrácení přijatého výdaje k opravě","description":"Schvalovatel vrátí doklad k opravě s povinným důvodem (stav returned). Vrátit lze jen doklad, který schválení vyžaduje, čeká na něj nebo se po schválení změnil. Opravený doklad se znovu odešle přes submitDocumentApproval (nebo uložením s issue: true); bez nového schválení ho vystaví jen jeho schvalovatel, a tím ho zároveň schválí.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":7},{"name":"id","in":"path","required":true,"description":"ID přijatého dokladu","schema":{"type":"integer"},"example":1544}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["reason"],"properties":{"reason":{"type":"string","description":"Důvod vrácení; mezery se sloučí, nejvýše 500 znaků"}}},"example":{"reason":"Chybí objednávka"}}}},"responses":{"200":{"description":"Detail dokladu jako v getDocument; approval.state je returned a důvod je v approval.history[].note.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Prázdný důvod: „Napište, proč doklad vracíte“ Důvod delší než 500 znaků: „Důvod může mít nejvýš 500 znaků“ Žádné pravidlo doklad nepokrývá: „Tento doklad podle pravidel firmy schválení nepotřebuje“ Volající ho nesmí vrátit: „Doklad smí vrátit …“ Doklad je schválený nebo už vrácený: „Vrátit lze jen doklad, který na schválení čeká“","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"schvalovani","x-saldo-access":"special","x-saldo-access-note":"Stejně jako u approveDocument: zapisující člen, který smí doklad schválit; ostatní zapisující členové dostanou 422 „Doklad smí vrátit …“, člen jen pro čtení 403.","x-saldo-side-effects":"Nastaví stav schvalování returned, přidá do historie schvalování záznam returned s důvodem a zapíše document.approval_returned.","x-saldo-repeat":"Druhé volání vrátí 422 „Vrátit lze jen doklad, který na schválení čeká“.","x-saldo-errors":[{"status":422,"when":"Prázdný důvod: „Napište, proč doklad vracíte“"},{"status":422,"when":"Důvod delší než 500 znaků: „Důvod může mít nejvýš 500 znaků“"},{"status":422,"when":"Žádné pravidlo doklad nepokrývá: „Tento doklad podle pravidel firmy schválení nepotřebuje“"},{"status":422,"when":"Volající ho nesmí vrátit: „Doklad smí vrátit …“"},{"status":422,"when":"Doklad je schválený nebo už vrácený: „Vrátit lze jen doklad, který na schválení čeká“"}],"x-saldo-example":{"note":"Vyžaduje zapnuté schvalování s pravidlem, které doklad pokrývá."}}},"/entities/{entity_id}/documents/{id}/attachments":{"get":{"operationId":"listDocumentAttachments","tags":["Přílohy a importy"],"summary":"Seznam příloh dokladu","description":"Vrátí metadata souborů přiložených k dokladu (skeny, PDF, obrázky, XML) bez jejich obsahu; obsah stáhnete operací downloadDocumentAttachment. Funguje u dokladu v jakémkoli stavu, tedy i u konceptu a stornovaného dokladu. Pořadí příloh není zaručené.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"Účetní jednotka (firma), jejímž jste přijatým členem.","schema":{"type":"integer"},"example":12},{"name":"id","in":"path","required":true,"description":"Doklad firmy.","schema":{"type":"integer"},"example":431}],"responses":{"200":{"description":"Objekt s polem attachments.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"prilohy-a-importy","x-saldo-access":"member","x-saldo-side-effects":"Nic nezapisuje.","x-saldo-limits":"Doklad může mít nejvýše 20 příloh.","x-saldo-response-fields":[{"name":"attachments","description":"Přílohy dokladu (nejvýše 20)."},{"name":"attachments[].id","description":"Identifikátor přílohy pro stažení nebo smazání."},{"name":"attachments[].filename","description":"Původní název souboru."},{"name":"attachments[].content_type","description":"Typ souboru rozpoznaný z obsahu při nahrání."},{"name":"attachments[].byte_size","description":"Velikost v bajtech."},{"name":"attachments[].inline","description":"true u PDF, JPEG, PNG, WebP a GIF (prohlížeč je zobrazí), false u HEIC, HEIF, XML, ZIP a textu (stáhnou se)."},{"name":"attachments[].created_at","description":"Čas nahrání."}]},"post":{"operationId":"uploadDocumentAttachment","tags":["Přílohy a importy"],"summary":"Přiložení souboru k dokladu","description":"Uloží jeden soubor jako přílohu dokladu. Typ se určuje podle obsahu souboru; přípona rozhoduje, když obsah typ neurčí (prostý text) nebo když označuje užší druh téhož obsahu – soubory .csv, .svg, .docx nebo .xlsx se proto odmítnou, i když jde o text, XML nebo ZIP. Přijme PDF, JPEG, PNG, WebP, GIF, HEIC, HEIF, XML, ZIP a prostý text. Přiložit lze i k vystavenému dokladu v uzamčeném období – příloha nemění zaúčtování. Pokud na doklad platí schvalování a byl už schválený, změna příloh ho buď znovu schválí (smí-li volající schvalovat), nebo ho vrátí do stavu „změněno po schválení“.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"Účetní jednotka (firma).","schema":{"type":"integer"},"example":12},{"name":"id","in":"path","required":true,"description":"Doklad firmy.","schema":{"type":"integer"},"example":431}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"Soubor přílohy, nejvýše 15 MB; název souboru se uloží (nejvýše posledních 180 znaků)."}}}}}},"responses":{"201":{"description":"Uložená příloha.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Chybí pole file se souborem (odpověď „Vyberte soubor k přiložení“).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"422":{"description":"Doklad už má 20 příloh („Doklad už má 20 příloh – nejdřív nějakou odeberte“). Soubor je prázdný („Soubor je prázdný“). Soubor je větší než 15 MB („Soubor je větší než 15 MB“). Obsah souboru není žádný z povolených typů („Přiložit lze PDF, obrázek (JPG, PNG, WebP, HEIC) nebo XML“ – text hlášky nevyjmenovává GIF, HEIF, ZIP a prostý text, které se přijmou).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"prilohy-a-importy","x-saldo-access":"writer","x-saldo-side-effects":"Uloží soubor do úložiště a připojí ho k dokladu, zapíše událost document.attached do historie změn a u schvalovaného dokladu přepočítá stav schválení (viz popis). Nic nezaúčtuje a nemění stav dokladu.","x-saldo-limits":"Nejvýše 15 MB na soubor a 20 příloh na doklad. Produkční proxy přijme celý požadavek nejvýše do 21 MB.","x-saldo-repeat":"Každé volání přidá novou přílohu; stejný soubor se znovu uloží jako další příloha (duplicity se nekontrolují).","x-saldo-errors":[{"status":400,"when":"Chybí pole file se souborem (odpověď „Vyberte soubor k přiložení“)."},{"status":422,"when":"Doklad už má 20 příloh („Doklad už má 20 příloh – nejdřív nějakou odeberte“)."},{"status":422,"when":"Soubor je prázdný („Soubor je prázdný“)."},{"status":422,"when":"Soubor je větší než 15 MB („Soubor je větší než 15 MB“)."},{"status":422,"when":"Obsah souboru není žádný z povolených typů („Přiložit lze PDF, obrázek (JPG, PNG, WebP, HEIC) nebo XML“ – text hlášky nevyjmenovává GIF, HEIF, ZIP a prostý text, které se přijmou)."}],"x-saldo-response-fields":[{"name":"id","description":"Identifikátor přílohy."},{"name":"filename","description":"Uložený název souboru."},{"name":"content_type","description":"Rozpoznaný typ souboru."},{"name":"byte_size","description":"Velikost v bajtech."},{"name":"inline","description":"Zda se soubor při stažení zobrazí v prohlížeči (PDF a běžné obrázky)."},{"name":"created_at","description":"Čas nahrání."}]}},"/entities/{entity_id}/documents/{id}/attachments/{attachment_id}":{"get":{"operationId":"downloadDocumentAttachment","tags":["Přílohy a importy"],"summary":"Stažení přílohy dokladu","description":"Vrátí obsah přílohy v původní podobě s typem rozpoznaným při nahrání. PDF, JPEG, PNG, WebP a GIF se posílají s Content-Disposition inline (zobrazí se v prohlížeči), ostatní typy jako attachment s původním názvem souboru.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"Účetní jednotka (firma).","schema":{"type":"integer"},"example":12},{"name":"id","in":"path","required":true,"description":"Doklad firmy.","schema":{"type":"integer"},"example":431},{"name":"attachment_id","in":"path","required":true,"description":"Příloha tohoto dokladu (id ze seznamu příloh).","schema":{"type":"integer"},"example":88}],"responses":{"200":{"description":"Binární obsah souboru; Content-Type je skutečný typ přílohy (např. application/pdf, image/jpeg, application/xml).","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"prilohy-a-importy","x-saldo-access":"member","x-saldo-side-effects":"Nic nezapisuje."},"delete":{"operationId":"deleteDocumentAttachment","tags":["Přílohy a importy"],"summary":"Smazání přílohy dokladu","description":"Odebere přílohu z dokladu a hned smaže i uložený soubor; smazání nelze vrátit. Saldo smazání nebrání ani u vystaveného dokladu v uzamčeném období. U schvalovaného dokladu, který byl schválený, se stav schválení přepočítá stejně jako po přiložení souboru.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"Účetní jednotka (firma).","schema":{"type":"integer"},"example":12},{"name":"id","in":"path","required":true,"description":"Doklad firmy.","schema":{"type":"integer"},"example":431},{"name":"attachment_id","in":"path","required":true,"description":"Příloha tohoto dokladu.","schema":{"type":"integer"},"example":88}],"responses":{"204":{"description":"Bez obsahu."},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"prilohy-a-importy","x-saldo-access":"writer","x-saldo-side-effects":"Smaže záznam přílohy i soubor v úložišti, zapíše událost document.detached do historie změn a u schvalovaného dokladu přepočítá stav schválení. Nic nezaúčtuje.","x-saldo-repeat":"Druhé volání se stejným attachment_id vrátí 404."}},"/entities/{entity_id}/documents/import_isdoc":{"post":{"operationId":"importIsdocDocuments","tags":["Přílohy a importy"],"summary":"Import faktur ve formátu ISDOC","description":"Z každé faktury v nahraných souborech (.isdoc, .isdocx, ISDOC.PDF s vloženým ISDOC nebo ZIP s více fakturami ISDOC) vytvoří doklad. Směr určí IČO dodavatele: je-li to IČO firmy, vznikne vydaný doklad s číslem ze souboru, jinak přijatý doklad s číslem dodavatele v původním čísle; parametr direction druhý směr odmítne. Chybějící kontakt se založí a položky dostanou účet podle dřívějších dokladů kontaktu (jinak výchozí účet kontaktu nebo firmy). Doklad s kontaktem a položkami se hned vystaví (v podvojném účetnictví i zaúčtuje), nebo se odešle ke schválení; přijatý doklad, který vypadá jako duplicita dřívějšího dokladu téhož dodavatele (stejné číslo, nebo stejná částka a měna s datem do ±3 dnů), zůstane konceptem s varováním. Je-li zapnutá automatizace auto_match (výchozí stav), vystavené doklady se ihned spárují s platbami, které už jsou v bance.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"Účetní jednotka (firma).","schema":{"type":"integer"},"example":12}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["files"],"properties":{"files":{"type":"array","description":"Soubory v poli files[] (jediný soubor lze poslat i jako files). ZIP bez manifest.xml s alespoň dvěma soubory .isdoc nebo .isdocx se rozdělí na jednotlivé faktury; jiný ZIP se čte jako jedna faktura ISDOCX.","items":{"type":"string","format":"binary"}},"direction":{"type":"string","description":"sale = přijmout jen faktury, kde je dodavatelem firma; purchase = jen přijaté faktury. Faktura druhého směru skončí se stavem error. Jiná hodnota nebo vynechání = oba směry.","enum":["sale","purchase"]}}}}}},"responses":{"200":{"description":"Výsledek pro každou fakturu (po rozbalení ZIPů) a souhrnné počty.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Nebyl nahrán žádný soubor („Vyberte soubory .isdoc nebo .isdocx“).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"413":{"description":"Některý soubor je větší než 15 MB („Soubor je větší než 15 MB“). Po rozbalení ZIPů je faktur víc než 200 („Najednou lze nahrát nejvýše 200 dokladů“).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"prilohy-a-importy","x-saldo-access":"writer","x-saldo-side-effects":"Vytvoří doklady (koncept, podle popisu vystavení s číslem a zaúčtováním, nebo odeslání ke schválení), založí chybějící kontakty, u ISDOC.PDF přiloží PDF k dokladu a zdrojové XML ISDOC (do 400 000 bajtů) uloží k dokladu. Zapisuje události do historie změn. Se zapnutým auto_match zapíše úhrady spárováním s existujícími bankovními pohyby (v podvojném účetnictví i s jejich zaúčtováním). U faktury v cizí měně bez kurzu v souboru načte kurz ČNB.","x-saldo-limits":"Zpracuje nejvýše 50 nahraných souborů – další se bez upozornění ignorují. Každý soubor nejvýše 15 MB, po rozbalení ZIPů nejvýše 200 faktur. ZIP s fakturami: nejvýše 200 položek, každá do 20 MB a celkem do 60 MB po rozbalení (jinak se čte jako jedna ISDOCX). Faktura datovaná do uzamčeného období skončí ve stavu error bez document_id, její koncept (s kontaktem, případně s PDF) ale v Saldu zůstane a další nahrání ho ohlásí jako duplicate. Produkční proxy přijme celý požadavek nejvýše do 21 MB.","x-saldo-repeat":"Opakované nahrání téže faktury nic nevytvoří: vydaná se pozná podle čísla mezi vydanými doklady, přijatá podle čísla dodavatele a IČO dodavatele nebo podle UUID ISDOC (stornované doklady se nepočítají); výsledek má stav duplicate a document_id existujícího dokladu.","x-saldo-errors":[{"status":400,"when":"Nebyl nahrán žádný soubor („Vyberte soubory .isdoc nebo .isdocx“)."},{"status":413,"when":"Některý soubor je větší než 15 MB („Soubor je větší než 15 MB“)."},{"status":413,"when":"Po rozbalení ZIPů je faktur víc než 200 („Najednou lze nahrát nejvýše 200 dokladů“)."}],"x-saldo-response-fields":[{"name":"results","description":"Jeden záznam na fakturu v pořadí nahrání."},{"name":"results[].status","description":"imported (doklad vznikl), duplicate (doklad už v Saldu je, nic nevzniklo), error (faktura se nenačetla nebo byla odmítnuta), no_isdoc (PDF bez vložených dat ISDOC)."},{"name":"results[].upload","description":"Pořadí nahraného souboru (od 0), ze kterého faktura pochází – u ZIPu mají všechny jeho faktury stejné."},{"name":"results[].filename","description":"Název souboru faktury (u ZIPu název souboru uvnitř archivu)."},{"name":"results[].document_id","description":"Vytvořený doklad (imported) nebo existující doklad (duplicate)."},{"name":"results[].number","description":"Číslo dokladu – u vydaných číslo ze souboru, u přijatých číslo z číselné řady Salda přidělené při vystavení (přijatý koncept má null)."},{"name":"results[].kind","description":"Druh vytvořeného dokladu (invoice_out, credit_out, proforma_out, advance_out, invoice_in, credit_in, proforma_in, advance_in)."},{"name":"results[].partner","description":"Název protistrany ze souboru."},{"name":"results[].total","description":"Částka k úhradě vytvořeného dokladu v jeho měně."},{"name":"results[].currency","description":"Měna dokladu."},{"name":"results[].duplicate_of","description":"U stavu duplicate dosavadní doklad (u vydaných i přijatých); u stavu imported jen u přijatého dokladu možná duplicita, jinak null. Pole id, number, kind, status, original_number, issue_date, total_payable, currency, partner, reason (number nebo amount) a message."},{"name":"results[].warnings","description":"Upozornění (nesedící součet, doklad ponechán jako koncept, čeká na schválení, PDF se nepřiložilo…)."},{"name":"results[].error","description":"Důvod u stavu error a no_isdoc."},{"name":"results[].paid","description":"true, pokud se doklad hned celý uhradil spárováním s bankovním pohybem."},{"name":"imported","description":"Počet výsledků ve stavu imported."},{"name":"paid","description":"Počet dokladů uhrazených spárováním s bankou."}],"x-saldo-example":{"note":"Přijatá faktura od cizího dodavatele – vznikne přijatý doklad, případně s novým kontaktem."}}},"/entities/{entity_id}/imports":{"get":{"operationId":"listImports","tags":["Přílohy a importy"],"summary":"Historie importů a údaje pro převod dat","description":"Vrátí posledních 30 importů firmy (nejnovější první) s počty a informací, zda byly vráceny, a údaje, které potřebuje průvodce převodem: způsob účetnictví, plátcovství DPH, začátek aktuálního účetního období a aktivní bankovní účty a pokladny s počátečními stavy.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"Účetní jednotka (firma).","schema":{"type":"integer"},"example":12}],"responses":{"200":{"description":"Historie importů a kontext firmy.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"prilohy-a-importy","x-saldo-access":"member","x-saldo-side-effects":"Nic nezapisuje.","x-saldo-limits":"Vrací nejvýše 30 importů.","x-saldo-response-fields":[{"name":"imports","description":"Nejvýše 30 importů, nejnovější první."},{"name":"imports[].batch","description":"Označení importu IMP-XXXXXX (pro vrácení)."},{"name":"imports[].type","description":"contacts, documents, trial_balance, open_items nebo money; type_label je český název."},{"name":"imports[].format","description":"Rozpoznaný formát (csv, pohoda, money_s3, form) a filename název souboru."},{"name":"imports[].counts","description":"Součty všech dávek importu – created, duplicate, skipped, error."},{"name":"imports[].created_at","description":"Čas první dávky; user je přihlašovací jméno toho, kdo import spustil, summary text z historie změn."},{"name":"imports[].undone","description":"Zda byl import vrácen; undone_at a undo_summary popisují vrácení."},{"name":"bookkeeping","description":"Způsob vedení (double_entry nebo tax_records); double_entry a vat_payer jako boolean."},{"name":"opening_date","description":"První den aktuálního účetního období (výchozí datum počátečních stavů)."},{"name":"money_accounts","description":"Aktivní bankovní účty a pokladny: id, name, kind, currency, number, account_code, opening_balance, opening_date."}]},"post":{"operationId":"runImportChunk","tags":["Přílohy a importy"],"summary":"Import jedné dávky dat z jiného programu","description":"Naimportuje jednu dávku řádků souboru (stejné pole type, file, mapping a options jako u náhledu) a vrátí next_offset pro další dávku. Klient posílá celý soubor znovu s každou dávkou a s batch z první odpovědi; všechny dávky se stejným batch tvoří jeden import s jedním záznamem v historii a lze je vrátit najednou. Jen řádky se stavem create něco založí: contacts kontakty; documents vystavené doklady (v podvojném účetnictví zaúčtované) s původními čísly (přijatý doklad, jehož číslo už v Saldu má jiný doklad, dostane číslo z číselné řady), novými kontakty a (bez options.payments=false) úhradami; open_items vystavené neuhrazené doklady s úhradou již zaplacené části; money počáteční stavy účtů a pokladen. trial_balance se neimportuje po dávkách: celý soubor musí být bez chybných řádků a MD se musí rovnat Dal, a pak nahradí všechny dosavadní počáteční stavy.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"Účetní jednotka (firma).","schema":{"type":"integer"},"example":12}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["type"],"properties":{"type":{"type":"string","description":"Co se importuje.","enum":["contacts","documents","trial_balance","open_items","money"]},"file":{"type":"string","format":"binary","description":"Tentýž soubor jako u náhledu (do 20 MB), povinný kromě type=money."},"mapping":{"type":"object","description":"Přiřazení sloupců CSV jako u náhledu (řetězec JSON)."},"options":{"type":"object","description":"Volby jako u náhledu (řetězec JSON)."},"batch":{"type":"string","description":"Označení importu IMP- a 6 znaků A–Z0–9 z odpovědi na první dávku. Bez něj vznikne nový import. Import vrácený nebo jiného druhu dat nelze doplnit."},"offset":{"type":"integer","description":"Index prvního řádku dávky (od 0), výchozí 0; u trial_balance se nepoužije."},"limit":{"type":"integer","description":"Počet řádků v dávce, 1 až maximum druhu: contacts 500, documents 100, open_items 200, money 100 (výchozí je maximum). U trial_balance se nepoužije. Při options.ares doporučujeme menší dávky (aplikace posílá 40)."}}}}}},"responses":{"201":{"description":"Výsledky řádků dávky a údaje pro další dávku.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"batch nemá tvar IMP-XXXXXX („Neplatné označení importu“). Import s tímto batch už byl vrácen, nebo patří k jinému druhu dat („… – spusťte nový“). trial_balance – předvaha má chybné řádky („Předvaha má chybné řádky (N) – …“), nesedí MD a Dal („Předvaha nesedí: MD … ≠ Dal … – rozdíl …“), nebo nemá žádný nenulový zůstatek. Stejné chyby souboru, druhu a voleb jako u náhledu (previewImport).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"prilohy-a-importy","x-saldo-access":"writer","x-saldo-side-effects":"Podle druhu: contacts založí kontakty (s označením importu v poznámce, s volbou ares se pro zakládané řádky volá ARES); documents založí kontakty, vystaví doklady (v podvojném účetnictví je zaúčtuje), posune číselné řady a zapíše úhrady podle POHODY; open_items založí kontakty, vystaví doklady (v daňové evidenci bez účetních zápisů) a zapíše úhradu zaplacené části k poslednímu dni před převodem; trial_balance smaže dosavadní počáteční stavy, nastaví počáteční stavy účtů a pokladen a vytvoří zápisy proti účtu 701; money nastaví počáteční stav a datum účtů a v podvojném účetnictví je zaúčtuje. Řádek, který selže, se vrátí jako error a ostatní pokračují. Každá dávka přičte své počty k události import.completed v historii změn, kde je uloženo i to, co se při vrácení obnoví. U cizí měny se načítá kurz ČNB.","x-saldo-limits":"Soubor nejvýše 20 MB, z CSV nejvýše 10 000 řádků. Dávka nejvýše 500 (contacts), 100 (documents, money) a 200 (open_items) řádků. ARES se u jedné dávky volá nejvýše 40 sekund v 6 vláknech; kontakty, které nestihne ověřit, se založí z údajů souboru a zpráva řádku to uvede, kontakt bez názvu v souboru pak skončí chybou. Doklady do uzamčeného období, přijaté doklady podléhající schvalování (pokud volající nesmí schvalovat) a řádky bez protistrany skončí jako error. Produkční proxy přijme celý požadavek nejvýše do 21 MB.","x-saldo-repeat":"Opakovaná dávka nic nezdvojí: už založené kontakty, doklady a neuhrazené faktury se poznají a vrátí jako duplicate, nezměněné počáteční stavy money jako skipped. trial_balance při opakování znovu nahradí všechny počáteční stavy. Každé volání bez batch založí nový import v historii.","x-saldo-errors":[{"status":422,"when":"batch nemá tvar IMP-XXXXXX („Neplatné označení importu“)."},{"status":422,"when":"Import s tímto batch už byl vrácen, nebo patří k jinému druhu dat („… – spusťte nový“)."},{"status":422,"when":"trial_balance – předvaha má chybné řádky („Předvaha má chybné řádky (N) – …“), nesedí MD a Dal („Předvaha nesedí: MD … ≠ Dal … – rozdíl …“), nebo nemá žádný nenulový zůstatek."},{"status":422,"when":"Stejné chyby souboru, druhu a voleb jako u náhledu (previewImport)."}],"x-saldo-response-fields":[{"name":"batch","description":"Označení importu IMP-XXXXXX; posílejte ho s dalšími dávkami."},{"name":"results","description":"Řádky dávky: index, line, label, status (created, duplicate, skipped, error), message a u created record ({type: partner, document, entry nebo bank_account, id, label, u dokladu i kind}; u entry bez id)."},{"name":"counts","description":"Počty této dávky – created, duplicate, skipped, error."},{"name":"next_offset","description":"offset pro další dávku; null, když je soubor hotový."},{"name":"total","description":"Počet řádků celého souboru."},{"name":"warnings","description":"Upozornění k souboru."}],"x-saldo-example":{"note":"První dávka bez batch. Kontakty z tohoto souboru už ukázková firma má (import IMP-UKAZKA), proto nic nevzniklo a všechny řádky jsou duplicate."}}},"/entities/{entity_id}/imports/preview":{"post":{"operationId":"previewImport","tags":["Přílohy a importy"],"summary":"Náhled importu dat z jiného programu","description":"Přečte soubor a u každého řádku určí, co by import udělal (založit, duplicita, přeskočit, chyba), bez uložení čehokoli. Druhy: contacts (adresář z CSV, POHODA XML nebo Money S3 XML), documents (faktury z POHODA XML), trial_balance (počáteční stavy z obratové předvahy v CSV, jen podvojné účetnictví), open_items (neuhrazené faktury k datu převodu z CSV, jen daňová evidence) a money (počáteční stavy účtů a pokladen z options.balances, bez souboru). U CSV rozpozná kódování a oddělovač a vrátí sloupce s navrženým přiřazením, které lze poslat zpět v mapping.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"Účetní jednotka (firma).","schema":{"type":"integer"},"example":12}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["type"],"properties":{"type":{"type":"string","description":"Co se importuje.","enum":["contacts","documents","trial_balance","open_items","money"]},"file":{"type":"string","format":"binary","description":"Soubor do 20 MB; povinný kromě type=money. CSV v UTF-8 (i s BOM), UTF-16 nebo Windows-1250 s oddělovačem středník, čárka, tabulátor nebo svislítko; soubor Excelu (XLSX) se odmítne."},"mapping":{"type":"object","description":"Jen u CSV (contacts, trial_balance, open_items): přiřazení polí ke sloupcům {pole: index sloupce od 0}. Pole uvedené s null nebo nečíselnou hodnotou se nepřiřadí, neuvedená pole se přiřadí automaticky podle záhlaví. Pole: contacts – name, first_name, last_name, ico, dic, street, city, zip, country, email, phone, web, bank_account, bank_code, iban, bic, due_days, note; trial_balance – account, name, debit, credit, balance, foreign; open_items – number, kind, partner, ico, dic, issue_date, due_date, total, remaining, base, vat, currency, variable_symbol. V multipart se posílá jako řetězec JSON."},"options":{"type":"object","description":"Volby podle druhu, v multipart jako řetězec JSON: contacts – ares (true = při importu doplnit název a adresu z ARES podle IČO; v náhledu se ARES nevolá); documents – payments (false = nepřevzít úhrady, výchozí je převzít); trial_balance – date (datum počátečních stavů, výchozí první den aktuálního účetního období), merge_analytics (výchozí true = analytické účty sloučit do syntetických), accounts ({kód účtu 211/221 ze souboru: id bankovního účtu nebo pokladny}); open_items – date (datum převodu, stejný výchozí), side (receivables nebo payables pro řádky, u kterých druh nejde poznat ze sloupce Druh); money – date a balances ([{id, amount, date}] pro bankovní účty a pokladny). Hodnotu false vyjádří jen JSON – pole formuláře options[…]=false se čte jako text a platí jako zapnuté."}}}}}},"responses":{"200":{"description":"Náhled s řádky a souhrnem; přesné další klíče závisí na druhu.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Neznámý type („Zvolte, co importujete: contacts, documents, trial_balance, open_items nebo money“). Chybí soubor („Vyberte soubor k importu“), soubor je tabulka Excelu, nebo je větší než 20 MB. mapping nebo options není platný JSON („Parametr mapping musí být objekt JSON“, resp. „Parametr options musí být objekt JSON“); platný JSON, který není objekt, se tiše ignoruje. documents – soubor není XML, neobsahuje faktury POHODA, nebo obsahuje pokladní doklady; contacts – XML není adresář POHODA ani firmy Money S3. trial_balance – firma nevede podvojné účetnictví, soubor je XML, nebo datum počátečních stavů leží v uzamčeném období; open_items – firma vede podvojné účetnictví, nebo soubor je XML.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"prilohy-a-importy","x-saldo-access":"writer","x-saldo-side-effects":"Nic nezapisuje. U documents s cizí měnou bez kurzu v souboru načte kurz ČNB.","x-saldo-limits":"Soubor nejvýše 20 MB; z CSV se čte nejvýše 10 000 datových řádků, další se bez upozornění ignorují. Produkční proxy přijme celý požadavek nejvýše do 21 MB.","x-saldo-errors":[{"status":422,"when":"Neznámý type („Zvolte, co importujete: contacts, documents, trial_balance, open_items nebo money“)."},{"status":422,"when":"Chybí soubor („Vyberte soubor k importu“), soubor je tabulka Excelu, nebo je větší než 20 MB."},{"status":422,"when":"mapping nebo options není platný JSON („Parametr mapping musí být objekt JSON“, resp. „Parametr options musí být objekt JSON“); platný JSON, který není objekt, se tiše ignoruje."},{"status":422,"when":"documents – soubor není XML, neobsahuje faktury POHODA, nebo obsahuje pokladní doklady; contacts – XML není adresář POHODA ani firmy Money S3."},{"status":422,"when":"trial_balance – firma nevede podvojné účetnictví, soubor je XML, nebo datum počátečních stavů leží v uzamčeném období; open_items – firma vede podvojné účetnictví, nebo soubor je XML."}],"x-saldo-response-fields":[{"name":"type","description":"Druh importu; type_label je český název."},{"name":"format","description":"Rozpoznaný formát (csv, pohoda, money_s3, form); format_label ho popisuje, u CSV i s kódováním a oddělovačem."},{"name":"filename","description":"Název nahraného souboru."},{"name":"rows","description":"Řádky: index (od 0), line (řádek v souboru nebo pořadí dokladu), status (create, duplicate, skip, error), message, warnings, label, detail, amount, currency, date, kind."},{"name":"summary","description":"Počty řádků – total, create, duplicate, skip, error."},{"name":"warnings","description":"Upozornění k celému souboru (např. soubor z jiné firmy podle IČO, výsledkové účty v předvaze)."},{"name":"columns","description":"U CSV sloupce souboru – index, header, field (přiřazené pole), sample (první neprázdná hodnota)."},{"name":"fields","description":"U CSV pole importu – key, label, required."},{"name":"mapping","description":"U CSV použité přiřazení {pole: index sloupce nebo null}."},{"name":"totals","description":"Jen trial_balance – debit, credit, difference a balanced (zda MD = Dal)."},{"name":"existing","description":"Jen trial_balance – dosavadní počáteční stavy, které import nahradí (count, amount, date, accounts)."},{"name":"money_accounts","description":"Jen trial_balance – bankovní účty a pokladny firmy; money_mapping {kód účtu ze souboru: id účtu}."},{"name":"date","description":"U trial_balance, open_items a money použité datum počátečních stavů či převodu."},{"name":"merge_analytics","description":"Jen trial_balance – použitá volba slučování analytik."},{"name":"side","description":"Jen open_items – použitá volba strany (receivables, payables nebo null)."},{"name":"payments","description":"Jen documents – zda se převezmou úhrady; entity_ico a file_ico jsou IČO firmy a IČO ze souboru."}],"x-saldo-example":{"note":"Ukázková firma už kontakty z tohoto souboru má (dřívější import IMP-UKAZKA v historii importů), proto náhled hlásí všechny řádky jako duplicate."}}},"/entities/{entity_id}/imports/{batch}":{"delete":{"operationId":"undoImport","tags":["Přílohy a importy"],"summary":"Vrácení importu","description":"Vrátí celý import se všemi dávkami v jedné transakci: smaže doklady z importu i s jejich úhradami a účetními zápisy, smaže počáteční stavy z předvahy a obnoví ty, které import nahradil (včetně počátečních stavů bankovních účtů a pokladen), vrátí číselné řady, pokud se od importu nepohnuly, a smaže kontakty založené importem – kromě těch, ke kterým mezitím přibyly doklady. Vrácení odmítne, pokud zasahuje do uzamčeného období nebo na import navazuje pozdější práce (úhrada přidaná po importu, navazující doklad, odečtená záloha, vzor opakované faktury).","parameters":[{"name":"entity_id","in":"path","required":true,"description":"Účetní jednotka (firma).","schema":{"type":"integer"},"example":12},{"name":"batch","in":"path","required":true,"description":"Označení importu IMP- a 6 znaků A–Z0–9 (z historie importů).","schema":{"type":"string"},"example":"IMP-7K2Q9D"}],"responses":{"200":{"description":"Co vrácení odstranilo a obnovilo.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"batch nemá tvar IMP-XXXXXX („Neplatné označení importu“). Import neexistuje („Import nebyl nalezen“), nebo už byl vrácen („Tento import už byl vrácen“). Datum dokladu, úhrady, počátečního stavu nebo obnovovaného stavu leží v uzamčeném období („Import zasahuje do uzamčeného období do … – nejdřív období odemkněte v Nastavení“). K importovanému dokladu přibyla úhrada („K dokladu … přibyla po importu úhrada – nejdřív ji smažte, pak import vraťte“), navazuje na něj jiný doklad, importovaná záloha je odečtená na jiném dokladu, nebo doklad slouží jako vzor opakované faktury.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"prilohy-a-importy","x-saldo-access":"writer","x-saldo-side-effects":"Smaže doklady, jejich úhrady a účetní zápisy, odpojí od nich majetek, smaže počáteční stavy z importu, obnoví dřívější počáteční stavy a číselné řady, smaže kontakty z importu bez dokladů a zapíše událost import.undone do historie změn.","x-saldo-repeat":"Druhé vrácení téhož importu vrátí 422 „Tento import už byl vrácen“.","x-saldo-errors":[{"status":422,"when":"batch nemá tvar IMP-XXXXXX („Neplatné označení importu“)."},{"status":422,"when":"Import neexistuje („Import nebyl nalezen“), nebo už byl vrácen („Tento import už byl vrácen“)."},{"status":422,"when":"Datum dokladu, úhrady, počátečního stavu nebo obnovovaného stavu leží v uzamčeném období („Import zasahuje do uzamčeného období do … – nejdřív období odemkněte v Nastavení“)."},{"status":422,"when":"K importovanému dokladu přibyla úhrada („K dokladu … přibyla po importu úhrada – nejdřív ji smažte, pak import vraťte“), navazuje na něj jiný doklad, importovaná záloha je odečtená na jiném dokladu, nebo doklad slouží jako vzor opakované faktury."}],"x-saldo-response-fields":[{"name":"documents","description":"Počet smazaných dokladů."},{"name":"partners","description":"Počet smazaných kontaktů."},{"name":"entries","description":"Počet smazaných počátečních stavů z předvahy."},{"name":"kept_partners","description":"Názvy kontaktů založených importem, které zůstaly, protože mají doklady."},{"name":"restored_accounts","description":"Počet bankovních účtů a pokladen s obnoveným počátečním stavem."},{"name":"restored_entries","description":"Počet obnovených dřívějších počátečních stavů."}]}},"/entities/{entity_id}/bank_accounts":{"get":{"operationId":"listBankAccounts","tags":["Banka, párování a výpisy"],"summary":"Seznam bankovních účtů a pokladen","description":"Vrátí všechny bankovní účty a pokladny firmy včetně archivovaných; nejdřív aktivní, pak podle druhu (`bank` před `cash`) a ID. Každý účet má vlastní analytický účet `221xxx` (bankovní účet) nebo `211xxx` (pokladna) a zůstatek k dnešnímu dni. V podvojném účetnictví je zůstatek účtu vedeného v CZK zůstatkem jeho analytického účtu podle účetních zápisů; jinak jde o počáteční stav + všechny pohyby účtu (i ignorované) + ručně zadané úhrady, u pokladny navíc vystavené pokladní doklady. Token Fio API se nikdy nevrací, jen příznak `api_connected`.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":12}],"responses":{"200":{"description":"Pole bankovních účtů a pokladen.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"banka","x-saldo-access":"member","x-saldo-side-effects":"Nic nezapisuje. U cizoměnového účtu v daňové evidenci načte kurz ČNB k dnešnímu dni pro `balance_czk`.","x-saldo-response-fields":[{"name":"kind","description":"`bank` = bankovní účet, `cash` = pokladna"},{"name":"name","description":"Název účtu"},{"name":"number","description":"Číslo účtu s případným předčíslím"},{"name":"bank_code","description":"Kód banky (4 číslice)"},{"name":"display_number","description":"Číslo účtu ve tvaru číslo/kód banky"},{"name":"iban","description":"IBAN (velkými písmeny bez mezer)"},{"name":"bic","description":"BIC/SWIFT"},{"name":"currency","description":"Měna účtu"},{"name":"account_code","description":"Analytický účet v účtovém rozvrhu (`221xxx` nebo `211xxx`)"},{"name":"opening_balance","description":"Počáteční stav v měně účtu"},{"name":"opening_date","description":"Datum počátečního stavu; zůstatky a kontrola výpisů se počítají od něj"},{"name":"is_default","description":"Výchozí účet svého druhu"},{"name":"archived","description":"Archivovaný účet (nezapočítává se do přehledu peněz a nenabízí se jako výchozí účet dokladů)"},{"name":"balance","description":"Zůstatek k dnešnímu dni v měně účtu"},{"name":"balance_czk","description":"Zůstatek v CZK; u cizoměnového účtu v podvojném účetnictví zůstatek účetních zápisů, v daňové evidenci přepočet kurzem ČNB k dnešku (`null`, když kurz není k dispozici)"},{"name":"api_connected","description":"Zda je k účtu uložený token Fio API"},{"name":"synced_at","description":"Čas posledního úspěšného stažení z Fio API"},{"name":"sync_error","description":"Text poslední chyby stažení z Fio API"}]},"post":{"operationId":"createBankAccount","tags":["Banka, párování a výpisy"],"summary":"Přidání bankovního účtu nebo pokladny","description":"Založí bankovní účet (`kind: bank`) nebo pokladnu (`kind: cash`) a přidělí mu nejnižší analytický účet `221001`–`221999`, resp. `211001`–`211999`, který nemá žádný jiný bankovní účet ani pokladna firmy, a tento účet založí v účtovém rozvrhu s názvem „název číslo/kód banky“. V podvojném účetnictví zaúčtuje nenulový počáteční stav (MD analytický účet / D `701`) ke dni `opening_date`, bez něj k prvnímu dni aktuálního účetního roku; počáteční stav v cizí měně přepočte kurzem ČNB k tomuto dni. `is_default: true` zruší příznak výchozího účtu u ostatních účtů stejného druhu. Do pokladny nelze importovat výpis a její zůstatek zahrnuje i vystavené pokladní doklady.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":12}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["bank_account"],"properties":{"bank_account":{"type":"object","properties":{"kind":{"type":"string","description":"Druh účtu, výchozí `bank`; později ho změnit nelze","enum":["bank","cash"],"default":"bank"},"name":{"type":"string","description":"Název, nejvýše 120 znaků; prázdný dostane název „Bankovní účet“ nebo „Pokladna“","maxLength":120},"number":{"type":"string","description":"Číslo účtu s případným předčíslím, např. `19-2000145399`"},"bank_code":{"type":"string","description":"Kód banky, přesně 4 číslice"},"iban":{"type":"string","description":"IBAN; mezery se odstraní a písmena převedou na velká"},"bic":{"type":"string","description":"BIC/SWIFT; mezery se odstraní a písmena převedou na velká"},"currency":{"type":"string","description":"Měna účtu jako tři velká písmena, výchozí `CZK`","default":"CZK"},"opening_balance":{"type":"number","description":"Počáteční stav v měně účtu, výchozí 0","default":0},"opening_date":{"type":"string","format":"date","description":"Datum počátečního stavu"},"is_default":{"type":"boolean","description":"Výchozí účet svého druhu"}}}}},"example":{"bank_account":{"kind":"bank","name":"Spořicí účet","number":"2400112238","bank_code":"2010","currency":"CZK","opening_balance":50000}}}}},"responses":{"201":{"description":"Založený účet ve stejném tvaru jako v seznamu účtů (včetně `account_code` a zůstatku).","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Nenulový počáteční stav spadá do uzamčeného období: „Období do … je uzamčeno – počáteční stav účtu nelze změnit“ V podvojném účetnictví nejde počáteční stav v cizí měně přepočítat, protože kurz ČNB není k dispozici: „Kurz ČNB pro … ke dni … se nepodařilo načíst – počáteční stav uložte prosím později“ Přidělený analytický účet už v účtovém rozvrhu je (řádek zůstal po smazaném účtu stejného druhu): „Číslo účtu už existuje“; založení projde, až se nepoužitý řádek z účtového rozvrhu smaže","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"banka","x-saldo-access":"writer","x-saldo-side-effects":"Vytvoří účet, řádek účtového rozvrhu s jeho analytickým účtem a v podvojném účetnictví účetní zápis počátečního stavu (zdroj `opening`). Zapíše auditní událost `bank_account.created`.","x-saldo-repeat":"Každé volání založí další účet s dalším volným analytickým účtem.","x-saldo-errors":[{"status":422,"when":"Nenulový počáteční stav spadá do uzamčeného období: „Období do … je uzamčeno – počáteční stav účtu nelze změnit“"},{"status":422,"when":"V podvojném účetnictví nejde počáteční stav v cizí měně přepočítat, protože kurz ČNB není k dispozici: „Kurz ČNB pro … ke dni … se nepodařilo načíst – počáteční stav uložte prosím později“"},{"status":422,"when":"Přidělený analytický účet už v účtovém rozvrhu je (řádek zůstal po smazaném účtu stejného druhu): „Číslo účtu už existuje“; založení projde, až se nepoužitý řádek z účtového rozvrhu smaže"}]}},"/entities/{entity_id}/bank_accounts/{id}":{"patch":{"operationId":"updateBankAccount","tags":["Banka, párování a výpisy"],"summary":"Úprava bankovního účtu nebo pokladny","description":"Změní údaje účtu nebo pokladny; druh (`kind`) změnit nelze a pole se ignoruje. Když se změní počáteční stav, jeho datum nebo měna, Saldo ověří, že původní ani nový nenulový počáteční stav nespadá do uzamčeného období, a v podvojném účetnictví zápis počátečního stavu smaže a zaúčtuje znovu. Řádek analytického účtu v účtovém rozvrhu se přejmenuje na „název číslo/kód banky“. `archived: true` účet archivuje: pohyby i zápisy zůstanou, jen se nezapočítává do přehledu peněz a nenabízí se jako výchozí.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":12},{"name":"id","in":"path","required":true,"description":"ID bankovního účtu nebo pokladny","schema":{"type":"integer"},"example":31}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["bank_account"],"properties":{"bank_account":{"type":"object","properties":{"name":{"type":"string","description":"Název, nejvýše 120 znaků","maxLength":120},"number":{"type":"string","description":"Číslo účtu s případným předčíslím"},"bank_code":{"type":"string","description":"Kód banky, přesně 4 číslice"},"iban":{"type":"string","description":"IBAN; mezery se odstraní a písmena převedou na velká"},"bic":{"type":"string","description":"BIC/SWIFT"},"currency":{"type":"string","description":"Měna účtu jako tři velká písmena; Saldo změně nebrání ani u účtu, který už má pohyby, výpisy nebo úhrady"},"opening_balance":{"type":"number","description":"Počáteční stav v měně účtu"},"opening_date":{"type":"string","format":"date","description":"Datum počátečního stavu"},"is_default":{"type":"boolean","description":"Výchozí účet svého druhu; ostatním účtům stejného druhu se příznak zruší"},"archived":{"type":"boolean","description":"Archivovat (`true`) nebo vrátit mezi aktivní (`false`)"}}}}},"example":{"bank_account":{"name":"Provozní účet Fio","is_default":true}}}}},"responses":{"200":{"description":"Upravený účet ve stejném tvaru jako v seznamu účtů.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Změna počátečního stavu zasahuje do uzamčeného období: „Období do … je uzamčeno – počáteční stav účtu nelze změnit“ Počáteční stav v cizí měně nejde přepočítat bez kurzu ČNB: „Kurz ČNB pro … ke dni … se nepodařilo načíst – počáteční stav uložte prosím později“","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"banka","x-saldo-access":"writer","x-saldo-side-effects":"Uloží změny účtu. Při změně počátečního stavu, jeho data nebo měny v podvojném účetnictví nahradí zápis počátečního stavu (MD analytický účet / D `701`). Přejmenuje řádek analytického účtu v účtovém rozvrhu. Zapíše auditní událost `bank_account.updated`.","x-saldo-repeat":"Opakování se stejnými daty nic dalšího nezmění, jen zapíše další auditní událost; zápis počátečního stavu se nahrazuje jen při skutečné změně počátečních údajů.","x-saldo-errors":[{"status":422,"when":"Změna počátečního stavu zasahuje do uzamčeného období: „Období do … je uzamčeno – počáteční stav účtu nelze změnit“"},{"status":422,"when":"Počáteční stav v cizí měně nejde přepočítat bez kurzu ČNB: „Kurz ČNB pro … ke dni … se nepodařilo načíst – počáteční stav uložte prosím později“"}]},"delete":{"operationId":"deleteBankAccount","tags":["Banka, párování a výpisy"],"summary":"Smazání nepoužitého bankovního účtu nebo pokladny","description":"Smaže bankovní účet nebo pokladnu, ale jen pokud nemá žádné bankovní pohyby, uložené výpisy, úhrady ani doklady, které na něj odkazují; jinak ho lze jen archivovat (`archived: true` v úpravě účtu). Se smazáním zmizí i uložený token Fio API a zápis počátečního stavu. Řádek analytického účtu (`221xxx` nebo `211xxx`) v účtovém rozvrhu zůstává: když Saldo tento kód později přidělí nově zakládanému účtu, založení skončí chybou „Číslo účtu už existuje“, dokud se řádek z účtového rozvrhu nesmaže. Pravidla pro banku omezená na smazaný účet zůstanou, žádný pohyb už nezachytí a při úpravě neprojdou kontrolou.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":12},{"name":"id","in":"path","required":true,"description":"ID bankovního účtu nebo pokladny","schema":{"type":"integer"},"example":33}],"responses":{"204":{"description":"Prázdná odpověď."},"422":{"description":"Účet se používá: „Účet má pohyby, výpisy nebo doklady – můžete ho jen archivovat“ Nenulový počáteční stav nebo jeho zápis leží v uzamčeném období: „Období do … je uzamčeno – počáteční stav účtu nelze změnit“ nebo „Období do … je uzamčeno – zaúčtování nelze změnit“","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"banka","x-saldo-access":"writer","x-saldo-side-effects":"Smaže účet a jeho zápis počátečního stavu (zdroj `opening`). Řádek analytického účtu v účtovém rozvrhu ponechá. Zapíše auditní událost `bank_account.deleted`.","x-saldo-repeat":"Druhé volání vrátí 404.","x-saldo-errors":[{"status":422,"when":"Účet se používá: „Účet má pohyby, výpisy nebo doklady – můžete ho jen archivovat“"},{"status":422,"when":"Nenulový počáteční stav nebo jeho zápis leží v uzamčeném období: „Období do … je uzamčeno – počáteční stav účtu nelze změnit“ nebo „Období do … je uzamčeno – zaúčtování nelze změnit“"}],"x-saldo-example":{"note":"Smazat jde jen účet bez pohybů, výpisů, úhrad a dokladů, proto příklad maže nově založený prázdný účet."}}},"/entities/{entity_id}/bank_accounts/{id}/connect":{"post":{"operationId":"connectBankAccountFeed","tags":["Banka, párování a výpisy"],"summary":"Připojení nebo odpojení Fio API k účtu","description":"Uloží k bankovnímu účtu token Fio API pro automatické stahování pohybů, nebo ho odpojí. Připojit lze jen účet s kódem banky `2010` (Fio banka); účet s jiným kódem banky nebo bez něj (typicky pokladnu) Saldo odmítne. Token musí mít přesně 64 znaků (písmena, číslice, `_` a `-`), uloží se šifrovaně a API ho už nikdy nevrátí, jen `api_connected: true`. Při připojení Saldo Fio nekontaktuje – platnost tokenu a to, že patří k tomuto účtu, se ověří až při stažení pohybů. Prázdný nebo chybějící `token` připojení zruší.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":12},{"name":"id","in":"path","required":true,"description":"ID bankovního účtu","schema":{"type":"integer"},"example":31}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string","description":"Token Fio API z internetového bankovnictví (Nastavení → API); prázdná hodnota připojení zruší"}}},"example":{"token":"SaldoDemoFioToken_0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJ"}}}},"responses":{"200":{"description":"Účet ve stejném tvaru jako v seznamu účtů, s `api_connected` a vymazaným `sync_error`.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Účet není u Fio banky: „Automatické stahování zatím umí jen Fio banka (kód banky 2010)“ Token nemá tvar tokenu Fio: „Token Fio API má 64 znaků – zkopírujte ho celý z internetového bankovnictví“","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"banka","x-saldo-access":"manager","x-saldo-side-effects":"Uloží zašifrovaný token a vymaže `sync_error`, nebo token smaže. Zapíše auditní událost `bank.feed_connected`, při odpojení `bank.feed_removed`. Fio API nevolá.","x-saldo-limits":"Token přesně 64 znaků `A–Z`, `a–z`, `0–9`, `_`, `-` (okrajové mezery se ořežou).","x-saldo-repeat":"Nový token přepíše předchozí; každé volání zapíše auditní událost.","x-saldo-errors":[{"status":422,"when":"Účet není u Fio banky: „Automatické stahování zatím umí jen Fio banka (kód banky 2010)“"},{"status":422,"when":"Token nemá tvar tokenu Fio: „Token Fio API má 64 znaků – zkopírujte ho celý z internetového bankovnictví“"}],"x-saldo-example":{"note":"Token je vymyšlený; při připojení se Fio nekontaktuje."}}},"/entities/{entity_id}/bank_accounts/{id}/sync":{"post":{"operationId":"syncBankAccount","tags":["Banka, párování a výpisy"],"summary":"Stažení nových pohybů z Fio API","description":"Stáhne z Fio API pohyby od poslední zarážky (dotaz `last`, Fio po každém stažení posune zarážku za vydané pohyby) a naimportuje je na účet stejně jako výpis: přeskočí pohyby, jejichž reference (ID pohybu Fio) už účet má, a pohyby s nulovou částkou nebo bez data. Když je zapnutá automatizace `auto_match`, nové pohyby spáruje s doklady, a když je zapnutá `bank_rules`, použije na ně pravidla pro banku. Pokud Fio vrátí výpis jiného účtu, nic se neimportuje. Na rozdíl od ručního importu se nevytváří archiv výpisu ani se neukládá soubor.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":12},{"name":"id","in":"path","required":true,"description":"ID bankovního účtu s připojeným Fio API","schema":{"type":"integer"},"example":31}],"responses":{"200":{"description":"Výsledek importu z Fio API a účet po stažení.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Účet nemá uložený token: „Účet nemá připojené Fio API“ Stahuje se častěji než jednou za 30 s: „Fio dovoluje stáhnout výpis nejvýš jednou za 30 sekund, zkuste to znovu za … s“; `sync_error` se neukládá Fio dotaz odmítlo nebo je nedostupné (neplatný token, pohyby starší 90 dní bez odemčené historie, více než 50 000 pohybů, výpadek nebo nečitelná odpověď) nebo token patří jinému účtu („Token patří k účtu …“); text chyby se uloží do `sync_error`","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"banka","x-saldo-access":"writer","x-saldo-side-effects":"Volá Fio API (`https://fioapi.fio.cz/v1/rest/last/…/transactions.json`). Vytvoří nové bankovní pohyby; podle automatizací zaznamená úhrady dokladů s účetními zápisy a pohyby vyřídí pravidly. Zapíše auditní událost `bank.imported` (zdroj `fio`), případně `payment.recorded` a `bank.rule_applied`. Uloží `synced_at` a vymaže `sync_error`; při chybě Fio uloží její text do `sync_error`.","x-saldo-limits":"Nejvýš jedno stažení za 30 s na jeden token v rámci procesu serveru; Fio při častějším dotazu vrací HTTP 409, které se hlásí stejně. Spojení 5 s, čtení odpovědi 30 s. Fio vydá najednou nejvýš 50 000 pohybů a pohyby starší 90 dní jen po odemčení historie v internetovém bankovnictví.","x-saldo-repeat":"Další stažení vrátí jen pohyby, které Fio od posledního stažení nevydalo; už uložené pohyby se navíc přeskočí podle reference. Volání dříve než za 30 s skončí chybou 422. Zarážku posune Fio už tím, že pohyby vydá: když pak import skončí chybou (např. „Token patří k účtu …“), tyto pohyby další stažení nevrátí a je potřeba je naimportovat z výpisu.","x-saldo-errors":[{"status":422,"when":"Účet nemá uložený token: „Účet nemá připojené Fio API“"},{"status":422,"when":"Stahuje se častěji než jednou za 30 s: „Fio dovoluje stáhnout výpis nejvýš jednou za 30 sekund, zkuste to znovu za … s“; `sync_error` se neukládá"},{"status":422,"when":"Fio dotaz odmítlo nebo je nedostupné (neplatný token, pohyby starší 90 dní bez odemčené historie, více než 50 000 pohybů, výpadek nebo nečitelná odpověď) nebo token patří jinému účtu („Token patří k účtu …“); text chyby se uloží do `sync_error`"}],"x-saldo-response-fields":[{"name":"format","description":"`fio_api`"},{"name":"import_batch","description":"Identifikátor dávky (12 šestnáctkových znaků) uložený u nových pohybů"},{"name":"statement","description":"Údaje výpisu z Fio (účet, období `from`–`to`, počáteční a konečný zůstatek, `fio` s ID pohybů a zarážky)"},{"name":"imported","description":"Počet nových pohybů"},{"name":"skipped","description":"Počet přeskočených pohybů (už uložené nebo s nulovou částkou); pohyb bez data nebo částky Saldo vynechá už při čtení odpovědi Fio a uvede ho jen ve `warnings`"},{"name":"matched","description":"Počet nových pohybů spárovaných s doklady"},{"name":"ruled","description":"Počet nových pohybů vyřízených pravidly"},{"name":"rules","description":"Co udělala pravidla – `transaction_id`, `rule_id`, `rule_name`, `action`, `result`, `text`"},{"name":"warnings","description":"Upozornění ke čtení výpisu"},{"name":"account","description":"Účet po stažení (s `synced_at` a `sync_error`)"}],"x-saldo-example":{"note":"Předpokládá, že účet má uložený token (viz připojení Fio API); odpověď Fio je v záznamu nahrazená ukázkovou."}}},"/entities/{entity_id}/bank_transactions":{"get":{"operationId":"listBankTransactions","tags":["Banka, párování a výpisy"],"summary":"Seznam bankovních pohybů","description":"Vrátí bankovní pohyby všech účtů firmy od nejnovějšího (datum zaúčtování, pak ID sestupně) po stránkách po 200; filtry se kombinují. `q` hledá v názvu protistrany a ve zprávě bez ohledu na velikost písmen (neplatí pro písmena s diakritikou – velké „Č“ v datech hledání „č“ nenajde), ve variabilním symbolu a v čísle protiúčtu. Každý řádek obsahuje spárované doklady, přiřazenou částku a u nespárovaného pohybu zbývající nespárovanou částku.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":12},{"name":"bank_account_id","in":"query","required":false,"description":"Jen pohyby tohoto účtu","schema":{"type":"integer"},"example":31},{"name":"status","in":"query","required":false,"description":"Stav pohybu: `unmatched` nespárováno, `matched` spárováno, `posted` zaúčtováno, `ignored` ignorováno","schema":{"type":"string","enum":["unmatched","matched","posted","ignored"]},"example":"unmatched"},{"name":"ids","in":"query","required":false,"description":"Čárkami oddělená ID pohybů (bere se nejvýše 200)","schema":{"type":"string"},"example":"5012,5013"},{"name":"from","in":"query","required":false,"description":"Pohyby zaúčtované tento den a později","schema":{"type":"string","format":"date"},"example":"2026-09-01"},{"name":"to","in":"query","required":false,"description":"Pohyby zaúčtované nejpozději tento den","schema":{"type":"string","format":"date"},"example":"2026-09-30"},{"name":"q","in":"query","required":false,"description":"Hledaný text (protistrana, zpráva, VS, protiúčet)","schema":{"type":"string"},"example":"nordwood"},{"name":"page","in":"query","required":false,"description":"Číslo stránky","schema":{"type":"integer","default":1,"minimum":1},"example":1}],"responses":{"200":{"description":"Stránka pohybů se součty a počty podle stavů.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"banka","x-saldo-access":"member","x-saldo-side-effects":"Nic nezapisuje.","x-saldo-limits":"200 pohybů na stránku; filtr `ids` bere nejvýše 200 ID.","x-saldo-response-fields":[{"name":"total","description":"Počet pohybů odpovídajících filtru"},{"name":"page","description":"Číslo stránky"},{"name":"per","description":"Velikost stránky (vždy 200)"},{"name":"sums","description":"`incoming` = součet příchozích a `outgoing` = součet odchozích (záporné číslo) za celý filtr, ne jen stránku"},{"name":"status_counts","description":"Počty pohybů podle stavu za všechny pohyby firmy bez ohledu na filtr"},{"name":"rows","description":"Pohyby: `id`, `bank_account_id`, `booked_on`, `amount` (kladná = příchozí, záporná = odchozí), `currency`, `counterparty_account`, `counterparty_bank_code`, `counterparty` (číslo/kód), `counterparty_name`, `variable_symbol`, `constant_symbol`, `specific_symbol`, `message`, `reference`, `import_batch`, `status`, `account_code` (účet nebo kategorie přímého zaúčtování), `documents` (spárované doklady `id`, `number`, `amount`), `assigned_amount` a `open_amount` (nespárovaná část, u jiného stavu než `unmatched` 0); poslední dvě chybí, když pro přepočet měny nejde načíst kurz ČNB"}]}},"/entities/{entity_id}/bank_transactions/import":{"post":{"operationId":"importBankStatement","tags":["Banka, párování a výpisy"],"summary":"Import bankovního výpisu (datový export nebo PDF)","description":"Naimportuje pohyby z výpisu na bankovní účet a uloží originál výpisu (datový soubor a PDF z banky) k období a dávce importu. `file` je datový export (GPC/ABO, XML camt.053, MT940/STA nebo CSV; kódování UTF-8, UTF-16 nebo Windows-1250), který se čte přesně, nebo PDF výpis banky, jehož čtení je v betaverzi s ověřeným rozvržením pro Air Bank (3030), Českou národní banku (0710), Českou spořitelnu (0800), ČSOB (0300), Equa bank (6100), Fio banku (2010), Komerční banku (0100), MONETA Money Bank (0600), Oberbank (8040), Raiffeisenbank (5500), Sberbank CZ (6800) a UniCredit Bank (2700); PDF jiných bank se čte také a náhled je označí `verified: false`. PDF se naimportuje, jen když počáteční zůstatek + pohyby = konečný zůstatek a souhlasí případně uvedený počet položek i součty příjmů a výdajů; naskenované PDF bez textu se odmítne. Období se bere z výpisu (uvedené období, jinak rozsah dat pohybů), `period_month` je povinný jen u výpisu, který neuvádí období ani datované pohyby; výpis musí patřit zvolenému účtu (IBAN, případně číslo účtu a kód banky) a na pokladnu ho importovat nelze. S `preview` vrátí náhled po všech kontrolách se stavem 200 a nic nezapíše; bez něj uloží nové pohyby (201), se zapnutou automatizací `auto_match` je spáruje s doklady a se zapnutou `bank_rules` na zbylé použije pravidla pro banku.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":12}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["bank_account_id","file"],"properties":{"bank_account_id":{"type":"integer","description":"ID bankovního účtu firmy (`kind: bank`), na který se výpis importuje"},"file":{"type":"string","format":"binary","description":"Datový export (nejvýše 5 MB) nebo PDF výpis banky (nejvýše 15 MB). CSV se rozpozná podle hlavičky (exporty Fio, Air Bank, KB, ČSOB, Raiffeisenbank, MONETA, České spořitelny i jiné); ZIP se nepřijímá."},"statement_pdf":{"type":"string","format":"binary","description":"Originální PDF výpis k datovému exportu, nejvýše 15 MB, musí jít o platné PDF. Když je `file` sám PDF, jiné PDF se odmítne."},"period_month":{"type":"string","description":"Měsíc výpisu `RRRR-MM` (rok 2000–2100); povinný jen u výpisu bez uvedeného období a datovaných pohybů. Když je zadán, použije se místo období z výpisu, všechny pohyby musí do měsíce patřit a období se považuje za potvrzené."},"password":{"type":"string","description":"Heslo zaheslovaného PDF; použije se jen pro toto čtení, neukládá se ani nezapisuje do logu"},"preview":{"type":"boolean","description":"`true` (nebo `1`) vrátí náhled importu a nic nezapíše","default":false}}}}}},"responses":{"201":{"description":"Výsledek importu a uložený výpis. S `preview` vrací stav 200 a místo výsledku náhled s poli `preview`, `format`, `pdf`, `period`, `account`, `statement_number`, `opening_balance`, `closing_balance`, `movements`, `total`, `checks`, `new_count`, `skipped_count`, `already_archived`, `sample`, `new_movements`, `pdf_bank` a `warnings`.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"413":{"description":"Soubor nebo PDF je větší než 15 MB: „Výpis je příliš velký (PDF nejvýše 15 MB, datový soubor 5 MB)“","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"422":{"description":"Účet je pokladna: „Výpis lze importovat jen na bankovní účet“ Datový export je větší než 5 MB: „Datový výpis přesahuje limit 5 MB“ `file` nebo `statement_pdf` není nahraný soubor nebo je prázdný: „Výpis chybí“, „Výpis je prázdný“, „PDF výpis chybí“, „PDF výpis je prázdný“ PDF není platné: „Příloha bankovního výpisu musí být platný soubor PDF“ PDF je zaheslované a heslo chybí nebo nesouhlasí: „…: PDF výpis je chráněný heslem – zadejte ho“ nebo „…: Heslo k PDF výpisu nesouhlasí“ Výpis nejde přečíst – text první chyby čtení, např. nerozpoznaný formát, ZIP, PDF bez textu, PDF nad 400 stran, čtení PDF přes 30 s, pohyby z PDF nesouhlasí se zůstatky, počtem položek nebo součty („… nic se neimportovalo – nahrajte datový export výpisu“), výpisy v jednom PDF na sebe nenavazují nebo patří různým účtům `file` je PDF a `statement_pdf` jiné PDF: „Výpis v PDF je zároveň originál od banky – druhé PDF nepřikládejte“ Chybné období: „Měsíc výpisu musí být ve tvaru RRRR-MM“, „Rok výpisu je mimo podporovaný rozsah“, „Datový soubor obsahuje pohyby mimo vybraný měsíc“, „Datový soubor uvádí období mimo vybraný měsíc“, „Výpis neuvádí období ani datované pohyby – vyberte měsíc výpisu“ Výpis patří jinému účtu: „Datový výpis patří jinému bankovnímu účtu, než je zvolený účet v Saldu“ Konflikt s uloženým originálem: „K tomuto datovému výpisu je uložené jiné PDF; existující originál nelze tiše nahradit“, „K tomuto datovému výpisu je PDF už zaevidované pro jiné období“, „Ke stejnému datovému souboru existuje více nepotvrzených období; PDF je nutné přiřadit ručně“","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"banka","x-saldo-access":"writer","x-saldo-side-effects":"Bez `preview` v jedné transakci vytvoří nové bankovní pohyby (stav `unmatched`) a archiv výpisu s datovým souborem a PDF, nebo doplní PDF k dříve uloženému výpisu stejného souboru a potvrdí jeho období; při jakékoli chybě se neuloží nic. Podle automatizací nové pohyby spáruje (úhrady dokladů s účetními zápisy) a vyřídí pravidly (zaúčtování, párování, ignorování). Zapíše auditní události `bank.imported`, `bank.statement_archived` nebo `bank.statement_pdf_attached`, případně `payment.recorded` a `bank.rule_applied`. S `preview` nic nezapisuje.","x-saldo-limits":"Soubor nad 15 MB odmítne stavem 413; datový export nejvýše 5 MB, PDF nejvýše 15 MB a 400 stran, každý krok čtení PDF nejvýše 30 s. Náhled vrací nejvýše 5 000 nových pohybů PDF a 5 ukázkových pohybů.","x-saldo-repeat":"Pohyby, jejichž reference (ID pohybu z banky, jinak otisk údajů pohybu) už účet má, se přeskočí; u PDF se navíc přeskočí pohyby, které účet má z jiného zdroje (stejná částka, nejdřív stejný den, pak ±3 dny, každý uložený pohyb nejvýš jednou). Stejný datový soubor (SHA-256) za stejné období nevytvoří druhý archiv, jen může doplnit chybějící PDF; jiné PDF k výpisu, který už PDF má, se odmítne. Auditní událost `bank.imported` se zapíše při každém volání bez `preview`.","x-saldo-errors":[{"status":413,"when":"Soubor nebo PDF je větší než 15 MB: „Výpis je příliš velký (PDF nejvýše 15 MB, datový soubor 5 MB)“"},{"status":422,"when":"Účet je pokladna: „Výpis lze importovat jen na bankovní účet“"},{"status":422,"when":"Datový export je větší než 5 MB: „Datový výpis přesahuje limit 5 MB“"},{"status":422,"when":"`file` nebo `statement_pdf` není nahraný soubor nebo je prázdný: „Výpis chybí“, „Výpis je prázdný“, „PDF výpis chybí“, „PDF výpis je prázdný“"},{"status":422,"when":"PDF není platné: „Příloha bankovního výpisu musí být platný soubor PDF“"},{"status":422,"code":"PDF_PASSWORD_REQUIRED","when":"PDF je zaheslované a heslo chybí nebo nesouhlasí: „…: PDF výpis je chráněný heslem – zadejte ho“ nebo „…: Heslo k PDF výpisu nesouhlasí“"},{"status":422,"when":"Výpis nejde přečíst – text první chyby čtení, např. nerozpoznaný formát, ZIP, PDF bez textu, PDF nad 400 stran, čtení PDF přes 30 s, pohyby z PDF nesouhlasí se zůstatky, počtem položek nebo součty („… nic se neimportovalo – nahrajte datový export výpisu“), výpisy v jednom PDF na sebe nenavazují nebo patří různým účtům"},{"status":422,"when":"`file` je PDF a `statement_pdf` jiné PDF: „Výpis v PDF je zároveň originál od banky – druhé PDF nepřikládejte“"},{"status":422,"when":"Chybné období: „Měsíc výpisu musí být ve tvaru RRRR-MM“, „Rok výpisu je mimo podporovaný rozsah“, „Datový soubor obsahuje pohyby mimo vybraný měsíc“, „Datový soubor uvádí období mimo vybraný měsíc“, „Výpis neuvádí období ani datované pohyby – vyberte měsíc výpisu“"},{"status":422,"when":"Výpis patří jinému účtu: „Datový výpis patří jinému bankovnímu účtu, než je zvolený účet v Saldu“"},{"status":422,"when":"Konflikt s uloženým originálem: „K tomuto datovému výpisu je uložené jiné PDF; existující originál nelze tiše nahradit“, „K tomuto datovému výpisu je PDF už zaevidované pro jiné období“, „Ke stejnému datovému souboru existuje více nepotvrzených období; PDF je nutné přiřadit ručně“"}],"x-saldo-response-fields":[{"name":"format","description":"Rozpoznaný formát `gpc`, `camt053`, `mt940`, `csv` nebo `pdf`"},{"name":"import_batch","description":"Identifikátor dávky (12 šestnáctkových znaků) uložený u nových pohybů"},{"name":"statement","description":"Co výpis uvádí o sobě – účet, číslo výpisu, období `from`–`to`, počáteční a konečný zůstatek; u PDF i `checks`"},{"name":"imported","description":"Počet nových pohybů"},{"name":"skipped","description":"Počet přeskočených pohybů (už uložené, u PDF i z jiného zdroje, nulové nebo bez data)"},{"name":"matched","description":"Počet nových pohybů spárovaných s doklady"},{"name":"ruled","description":"Počet nových pohybů vyřízených pravidly; `rules` popisuje, co pravidla udělala"},{"name":"warnings","description":"Upozornění ke čtení výpisu (např. strany PDF bez přečtených pohybů)"},{"name":"archive","description":"Uložený výpis – `id`, `bank_account_id`, `period_key` (`RRRR-MM` nebo `RRRR-MM-DD..RRRR-MM-DD`), `period_from`, `period_to`, `period_confirmed`, `format`, `data_filename`, `pdf_filename`, `import_batch`, `imported_count`, `skipped_count`, `created_at`; u opakovaného importu stejného souboru dosavadní výpis"},{"name":"period","description":"Jen náhled: období `key`, `from`, `to` a `confirmed` (potvrzené měsícem, PDF nebo obdobím uvedeným v PDF)"},{"name":"new_count","description":"Jen náhled – kolik pohybů by bylo nových; `skipped_count` kolik by se přeskočilo"},{"name":"already_archived","description":"Jen náhled – stejný datový soubor za stejné období už je uložený"},{"name":"checks","description":"Jen náhled PDF – výsledky kontrol (zůstatky, počet položek, součty, průběžné zůstatky, počet výpisů v PDF)"},{"name":"sample","description":"Jen náhled – prvních 5 nových pohybů"},{"name":"new_movements","description":"Jen náhled PDF – nové pohyby ke kontrole (nejvýše 5 000); u datového exportu `null`"},{"name":"pdf_bank","description":"Jen náhled PDF – banka výpisu `code`, `name` a `verified` (rozvržení ověřené na skutečných výpisech)"}],"x-saldo-example":{"note":"Datový výpis camt.053 k tomuto bankovnímu účtu; období a zůstatky se čtou ze souboru. Ukázková firma má tento soubor už naimportovaný, takže záznam ukazuje opakovaný import: oba pohyby se přeskočily (`imported: 0`, `skipped: 2`) a `archive` je dosavadní uložený výpis s původní dávkou."}}},"/entities/{entity_id}/bank_transactions/auto_match":{"post":{"operationId":"autoMatchBankTransactions","tags":["Banka, párování a výpisy"],"summary":"Automatické párování pohybů s doklady","description":"Spáruje nespárované pohyby s vystavenými doklady, u kterých je shoda jistá, a zaznamená jejich úhradu. Skóre sčítá shodu variabilního symbolu (60), částky (35), čísla účtu kontaktu (15) a názvu protistrany (10); jistá shoda má skóre aspoň 90 a vyšší než druhý nejlepší doklad, takže automaticky se páruje jen při shodě VS i částky. Automaticky se nikdy nepárují pohyby v uzamčeném období, přijaté faktury placené kartou a odchozí platby v CZK, ke kterým může patřit neuhrazený přijatý doklad se stejnou částkou, datem vystavení ±3 dny a odpovídajícím obchodníkem (u platby kartou vystavený, s přiloženým originálem nebo placený kartou, u jiné platby jen placený kartou) – takové pohyby se nabídnou jen v návrzích k ručnímu spárování. Přepínač automatizace `auto_match` toto ruční spuštění neomezuje.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":12}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"transaction_ids":{"type":"array","description":"Jen tyto pohyby (pole ID, bere se nejvýše 1 000; text s ID oddělenými čárkami se nerozdělí). Bez pole se zpracují všechny nespárované pohyby firmy; prázdné pole nespáruje nic.","items":{"type":"integer"}}}},"example":{"transaction_ids":[64]}}}},"responses":{"200":{"description":"Počet spárovaných pohybů a jejich páry.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"banka","x-saldo-access":"writer","x-saldo-side-effects":"Pro každou jistou shodu vytvoří úhradu dokladu (datum pohybu, způsob `bank`, vazba na pohyb) ve výši menší z nespárované části pohybu a zbývající úhrady dokladu; v podvojném účetnictví ji zaúčtuje (např. MD `221xxx` / D `311`, případně kurzový rozdíl `563`/`663`), přepočte uhrazenou částku dokladu a plně přiřazený pohyb označí `matched`. Zapíše auditní událost `payment.recorded` u každé úhrady. Pohyb, u kterého párování selže, přeskočí.","x-saldo-limits":"Nejvýše 1 000 ID v `transaction_ids`.","x-saldo-repeat":"Zpracuje jen pohyby ve stavu `unmatched`; už spárované se znovu nepárují, takže opakované volání spáruje jen to, co mezitím přibylo.","x-saldo-response-fields":[{"name":"matched","description":"Počet spárovaných pohybů"},{"name":"details","description":"Páry `transaction_id`, `document_id`, `score`"}],"x-saldo-example":{"note":"Pohyb v ukázce nemá jistou shodu s žádným dokladem, proto se nic nespárovalo (`matched: 0`)."}}},"/entities/{entity_id}/bank_transactions/statements":{"get":{"operationId":"listBankStatements","tags":["Banka, párování a výpisy"],"summary":"Uložené výpisy s kontrolou zůstatků","description":"Vrátí nejvýše 120 naposledy uložených výpisů (od nejnovějšího), volitelně jen jednoho účtu, a u každého výsledek kontroly `reconciliation`. Kontrola ověřuje, že počáteční zůstatek + pohyby = konečný zůstatek výpisu, návaznost na předchozí výpis účtu, chybějící výpis mezi nimi, jiný výpis za překrývající se období, že pohyby v Saldu za období odpovídají výpisu a že konečný zůstatek souhlasí s účetnictvím ke konci období (v podvojném účetnictví analytický účet `221xxx`, u cizoměnového účtu spárované a zaúčtované pohyby v měně účtu, v daňové evidenci počáteční stav + pohyby + ruční úhrady; vždy od data počátečního stavu účtu). Kontrolované období je období uvedené v souboru, jinak rozsah dat jeho pohybů; zvolený měsíc (`period_from`–`period_to`) se použije, jen když soubor neuvádí ani jedno. U souboru bez uvedeného období se tak kontroluje jen úsek od prvního do posledního pohybu, i když byl importován s `period_month`, a zbytek měsíce se může hlásit jako chybějící výpis. Kontrola nikdy nic neúčtuje. `status` je `matched` (vše sedí), `mismatch` (jiná měna než účet, počáteční zůstatek + pohyby ≠ konečný, nenavazuje na předchozí výpis, pohyby v Saldu se liší od výpisu nebo konečný zůstatek nesouhlasí s účetnictvím), `gap` (chybí výpis – jen když zůstatky nenavazují, Saldo má v mezeře pohyby nebo mezera obsahuje celý měsíc), `needs_manual` (výpis nemá období, soubor nejde přečíst nebo neuvádí zůstatky), `before_opening` (výpis končí před počátečním stavem účtu, jen informativně) nebo `reviewed` (problém označený jako ručně zkontrolovaný, dokud se výsledek kontroly nezmění).","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":12},{"name":"bank_account_id","in":"query","required":false,"description":"Jen výpisy tohoto účtu (účet musí patřit firmě, jinak 404)","schema":{"type":"integer"},"example":31}],"responses":{"200":{"description":"Pole uložených výpisů, každý s objektem `reconciliation`.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"banka","x-saldo-access":"member","x-saldo-side-effects":"Nic nezapisuje s jednou výjimkou: u výpisů uložených dřív, než Saldo začalo evidovat údaje ze souboru (zůstatky, období a součet pohybů), je jednou načte z uloženého souboru a uloží k výpisu bez auditní události.","x-saldo-limits":"Nejvýše 120 nejnověji uložených výpisů.","x-saldo-response-fields":[{"name":"id","description":"ID uloženého výpisu (`archive_id`); `bank_account_id` jeho účet, `created_at` čas uložení"},{"name":"period_key","description":"`RRRR-MM`, nebo `RRRR-MM-DD..RRRR-MM-DD` pro jiné období; `period_from`, `period_to` a `period_confirmed` k tomu"},{"name":"format","description":"Formát zdroje (`gpc`, `camt053`, `mt940`, `csv`, `pdf`)"},{"name":"data_filename","description":"Název uloženého datového souboru; `pdf_filename` název PDF (`null` bez PDF)"},{"name":"import_batch","description":"Dávka importu; `imported_count` a `skipped_count` z prvního importu souboru"},{"name":"reconciliation.status","description":"Výsledek kontroly (viz popis)"},{"name":"reconciliation.issues","description":"Popisy problémů česky, nejdůležitější první; překryv s jiným výpisem je jen upozornění a stav nemění"},{"name":"reconciliation.period","description":"Kontrolované období `from`–`to` (viz popis); `currency` je měna výpisu, jinak měna účtu"},{"name":"reconciliation.opening_balance","description":"Platný počáteční zůstatek (ze souboru nebo ručně zadaný), `closing_balance` konečný; `file_opening_balance` a `file_closing_balance` jsou hodnoty ze souboru, `source` je `file`, `manual` nebo `null`"},{"name":"reconciliation.movements_total","description":"Součet pohybů ve výpisu, `movements_count` jejich počet, `movements_difference` rozdíl proti zůstatkům"},{"name":"reconciliation.previous","description":"Předchozí výpis účtu (`id`, `period_key`, `from`, `to`, `closing_balance`); `continuity_difference` rozdíl návaznosti"},{"name":"reconciliation.gap","description":"Chybějící období `from`–`to`, jinak `null`; `overlaps` ID výpisů za překrývající se období"},{"name":"reconciliation.imported","description":"Pohyby v Saldu za období proti souboru – `total`, `difference`, `ok`"},{"name":"reconciliation.books","description":"Účetnictví na začátku a konci období – `label`, `account_code`, `ledger`, `currency`, `opening`, `closing`, `opening_difference`, `closing_difference`; při rozdílu v podvojném účetnictví `pending` (`count`, `total`) s nezaúčtovanými nebo ignorovanými pohyby do konce období"},{"name":"reconciliation.manual","description":"Kdo a kdy zadal zůstatky ručně a poznámka (`by`, `at`, `note`)"},{"name":"reconciliation.review","description":"Ruční kontrola (`by`, `at`, `note`, `current`); `current` je `false`, když se výsledek kontroly od označení změnil"}]}},"/entities/{entity_id}/bank_transactions/statements/{archive_id}/{kind}":{"get":{"operationId":"downloadBankStatementFile","tags":["Banka, párování a výpisy"],"summary":"Stažení originálu uloženého výpisu","description":"Stáhne uložený originál výpisu: `data` je importovaný soubor, `pdf` PDF výpis banky. U výpisu importovaného z PDF je týž soubor uložen jako oba druhy. Odpověď je příloha s původním názvem souboru a hlavičkami `Cache-Control: private, no-store` a `X-Content-Type-Options: nosniff`.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":12},{"name":"archive_id","in":"path","required":true,"description":"ID uloženého výpisu","schema":{"type":"integer"},"example":7},{"name":"kind","in":"path","required":true,"description":"`data` = importovaný soubor, `pdf` = originální PDF výpis","schema":{"type":"string","enum":["data","pdf"]},"example":"data"}],"responses":{"200":{"description":"Obsah souboru; pro `pdf` s typem `application/pdf`, pro `data` s typem `application/octet-stream`.","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"404":{"description":"Výpis nemá uložený soubor tohoto druhu (např. datový export bez PDF) nebo `kind` není `data` ani `pdf`","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"banka","x-saldo-access":"member","x-saldo-side-effects":"Nic nezapisuje.","x-saldo-errors":[{"status":404,"when":"Výpis nemá uložený soubor tohoto druhu (např. datový export bez PDF) nebo `kind` není `data` ani `pdf`"}]}},"/entities/{entity_id}/bank_transactions/statements/{archive_id}/balances":{"patch":{"operationId":"updateBankStatementBalances","tags":["Banka, párování a výpisy"],"summary":"Zadání zůstatků výpisu opsaných z PDF","description":"Uloží počáteční a konečný zůstatek opsaný z PDF výpisu banky pro strany, které datový soubor neuvádí; stranu uvedenou v souboru změnit nelze (zadaná hodnota musí souhlasit, prázdná ji ponechá). Částka se čte jako v aplikaci: mezery a apostrofy se vynechají, poslední tečka nebo čárka je desetinná a smí mít nejvýše dvě desetinná místa (např. `12 500,40`). Výpis, jehož období končí v uzamčeném období, měnit nelze. Nic se neúčtuje; změní se jen podklad kontroly, jejíž nový výsledek odpověď vrací.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":12},{"name":"archive_id","in":"path","required":true,"description":"ID uloženého výpisu","schema":{"type":"integer"},"example":8}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"opening_balance":{"type":"string","description":"Počáteční zůstatek z PDF (text nebo číslo); povinný, když ho soubor neuvádí"},"closing_balance":{"type":"string","description":"Konečný zůstatek z PDF (text nebo číslo); povinný, když ho soubor neuvádí"},"note":{"type":"string","description":"Poznámka, nejvýše 250 znaků","maxLength":250}}},"example":{"opening_balance":"412 380,00","closing_balance":"431 250,50","note":"Opsáno z PDF výpisu č. 9"}}}},"responses":{"200":{"description":"Výpis ve stejném tvaru jako v seznamu výpisů, s novým výsledkem kontroly `reconciliation` (`source` = `manual`).","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Soubor uvádí oba zůstatky: „Zůstatky z datového výpisu nelze přepsat ručně“ Výpis patří do uzamčeného období: „Období do … je uzamčeno – zůstatky tohoto výpisu už nelze měnit“ Chybí zůstatek, který soubor neuvádí: „Zadejte počáteční i konečný zůstatek z PDF výpisu“, „Zadejte počáteční zůstatek z PDF výpisu“, „Zadejte konečný zůstatek z PDF výpisu“ Zadaná hodnota se liší od zůstatku ze souboru: „Počáteční (Konečný) zůstatek uvádí datový výpis (…) – nelze ho přepsat ručně“ Hodnota není číslo: „Počáteční (Konečný) zůstatek zadejte jako číslo s nejvýše dvěma desetinnými místy, např. 12 500,40“","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"banka","x-saldo-access":"manager","x-saldo-side-effects":"Uloží zůstatky k výpisu se zdrojem `manual`, kdo a kdy je zadal a poznámku. Zapíše auditní událost `bank.statement_balances_entered` s původními i novými hodnotami. Neúčtuje.","x-saldo-repeat":"Každé volání hodnoty přepíše a zapíše další auditní událost.","x-saldo-errors":[{"status":422,"when":"Soubor uvádí oba zůstatky: „Zůstatky z datového výpisu nelze přepsat ručně“"},{"status":422,"when":"Výpis patří do uzamčeného období: „Období do … je uzamčeno – zůstatky tohoto výpisu už nelze měnit“"},{"status":422,"when":"Chybí zůstatek, který soubor neuvádí: „Zadejte počáteční i konečný zůstatek z PDF výpisu“, „Zadejte počáteční zůstatek z PDF výpisu“, „Zadejte konečný zůstatek z PDF výpisu“"},{"status":422,"when":"Zadaná hodnota se liší od zůstatku ze souboru: „Počáteční (Konečný) zůstatek uvádí datový výpis (…) – nelze ho přepsat ručně“"},{"status":422,"when":"Hodnota není číslo: „Počáteční (Konečný) zůstatek zadejte jako číslo s nejvýše dvěma desetinnými místy, např. 12 500,40“"}],"x-saldo-example":{"note":"Výpis z datového souboru, který zůstatky neuvádí."}}},"/entities/{entity_id}/bank_transactions/statements/{archive_id}/review":{"post":{"operationId":"reviewBankStatement","tags":["Banka, párování a výpisy"],"summary":"Označení problémového výpisu jako ručně zkontrolovaného","description":"Označí výpis, u kterého kontrola našla problém (`mismatch`, `gap` nebo `needs_manual`), jako ručně zkontrolovaný s poznámkou, co bylo ověřeno. Saldo si uloží otisk (SHA-256) výsledku kontroly; stav `reviewed` platí, jen dokud se výsledek kontroly nezmění – pak se vrátí původní problém a `review.current` je `false`. Výpis bez problému ani výpis, jehož období končí v uzamčeném období, označit nelze.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":12},{"name":"archive_id","in":"path","required":true,"description":"ID uloženého výpisu","schema":{"type":"integer"},"example":7}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["note"],"properties":{"note":{"type":"string","description":"Co bylo u výpisu ověřeno; po oříznutí mezer 1–250 znaků","maxLength":250}}},"example":{"note":"Rozdíl tvoří platba zaúčtovaná až v dalším měsíci, ověřeno v internetovém bankovnictví"}}}},"responses":{"200":{"description":"Výpis ve stejném tvaru jako v seznamu výpisů, s výsledkem kontroly `reconciliation` (stav `reviewed`).","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Poznámka chybí: „Napište, co jste u výpisu ověřili“ Poznámka je delší než 250 znaků: „Poznámka může mít nejvýše 250 znaků“ Kontrola nenašla problém: „Ručně lze označit jen výpis, u kterého kontrola našla problém“ Výpis patří do uzamčeného období: „Období do … je uzamčeno – ruční kontrolu tohoto výpisu už nelze měnit“","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"banka","x-saldo-access":"manager","x-saldo-side-effects":"Uloží k výpisu, kdo a kdy ho zkontroloval, poznámku a otisk výsledku kontroly. Zapíše auditní událost `bank.statement_reviewed` se stavem a problémy. Neúčtuje.","x-saldo-repeat":"Nové označení přepíše předchozí (poznámku, čas i otisk) a zapíše další auditní událost.","x-saldo-errors":[{"status":422,"when":"Poznámka chybí: „Napište, co jste u výpisu ověřili“"},{"status":422,"when":"Poznámka je delší než 250 znaků: „Poznámka může mít nejvýše 250 znaků“"},{"status":422,"when":"Kontrola nenašla problém: „Ručně lze označit jen výpis, u kterého kontrola našla problém“"},{"status":422,"when":"Výpis patří do uzamčeného období: „Období do … je uzamčeno – ruční kontrolu tohoto výpisu už nelze měnit“"}],"x-saldo-example":{"note":"Předpokládá, že kontrola výpisu našla problém (např. rozdíl proti účtu 221)."}},"delete":{"operationId":"withdrawBankStatementReview","tags":["Banka, párování a výpisy"],"summary":"Zrušení ruční kontroly výpisu","description":"Zruší ruční kontrolu výpisu, takže se jeho problém znovu počítá. Výpis, jehož období končí v uzamčeném období, změnit nelze.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":12},{"name":"archive_id","in":"path","required":true,"description":"ID uloženého výpisu","schema":{"type":"integer"},"example":7}],"responses":{"200":{"description":"Výpis ve stejném tvaru jako v seznamu výpisů, s výsledkem kontroly bez ruční kontroly (`review` je `null`).","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Výpis není označený: „Výpis není označený jako zkontrolovaný ručně“ Výpis patří do uzamčeného období: „Období do … je uzamčeno – ruční kontrolu tohoto výpisu už nelze měnit“","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"banka","x-saldo-access":"manager","x-saldo-side-effects":"Smaže u výpisu údaje o ruční kontrole. Zapíše auditní událost `bank.statement_review_withdrawn` s původní kontrolou.","x-saldo-repeat":"Druhé volání skončí chybou 422, protože výpis už označený není.","x-saldo-errors":[{"status":422,"when":"Výpis není označený: „Výpis není označený jako zkontrolovaný ručně“"},{"status":422,"when":"Výpis patří do uzamčeného období: „Období do … je uzamčeno – ruční kontrolu tohoto výpisu už nelze měnit“"}],"x-saldo-example":{"note":"Navazuje na označení výpisu jako ručně zkontrolovaného."}}},"/entities/{entity_id}/bank_transactions/{id}/suggestions":{"get":{"operationId":"listBankTransactionSuggestions","tags":["Banka, párování a výpisy"],"summary":"Návrhy dokladů ke spárování s pohybem","description":"Vrátí nejvýše 8 dokladů, se kterými lze nespárovaný pohyb spárovat, seřazených podle skóre. Kandidáti jsou otevřené vystavené doklady správného směru (k příchozí platbě vydané faktury, zálohové faktury a přijaté dobropisy, k odchozí přijaté faktury, zálohy a vydané dobropisy; nejvýše 400 nejnovějších); skóre sčítá shodu VS (60), částky (35), účtu kontaktu (15) a názvu protistrany (10) a vrací se jen návrhy se skóre aspoň 10. U odchozí karetní platby v CZK se na začátek zařadí vystavené přijaté faktury s přiloženým originálem, stejnou částkou, datem vystavení ±3 dny a odpovídajícím obchodníkem (`source: card_receipt`, `requires_confirmation: true`, skóre nejvýš 89) – takový doklad se nikdy nespáruje automaticky. Pohyb, který není ve stavu `unmatched` nebo nemá nespárovanou část, dostane prázdné pole.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":12},{"name":"id","in":"path","required":true,"description":"ID bankovního pohybu","schema":{"type":"integer"},"example":5012}],"responses":{"200":{"description":"Pole návrhů.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"banka","x-saldo-access":"member","x-saldo-side-effects":"Nic nezapisuje.","x-saldo-limits":"Nejvýše 8 návrhů z nejvýše 400 nejnovějších kandidátů.","x-saldo-response-fields":[{"name":"document_id","description":"ID dokladu; `number` jeho číslo, `partner` název kontaktu"},{"name":"remaining","description":"Zbývající úhrada dokladu v jeho měně (`currency`); `due_date` splatnost"},{"name":"score","description":"Skóre shody 10–100"},{"name":"reasons","description":"Důvody česky (variabilní symbol, částka, číslo účtu, název protistrany, originál dokladu, datum karetní platby)"},{"name":"source","description":"`card_receipt` u dokladu k karetní platbě, jinak chybí"},{"name":"requires_confirmation","description":"`true` u dokladu, který je nutné spárovat ručně"}]}},"/entities/{entity_id}/bank_transactions/{id}/match":{"post":{"operationId":"matchBankTransaction","tags":["Banka, párování a výpisy"],"summary":"Spárování pohybu s dokladem","description":"Spáruje pohyb s vystaveným dokladem správného směru a zaznamená jeho úhradu s datem pohybu. Bez `amount` přiřadí menší z nespárované části pohybu a zbývající úhrady dokladu; u dokladu v jiné měně přepočítá kurzem ČNB ke dni pohybu (když kurz ČNB chybí, kurzem dokladu) a když se nespárovaná část od zbytku dokladu liší nejvýš o 3 %, uhradí celý zbytek dokladu. V podvojném účetnictví se úhrada zaúčtuje (vydaná faktura MD `221xxx` / D `311`, přijatá MD `321` / D `221xxx`, zálohy přes `324`/`314`, případně kurzový rozdíl `563`/`663`). Pohyb přejde do stavu `matched`, až je přiřazený celý; jinak zůstane `unmatched` a zbytek lze spárovat s dalším dokladem nebo zaúčtovat. Karetní platba spárovaná s přijatou fakturou placenou kartou se zaznamená jako úhrada kartou.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":12},{"name":"id","in":"path","required":true,"description":"ID bankovního pohybu","schema":{"type":"integer"},"example":5012}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["document_id"],"properties":{"document_id":{"type":"integer","description":"ID vystaveného dokladu firmy"},"amount":{"type":"number","description":"Částka úhrady v měně dokladu (znaménko se ignoruje); nesmí převýšit zbývající úhradu dokladu ani nespárovanou část pohybu"}}},"example":{"document_id":143}}}},"responses":{"200":{"description":"Pohyb ve stejném tvaru jako řádek seznamu pohybů (se `status`, `documents` a `open_amount`).","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Pohyb je v uzamčeném období: „Období do … je uzamčeno – pohyb nelze změnit“ Pohyb je vyřízený: „Pohyb už je zaúčtovaný“, „Pohyb je ignorovaný – nejdřív ho vraťte mezi nespárované“, „Pohyb už je spárovaný“ Doklad nejde uhradit: „Doklad není vystavený“, „Doklad je už uhrazený“ Doklad je opačného směru: „Příchozí platbu lze spárovat jen s vydanou fakturou, zálohou nebo přijatým dobropisem“ nebo „Odchozí platbu lze spárovat jen s přijatou fakturou, zálohou nebo vydaným dobropisem“ Chybná částka: „Částka převyšuje zbývající úhradu dokladu“, „Částka převyšuje nespárovanou část pohybu“, „Částka úhrady nesmí být nulová“ Pohyb je v cizí měně jiné než doklad a kurz ČNB k datu pohybu není k dispozici: „Kurz ČNB pro … ke dni … se nepodařilo načíst – zkuste to prosím později“ (v měně dokladu se místo chybějícího kurzu ČNB použije kurz dokladu)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"banka","x-saldo-access":"writer","x-saldo-side-effects":"Vytvoří úhradu dokladu navázanou na pohyb a jeho účet, v podvojném účetnictví účetní zápisy úhrady (zdroj `payment`), přepočte uhrazenou částku dokladu a stav pohybu. Zapíše auditní událost `payment.recorded`.","x-saldo-repeat":"Každé úspěšné volání vytvoří novou úhradu. Opakování bez `amount` se odmítne, jakmile je pohyb celý přiřazen („Pohyb už je spárovaný“) nebo doklad uhrazen („Doklad je už uhrazený“); s menší `amount` vznikají další dílčí úhrady.","x-saldo-errors":[{"status":422,"when":"Pohyb je v uzamčeném období: „Období do … je uzamčeno – pohyb nelze změnit“"},{"status":422,"when":"Pohyb je vyřízený: „Pohyb už je zaúčtovaný“, „Pohyb je ignorovaný – nejdřív ho vraťte mezi nespárované“, „Pohyb už je spárovaný“"},{"status":422,"when":"Doklad nejde uhradit: „Doklad není vystavený“, „Doklad je už uhrazený“"},{"status":422,"when":"Doklad je opačného směru: „Příchozí platbu lze spárovat jen s vydanou fakturou, zálohou nebo přijatým dobropisem“ nebo „Odchozí platbu lze spárovat jen s přijatou fakturou, zálohou nebo vydaným dobropisem“"},{"status":422,"when":"Chybná částka: „Částka převyšuje zbývající úhradu dokladu“, „Částka převyšuje nespárovanou část pohybu“, „Částka úhrady nesmí být nulová“"},{"status":422,"when":"Pohyb je v cizí měně jiné než doklad a kurz ČNB k datu pohybu není k dispozici: „Kurz ČNB pro … ke dni … se nepodařilo načíst – zkuste to prosím později“ (v měně dokladu se místo chybějícího kurzu ČNB použije kurz dokladu)"}],"x-saldo-example":{"note":"Příchozí platba spárovaná s vydanou fakturou."}}},"/entities/{entity_id}/bank_transactions/{id}/book":{"post":{"operationId":"bookBankTransaction","tags":["Banka, párování a výpisy"],"summary":"Přímé zaúčtování pohybu bez dokladu","description":"Zaúčtuje pohyb bez dokladu (poplatek, úrok, daň, převod) přímo na zvolený účet nebo kategorii a označí ho `posted`. V podvojném účetnictví vytvoří jeden zápis ke dni pohybu: u příchozí platby MD analytický účet banky / D `account_code`, u odchozí MD `account_code` / D účet banky, na nespárovanou část pohybu v CZK (u cizí měny kurzem ČNB ke dni pohybu, s částkou v měně), takže u částečně spárovaného pohybu jen zbytek. V daňové evidenci se zápis nevytváří a `account_code` je kategorie příjmu nebo výdaje (např. `V15`). Saldo kontroluje jen tvar kódu, ne to, zda účet v účtovém rozvrhu existuje.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":12},{"name":"id","in":"path","required":true,"description":"ID bankovního pohybu","schema":{"type":"integer"},"example":5012}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["account_code"],"properties":{"account_code":{"type":"string","description":"Účet nebo kategorie; převede se na velká písmena, smí obsahovat číslice, písmena, tečku a pomlčku (nejvýše 12 znaků) a v podvojném účetnictví nesmí být shodný s analytickým účtem banky"},"text":{"type":"string","description":"Text účetního zápisu, použije se jen v podvojném účetnictví (delší se zkrátí na 250 znaků); výchozí je zpráva pohybu, název protistrany nebo „Bankovní pohyb“"}}},"example":{"account_code":"648","text":"Ostatní provozní výnos"}}}},"responses":{"200":{"description":"Pohyb ve stejném tvaru jako řádek seznamu pohybů (`status` = `posted`, `account_code`).","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Pohyb je v uzamčeném období: „Období do … je uzamčeno – pohyb nelze změnit“ Pohyb je vyřízený: „Pohyb už je zaúčtovaný“, „Pohyb je ignorovaný – nejdřív ho vraťte mezi nespárované“, „Pohyb už je spárovaný“ Pohyb v cizí měně nejde přepočítat: „Kurz ČNB pro … ke dni … se nepodařilo načíst – zkuste to prosím později“","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"banka","x-saldo-access":"writer","x-saldo-side-effects":"Uloží stav `posted` a `account_code`; v podvojném účetnictví vytvoří účetní zápis se zdrojem `bank` (případné starší zápisy téhož pohybu nahradí). Zapíše auditní událost `bank.posted`.","x-saldo-repeat":"Druhé volání skončí 422 „Pohyb už je zaúčtovaný“; jiný účet lze zvolit až po vrácení pohybu mezi nespárované.","x-saldo-errors":[{"status":422,"when":"Pohyb je v uzamčeném období: „Období do … je uzamčeno – pohyb nelze změnit“"},{"status":422,"when":"Pohyb je vyřízený: „Pohyb už je zaúčtovaný“, „Pohyb je ignorovaný – nejdřív ho vraťte mezi nespárované“, „Pohyb už je spárovaný“"},{"status":422,"when":"Pohyb v cizí měně nejde přepočítat: „Kurz ČNB pro … ke dni … se nepodařilo načíst – zkuste to prosím později“"}]}},"/entities/{entity_id}/bank_transactions/{id}/ignore":{"post":{"operationId":"ignoreBankTransaction","tags":["Banka, párování a výpisy"],"summary":"Ignorování pohybu","description":"Označí pohyb jako ignorovaný (typicky převod mezi vlastními účty), takže se nenabízí k párování ani zaúčtování. Pohyb s přiřazenou úhradou ignorovat nejde, nejdřív je nutné párování zrušit (vrácení pohybu mezi nespárované). U zaúčtovaného pohybu se jeho zápis smaže.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":12},{"name":"id","in":"path","required":true,"description":"ID bankovního pohybu","schema":{"type":"integer"},"example":5012}],"responses":{"200":{"description":"Pohyb ve stejném tvaru jako řádek seznamu pohybů (`status` = `ignored`).","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Pohyb je v uzamčeném období: „Období do … je uzamčeno – pohyb nelze změnit“ Pohyb má úhradu: „Pohyb má přiřazené úhrady – nejdřív zrušte párování“","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"banka","x-saldo-access":"writer","x-saldo-side-effects":"Nastaví stav `ignored`, vymaže `account_code` a smaže zápisy pohybu se zdrojem `bank`. Zapíše auditní událost `bank.ignored`.","x-saldo-repeat":"Lze opakovat bez chyby; každé volání zapíše další auditní událost.","x-saldo-errors":[{"status":422,"when":"Pohyb je v uzamčeném období: „Období do … je uzamčeno – pohyb nelze změnit“"},{"status":422,"when":"Pohyb má úhradu: „Pohyb má přiřazené úhrady – nejdřív zrušte párování“"}]}},"/entities/{entity_id}/bank_transactions/{id}/reset":{"post":{"operationId":"resetBankTransaction","tags":["Banka, párování a výpisy"],"summary":"Vrácení pohybu mezi nespárované","description":"Vrátí spárovaný, zaúčtovaný nebo ignorovaný pohyb mezi nespárované: zruší všechny jeho úhrady dokladů včetně jejich účetních zápisů (doklady znovu čekají na úhradu), smaže zápis přímého zaúčtování, vymaže `account_code` a nastaví stav `unmatched`. Pohyb ani jeho úhradu v uzamčeném období vrátit nelze.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":12},{"name":"id","in":"path","required":true,"description":"ID bankovního pohybu","schema":{"type":"integer"},"example":5013}],"responses":{"200":{"description":"Pohyb ve stejném tvaru jako řádek seznamu pohybů (`status` = `unmatched`, prázdné `documents`).","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Pohyb je v uzamčeném období: „Období do … je uzamčeno – pohyb nelze změnit“ Úhrada je v uzamčeném období: „Období do … je uzamčeno – úhradu z … nelze měnit“","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"banka","x-saldo-access":"writer","x-saldo-side-effects":"Smaže úhrady navázané na pohyb a jejich zápisy (zdroj `payment`), přepočte uhrazené částky dokladů, smaže zápisy se zdrojem `bank` a nastaví stav `unmatched`. Zapíše auditní událost `payment.deleted` za každou úhradu a `bank.reset`; pohyb pak už nenese značku vyřízení pravidlem.","x-saldo-repeat":"U nespárovaného pohybu bez úhrad nic nezmění, jen zapíše další auditní událost `bank.reset`.","x-saldo-errors":[{"status":422,"when":"Pohyb je v uzamčeném období: „Období do … je uzamčeno – pohyb nelze změnit“"},{"status":422,"when":"Úhrada je v uzamčeném období: „Období do … je uzamčeno – úhradu z … nelze měnit“"}]}},"/entities/{entity_id}/bank_rules":{"get":{"operationId":"listBankRules","tags":["Banka, párování a výpisy"],"summary":"Seznam pravidel pro banku","description":"Vrátí všechna pravidla pro banku firmy včetně vypnutých v pořadí, ve kterém se zkoušejí (`position`, pak ID). Ke každému přidá český popis podmínek (`summary`) a akce (`action_summary`), název akce, jméno kontaktu a název účtu.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":12}],"responses":{"200":{"description":"Pole pravidel.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"banka","x-saldo-access":"member","x-saldo-side-effects":"Nic nezapisuje.","x-saldo-response-fields":[{"name":"id","description":"ID pravidla"},{"name":"name","description":"Název"},{"name":"active","description":"Zda je pravidlo zapnuté"},{"name":"position","description":"Pořadí (menší se zkouší dřív)"},{"name":"action","description":"`post` zaúčtovat na účet, `match` spárovat s fakturami kontaktu, `partner` přiřadit ke kontaktu, `ignore` ignorovat"},{"name":"conditions","description":"Podmínky ve tvaru, v jakém je Saldo uložilo (viz vytvoření pravidla)"},{"name":"action_data","description":"Data akce (`account_code`, `text`, `partner_id`)"},{"name":"matches_count","description":"Kolikrát pravidlo vyřídilo pohyb; `last_matched_at` kdy naposledy"},{"name":"summary","description":"Podmínky česky, např. „Odchozí · zpráva obsahuje „poplat““"},{"name":"action_summary","description":"Akce česky, např. „Zaúčtovat na 568 Ostatní finanční náklady“; `action_label` název akce"},{"name":"partner_name","description":"Jméno kontaktu z `action_data`; `account_name` název účtu z `action_data`"}]},"post":{"operationId":"createBankRule","tags":["Banka, párování a výpisy"],"summary":"Vytvoření pravidla pro banku","description":"Vytvoří pravidlo pro banku a zařadí ho na konec pořadí. Pravidlo zachytí nespárovaný pohyb, který splní všechny zadané podmínky, a musí mít aspoň jednu podmínku kromě směru a účtu (protiúčet, protistrana, zpráva, symbol nebo rozmezí částky). Akce `post` zaúčtuje pohyb na účet nebo kategorii, která musí být aktivní v účtovém rozvrhu; `match` ho spáruje s otevřenými doklady kontaktu (jednoznačná shoda VS, jinak nejdříve splatný doklad se shodnou částkou, jinak aspoň dva nejdříve splatné doklady, jejichž součet přesně dá částku pohybu; přijaté faktury placené kartou vynechá) a kontaktu bez čísla účtu uloží protiúčet; `partner` uloží kontaktu protiúčet, pokud ho nemá, a zkusí spárovat; `ignore` pohyb ignoruje. S `apply: true` se zapnuté pravidlo hned použije na nespárované pohyby firmy.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":12}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["bank_rule"],"properties":{"bank_rule":{"type":"object","required":["name","action","conditions"],"properties":{"name":{"type":"string","description":"Název pravidla, nejvýše 120 znaků","maxLength":120},"active":{"type":"boolean","description":"Zapnuté pravidlo, výchozí `true`","default":true},"action":{"type":"string","description":"`post` zaúčtovat, `match` spárovat s fakturami kontaktu, `partner` přiřadit ke kontaktu, `ignore` ignorovat","enum":["post","match","partner","ignore"]},"conditions":{"type":"object","description":"Podmínky, pohyb musí splnit všechny; neznámé klíče a prázdné hodnoty se zahodí. Samotný směr nebo účet nestačí. Text se porovnává bez ohledu na velikost písmen a diakritiku.","properties":{"direction":{"type":"string","description":"`in` příchozí, `out` odchozí platba","enum":["in","out"]},"bank_account_id":{"type":"integer","description":"Jen pohyby tohoto bankovního účtu firmy"},"counterparty_account":{"type":"string","description":"Protiúčet `předčíslí-číslo/kód banky` nebo IBAN (český se převede na číslo účtu); bez kódu banky odpovídá číslo u kterékoli banky; nejvýše 60 znaků"},"counterparty_name":{"type":"string","description":"Název protistrany obsahuje tento text (nejvýše 120 znaků)"},"message":{"type":"object","description":"Zpráva pro příjemce; `op` `contains` (obsahuje) nebo `equals` (je), `value` nejvýše 140 znaků. Místo objektu lze poslat jen text, pak platí `contains`.","properties":{"op":{"type":"string","description":"Způsob porovnání, jiná hodnota znamená `contains`","enum":["contains","equals"]},"value":{"type":"string","description":"Hledaný text"}}},"variable_symbol":{"type":"object","description":"Variabilní symbol, stejný tvar jako `message`; mezery se ignorují a `equals` nebere ohled na úvodní nuly"},"constant_symbol":{"type":"object","description":"Konstantní symbol, stejný tvar a porovnání jako `variable_symbol`"},"specific_symbol":{"type":"object","description":"Specifický symbol, stejný tvar a porovnání jako `variable_symbol`"},"amount_min":{"type":"number","description":"Nejmenší částka pohybu v absolutní hodnotě (0 se nebere)"},"amount_max":{"type":"number","description":"Největší částka pohybu v absolutní hodnotě; nesmí být menší než `amount_min`"}}},"action_data":{"type":"object","description":"Data akce; pro `ignore` se nic neukládá","properties":{"account_code":{"type":"string","description":"Pro `post` povinný účet nebo kategorie, která je aktivní v účtovém rozvrhu firmy"},"text":{"type":"string","description":"Pro `post` text účetního zápisu (nejvýše 250 znaků), jinak se použije název pravidla"},"partner_id":{"type":"integer","description":"ID kontaktu firmy; povinné pro `match` a `partner`, u `post` volitelné (kontakt se zapíše k účetnímu zápisu)"}}}}},"apply":{"type":"boolean","description":"`true` hned použije nové pravidlo (je-li zapnuté) na nespárované pohyby firmy"}}},"example":{"bank_rule":{"name":"Bankovní poplatky","action":"post","conditions":{"direction":"out","message":{"op":"contains","value":"poplat"}},"action_data":{"account_code":"568","text":"Bankovní poplatky"}},"apply":true}}}},"responses":{"201":{"description":"Vytvořené pravidlo a výsledek okamžitého použití.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"banka","x-saldo-access":"writer","x-saldo-side-effects":"Vytvoří pravidlo a zapíše auditní událost `bank_rule.created`; s `apply: true` navíc vyřídí zachycené pohyby stejně jako spuštění pravidel.","x-saldo-repeat":"Každé volání vytvoří další pravidlo.","x-saldo-response-fields":[{"name":"rule","description":"Pravidlo ve stejném tvaru jako v seznamu pravidel"},{"name":"applied","description":"Počet pohybů, které pravidlo hned vyřídilo (bez `apply` 0)"},{"name":"rows","description":"Vyřízené pohyby – `transaction_id`, `rule_id`, `rule_name`, `action`, `result`, `text`"}]}},"/entities/{entity_id}/bank_rules/{id}":{"patch":{"operationId":"updateBankRule","tags":["Banka, párování a výpisy"],"summary":"Úprava pravidla pro banku","description":"Změní název, zapnutí, akci, podmínky nebo data akce pravidla; poslané `conditions` a `action_data` nahradí dosavadní celé. Platí stejné kontroly jako při vytvoření a týkají se celého pravidla, ne jen změněných polí: pravidlo omezené na smazaný bankovní účet nebo zaúčtovávající na účet, který v účtovém rozvrhu chybí či je vypnutý, proto nejde uložit (ani jen vypnout), dokud se to neopraví; smazat ho lze vždy. S `apply: true` se pravidlo po uložení hned použije na nespárované pohyby firmy (jen když je zapnuté). Pořadí mění jen operace změny pořadí a na dříve vyřízené pohyby úprava nemá vliv.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":12},{"name":"id","in":"path","required":true,"description":"ID pravidla","schema":{"type":"integer"},"example":4}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["bank_rule"],"properties":{"bank_rule":{"type":"object","properties":{"name":{"type":"string","description":"Název pravidla, nejvýše 120 znaků","maxLength":120},"active":{"type":"boolean","description":"Zapnout nebo vypnout pravidlo"},"action":{"type":"string","description":"Akce pravidla","enum":["post","match","partner","ignore"]},"conditions":{"type":"object","description":"Nové podmínky celé, ve stejném tvaru jako při vytvoření"},"action_data":{"type":"object","description":"Nová data akce celá, ve stejném tvaru jako při vytvoření"}}},"apply":{"type":"boolean","description":"`true` hned použije upravené pravidlo (je-li zapnuté) na nespárované pohyby firmy"}}},"example":{"bank_rule":{"active":false}}}}},"responses":{"200":{"description":"Upravené pravidlo (`rule`) a výsledek okamžitého použití (`applied`, `rows`) jako při vytvoření.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"banka","x-saldo-access":"writer","x-saldo-side-effects":"Uloží změny a zapíše auditní událost `bank_rule.updated`; s `apply: true` navíc vyřídí zachycené pohyby stejně jako spuštění pravidel.","x-saldo-repeat":"Opakování se stejnými daty pravidlo nezmění, jen zapíše další auditní událost."},"delete":{"operationId":"deleteBankRule","tags":["Banka, párování a výpisy"],"summary":"Smazání pravidla pro banku","description":"Smaže pravidlo. Co pravidlo dříve udělalo (zaúčtování, spárování, ignorování), zůstává beze změny.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":12},{"name":"id","in":"path","required":true,"description":"ID pravidla","schema":{"type":"integer"},"example":4}],"responses":{"204":{"description":"Prázdná odpověď."},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"banka","x-saldo-access":"writer","x-saldo-side-effects":"Smaže pravidlo a zapíše auditní událost `bank_rule.deleted`.","x-saldo-repeat":"Druhé volání vrátí 404."}},"/entities/{entity_id}/bank_rules/apply":{"post":{"operationId":"applyBankRules","tags":["Banka, párování a výpisy"],"summary":"Spuštění pravidel na nespárované pohyby","description":"Použije zapnutá pravidla v pořadí na nespárované pohyby firmy nebo jen na `transaction_ids`; na pohyb se uplatní první pravidlo, jehož podmínky pohyb splní a jehož akci jde provést – když akce nejde (např. kontakt nemá odpovídající doklad), zkusí se další pravidlo. S `rule_id` se použije jen toto jedno pravidlo, a to i když je vypnuté. Přeskočí pohyby s přiřazenou úhradou (i částečnou), pohyby v uzamčeném období a odchozí pohyby v CZK, ke kterým existuje neuhrazený přijatý doklad se stejnou částkou, datem vystavení ±3 dny a odpovídajícím obchodníkem (vystavený, nebo koncept s přílohou) – ty čekají na ruční spárování. Přepínač automatizace `bank_rules` toto ruční spuštění neomezuje.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":12}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"rule_id":{"type":"integer","description":"Použít jen toto pravidlo firmy (i vypnuté)"},"transaction_ids":{"type":"array","description":"Jen tyto pohyby; lze poslat i jako text s ID oddělenými čárkami. Prázdné pole nebo prázdný text znamená všechny nespárované pohyby firmy (na rozdíl od automatického párování).","items":{"type":"integer"}}}}}}},"responses":{"200":{"description":"Počet vyřízených pohybů a co s nimi pravidla udělala.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"banka","x-saldo-access":"writer","x-saldo-side-effects":"Podle akce pohyb zaúčtuje (stav `posted`, v podvojném účetnictví zápis se zdrojem `bank`, s kontaktem z pravidla; událost `bank.posted`), spáruje s doklady kontaktu (úhrady se zápisy, událost `payment.recorded`; kontaktu bez čísla účtu uloží protiúčet), jen uloží protiúčet ke kontaktu (`partner`, když spárovat nejde) nebo pohyb ignoruje (stav `ignored`). U pravidla zvýší `matches_count` a nastaví `last_matched_at`; za každý vyřízený pohyb zapíše auditní událost `bank.rule_applied`.","x-saldo-repeat":"Vyřízené pohyby už nejsou nespárované, takže je další spuštění znovu nezpracuje; pravidlo `partner`, které jen uložilo číslo účtu, se podruhé neuplatní.","x-saldo-response-fields":[{"name":"applied","description":"Počet vyřízených pohybů"},{"name":"rows","description":"Řádky `transaction_id`, `rule_id`, `rule_name`, `action`, `result` (`posted`, `matched`, `partner`, `ignored`) a `text` (např. „zaúčtován na 568“)"}]}},"/entities/{entity_id}/bank_rules/preview":{"post":{"operationId":"previewBankRule","tags":["Banka, párování a výpisy"],"summary":"Náhled pohybů, které by pravidlo zachytilo","description":"Ukáže, které pohyby z posledních 12 měsíců by pravidlo zachytilo a co by s nimi udělalo, a pravidlo neuloží. Posílá se stejný objekt `bank_rule` jako při vytvoření; kontroluje se jen to, že má aspoň jednu podmínku kromě směru a účtu. `outcome` říká, co by se s pohybem stalo (např. „Zaúčtuje na 568“), nebo že je už vyřízený či částečně spárovaný a pravidlo ho přeskočí. Náhled nezohledňuje, že spuštění přeskočí pohyby v uzamčeném období a pohyby s možným přijatým dokladem.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":12}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["bank_rule"],"properties":{"bank_rule":{"type":"object","required":["conditions"],"properties":{"name":{"type":"string","description":"Název (pro náhled nepovinný)"},"action":{"type":"string","description":"Akce pravidla","enum":["post","match","partner","ignore"]},"conditions":{"type":"object","description":"Podmínky ve stejném tvaru jako při vytvoření pravidla"},"action_data":{"type":"object","description":"Data akce ve stejném tvaru jako při vytvoření pravidla"}}}}},"example":{"bank_rule":{"name":"Bankovní poplatky","action":"post","conditions":{"direction":"out","message":{"op":"contains","value":"poplat"}},"action_data":{"account_code":"568"}}}}}},"responses":{"200":{"description":"Zachycené pohyby a co by s nimi pravidlo udělalo.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Pravidlo nemá podmínku: „Zadejte alespoň jednu podmínku – účet nebo název protistrany, zprávu, symbol nebo rozmezí částky“","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"banka","x-saldo-access":"member","x-saldo-side-effects":"Nic nezapisuje.","x-saldo-limits":"Prohledá nejvýše 2 000 nejnovějších pohybů za posledních 12 měsíců a vrátí nejvýše 40 řádků.","x-saldo-errors":[{"status":422,"when":"Pravidlo nemá podmínku: „Zadejte alespoň jednu podmínku – účet nebo název protistrany, zprávu, symbol nebo rozmezí částky“"}],"x-saldo-response-fields":[{"name":"scanned","description":"Počet prohledaných pohybů"},{"name":"count","description":"Počet zachycených pohybů"},{"name":"open","description":"Kolik zachycených pohybů je nespárovaných a bez úhrady"},{"name":"rows","description":"Nejvýše 40 pohybů – `id`, `booked_on`, `amount`, `currency`, `counterparty_name`, `counterparty`, `variable_symbol`, `message`, `status` a `outcome`"}]}},"/entities/{entity_id}/bank_rules/draft":{"get":{"operationId":"draftBankRule","tags":["Banka, párování a výpisy"],"summary":"Návrh pravidla z jednoho pohybu","description":"Navrhne pravidlo podle jednoho pohybu a nic neuloží. Platbu státu (odchozí platba na účet v ČNB s VS) rozpozná podle předčíslí účtu finančního úřadu, podle ČSSZ nebo zdravotní pojišťovny a navrhne zaúčtování (v podvojném účetnictví `343`, `341`, `342`, `538` nebo `336`, v daňové evidenci `V94`, `V03`, `V11` nebo `V91`); převod mezi vlastními účty navrhne ignorovat, poplatek zaúčtovat na `568` (`V15`), úrok na `662` (`P90`). Karetní platbu navrhne podle obchodníka a ostatní pohyby podle protistrany – s účtem, na který se její pohyby dřív zaúčtovaly, nebo se spárováním s kontaktem, kterému číslo účtu patří. `hint` vysvětluje důvod návrhu.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":12},{"name":"transaction_id","in":"query","required":true,"description":"ID bankovního pohybu firmy","schema":{"type":"integer"},"example":5012}],"responses":{"200":{"description":"Navržené pravidlo ve tvaru pro vytvoření pravidla.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"banka","x-saldo-access":"member","x-saldo-side-effects":"Nic nezapisuje.","x-saldo-response-fields":[{"name":"name","description":"Navržený název"},{"name":"conditions","description":"Navržené podmínky"},{"name":"action","description":"Navržená akce"},{"name":"action_data","description":"Navržená data akce (u karetní platby nebo neznámé protistrany může chybět `account_code`)"},{"name":"hint","description":"Česky, proč Saldo pravidlo navrhuje a co zkontrolovat"}]}},"/entities/{entity_id}/bank_rules/suggestions":{"get":{"operationId":"listBankRuleSuggestions","tags":["Banka, párování a výpisy"],"summary":"Doporučená pravidla z historie pohybů","description":"Doporučí nejvýše 8 pravidel naučených z pohybů za posledních 12 měsíců: platby státu, převody mezi vlastními účty, bankovní poplatky a úroky, protistrany aspoň dvakrát zaúčtované na stejný účet a aspoň dvě karetní platby u stejného obchodníka. Návrh, jehož pohyby všechny zachytí některé existující pravidlo (i vypnuté) nebo dřívější návrh, se vynechá. `complete` říká, zda jde pravidlo uložit bez doplnění (např. karetní pravidlo bez známého účtu doplnění potřebuje).","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":12}],"responses":{"200":{"description":"Objekt s polem `rows`.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"banka","x-saldo-access":"member","x-saldo-side-effects":"Nic nezapisuje.","x-saldo-limits":"Nejvýše 8 návrhů z nejvýše 2 000 nejnovějších pohybů za 12 měsíců.","x-saldo-response-fields":[{"name":"rows","description":"Návrhy – `key`, `kind` (`state`, `transfer`, `fees`, `interest`, `posted`, `card`), `title`, `reason`, `rule` (`name`, `conditions`, `action`, `action_data`), `count` (zachycené pohyby), `open` (z toho nespárované), `complete` a `samples` (nejvýše 3 pohyby)"}]}},"/entities/{entity_id}/bank_rules/applied":{"get":{"operationId":"listAppliedBankRules","tags":["Banka, párování a výpisy"],"summary":"Pohyby vyřízené pravidlem","description":"Pro zadané pohyby vrátí pravidlo, které je naposledy vyřídilo – jen když pohyb potom nebyl změněn ani vrácen mezi nespárované. Slouží ke značce „pravidlo“ u pohybu; pohyby jiné firmy a neznámá ID se vynechají.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":12},{"name":"ids","in":"query","required":false,"description":"ID pohybů oddělená čárkami (lze i opakovat `ids[]`); bere se nejvýše 500 různých","schema":{"type":"string"},"example":"5012,5013"}],"responses":{"200":{"description":"Objekt, jehož klíče jsou ID pohybů (jako text) a hodnoty `rule_id`, `rule_name` a `at` (kdy pravidlo pohyb vyřídilo); pohyby bez takového pravidla chybí.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"banka","x-saldo-access":"member","x-saldo-side-effects":"Nic nezapisuje.","x-saldo-limits":"Nejvýše 500 ID.","x-saldo-example":{"note":"Pohyb v ukázce nevyřídilo pravidlo (spároval se s fakturou), proto je odpověď prázdný objekt."}}},"/entities/{entity_id}/bank_rules/reorder":{"post":{"operationId":"reorderBankRules","tags":["Banka, párování a výpisy"],"summary":"Změna pořadí pravidel pro banku","description":"Nastaví pořadí pravidel: pravidla z `ids` (jen ta, která firma má) půjdou v zadaném pořadí na začátek, ostatní za ně v dosavadním pořadí, a pozice se přečíslují od 1. Pořadí určuje, které pravidlo se na pohyb uplatní dřív.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":12}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["ids"],"properties":{"ids":{"type":"array","description":"ID pravidel v požadovaném pořadí (pole; neznámá ID se vynechají, text s ID oddělenými čárkami se nerozdělí)","items":{"type":"integer"}}}},"example":{"ids":[1]}}}},"responses":{"200":{"description":"Všechna pravidla v novém pořadí ve stejném tvaru jako v seznamu pravidel.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"banka","x-saldo-access":"writer","x-saldo-side-effects":"Přepíše pozice pravidel a zapíše auditní událost `bank_rule.reordered`.","x-saldo-repeat":"Stejné pořadí lze poslat opakovaně; každé volání zapíše auditní událost."}},"/entities/{entity_id}/documents/waiting_payments":{"get":{"operationId":"listWaitingPayments","tags":["Banka, párování a výpisy"],"summary":"Úhrady vydaných dokladů čekající v bance na spárování","description":"Vrátí otevřené vystavené doklady (vydané faktury, zálohové faktury, přijaté dobropisy), jejichž úhrada už je mezi nespárovanými příchozími pohyby – přesně ty, které by spárovalo automatické párování (shoda VS i částky, jednoznačně, mimo uzamčené období), nejvýše jeden pohyb na doklad. Připojí datum posledního bankovního pohybu firmy a počet importovaných vydaných faktur a záloh po splatnosti (ISDOC, POHODA, import), které nejsou mezi řádky a jejichž splatnost je až po posledním pohybu, takže jejich úhradu bankovní data zatím nemohou ukázat (bez pohybů v bance všechny takové doklady).","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":12}],"responses":{"200":{"description":"Doklady s čekající úhradou a údaje o pokrytí bankovními daty.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"banka","x-saldo-access":"member","x-saldo-side-effects":"Nic nezapisuje. Úhrady nezaznamená – k tomu slouží automatické párování s `transaction_ids`.","x-saldo-response-fields":[{"name":"rows","description":"Řádky `document_id`, `number`, `transaction_id`, `booked_on`, `amount`, `currency` (seřazené podle data pohybu)"},{"name":"statements_until","description":"Datum posledního bankovního pohybu firmy, `null` bez pohybů"},{"name":"beyond_statements","description":"Počet importovaných vydaných faktur a záloh po splatnosti, které nejsou mezi řádky a mají splatnost po `statements_until` (bez pohybů všechny takové)"}],"x-saldo-example":{"note":"V ukázkové firmě teď žádná úhrada vydaného dokladu na spárování nečeká, proto je `rows` prázdné."}}},"/entities/{entity_id}/accounts":{"get":{"operationId":"listAccounts","tags":["Účetní knihy a výkazy"],"summary":"Účtový rozvrh nebo kategorie daňové evidence","description":"Vrátí všechny účty firmy seřazené podle kódu, včetně neaktivních. V podvojném účetnictví je to účtový rozvrh (např. 221, 311, 518, 602), v daňové evidenci kategorie příjmů a výdajů (např. P02, V05).","parameters":[{"name":"entity_id","in":"path","required":true,"description":"Účetní jednotka (firma).","schema":{"type":"integer"},"example":12}],"responses":{"200":{"description":"Pole účtů (bez obalového objektu).","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"ucetnictvi","x-saldo-access":"member","x-saldo-side-effects":"Nic nezapisuje.","x-saldo-response-fields":[{"name":"[].id","description":"Identifikátor účtu pro úpravu a smazání."},{"name":"[].code","description":"Kód účtu nebo kategorie."},{"name":"[].name","description":"Název."},{"name":"[].kind","description":"Druh (asset, liability, equity, expense, revenue, closing, off_balance, neutral); kind_label je český název."},{"name":"[].tax_relevant","description":"Zda je účet daňový."},{"name":"[].statement_line","description":"Ruční přiřazení řádku rozvahy nebo výkazu zisku a ztráty, jinak null."},{"name":"[].active","description":"Zda je účet aktivní."}]},"post":{"operationId":"createAccount","tags":["Účetní knihy a výkazy"],"summary":"Založení účtu nebo kategorie","description":"Přidá do účtového rozvrhu (nebo mezi kategorie daňové evidence) nový účet, typicky analytický účet jako 518100. Kód se převede na velká písmena a musí být ve firmě jedinečný. Hodnoty statement_line nabízí sestava statements v poli line_options; uložit ale jde jen řádky rozvahy (ak:…, pa:…) – hodnoty vz:… pro výkaz zisku a ztráty validace odmítne (viz chyby).","parameters":[{"name":"entity_id","in":"path","required":true,"description":"Účetní jednotka (firma).","schema":{"type":"integer"},"example":12}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["account"],"properties":{"account":{"type":"object","required":["code","name","kind"],"properties":{"code":{"type":"string","description":"Kód: 1–12 znaků, číslice, velká písmena, tečka a pomlčka; první znak číslice nebo písmeno."},"name":{"type":"string","description":"Název, nejvýše 160 znaků."},"kind":{"type":"string","description":"Druh účtu – aktivní, pasivní, vlastní kapitál, nákladový, výnosový, závěrkový, podrozvahový, neutrální.","enum":["asset","liability","equity","expense","revenue","closing","off_balance","neutral"]},"tax_relevant":{"type":"boolean","description":"Daňový účet (výchozí true)."},"statement_line":{"type":"string","description":"Ruční přiřazení řádku výkazů: ak: nebo pa: a označení řádku rozvahy z velkých písmen, číslic a teček (např. ak:C.II.2.4); bez něj se řádek určí podle syntetického účtu. Validace připouští jen tento tvar, proto kódy řádků výkazu zisku a ztráty z line_options (např. vz:n_vs_sluzby) odmítne."},"active":{"type":"boolean","description":"Aktivní účet (výchozí true)."}}}}},"example":{"account":{"code":"518100","name":"Software a cloudové služby","kind":"expense","tax_relevant":true}}}}},"responses":{"201":{"description":"Založený účet ve stejném tvaru jako v seznamu účtů.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"statement_line nemá tvar ak:, pa: nebo vz: s velkými písmeny, číslicemi a tečkami – platí pro všechny řádky výkazu zisku a ztráty z line_options (malá písmena a podtržítka), takže přiřazení k řádku VZZ API neuloží (známá chyba).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"ucetnictvi","x-saldo-access":"writer","x-saldo-side-effects":"Založí účet a zapíše událost account.created do historie změn. Nic nezaúčtuje.","x-saldo-repeat":"Druhé založení se stejným kódem skončí chybou validace 422 (kód už existuje).","x-saldo-errors":[{"status":422,"when":"statement_line nemá tvar ak:, pa: nebo vz: s velkými písmeny, číslicemi a tečkami – platí pro všechny řádky výkazu zisku a ztráty z line_options (malá písmena a podtržítka), takže přiřazení k řádku VZZ API neuloží (známá chyba)."}]}},"/entities/{entity_id}/accounts/{id}":{"patch":{"operationId":"updateAccount","tags":["Účetní knihy a výkazy"],"summary":"Úprava účtu nebo kategorie","description":"Změní název, druh, daňovost, přiřazení k řádku výkazů nebo aktivitu účtu; kód změnit nelze (pole code se tiše ignoruje). Sestavy se počítají z aktuálních údajů účtu, takže změna druhu, daňovosti nebo řádku výkazu se projeví i ve výstupech za uzamčená období – uzamčení úpravě nebrání. Nepoužívaný účet raději deaktivujte (active: false) než mažte.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"Účetní jednotka (firma).","schema":{"type":"integer"},"example":12},{"name":"id","in":"path","required":true,"description":"Účet firmy (id ze seznamu účtů).","schema":{"type":"integer"},"example":815}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["account"],"properties":{"account":{"type":"object","properties":{"name":{"type":"string","description":"Název, nejvýše 160 znaků."},"kind":{"type":"string","description":"Druh účtu.","enum":["asset","liability","equity","expense","revenue","closing","off_balance","neutral"]},"tax_relevant":{"type":"boolean","description":"Daňový účet."},"statement_line":{"type":"string","description":"Ruční přiřazení řádku rozvahy (ak:…, pa:…); prázdná hodnota přiřazení zruší. Kódy řádků výkazu zisku a ztráty (vz:…) validace odmítne."},"active":{"type":"boolean","description":"Aktivní účet."}}}}},"example":{"account":{"name":"Ostatní služby – provoz","active":true}}}}},"responses":{"200":{"description":"Upravený účet.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"statement_line nemá tvar ak:, pa: nebo vz: s velkými písmeny, číslicemi a tečkami – platí pro všechny řádky výkazu zisku a ztráty z line_options, takže přiřazení k řádku VZZ API neuloží (známá chyba).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"ucetnictvi","x-saldo-access":"writer","x-saldo-side-effects":"Změní účet. Událost do historie změn nezapisuje a nic nezaúčtuje.","x-saldo-repeat":"Stejný požadavek vede ke stejnému stavu.","x-saldo-errors":[{"status":422,"when":"statement_line nemá tvar ak:, pa: nebo vz: s velkými písmeny, číslicemi a tečkami – platí pro všechny řádky výkazu zisku a ztráty z line_options, takže přiřazení k řádku VZZ API neuloží (známá chyba)."}]},"delete":{"operationId":"deleteAccount","tags":["Účetní knihy a výkazy"],"summary":"Smazání nepoužitého účtu","description":"Smaže účet, pokud jeho kód není v žádném účetním zápisu (na straně MD ani Dal) ani v položce žádného dokladu firmy; porovnává se přesná shoda kódu. Jiné odkazy (bankovní účet, bankovní pravidlo, majetek, výchozí účet kontaktu) se nekontrolují. Použitý účet lze jen deaktivovat.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"Účetní jednotka (firma).","schema":{"type":"integer"},"example":12},{"name":"id","in":"path","required":true,"description":"Účet firmy.","schema":{"type":"integer"},"example":902}],"responses":{"204":{"description":"Bez obsahu."},"422":{"description":"Kód je použitý v zápisech nebo položkách dokladů („Účet je použitý v zápisech – můžete ho jen deaktivovat“).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"ucetnictvi","x-saldo-access":"writer","x-saldo-side-effects":"Smaže účet. Událost do historie změn nezapisuje.","x-saldo-repeat":"Druhé volání vrátí 404.","x-saldo-errors":[{"status":422,"when":"Kód je použitý v zápisech nebo položkách dokladů („Účet je použitý v zápisech – můžete ho jen deaktivovat“)."}]}},"/entities/{entity_id}/entries":{"get":{"operationId":"listEntries","tags":["Účetní knihy a výkazy"],"summary":"Účetní deník","description":"Vrátí účetní zápisy za období chronologicky (datum, pak pořadí vzniku) po stránkách, se součtem částek všech vyhovujících zápisů. Filtry lze kombinovat: účet (prefix na straně MD nebo Dal, takže 311 zahrne i 311xxx), text zápisu, doklad a zdroj zápisu.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"Účetní jednotka (firma).","schema":{"type":"integer"},"example":12},{"name":"year","in":"query","required":false,"description":"Účetní období začínající v tomto roce; výchozí je aktuální rok. Nečíselná hodnota se bere jako aktuální rok, mimo rozsah se ořízne.","schema":{"type":"integer","minimum":2000,"maximum":2100},"example":2026},{"name":"from","in":"query","required":false,"description":"Začátek období (YYYY-MM-DD); výchozí je první den účetního období year.","schema":{"type":"string","format":"date"},"example":"2026-09-01"},{"name":"to","in":"query","required":false,"description":"Konec období včetně (YYYY-MM-DD); výchozí je poslední den účetního období year.","schema":{"type":"string","format":"date"},"example":"2026-09-30"},{"name":"account","in":"query","required":false,"description":"Kód účtu nebo jeho začátek; zápis se vrátí, pokud jím začíná strana MD nebo Dal.","schema":{"type":"string"},"example":"221"},{"name":"q","in":"query","required":false,"description":"Hledaný text v textu zápisu bez ohledu na velikost písmen, s výjimkou velkých písmen s diakritikou v textu zápisu (databáze SQLite převádí na malá písmena jen ASCII): text „Úhrada“ se najde dotazem „hrada“, ne „úhrada“ ani „Úhrada“.","schema":{"type":"string"},"example":"nájem"},{"name":"document_id","in":"query","required":false,"description":"Jen zápisy tohoto dokladu.","schema":{"type":"integer"},"example":431},{"name":"source_type","in":"query","required":false,"description":"Zdroje oddělené čárkou: document, payment, bank, asset, payroll, manual, opening, closing, revaluation. Neznámé hodnoty se vynechají; když žádná neplatí, výsledek je prázdný. Pole source_type[] se nepodporuje.","schema":{"type":"string"},"example":"manual,opening"},{"name":"page","in":"query","required":false,"description":"Stránka od 1.","schema":{"type":"integer","default":1,"minimum":1},"example":1},{"name":"per","in":"query","required":false,"description":"Počet zápisů na stránce.","schema":{"type":"integer","default":200,"minimum":1,"maximum":1000},"example":50}],"responses":{"200":{"description":"Stránka zápisů se součty.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"ucetnictvi","x-saldo-access":"member","x-saldo-side-effects":"Nic nezapisuje.","x-saldo-limits":"Nejvýše 1000 zápisů na stránce.","x-saldo-response-fields":[{"name":"total","description":"Počet všech vyhovujících zápisů."},{"name":"sum","description":"Součet částek všech vyhovujících zápisů v Kč."},{"name":"page","description":"Vrácená stránka; per je velikost stránky."},{"name":"rows","description":"Zápisy: id, date, text, debit_account (MD), credit_account (Dal), amount (Kč), source_type, document_id, document_number, variable_symbol, currency a amount_currency (u cizí měny)."}]},"post":{"operationId":"createEntry","tags":["Účetní knihy a výkazy"],"summary":"Ruční účetní zápis","description":"Vytvoří jeden účetní zápis MD/Dal v Kč (interní doklad, dohadná položka, oprava) nebo s opening: true počáteční stav. Kódy účtů se převedou na velká písmena a kontroluje se jen jejich tvar a to, že se strany liší – existence účtu v účtovém rozvrhu se neověřuje. Částka se zaokrouhlí na haléře; chybějící nebo nečíselná částka se uloží jako 0,00 a kladné znaménko se nevyžaduje. Datum v uzamčeném období je odmítnuto.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"Účetní jednotka (firma).","schema":{"type":"integer"},"example":12}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["entry"],"properties":{"entry":{"type":"object","required":["date","debit_account","credit_account"],"properties":{"date":{"type":"string","format":"date","description":"Datum zápisu (YYYY-MM-DD); chybějící nebo neplatné datum vrátí 400."},"debit_account":{"type":"string","description":"Účet strany MD (1–12 znaků, číslice, písmena, tečka, pomlčka)."},"credit_account":{"type":"string","description":"Účet strany Dal; musí se lišit od MD."},"amount":{"type":"number","description":"Částka v Kč; přijme i desetinnou čárku („1500,50“)."},"text":{"type":"string","description":"Text zápisu; delší než 250 znaků se zkrátí."},"opening":{"type":"boolean","description":"true = počáteční stav (zdroj opening), jinak ruční zápis (manual)."}}}}},"example":{"entry":{"date":"2026-08-31","debit_account":"518","credit_account":"389","amount":4200,"text":"Dohadná položka – energie za minulý měsíc"}}}}},"responses":{"201":{"description":"Všechny sloupce vytvořeného zápisu: id, entity_id, date, debit_account, credit_account, amount, text, source_type (manual nebo opening), source_id, document_id, partner_id, currency, amount_currency, cost_center, variable_symbol, created_at, updated_at.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Datum leží v uzamčeném období („Období je uzamčeno“).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"ucetnictvi","x-saldo-access":"writer","x-saldo-side-effects":"Vytvoří jeden účetní zápis a zapíše událost entry.created do historie změn.","x-saldo-repeat":"Každé volání vytvoří další zápis; duplicity se nekontrolují.","x-saldo-errors":[{"status":422,"when":"Datum leží v uzamčeném období („Období je uzamčeno“)."}]}},"/entities/{entity_id}/entries/{id}":{"delete":{"operationId":"deleteEntry","tags":["Účetní knihy a výkazy"],"summary":"Smazání ručního zápisu","description":"Smaže ruční zápis nebo počáteční stav, který nevznikl z jiného záznamu (source_type manual nebo opening bez source_id, tedy i počáteční stavy z importu předvahy). Zápisy z dokladů, úhrad, banky, odpisů, mezd, uzávěrky, kurzových rozdílů a počáteční stavy bankovních účtů tudy smazat nelze – vrátí 404. Zápis v uzamčeném období je odmítnut.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"Účetní jednotka (firma).","schema":{"type":"integer"},"example":12},{"name":"id","in":"path","required":true,"description":"Ruční zápis nebo počáteční stav bez zdroje.","schema":{"type":"integer"},"example":5120}],"responses":{"204":{"description":"Bez obsahu."},"422":{"description":"Datum zápisu leží v uzamčeném období („Období je uzamčeno“).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"ucetnictvi","x-saldo-access":"writer","x-saldo-side-effects":"Smaže zápis a zapíše událost entry.deleted do historie změn.","x-saldo-repeat":"Druhé volání vrátí 404.","x-saldo-errors":[{"status":422,"when":"Datum zápisu leží v uzamčeném období („Období je uzamčeno“)."}]}},"/entities/{entity_id}/reports/{report}":{"get":{"operationId":"getReport","tags":["Účetní knihy a výkazy"],"summary":"Účetní sestava","description":"Vrátí jednu sestavu podle hodnoty report. Každá sestava má vlastní parametry a strukturu odpovědi (viz variants). Sestavy jen čtou data a nic nezaúčtují.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"Účetní jednotka (firma).","schema":{"type":"integer"},"example":12},{"name":"report","in":"path","required":true,"description":"Sestava.","schema":{"type":"string","enum":["dashboard","trial_balance","account","saldokonto","statements","cash_book","money","compliance","forecast","projects","insights"]},"example":"trial_balance"}],"responses":{"200":{"description":"Obsah sestavy podle varianty.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"description":"Neznámá hodnota report („Neznámá sestava“).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"ucetnictvi","x-saldo-access":"member","x-saldo-side-effects":"Nic nezapisuje. Sestavy s účty nebo doklady v cizí měně (money, dashboard, forecast, insights) mohou načíst kurz ČNB.","x-saldo-errors":[{"status":404,"when":"Neznámá hodnota report („Neznámá sestava“)."}],"x-saldo-variants":[{"param":"report","value":"dashboard","summary":"Přehled firmy za účetní období","description":"Tržby, náklady a zisk po 12 měsících účetního období (v podvojném účetnictví ze zápisů na účtech tříd 6 a 5 bez 59x, v daňové evidenci z peněžního deníku), peníze na účtech, otevřené pohledávky a závazky, odhad DPH za běžné období, počty, upozornění, 5 největších odběratelů a dodavatelů a 8 posledních dokladů.","parameters":[{"name":"year","in":"query","required":false,"description":"Účetní období začínající v tomto roce; výchozí je aktuální rok.","schema":{"type":"integer","minimum":2000,"maximum":2100},"example":2026}],"response-fields":[{"name":"months","description":"12 měsíců – month, label (MM/YYYY), revenue, costs, profit; totals je jejich součet."},{"name":"money","description":"Zůstatky účtů a pokladen k dnešku (jako sestava money)."},{"name":"receivables","description":"Otevřené vydané faktury a dobropisy v Kč – total, count, overdue, overdue_count, due_soon a due_soon_count (do 7 dní); payables totéž pro přijaté."},{"name":"vat","description":"U plátce DPH odhad za běžné období – from, to, frequency, output, input, due, deadline; u neplátce null."},{"name":"counts","description":"drafts (koncepty), unmatched (nespárované pohyby), partners, documents (doklady období)."},{"name":"alerts","description":"Upozornění – level, key, title, detail, amount, action; obsahuje i nejvýše 6 kontrol ze sestavy compliance."},{"name":"top_customers","description":"5 odběratelů s nejvyšším základem v Kč za období – partner_id, name, amount; top_suppliers totéž pro dodavatele."},{"name":"recent","description":"8 posledních dokladů všech druhů podle data vystavení, včetně konceptů (souhrn dokladu jako v seznamu dokladů)."}]},{"param":"report","value":"trial_balance","summary":"Obratová předvaha","description":"Po účtech tak, jak jsou v zápisech (analytické účty zvlášť): počáteční stav k začátku období, obraty MD a Dal a konečný stav. Počáteční stav rozvahových účtů zahrnuje převedený výsledek minulých let (428 nebo 429), výsledkové účty začínají od začátku účetního období. Účty bez stavu i obratů se vynechají.","parameters":[{"name":"year","in":"query","required":false,"description":"Účetní období začínající v tomto roce; výchozí je aktuální rok.","schema":{"type":"integer","minimum":2000,"maximum":2100},"example":2026},{"name":"from","in":"query","required":false,"description":"Začátek období; výchozí je začátek účetního období year.","schema":{"type":"string","format":"date"},"example":"2026-01-01"},{"name":"to","in":"query","required":false,"description":"Konec období včetně; výchozí je konec účetního období year.","schema":{"type":"string","format":"date"},"example":"2026-09-30"}],"response-fields":[{"name":"rows","description":"code, name, kind, opening, debit, credit, closing."},{"name":"totals","description":"debit, credit, balanced (MD = Dal), opening, closing."},{"name":"range","description":"Použité období {from, to}."}]},{"param":"report","value":"account","summary":"Hlavní kniha účtu","description":"Zápisy jednoho účtu za období chronologicky s průběžným zůstatkem. Kód se bere jako začátek, takže 311 zahrne i analytické účty 311xxx; počáteční stav se počítá stejně jako v předvaze.","parameters":[{"name":"code","in":"query","required":true,"description":"Kód účtu nebo jeho začátek (převede se na velká písmena); bez něj vrátí 400.","schema":{"type":"string"},"example":"311"},{"name":"year","in":"query","required":false,"description":"Účetní období začínající v tomto roce; výchozí je aktuální rok.","schema":{"type":"integer","minimum":2000,"maximum":2100},"example":2026},{"name":"from","in":"query","required":false,"description":"Začátek období; výchozí je začátek účetního období year.","schema":{"type":"string","format":"date"},"example":"2026-01-01"},{"name":"to","in":"query","required":false,"description":"Konec období včetně; výchozí je konec účetního období year.","schema":{"type":"string","format":"date"},"example":"2026-09-30"}],"response-fields":[{"name":"code","description":"Kód z dotazu; name je název účtu s přesně tímto kódem, jinak null."},{"name":"opening","description":"Počáteční stav k začátku období."},{"name":"lines","description":"Zápisy jako v deníku doplněné o debit, credit a balance (průběžný zůstatek)."},{"name":"debit","description":"Obrat MD; credit obrat Dal; closing konečný stav."},{"name":"range","description":"Použité období {from, to}."}]},{"param":"report","value":"saldokonto","summary":"Saldokonto pohledávek nebo závazků","description":"Otevřené vystavené faktury a dobropisy k datu as_of podle úhrad do tohoto dne, po kontaktech a s rozdělením podle dnů po splatnosti. V podvojném účetnictví je zůstatek v Kč u dokladu podle zápisů na 311 nebo 321 (i s kurzovými rozdíly) a reconciliation porovná součet dokladů se stavem účtu.","parameters":[{"name":"side","in":"query","required":false,"description":"receivables = vydané faktury a dobropisy, payables = přijaté; jiná hodnota znamená receivables.","schema":{"type":"string","enum":["receivables","payables"],"default":"receivables"},"example":"payables"},{"name":"as_of","in":"query","required":false,"description":"Datum, ke kterému se saldokonto počítá; výchozí je dnešek.","schema":{"type":"string","format":"date"},"example":"2026-09-30"}],"response-fields":[{"name":"partners","description":"Kontakty seřazené podle dlužné částky – partner_id, name, ico, total_czk, overdue_czk a items (document_id, number, kind, issue_date, due_date, currency, total, remaining, remaining_czk, days_overdue, bucket)."},{"name":"buckets","description":"Součty podle stáří – not_due, d30, d60, d90, d90plus (key, label, total_czk)."},{"name":"total_czk","description":"Součet otevřených položek v Kč."},{"name":"reconciliation","description":"Jen v podvojném účetnictví – account (311 nebo 321), ledger_total_czk, open_items_total_czk, difference_czk, reconciled."}]},{"param":"report","value":"statements","summary":"Rozvaha a výkaz zisku a ztráty","description":"Rozvaha a výkaz zisku a ztráty v druhovém členění za účetní období year s údaji minulého období, v rozsahu podle kategorie účetní jednotky z nastavení (mikro a malá zkrácený, střední a velká plný; výchozí mikro). Počítá se ze zápisů s převodem výsledku; určeno pro podvojné účetnictví, způsob vedení kód nekontroluje.","parameters":[{"name":"year","in":"query","required":false,"description":"Účetní období začínající v tomto roce; výchozí je aktuální rok.","schema":{"type":"integer","minimum":2000,"maximum":2100},"example":2026}],"response-fields":[{"name":"rozvaha","description":"scope, full, aktiva, pasiva, aktiva_total, pasiva_total, cizi_zdroje, balanced, difference."},{"name":"vzz","description":"Výkaz zisku a ztráty – layout, lines a result (provozni, financni, pred_dani, dan, po_dani, za_obdobi, cisty_obrat)."},{"name":"cashflow","description":"Přehled o peněžních tocích odvozený z výkazů; equity přehled o změnách vlastního kapitálu."},{"name":"result","description":"vh_za_obdobi, vh_za_obdobi_prev, vh_pred_zdanenim."},{"name":"checks","description":"Kontroly výkazů; unmapped jsou účty se zůstatkem bez přiřazeného řádku."},{"name":"row_map","description":"Přiřazení účtů k řádkům; line_options jsou platné hodnoty statement_line pro účty."},{"name":"period","description":"Období {from, to}; category je kategorie účetní jednotky, opening_difference nevyrovnaný zůstatek účtu 701."},{"name":"accounts","description":"Konečné zůstatky účtů – code, closing, previous."}]},{"param":"report","value":"cash_book","summary":"Peněžní deník","description":"Příjmy a výdaje podle dne úhrady: úhrady faktur rozdělené podle položek a kategorií, pokladní doklady podle data vystavení a přímo zaúčtované bankovní pohyby; u plátce DPH se odděluje DPH. Určeno pro daňovou evidenci, způsob vedení kód nekontroluje.","parameters":[{"name":"year","in":"query","required":false,"description":"Účetní období začínající v tomto roce; výchozí je aktuální rok.","schema":{"type":"integer","minimum":2000,"maximum":2100},"example":2026},{"name":"from","in":"query","required":false,"description":"Začátek období; výchozí je začátek účetního období year.","schema":{"type":"string","format":"date"},"example":"2026-01-01"},{"name":"to","in":"query","required":false,"description":"Konec období včetně; výchozí je konec účetního období year.","schema":{"type":"string","format":"date"},"example":"2026-09-30"}],"response-fields":[{"name":"rows","description":"date, number, text, partner, category, category_name, kind, tax_relevant, amount (příjem kladně, výdaj záporně), vat, base, source (Úhrada, Pokladna, Banka), document_id."},{"name":"categories","description":"Součty po kategoriích – code, name, kind, tax_relevant, income, expense."},{"name":"totals","description":"income, expense a profit (jen daňové kategorie), cash_in, cash_out, vat_net."},{"name":"range","description":"Použité období {from, to}."}]},{"param":"report","value":"money","summary":"Peníze na účtech a v pokladnách","description":"Zůstatky aktivních bankovních účtů a pokladen k datu on. V podvojném účetnictví se zůstatek účtu v Kč bere ze zápisů na jeho účtu 21x/22x; v daňové evidenci a u účtů v cizí měně z počátečního stavu, pohybů, ručních úhrad a pokladních dokladů. balance_czk účtu v cizí měně je v podvojném účetnictví účetní hodnota, v daňové evidenci přepočet kurzem ČNB k datu (bez kurzu null).","parameters":[{"name":"on","in":"query","required":false,"description":"Datum zůstatků; výchozí je dnešek.","schema":{"type":"string","format":"date"},"example":"2026-09-30"}],"response-fields":[{"name":"accounts","description":"id, name, kind (bank nebo cash), currency, number, iban, account_code, balance (v měně účtu), balance_czk."},{"name":"total_czk","description":"Součet balance_czk."}]},{"param":"report","value":"compliance","summary":"Kontroly lhůt a limitů","description":"Kontroly k dnešku: oprava odpočtu DPH u faktur 6 měsíců po splatnosti (§ 74b ZDPH), daňové doklady vystavené po lhůtě, čísla dodavatelů delší než 60 znaků pro kontrolní hlášení, hotovostní platby nad 270 000 Kč, nespolehliví plátci a kontakty v insolvenci podle uloženého stavu kontaktů (bez dotazu do registrů), registrace k DPH u neplátce a vratka záloh OSVČ v roce 2026. Kontroly DPH běží jen u plátce.","response-fields":[{"name":"checks","description":"level (critical, warning, info), key (vat_74b, issue_15, kh_number, cash_limit, unreliable, insolvency, vat_registration, sp_refund_2026), title, detail, document_id, number."}]},{"param":"report","value":"forecast","summary":"Výhled peněz na dny dopředu","description":"Dnešní zůstatek všech účtů a pokladen plus očekávané příjmy a výdaje: neuhrazené vystavené faktury, zálohové faktury a dobropisy k datu splatnosti (po splatnosti odhadem za 7 dní u pohledávek a za 3 dny u závazků), aktivní opakované faktury, DPH, mzdy a zálohy OSVČ. Vrací denní průběh, týdenní součty a nejnižší bod.","parameters":[{"name":"days","in":"query","required":false,"description":"Horizont ve dnech; mimo rozsah se ořízne.","schema":{"type":"integer","default":90,"minimum":14,"maximum":180},"example":30}],"response-fields":[{"name":"opening","description":"Dnešní zůstatek v Kč; closing zůstatek na konci horizontu (until)."},{"name":"inflow","description":"Součet očekávaných příjmů; outflow výdajů (záporně)."},{"name":"low","description":"Den s nejnižším zůstatkem {date, change, balance}."},{"name":"series","description":"Každý den horizontu včetně dneška – date, change, balance."},{"name":"weeks","description":"Po týdnech – week (pondělí), inflow, outflow."},{"name":"items","description":"Nejvýše 60 položek – date, amount, kind (receivable, payable, recurring, vat, payroll, zp, sp), estimated, label, u faktur document_id a overdue; count je jejich celkový počet."}]},{"param":"report","value":"projects","summary":"Zakázky a střediska","description":"Výnosy, náklady a marže po zakázkách nebo střediscích z vystavených dokladů účetního období podle DUZP (jinak data vystavení). U neplátce DPH a u neodpočitatelné DPH se DPH počítá do nákladů. Doklady bez zakázky nebo střediska tvoří vlastní řádek. S only=values vrátí jen seznam použitých hodnot.","parameters":[{"name":"year","in":"query","required":false,"description":"Účetní období začínající v tomto roce; výchozí je aktuální rok.","schema":{"type":"integer","minimum":2000,"maximum":2100},"example":2026},{"name":"dimension","in":"query","required":false,"description":"project = zakázka, cost_center = středisko; jiná hodnota znamená project.","schema":{"type":"string","enum":["project","cost_center"],"default":"project"},"example":"cost_center"},{"name":"only","in":"query","required":false,"description":"values = vrátit jen {values}.","schema":{"type":"string","enum":["values"]},"example":"values"}],"response-fields":[{"name":"rows","description":"key, label, revenue, costs, margin, margin_share (%), documents_count, months (12 měsíčních výsledků) a documents (nejvýše 200 nejnovějších – id, number, kind, partner, date, amount)."},{"name":"totals","description":"revenue, costs, margin, margin_share."},{"name":"values","description":"Použité hodnoty {project: [], cost_center: []}, každé nejvýše 500."}]},{"param":"report","value":"insights","summary":"Přehled pro majitele","description":"Kolik peněz je opravdu k dispozici po odečtení DPH, rezervy na daň z příjmů a závazků splatných do 14 dnů (available); u OSVČ kolik si měsíčně odkládat na daň a pojistné (set_aside); průměrné měsíční spalování a na jak dlouho peníze vystačí podle posledních 6 ukončených měsíců (runway); srovnání tržeb, nákladů, marže a doby úhrady faktur s loňskem (health).","parameters":[{"name":"year","in":"query","required":false,"description":"Účetní období pro health; výchozí je aktuální rok.","schema":{"type":"integer","minimum":2000,"maximum":2100},"example":2026}],"response-fields":[{"name":"available","description":"total, total_with_receivables, horizon, money, vat, reserve, payables, receivables."},{"name":"set_aside","description":"Jen u fyzické osoby, jinak null."},{"name":"runway","description":"months_used, from, to, burn, money, months, until, series."},{"name":"health","description":"Srovnání s loňskem včetně dso a dpo; null, pokud účetní období ještě nezačalo."},{"name":"segment","description":"Segment z profilu firmy (osvc, startup, small, growing, accountant); natural_person je boolean."}]}]}},"/entities/{entity_id}/closing":{"get":{"operationId":"getYearEndClose","tags":["Účetní knihy a výkazy"],"summary":"Kontrolní seznam roční uzávěrky","description":"Vrátí kroky roční uzávěrky účetního období se stavem každého kroku (banka, koncepty, pohledávky po splatnosti, odpisy, kurzové rozdíly, mzdy, DPH, daň z příjmů, výkazy, uzamčení), náhled kurzových rozdílů k rozvahovému dni a vypočtenou a zaúčtovanou daň z příjmů právnické osoby. Kroky, které se firmy netýkají, se vynechají: odpisy, kurzové rozdíly a výkazy v daňové evidenci, odpisy také bez odpisovaného majetku, banka bez bankovního účtu, mzdy bez pracovníků, DPH bez registrace k DPH a daň z příjmů mimo právnické osoby v podvojném účetnictví.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"Účetní jednotka (firma).","schema":{"type":"integer"},"example":12},{"name":"year","in":"query","required":false,"description":"Účetní období začínající v tomto roce; výchozí je aktuální rok.","schema":{"type":"integer","minimum":2000,"maximum":2100},"example":2025}],"responses":{"200":{"description":"Stav roční uzávěrky.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"U právnické osoby v podvojném účetnictví pro rok, pro který Saldo nemá zákonné sazby daně z příjmů – výpočet daně selže („Pro rok RRRR nejsou k dispozici zákonné sazby“) a kontrolní seznam se nevrátí.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"ucetnictvi","x-saldo-access":"member","x-saldo-side-effects":"Nic nezapisuje. Po rozvahovém dni načítá kurzy ČNB k náhledu kurzových rozdílů.","x-saldo-errors":[{"status":422,"when":"U právnické osoby v podvojném účetnictví pro rok, pro který Saldo nemá zákonné sazby daně z příjmů – výpočet daně selže („Pro rok RRRR nejsou k dispozici zákonné sazby“) a kontrolní seznam se nevrátí."}],"x-saldo-response-fields":[{"name":"date","description":"Rozvahový den (poslední den účetního období); finished říká, zda už minul, locked, zda je uzamčený."},{"name":"double_entry","description":"Zda firma vede podvojné účetnictví."},{"name":"steps","description":"Kroky – key (bank, drafts, receivables, depreciation, revaluation, payroll, vat, income_tax, statements, lock), title, state (done, todo, warning, info, waiting), detail, action (lock, depreciation, revaluation, income_tax nebo null) a link do aplikace."},{"name":"revaluation","description":"Náhled kurzových rozdílů (jako odpověď postFxRevaluation); do rozvahového dne včetně {future: true, rows: [], posted: false}; v daňové evidenci null."},{"name":"income_tax","description":"computed (daň podle výpočtu, celé Kč), posted (zaúčtováno 591), entry_date, up_to_date; null mimo právnické osoby v podvojném účetnictví."}]}},"/entities/{entity_id}/closing/month":{"get":{"operationId":"getMonthClose","tags":["Účetní knihy a výkazy"],"summary":"Kontrolní seznam měsíční uzávěrky","description":"Vrátí kroky měsíční uzávěrky zvoleného měsíce: banka za celý měsíc (nespárované pohyby a pokrytí výpisy), koncepty, skeny přijatých dokladů, záporná pokladna, přiznání k DPH a kontrolní hlášení (u plátce), mzdy a uzamčení. Kroky, které se firmy netýkají, se vynechají.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"Účetní jednotka (firma).","schema":{"type":"integer"},"example":12},{"name":"year","in":"query","required":false,"description":"Kalendářní rok; výchozí je aktuální rok.","schema":{"type":"integer","minimum":2000,"maximum":2100},"example":2026},{"name":"month","in":"query","required":true,"description":"Měsíc 1–12.","schema":{"type":"integer","minimum":1,"maximum":12},"example":8}],"responses":{"200":{"description":"Stav měsíční uzávěrky.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"month chybí nebo není 1–12 („Zvolte měsíc 1–12“).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"ucetnictvi","x-saldo-access":"member","x-saldo-side-effects":"Nic nezapisuje.","x-saldo-errors":[{"status":400,"when":"month chybí nebo není 1–12 („Zvolte měsíc 1–12“)."}],"x-saldo-response-fields":[{"name":"from","description":"První den měsíce; date poslední den, finished zda měsíc skončil, locked zda je uzamčený."},{"name":"steps","description":"Kroky – key (bank, drafts, attachments, cash, vat, kh, payroll, lock), title, state (done, todo, warning, info, waiting), detail, action (lock nebo null), link."}]}},"/entities/{entity_id}/closing/revaluation":{"post":{"operationId":"postFxRevaluation","tags":["Účetní knihy a výkazy"],"summary":"Zaúčtování kurzových rozdílů k rozvahovému dni","description":"Přecení otevřené vydané a přijaté faktury a dobropisy v cizí měně (podle zůstatku na 311/321) a bankovní účty a pokladny v cizí měně kurzem ČNB k rozvahovému dni a rozdíly zaúčtuje na 563/663. U faktur se k prvnímu dni dalšího období zaúčtuje storno (pokud není uzamčeno), u účtů a pokladen ne. Účet v cizí měně s nespárovanými pohyby do rozvahového dne se nepřecení. Dřívější přecenění téhož roku se nejdřív smaže, výsledek tedy nahrazuje předchozí.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"Účetní jednotka (firma).","schema":{"type":"integer"},"example":12},{"name":"year","in":"query","required":false,"description":"Účetní období začínající v tomto roce; výchozí je aktuální rok.","schema":{"type":"integer","minimum":2000,"maximum":2100},"example":2025}],"responses":{"200":{"description":"Náhled přecenění po zaúčtování.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Firma nevede podvojné účetnictví („Kurzové rozdíly k rozvahovému dni se účtují jen v podvojném účetnictví“). Rozvahový den je v uzamčeném období („Období k … je uzamčeno – kurzové rozdíly už nelze měnit“). Rozvahový den ještě nenastal („Kurzové rozdíly se účtují až po rozvahovém dni …“). Pro některou měnu chybí kurz ČNB („Chybí kurz ČNB k … pro …“).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"ucetnictvi","x-saldo-access":"writer","x-saldo-side-effects":"Smaže dřívější zápisy přecenění k rozvahovému dni a ke dni storna, vytvoří nové zápisy 563/663 (zdroj revaluation) a u faktur jejich storna, zapíše událost closing.revaluation do historie změn. Načítá kurzy ČNB.","x-saldo-repeat":"Opakování vede ke stejnému zaúčtování (staré zápisy se nahradí), pokaždé ale přibude událost v historii.","x-saldo-errors":[{"status":422,"when":"Firma nevede podvojné účetnictví („Kurzové rozdíly k rozvahovému dni se účtují jen v podvojném účetnictví“)."},{"status":422,"when":"Rozvahový den je v uzamčeném období („Období k … je uzamčeno – kurzové rozdíly už nelze měnit“)."},{"status":422,"when":"Rozvahový den ještě nenastal („Kurzové rozdíly se účtují až po rozvahovém dni …“)."},{"status":422,"when":"Pro některou měnu chybí kurz ČNB („Chybí kurz ČNB k … pro …“)."}],"x-saldo-response-fields":[{"name":"date","description":"Rozvahový den; reversal_date den storna u faktur."},{"name":"rows","description":"Položky – type (document nebo money), id, label, account, currency, open_amount, book_value, book_rate, rate, new_value, difference, effect, reverse, number, kind, blocked (důvod, proč se nepřecenila)."},{"name":"gain","description":"Kurzové zisky; loss ztráty; net výsledek přecenění."},{"name":"missing_rates","description":"Měny bez kurzu ČNB (při zaúčtování vedou k chybě)."},{"name":"blocked","description":"Počet účtů čekajících na spárování pohybů."},{"name":"posted","description":"Zda k rozvahovému dni existuje aspoň jeden zápis přecenění – bez nenulového rozdílu zůstane false i po zaúčtování; posted_on je čas vytvoření posledního zápisu."}],"x-saldo-example":{"note":"Ukázková firma nemá ke konci roku 2025 položky v cizí měně, výsledek proto nemá řádky, nic se nezaúčtuje a posted zůstane false."}},"delete":{"operationId":"deleteFxRevaluation","tags":["Účetní knihy a výkazy"],"summary":"Zrušení kurzových rozdílů k rozvahovému dni","description":"Smaže zápisy přecenění k rozvahovému dni a jejich storna ke dni následujícímu. Platí stejné podmínky jako pro zaúčtování, včetně toho, že rozvahový den už musí minout.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"Účetní jednotka (firma).","schema":{"type":"integer"},"example":12},{"name":"year","in":"query","required":false,"description":"Účetní období začínající v tomto roce; výchozí je aktuální rok.","schema":{"type":"integer","minimum":2000,"maximum":2100},"example":2025}],"responses":{"200":{"description":"Náhled přecenění po zrušení (stejný tvar jako u postFxRevaluation, posted false).","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Firma nevede podvojné účetnictví („Kurzové rozdíly k rozvahovému dni se účtují jen v podvojném účetnictví“). Rozvahový den je v uzamčeném období („Období k … je uzamčeno – kurzové rozdíly už nelze měnit“). Rozvahový den ještě nenastal („Kurzové rozdíly se účtují až po rozvahovém dni …“).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"ucetnictvi","x-saldo-access":"writer","x-saldo-side-effects":"Smaže zápisy zdroje revaluation k rozvahovému dni a ke dni storna a zapíše událost closing.revaluation_removed do historie změn. Načítá kurzy ČNB pro náhled.","x-saldo-repeat":"Opakování nic dalšího nesmaže, ale pokaždé zapíše událost do historie.","x-saldo-errors":[{"status":422,"when":"Firma nevede podvojné účetnictví („Kurzové rozdíly k rozvahovému dni se účtují jen v podvojném účetnictví“)."},{"status":422,"when":"Rozvahový den je v uzamčeném období („Období k … je uzamčeno – kurzové rozdíly už nelze měnit“)."},{"status":422,"when":"Rozvahový den ještě nenastal („Kurzové rozdíly se účtují až po rozvahovém dni …“)."}]}},"/entities/{entity_id}/closing/income_tax":{"post":{"operationId":"postIncomeTax","tags":["Účetní knihy a výkazy"],"summary":"Zaúčtování daně z příjmů právnické osoby","description":"Spočítá daň z příjmů právnických osob za účetní období (zaokrouhlenou na celé Kč) a zaúčtuje ji jedním zápisem 591/341 k rozvahovému dni; dřívější zápis daně téhož období se nejdřív smaže. Nulová daň se nezaúčtuje. Kód nekontroluje, zda období už skončilo, takže daň lze zaúčtovat i za běžící rok podle dosavadních údajů.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"Účetní jednotka (firma).","schema":{"type":"integer"},"example":12},{"name":"year","in":"query","required":false,"description":"Účetní období začínající v tomto roce; výchozí je aktuální rok.","schema":{"type":"integer","minimum":2000,"maximum":2100},"example":2025}],"responses":{"200":{"description":"Stav daně po zaúčtování.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Firma není právnická osoba v podvojném účetnictví („Daň z příjmů se takto účtuje jen u právnických osob v podvojném účetnictví“). Rozvahový den je v uzamčeném období („Rok … je uzamčený – zaúčtování daně už nelze měnit“). Pro rok nejsou v Saldu zákonné sazby daně z příjmů („Pro rok RRRR nejsou k dispozici zákonné sazby“).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"ucetnictvi","x-saldo-access":"writer","x-saldo-side-effects":"Smaže dřívější zápisy daně (zdroj closing, MD 591) v období, vytvoří nový zápis 591/341 a zapíše událost closing.income_tax do historie změn.","x-saldo-repeat":"Opakování nahradí zápis aktuálně vypočtenou daní; pokaždé přibude událost v historii.","x-saldo-errors":[{"status":422,"when":"Firma není právnická osoba v podvojném účetnictví („Daň z příjmů se takto účtuje jen u právnických osob v podvojném účetnictví“)."},{"status":422,"when":"Rozvahový den je v uzamčeném období („Rok … je uzamčený – zaúčtování daně už nelze měnit“)."},{"status":422,"when":"Pro rok nejsou v Saldu zákonné sazby daně z příjmů („Pro rok RRRR nejsou k dispozici zákonné sazby“)."}],"x-saldo-response-fields":[{"name":"computed","description":"Daň podle aktuálního výpočtu v celých Kč."},{"name":"posted","description":"Součet zaúčtované daně (591) v období."},{"name":"entry_date","description":"Datum zápisu (rozvahový den)."},{"name":"up_to_date","description":"Zda zaúčtovaná daň odpovídá výpočtu."}]},"delete":{"operationId":"deleteIncomeTax","tags":["Účetní knihy a výkazy"],"summary":"Zrušení zaúčtované daně z příjmů","description":"Smaže zápisy daně z příjmů (591) daného účetního období. Platí stejné podmínky jako pro zaúčtování.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"Účetní jednotka (firma).","schema":{"type":"integer"},"example":12},{"name":"year","in":"query","required":false,"description":"Účetní období začínající v tomto roce; výchozí je aktuální rok.","schema":{"type":"integer","minimum":2000,"maximum":2100},"example":2025}],"responses":{"200":{"description":"Stav daně po zrušení (computed, posted 0, entry_date, up_to_date).","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Firma není právnická osoba v podvojném účetnictví („Daň z příjmů se takto účtuje jen u právnických osob v podvojném účetnictví“). Rozvahový den je v uzamčeném období („Rok … je uzamčený – zaúčtování daně už nelze měnit“). Pro rok nejsou v Saldu zákonné sazby daně z příjmů („Pro rok RRRR nejsou k dispozici zákonné sazby“) – podmínky se ověřují výpočtem daně, takže ani zrušení neproběhne.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"ucetnictvi","x-saldo-access":"writer","x-saldo-side-effects":"Smaže zápisy daně období a zapíše událost closing.income_tax_removed do historie změn.","x-saldo-repeat":"Opakování nic dalšího nesmaže, ale pokaždé zapíše událost do historie.","x-saldo-errors":[{"status":422,"when":"Firma není právnická osoba v podvojném účetnictví („Daň z příjmů se takto účtuje jen u právnických osob v podvojném účetnictví“)."},{"status":422,"when":"Rozvahový den je v uzamčeném období („Rok … je uzamčený – zaúčtování daně už nelze měnit“)."},{"status":422,"when":"Pro rok nejsou v Saldu zákonné sazby daně z příjmů („Pro rok RRRR nejsou k dispozici zákonné sazby“) – podmínky se ověřují výpočtem daně, takže ani zrušení neproběhne."}]}},"/entities/{entity_id}/taxes/{report}":{"get":{"operationId":"getTaxReport","tags":["Daně, podání a doručenky"],"summary":"Daňový výkaz nebo přehled podle hodnoty report","description":"Sestaví a vrátí jeden daňový výkaz z aktuálních dat účetní jednotky; který, určuje hodnota report (viz varianty). Počítá se při každém volání z vystavených dokladů, účetních zápisů, bankovních pohybů a nastavení firmy. Operace nic neukládá a nic nepodává – XML, kontrolu v EPO a uložení podání obstarávají operace …/xml, …/epo, …/filing a /filings.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky","schema":{"type":"integer"},"example":12},{"name":"report","in":"path","required":true,"description":"Druh výkazu (viz varianty)","schema":{"type":"string","enum":["vat_return","control_statement","recap_statement","income_tax","regime","filings_check","depreciation","payments"]},"example":"vat_return"}],"responses":{"200":{"description":"JSON podle varianty.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"description":"Neznámá hodnota report (error „Neznámý daňový výkaz“)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"dane","x-saldo-access":"member","x-saldo-side-effects":"Nic nezapisuje.","x-saldo-errors":[{"status":404,"when":"Neznámá hodnota report (error „Neznámý daňový výkaz“)"}],"x-saldo-variants":[{"param":"report","value":"vat_return","summary":"Přiznání k DPH za období","description":"Sestaví přiznání k DPH (řádky formuláře DPHDP3) z vystavených dokladů druhů invoice_out, invoice_in, credit_out, credit_in, advance_out, advance_in, cash_in a cash_out, jejichž datum pro DPH spadá do období; koncepty a stornované doklady se nezapočítají. Období určí period; bez něj year a month, u čtvrtletního plátce bez month čtvrtletí quarter. Výchozí je běžící měsíc (čtvrtletí) aktuálního roku, u jiného roku prosinec (4. čtvrtletí). Bez period má identifikovaná osoba vždy měsíční období.","parameters":[{"name":"period","in":"query","required":false,"description":"Období ve tvaru YYYY-MM nebo YYYY-Qn (např. 2026-08, 2026-Q3); má přednost před year, month a quarter. Neplatná hodnota skončí chybou 500.","schema":{"type":"string"},"example":"2026-08"},{"name":"year","in":"query","required":false,"description":"Rok období, když chybí period; výchozí (i při nečíselné hodnotě) aktuální rok","schema":{"type":"integer","minimum":2000,"maximum":2100},"example":2026},{"name":"month","in":"query","required":false,"description":"Měsíc období, když chybí period; mimo 1–12 skončí chybou 500","schema":{"type":"integer","minimum":1,"maximum":12},"example":8},{"name":"quarter","in":"query","required":false,"description":"Čtvrtletí; použije se jen u čtvrtletního plátce, když chybí period i month","schema":{"type":"integer","minimum":1,"maximum":4},"example":3}],"response-fields":[{"name":"period","description":"Období: year, month, quarter, from, to, label, deadline (lhůta pro podání), key"},{"name":"report.period","description":"Období, za které je přiznání sestavené (stejné jako period)"},{"name":"report.form","description":"Označení tiskopisu přiznání, podle kterého jsou řádky sestavené (např. „25 5401 MFin 5401 vzor č. 26“)"},{"name":"report.rows","description":"Částky podle čísel řádků přiznání"},{"name":"report.own_tax","description":"Vlastní daňová povinnost (řádek 64)"},{"name":"report.excess_deduction","description":"Nadměrný odpočet (řádek 65)"},{"name":"report.documents","description":"Číslo řádku → ID dokladů, které do něj přispěly"},{"name":"report.warnings","description":"Upozornění k dokladům, které se nepodařilo zařadit nebo vyžadují kontrolu"}],"errors":[{"status":422,"when":"Účetní jednotka není plátcem ani identifikovanou osobou (vat_status none) – „Účetní jednotka není registrovaná k DPH“"},{"status":500,"when":"Neplatné period, month nebo quarter (výjimka z Vat::Period se neošetřuje)"}]},{"param":"report","value":"control_statement","summary":"Kontrolní hlášení za období","description":"Sestaví kontrolní hlášení (oddíly A.1–A.5 a B.1–B.3) ze stejných dokladů jako přiznání k DPH a přidá kontrolní součty proti řádkům přiznání. Období se volí stejně jako u vat_return. Identifikovaná osoba kontrolní hlášení nepodává (422 IDENTIFIED_KH); právnická osoba ho podává za každý měsíc, čtvrtletní období proto odmítne (422 MONTHLY_KH).","parameters":[{"name":"period","in":"query","required":false,"description":"Období YYYY-MM nebo YYYY-Qn; má přednost před year, month a quarter. Neplatná hodnota skončí chybou 500.","schema":{"type":"string"},"example":"2026-08"},{"name":"year","in":"query","required":false,"description":"Rok období, když chybí period; výchozí aktuální rok","schema":{"type":"integer","minimum":2000,"maximum":2100},"example":2026},{"name":"month","in":"query","required":false,"description":"Měsíc období, když chybí period","schema":{"type":"integer","minimum":1,"maximum":12},"example":8},{"name":"quarter","in":"query","required":false,"description":"Čtvrtletí u čtvrtletního plátce – jen pro fyzickou osobu","schema":{"type":"integer","minimum":1,"maximum":4},"example":3}],"response-fields":[{"name":"period","description":"Období (jako u vat_return)"},{"name":"report.sections","description":"Oddíly a1, a2, a3, a4, b1, b2 jako seznamy dokladů; a5 a b3 jako souhrnné částky s document_ids"},{"name":"report.control","description":"Kontrolní součty: base a return_rows – řádky přiznání, se kterými se porovnávají"},{"name":"report.warnings","description":"Upozornění k dokladům"}],"errors":[{"status":422,"when":"Účetní jednotka není registrovaná k DPH"},{"status":422,"code":"IDENTIFIED_KH","when":"Identifikovaná osoba kontrolní hlášení nepodává (§ 101c ZDPH)"},{"status":422,"code":"MONTHLY_KH","when":"Právnická osoba zvolila čtvrtletí – kontrolní hlášení podává za každý měsíc (§ 101e ZDPH)"},{"status":500,"when":"Neplatné period, month nebo quarter"}]},{"param":"report","value":"recap_statement","summary":"Souhrnné hlášení za období","description":"Sestaví souhrnné hlášení VIES z vystavených prodejních dokladů v režimu dodání zboží, poskytnutí služby nebo třístranného obchodu do jiného státu EU, seskupených podle státu, DIČ odběratele a kódu plnění. Období se volí stejně jako u vat_return.","parameters":[{"name":"period","in":"query","required":false,"description":"Období YYYY-MM nebo YYYY-Qn; má přednost před year, month a quarter. Neplatná hodnota skončí chybou 500.","schema":{"type":"string"},"example":"2026-08"},{"name":"year","in":"query","required":false,"description":"Rok období, když chybí period; výchozí aktuální rok","schema":{"type":"integer","minimum":2000,"maximum":2100},"example":2026},{"name":"month","in":"query","required":false,"description":"Měsíc období, když chybí period","schema":{"type":"integer","minimum":1,"maximum":12},"example":8},{"name":"quarter","in":"query","required":false,"description":"Čtvrtletí u čtvrtletního plátce","schema":{"type":"integer","minimum":1,"maximum":4},"example":3}],"response-fields":[{"name":"report.rows","description":"Řádky: country, vat_id, code (kód plnění), count, value (Kč), document_ids"},{"name":"report.total_value","description":"Součet hodnot všech řádků"},{"name":"report.warnings","description":"Upozornění, např. čtvrtletní období u dodání zboží"}],"errors":[{"status":422,"when":"Účetní jednotka není registrovaná k DPH"},{"status":500,"when":"Neplatné period, month nebo quarter"}]},{"param":"report","value":"income_tax","summary":"Výpočet daně z příjmů za rok","description":"Spočítá daň z příjmů za rok year. U OSVČ (kind dpfo) z peněžního deníku nebo účetnictví a daňového profilu: základ daně, slevy, daňové zvýhodnění, sociální a zdravotní pojištění a zálohy na další rok. U právnické osoby (kind dppo) z účetní závěrky za účetní období začínající v roce year: úpravy základu daně včetně rozdílu účetních a daňových odpisů, daň, zálohy a doplatek. Rok bez zákonných sazeb v Saldu (mimo 2024–2026) vrátí 422.","parameters":[{"name":"year","in":"query","required":false,"description":"Zdaňovací období (rok); výchozí aktuální rok","schema":{"type":"integer","minimum":2000,"maximum":2100},"example":2026}],"response-fields":[{"name":"kind","description":"dpfo (OSVČ) nebo dppo (právnická osoba)"},{"name":"books","description":"Jen dpfo: income, expenses, depreciation a source (peněžní deník nebo účetnictví)"},{"name":"result","description":"Výpočet: mimo jiné tax, form_rows (řádky přiznání) a warnings; u dpfo také sp, zp, tax_advances a tax_balance, u dppo advances a balance"},{"name":"profile","description":"Daňový profil firmy, ze kterého výpočet vychází"},{"name":"statements_result","description":"Jen dppo: výsledek hospodaření z výkazu zisku a ztráty"},{"name":"non_deductible","description":"Jen dppo: daňově neuznatelné náklady podle účtů"},{"name":"statements","description":"Jen dppo: účetní závěrka (rozvaha a výkaz zisku a ztráty)"}],"errors":[{"status":422,"when":"Pro rok nejsou v Saldu zákonné sazby („Pro rok … nejsou k dispozici zákonné sazby“)"}]},{"param":"report","value":"regime","summary":"Srovnání daňových režimů OSVČ za rok","description":"Porovná za rok year odvody OSVČ (daň, sociální a zdravotní pojištění) při skutečných výdajích, výdajových paušálech a paušální dani a doporučí nejvýhodnější variantu, na kterou má nárok. Vychází z příjmů a výdajů v knihách a z daňového profilu. U právnické osoby se volání neodmítne, výsledek má ale smysl jen u OSVČ.","parameters":[{"name":"year","in":"query","required":false,"description":"Rok srovnání; výchozí aktuální rok","schema":{"type":"integer","minimum":2000,"maximum":2100},"example":2026}],"response-fields":[{"name":"year","description":"Rok srovnání"},{"name":"income","description":"Příjmy za rok"},{"name":"actual_expenses","description":"Skutečné výdaje včetně daňových odpisů"},{"name":"income_kind","description":"Druh příjmů pro výdajový paušál (např. trade)"},{"name":"current","description":"Klíč současného režimu: actual_expenses, flat_rate_80, flat_rate_60, flat_rate_40, flat_rate_30 (výdajový paušál v procentech), flat_rate_mixed nebo flat_tax"},{"name":"recommended","description":"Klíč doporučeného režimu (stejné hodnoty jako current)"},{"name":"savings","description":"Úspora doporučeného režimu proti současnému"},{"name":"options","description":"Všechny varianty s odvody, eligible a savings_vs_current"},{"name":"summary","description":"Slovní shrnutí"},{"name":"warnings","description":"Upozornění"},{"name":"books","description":"Příjmy a výdaje z knih, ze kterých srovnání vychází"}],"errors":[{"status":422,"when":"Pro rok nejsou v Saldu zákonné sazby"}]},{"param":"report","value":"filings_check","summary":"Připravenost ročních podání za rok","description":"Zkusí za rok year sestavit přiznání k dani z příjmů (DPFDP7 u OSVČ, DPPDP9 u právnické osoby) a u OSVČ i přehled pro ČSSZ (OSVC25) a pro zdravotní pojišťovnu (formát v6). U každého formuláře vrátí, co chybí a kde to doplnit, upozornění, souhrn částek, lhůtu podle způsobu podání, adresáta a už uložená podání. Mezi problémy se objeví i omezení Salda: DPFO jen za roky 2024–2025, přehledy jen za rok 2025 a DPPO za celé zdaňovací období 2026 zatím ne. Nic neukládá ani nepodává.","parameters":[{"name":"year","in":"query","required":false,"description":"Rok podání; výchozí aktuální rok","schema":{"type":"integer","minimum":2000,"maximum":2100},"example":2025}],"response-fields":[{"name":"year","description":"Rok"},{"name":"forms","description":"Formuláře: kind (dpfo, dppo, prehled_sp, prehled_zp), title, form, ready, problems, warnings, summary, deadline, recipient, filings"},{"name":"forms[].problems","description":"message a fix – kde údaj doplnit: settings (nastavení firmy), profile (daňový profil), books (účetnictví) nebo null; u přehledů i field"},{"name":"forms[].deadline","description":"date, mode, label a options – lhůty pro jednotlivé způsoby podání, posunuté na pracovní den"},{"name":"forms[].filings","description":"Uložená podání tohoto druhu za rok"},{"name":"options","description":"Jen OSVČ: seznam správ sociálního zabezpečení a zdravotních pojišťoven; jinak prázdný objekt"}],"errors":[{"status":422,"when":"Pro rok nejsou v Saldu zákonné sazby"}],"example":{"note":"Rok 2025 je poslední, za který Saldo sestaví všechny tři formuláře OSVČ."}},{"param":"report","value":"depreciation","summary":"Daňové odpisy za rok","description":"Vrátí součet daňově uznatelných odpisů za rok year z veškerého odpisovaného majetku, který má daňovou odpisovou skupinu.","parameters":[{"name":"year","in":"query","required":false,"description":"Rok; výchozí aktuální rok","schema":{"type":"integer","minimum":2000,"maximum":2100},"example":2026}],"response-fields":[{"name":"year","description":"Rok"},{"name":"amount","description":"Daňové odpisy celkem (Kč)"}]},{"param":"report","value":"payments","summary":"Platby finančnímu úřadu, ČSSZ a zdravotním pojišťovnám","description":"Vrátí platby se splatností v měsících from–to: DPH nebo nadměrný odpočet, zálohy na daň z příjmů, paušální daň, zálohy OSVČ na sociální a zdravotní pojištění, nemocenské pojištění, odvody za zaměstnance, srážkovou a silniční daň. U každé platby účet, IBAN, symboly, termín posunutý na pracovní den, QR Platbu (SPAYD) a stav. Za zaplacenou se platba považuje, když mezi odchozími bankovními pohyby v Kč je pohyb se správnou částkou a shodným účtem nebo variabilním symbolem, s datem od začátku sledovaného období do 60 dnů po splatnosti (u silniční daně bez částky musí sedět účet i symbol). Chybějící údaje vrátí v missing, u OSVČ i s návrhem nalezeným v jejích platbách.","parameters":[{"name":"from","in":"query","required":false,"description":"První měsíc ve tvaru YYYY-MM (nebo datum YYYY-MM-DD; použije se jeho měsíc); výchozí předchozí měsíc","schema":{"type":"string"},"example":"2026-08"},{"name":"to","in":"query","required":false,"description":"Poslední měsíc ve tvaru YYYY-MM (nebo datum YYYY-MM-DD; použije se konec jeho měsíce); výchozí měsíc o dva po aktuálním","schema":{"type":"string"},"example":"2026-11"}],"response-fields":[{"name":"from","description":"První den rozsahu"},{"name":"to","description":"Poslední den rozsahu"},{"name":"today","description":"Dnešní datum, ke kterému je stav plateb spočten"},{"name":"next","description":"Klíč nejbližší nezaplacené platby (přednostně po splatnosti)"},{"name":"summary","description":"Počet a součet plateb podle stavu due, overdue, paid, refund a počet odhadů (estimate)"},{"name":"items","description":"Platby: key, kind, authority (fu, cssz, zp), title, period, due_date, statutory_date, shifted, shift_basis, recipient, account, iban, bic, amount, currency, variable_symbol, constant_symbol, specific_symbol, message, basis, source, status, paid, accepts a reduced (další částky, které se také uznají jako úhrada), ready, explanation, spayd, estimate, estimate_note, missing, notes"},{"name":"items[].status","description":"paid (spárováno s pohybem), due, overdue, nothing (nic k platbě), refund (vratka nadměrného odpočtu)"},{"name":"missing","description":"Chybějící údaje: field, label, fix, where, items a suggestion (value, display, count, last_on) nalezený v bankovních pohybech"},{"name":"notes","description":"Poznámky k výpočtu"},{"name":"options","description":"Číselníky správ sociálního zabezpečení a pojišťoven a zvolené hodnoty"},{"name":"sources","description":"Zdroje čísel účtů a symbolů"}],"errors":[{"status":422,"when":"Konec rozsahu je před začátkem („Konec období musí být po jeho začátku“)"},{"status":422,"when":"Rozsah je delší než 24 měsíců"}],"limits":"Nejvýše 24 měsíců v jednom dotazu."}]}},"/entities/{entity_id}/taxes/{report}/xml":{"get":{"operationId":"getTaxXml","tags":["Daně, podání a doručenky"],"summary":"XML podání pro EPO nebo přehled OSVČ ke stažení","description":"Sestaví a vrátí soubor XML s podáním: přiznání k DPH, kontrolní a souhrnné hlášení a přiznání k dani z příjmů ve formátu EPO (portál Moje daně), přehledy OSVČ ve formátech ČSSZ a zdravotních pojišťoven. Soubor se jen vrátí ke stažení: Saldo ho nikam neposílá a jako podání ho neukládá (k tomu slouží POST /filings a POST …/taxes/{report}/filing). Na rozdíl od GET …/taxes/vat_return operace nekontroluje registraci k DPH; u firmy neregistrované k DPH vznikne u dph, kh a sh podání bez dokladů.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky","schema":{"type":"integer"},"example":12},{"name":"report","in":"path","required":true,"description":"Druh podání (viz varianty)","schema":{"type":"string","enum":["dph","kh","sh","income_tax","prehled_sp","prehled_zp"]},"example":"dph"},{"name":"year","in":"query","required":false,"description":"Rok – u DPH, když chybí period; u daně z příjmů a přehledů zdaňovací období; výchozí aktuální rok","schema":{"type":"integer","minimum":2000,"maximum":2100},"example":2026},{"name":"filing_type","in":"query","required":false,"description":"Druh podání: B řádné, O opravné, D dodatečné, E opravné dodatečné, N následné. Význam se liší podle varianty (viz varianty); neznámá hodnota se bere jako B.","schema":{"type":"string","enum":["B","O","D","E","N"],"default":"B"},"example":"B"},{"name":"date","in":"query","required":false,"description":"Datum podání (vyplnění) uvedené v XML; výchozí dnešní datum","schema":{"type":"string","format":"date"},"example":"2026-09-25"},{"name":"reasons_found_on","in":"query","required":false,"description":"Den zjištění důvodů pro dodatečné či následné podání (u přehledu ČSSZ datum zjištění nové výše vyměřovacího základu u opravného přehledu)","schema":{"type":"string","format":"date"},"example":"2026-09-10"}],"responses":{"200":{"description":"Soubor XML (Content-Disposition attachment). Název: {druh}-{DIČ nebo IČO}-{období}.xml u DPH, KH, SH a daně z příjmů (druh dph, kh, sh, dpfo, dppo), prehled-osvc-{rok}-cssz.xml a prehled-osvc-{rok}-{pojišťovna}.xml u přehledů (u opravného s příponou -opravny).","content":{"application/xml":{"schema":{"type":"string","format":"binary"}}}},"422":{"description":"Nelze sestavit XML (chybí nebo je neplatný údaj firmy či dokladu, chybí den zjištění důvodů u dodatečného podání, rok není podporovaný…); error obsahuje důvod česky Neznámá hodnota report („Neznámý typ podání“)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"dane","x-saldo-access":"member","x-saldo-side-effects":"Po úspěšném sestavení zapíše do historie firmy událost tax.xml („Vytvořeno XML …“), a to i při GET, u člena jen pro čtení a u API klíče jen pro čtení. Nic jiného neukládá a nic nikam neposílá.","x-saldo-errors":[{"status":422,"when":"Nelze sestavit XML (chybí nebo je neplatný údaj firmy či dokladu, chybí den zjištění důvodů u dodatečného podání, rok není podporovaný…); error obsahuje důvod česky"},{"status":422,"when":"Neznámá hodnota report („Neznámý typ podání“)"}],"x-saldo-variants":[{"param":"report","value":"dph","summary":"Přiznání k DPH (DPHDP3) jako XML","description":"XML přiznání k DPH ve formátu EPO DPHDP3 verze 03.01 za období zvolené jako u GET …/taxes/vat_return. filing_type: B řádné, O opravné, D dodatečné, E opravné dodatečné; N se zapíše jako dodatečné. U D, E a N je povinný reasons_found_on.","parameters":[{"name":"period","in":"query","required":false,"description":"Období YYYY-MM nebo YYYY-Qn; má přednost před year, month a quarter. Neplatná hodnota skončí chybou 500.","schema":{"type":"string"},"example":"2026-08"},{"name":"month","in":"query","required":false,"description":"Měsíc, když chybí period","schema":{"type":"integer","minimum":1,"maximum":12},"example":8},{"name":"quarter","in":"query","required":false,"description":"Čtvrtletí čtvrtletního plátce, když chybí period i month","schema":{"type":"integer","minimum":1,"maximum":4},"example":3}],"errors":[{"status":422,"when":"Dodatečné podání bez reasons_found_on („Dodatečné či následné podání vyžaduje den zjištění důvodů pro jeho podání“)"},{"status":422,"when":"Neplatné DIČ, finanční úřad, územní pracoviště nebo kód CZ-NACE firmy"},{"status":500,"when":"Neplatné period, month nebo quarter"}]},{"param":"report","value":"kh","summary":"Kontrolní hlášení (DPHKH1) jako XML","description":"XML kontrolního hlášení ve formátu EPO DPHKH1 verze 03.01. filing_type: B řádné, O opravné, N následné (D se zapíše jako následné), E opravné následné; u D, E a N je povinný reasons_found_on. Identifikované osobě a právnické osobě se čtvrtletním obdobím vrátí 422 – na rozdíl od GET …/taxes/control_statement bez pole code.","parameters":[{"name":"period","in":"query","required":false,"description":"Období YYYY-MM nebo YYYY-Qn; má přednost před year, month a quarter. Neplatná hodnota skončí chybou 500.","schema":{"type":"string"},"example":"2026-08"},{"name":"month","in":"query","required":false,"description":"Měsíc, když chybí period","schema":{"type":"integer","minimum":1,"maximum":12},"example":8},{"name":"quarter","in":"query","required":false,"description":"Čtvrtletí, když chybí period i month (jen fyzická osoba)","schema":{"type":"integer","minimum":1,"maximum":4},"example":3}],"errors":[{"status":422,"when":"Identifikovaná osoba („Identifikovaná osoba kontrolní hlášení nepodává (§ 101c ZDPH).“)"},{"status":422,"when":"Právnická osoba a čtvrtletní období („Právnická osoba podává kontrolní hlášení za kalendářní měsíc (§ 101e odst. 1 ZDPH)“)"},{"status":422,"when":"Dokladu v hlášení chybí DIČ partnera, evidenční číslo nebo kód předmětu plnění"},{"status":500,"when":"Neplatné period, month nebo quarter"}]},{"param":"report","value":"sh","summary":"Souhrnné hlášení (DPHSHV) jako XML","description":"XML souhrnného hlášení ve formátu EPO DPHSHV verze 02.01. filing_type B vytvoří řádné hlášení (R), O, D a N následné (N); E (opravné dodatečné) souhrnné hlášení nezná a vrátí 422. Den zjištění důvodů se nevyžaduje.","parameters":[{"name":"period","in":"query","required":false,"description":"Období YYYY-MM nebo YYYY-Qn; má přednost před year, month a quarter. Neplatná hodnota skončí chybou 500.","schema":{"type":"string"},"example":"2026-08"},{"name":"month","in":"query","required":false,"description":"Měsíc, když chybí period","schema":{"type":"integer","minimum":1,"maximum":12},"example":8},{"name":"quarter","in":"query","required":false,"description":"Čtvrtletí, když chybí period i month","schema":{"type":"integer","minimum":1,"maximum":4},"example":3}],"errors":[{"status":422,"when":"filing_type E („Neznámý druh podání :supplementary_corrective“)"},{"status":422,"when":"Odběratel nemá platné DIČ („Souhrnné hlášení – neplatné DIČ pořizovatele …“)"},{"status":500,"when":"Neplatné period, month nebo quarter"}]},{"param":"report","value":"income_tax","summary":"Přiznání k dani z příjmů (DPFDP7 nebo DPPDP9) jako XML","description":"XML přiznání k dani z příjmů za rok year: u OSVČ DPFDP7 verze 01.01.02 (jen roky 2024–2025), u právnické osoby DPPDP9 verze 05.01.01 s rozvahou a výkazem zisku a ztráty. DPPO vyžaduje vyrovnanou rozvahu; za celé zdaňovací období 2026 ho Saldo zatím odmítne, struktura formuláře pokrývá rok 2026 jen pro jeho části. filing_type: B, O, D, E (N se zapíše jako D); u D, E i N je povinný reasons_found_on a last_known_tax.","parameters":[{"name":"last_known_tax","in":"query","required":false,"description":"Poslední známá daň – povinná u dodatečného přiznání (D, E, N)","schema":{"type":"number"},"example":48210},{"name":"publish","in":"query","required":false,"description":"Jen DPPO – přesně hodnota false vynechá žádost o zveřejnění rozvahy a výkazu zisku a ztráty ve sbírce listin; jiná hodnota (i 0) žádost ponechá","schema":{"type":"boolean","default":true},"example":true},{"name":"accounts_approved","in":"query","required":false,"description":"Jen DPPO – true uvede, že účetní závěrka je schválená","schema":{"type":"boolean","default":false},"example":false},{"name":"accounts_audited","in":"query","required":false,"description":"Jen DPPO s povinným auditem – true uvede, že závěrka je ověřená auditorem","schema":{"type":"boolean","default":false},"example":false}],"errors":[{"status":422,"when":"Rok mimo formulář („… lze sestavit jen za roky 2024–2025“ u DPFO, 2021–2026 u DPPO) nebo bez zákonných sazeb v Saldu"},{"status":422,"when":"DPPO za celé zdaňovací období 2026 („Přiznání za celé zdaňovací období 2026 zatím sestavit nelze …“)"},{"status":422,"when":"Chybějící údaje („Doplňte DIČ v Nastavení → Firma; …“), nevyrovnaná rozvaha nebo neúplné údaje zástupce"},{"status":422,"when":"Dodatečné přiznání (D, E, N) bez last_known_tax nebo bez reasons_found_on"}]},{"param":"report","value":"prehled_sp","summary":"Přehled OSVČ pro ČSSZ (OSVC25) jako XML","description":"XML přehledu o příjmech a výdajích OSVČ pro ČSSZ ve formátu e-Podání OSVC25 (jmenný prostor http://schemas.cssz.cz/OSVC2025). Jen pro OSVČ a jen za rok 2025. filing_type O vytvoří opravný přehled (vyžaduje reasons_found_on a reason), jakákoli jiná hodnota řádný. Před vrácením projde XML kontrolami podle pravidel ČSSZ; nalezené problémy vrátí v poli problems.","parameters":[{"name":"reason","in":"query","required":false,"description":"Důvod opravného přehledu (povinný u filing_type O)","schema":{"type":"string"},"example":"Opravné daňové přiznání"},{"name":"tax_return","in":"query","required":false,"description":"Jak se podává daňové přiznání (ovlivní lhůtu přehledu); výchozí advisor, má-li firma v nastavení daňového poradce, jinak standard; neznámá hodnota se ignoruje","schema":{"type":"string","enum":["standard","electronic","advisor","none","extended"]},"example":"electronic"},{"name":"tax_return_extended_until","in":"query","required":false,"description":"Den, do kterého finanční úřad prodloužil lhůtu – povinný u tax_return extended","schema":{"type":"string","format":"date"},"example":"2026-07-01"}],"errors":[{"status":422,"when":"Firma není OSVČ („Přehledy pro ČSSZ a zdravotní pojišťovnu podává jen OSVČ“)"},{"status":422,"when":"Rok jiný než 2025, chybějící údaje daňového profilu nebo nesplněné kontroly ČSSZ; odpověď { error, problems } s jednotlivými nálezy"}]},{"param":"report","value":"prehled_zp","summary":"Přehled OSVČ pro zdravotní pojišťovnu jako XML","description":"XML přehledu OSVČ pro zdravotní pojišťovnu ve společném formátu pojišťoven (prehledOSVC v6, jmenný prostor http://xmlns.vzp.cz/prehledOSVC/v6). Jen pro OSVČ a jen za rok 2025. filing_type O vytvoří opravný přehled, jiná hodnota řádný. Před vrácením projde XML kontrolami; problémy vrátí v poli problems.","parameters":[{"name":"tax_return","in":"query","required":false,"description":"Jak se podává daňové přiznání; výchozí advisor nebo standard podle nastavení firmy","schema":{"type":"string","enum":["standard","electronic","advisor","none","extended"]},"example":"electronic"},{"name":"tax_return_extended_until","in":"query","required":false,"description":"Den, do kterého finanční úřad prodloužil lhůtu – povinný u tax_return extended","schema":{"type":"string","format":"date"},"example":"2026-07-01"}],"errors":[{"status":422,"when":"Firma není OSVČ"},{"status":422,"when":"Rok jiný než 2025, chybějící údaje daňového profilu nebo nesplněné kontroly; odpověď { error, problems }"}]}]}},"/entities/{entity_id}/taxes/{report}/epo":{"post":{"operationId":"passTaxXmlToEpo","tags":["Daně, podání a doručenky"],"summary":"Kontrola podání v EPO nebo otevření předvyplněného formuláře","description":"Sestaví XML podání stejně jako GET …/taxes/{report}/xml a předá ho rozhraní EPO portálu Moje daně. S check=true ho portál jen zkontroluje v testovacím režimu a vrátí nalezené chyby. Bez check portál vrátí odkaz na formulář předvyplněný tímto XML. Ani jedna možnost nic nepodá: podání odešle až uživatel sám v portálu Moje daně a Saldo o tom nic neví. Stav podání v Saldu se nemění a podání se neukládá. Vstupy lze poslat v těle JSON i v query stringu.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky","schema":{"type":"integer"},"example":12},{"name":"report","in":"path","required":true,"description":"Druh podání; prehled_sp a prehled_zp vrátí 422","schema":{"type":"string","enum":["dph","kh","sh","income_tax"]},"example":"dph"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"check":{"type":"boolean","description":"true = jen kontrola v testovacím režimu EPO; false = odkaz na předvyplněný formulář","default":false},"year":{"type":"integer","description":"Rok (u DPH, když chybí period; u daně z příjmů zdaňovací období); výchozí aktuální rok"},"filing_type":{"type":"string","description":"Druh podání jako u GET …/xml; výchozí B","enum":["B","O","D","E","N"]},"date":{"type":"string","format":"date","description":"Datum podání uvedené v XML; výchozí dnešní datum"},"reasons_found_on":{"type":"string","format":"date","description":"Den zjištění důvodů – povinný u dodatečného či následného podání"}}}}}},"responses":{"200":{"description":"S check=true výsledek kontroly (errors, raw), jinak odkaz na formulář (url, valid_until). Chyby nalezené portálem vrací operace se stavem 200 v poli errors.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"report je prehled_sp nebo prehled_zp („Přehledy OSVČ se podávají ČSSZ a zdravotní pojišťovně, ne přes portál Moje daně“); XML se sestaví dřív, takže chybějící údaje přehledu vrátí 422 s problems Nelze sestavit XML – stejné důvody jako u GET …/taxes/{report}/xml Neznámá hodnota report („Neznámý typ podání“)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"502":{"description":"Portál Moje daně je nedostupný nebo odpověděl chybovým stavem HTTP („Portál Moje daně …“), nebo bez check nevrátil odkaz na formulář (error pak obsahuje první chybu hlášenou portálem)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"dane","x-saldo-access":"writer","x-saldo-side-effects":"Pošle XML metodou POST na https://mojedane.gov.cz/dpr/epo_podani: s check=true s parametrem test=1 (kontrolní hlášení zabalené do ZIP jako podani.xml), bez check s parametrem otevriFormular=1. Saldo tím podání neodesílá: test=1 je kontrola v testovacím režimu, otevriFormular=1 formulář jen předvyplní a odeslat ho musí uživatel v portálu; o odeslání se Saldo nedozví. Po úspěšné odpovědi portálu zapíše do historie událost tax.epo; jinak nezapisuje nic.","x-saldo-limits":"Spojení s portálem má limit 10 s na navázání a 40 s na odpověď.","x-saldo-repeat":"Každé volání znovu kontaktuje portál a zapíše novou událost; nic se nehromadí ani nepodává.","x-saldo-errors":[{"status":422,"when":"report je prehled_sp nebo prehled_zp („Přehledy OSVČ se podávají ČSSZ a zdravotní pojišťovně, ne přes portál Moje daně“); XML se sestaví dřív, takže chybějící údaje přehledu vrátí 422 s problems"},{"status":422,"when":"Nelze sestavit XML – stejné důvody jako u GET …/taxes/{report}/xml"},{"status":422,"when":"Neznámá hodnota report („Neznámý typ podání“)"},{"status":502,"when":"Portál Moje daně je nedostupný nebo odpověděl chybovým stavem HTTP („Portál Moje daně …“), nebo bez check nevrátil odkaz na formulář (error pak obsahuje první chybu hlášenou portálem)"}],"x-saldo-response-fields":[{"name":"errors","description":"Jen s check=true: chyby hlášené portálem ve tvaru „Typ: text“; prázdné pole = bez chyb"},{"name":"raw","description":"Jen s check=true: odpověď portálu, nejvýše 4000 znaků"},{"name":"url","description":"Jen bez check: adresa předvyplněného formuláře na mojedane.gov.cz"},{"name":"valid_until","description":"Jen bez check: čas volání + 30 minut – platnost odkazu, jak ji předpokládá Saldo (portál ji nevrací)"}],"x-saldo-variants":[{"param":"report","value":"dph","summary":"Přiznání k DPH v EPO","description":"XML přiznání k DPH (DPHDP3) za zvolené období.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"period":{"type":"string","description":"Období YYYY-MM nebo YYYY-Qn; má přednost před year, month a quarter. Neplatná hodnota skončí chybou 500."},"month":{"type":"integer","description":"Měsíc 1–12, když chybí period"},"quarter":{"type":"integer","description":"Čtvrtletí 1–4 čtvrtletního plátce, když chybí period i month"}}},"example":{"period":"2026-08","check":true}}}},"example":{"note":"Volání portálu Moje daně je v ukázce nahrazeno záznamem."}},{"param":"report","value":"kh","summary":"Kontrolní hlášení v EPO","description":"XML kontrolního hlášení (DPHKH1). Pro kontrolu (check=true) se posílá zabalené do ZIP. Identifikovaná osoba a právnická osoba se čtvrtletním obdobím dostanou 422.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"period":{"type":"string","description":"Období YYYY-MM nebo YYYY-Qn. Neplatná hodnota skončí chybou 500."},"month":{"type":"integer","description":"Měsíc 1–12, když chybí period"},"quarter":{"type":"integer","description":"Čtvrtletí 1–4, když chybí period i month (jen fyzická osoba)"}}},"example":{"period":"2026-08","check":true}}}},"errors":[{"status":422,"when":"Identifikovaná osoba nebo právnická osoba se čtvrtletním obdobím"}],"example":{"note":"Volání portálu Moje daně je v ukázce nahrazeno záznamem."}},{"param":"report","value":"sh","summary":"Souhrnné hlášení v EPO","description":"XML souhrnného hlášení (DPHSHV); filing_type E vrátí 422.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"period":{"type":"string","description":"Období YYYY-MM nebo YYYY-Qn. Neplatná hodnota skončí chybou 500."},"month":{"type":"integer","description":"Měsíc 1–12, když chybí period"},"quarter":{"type":"integer","description":"Čtvrtletí 1–4, když chybí period i month"}}},"example":{"period":"2026-08"}}}},"example":{"note":"Bez check – vrátí odkaz na předvyplněný formulář. Volání portálu je v ukázce nahrazeno záznamem."}},{"param":"report","value":"income_tax","summary":"Přiznání k dani z příjmů v EPO","description":"XML přiznání k dani z příjmů (DPFDP7 u OSVČ, DPPDP9 u právnické osoby) se stejnými omezeními jako u GET …/xml.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"last_known_tax":{"type":"number","description":"Poslední známá daň – povinná u dodatečného přiznání (D, E, N)"},"publish":{"type":"string","description":"Jen DPPO – řetězec \"false\" vynechá žádost o zveřejnění závěrky. Hodnota se porovnává jako text: JSON false se nerozpozná a závěrka se zveřejní. Bez pole se zveřejní.","enum":["false"]},"accounts_approved":{"type":"boolean","description":"Jen DPPO – závěrka je schválená; výchozí false"},"accounts_audited":{"type":"boolean","description":"Jen DPPO s auditem – závěrka je ověřená; výchozí false"}}},"example":{"year":2025}}}},"errors":[{"status":422,"when":"DPFO mimo roky 2024–2025, DPPO za celé zdaňovací období 2026, chybějící údaje nebo nevyrovnaná rozvaha"}],"example":{"note":"Bez check – vrátí odkaz na předvyplněný formulář. Volání portálu je v ukázce nahrazeno záznamem."}}]}},"/entities/{entity_id}/taxes/{report}/validate":{"post":{"operationId":"validateOverviewAtCssz","tags":["Daně, podání a doručenky"],"summary":"Předběžná kontrola přehledu OSVČ u ČSSZ","description":"Sestaví XML přehledu OSVČ pro ČSSZ (jako GET …/taxes/prehled_sp/xml) a pošle ho k anonymní předběžné kontrole validační službě ČSSZ. Vrátí, zda přehled kontrolou prošel, a nálezy s kódy ČSSZ. Přehled se tím nepodává a v Saldu se neukládá. Jiná hodnota report než prehled_sp vrátí 422. Vstupy lze poslat v těle JSON i v query stringu.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky","schema":{"type":"integer"},"example":12},{"name":"report","in":"path","required":true,"description":"Jediná podporovaná hodnota","schema":{"type":"string","enum":["prehled_sp"]},"example":"prehled_sp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"year":{"type":"integer","description":"Rok přehledu – Saldo sestaví jen rok 2025; výchozí aktuální rok"},"filing_type":{"type":"string","description":"O = opravný přehled, jinak řádný"},"date":{"type":"string","format":"date","description":"Datum vyplnění; výchozí dnešní datum"},"reasons_found_on":{"type":"string","format":"date","description":"Datum zjištění nové výše vyměřovacího základu (u opravného)"},"reason":{"type":"string","description":"Důvod opravného přehledu"},"tax_return":{"type":"string","description":"Jak se podává daňové přiznání","enum":["standard","electronic","advisor","none","extended"]},"tax_return_extended_until":{"type":"string","format":"date","description":"Prodloužená lhůta – povinná u tax_return extended"}}},"example":{"year":2025}}}},"responses":{"200":{"description":"Výsledek kontroly ČSSZ.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"report není prehled_sp („Předběžnou kontrolu nabízí jen ČSSZ pro přehled OSVČ“) XML přehledu nelze sestavit (firma není OSVČ, rok jiný než 2025, chybějící údaje); odpověď { error, problems }","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"502":{"description":"Validační služba ČSSZ neodpověděla včas, je nedostupná nebo nevrátila výsledek","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"dane","x-saldo-access":"writer","x-saldo-side-effects":"Pošle XML přehledu na https://epodani.cssz.cz/ePodaniValidace.svc (SOAP ValidujPodani, bez přihlášení). Služba přehled jen kontroluje, nic se nepodá. Po odpovědi služby zapíše do historie událost tax.validate.","x-saldo-limits":"Spojení se službou ČSSZ má limit 10 s na navázání a 40 s na odpověď.","x-saldo-repeat":"Každé volání pošle přehled ke kontrole znovu a zapíše novou událost.","x-saldo-errors":[{"status":422,"when":"report není prehled_sp („Předběžnou kontrolu nabízí jen ČSSZ pro přehled OSVČ“)"},{"status":422,"when":"XML přehledu nelze sestavit (firma není OSVČ, rok jiný než 2025, chybějící údaje); odpověď { error, problems }"},{"status":502,"when":"Validační služba ČSSZ neodpověděla včas, je nedostupná nebo nevrátila výsledek"}],"x-saldo-response-fields":[{"name":"ok","description":"true, když služba vrátila výsledek OK"},{"name":"findings","description":"Nálezy: category, code (kód chyby ČSSZ), message, form"}],"x-saldo-example":{"note":"Volání služby ČSSZ je v ukázce nahrazeno záznamem."}}},"/entities/{entity_id}/taxes/{report}/filing":{"post":{"operationId":"createTaxFiling","tags":["Daně, podání a doručenky"],"summary":"Uložení podání daně z příjmů nebo přehledu OSVČ","description":"Sestaví XML jako GET …/taxes/{report}/xml a uloží ho jako podání ve stavu draft (Připraveno) spolu se snímkem výpočtu. Podání tím nikam neodchází; odeslání uživatel potvrdí později přes PATCH /filings/{id} se stavem filed. Podání k DPH (dph, kh, sh) se ukládají přes POST /filings. Vstupy lze poslat v těle JSON i v query stringu.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky","schema":{"type":"integer"},"example":12},{"name":"report","in":"path","required":true,"description":"Druh podání; jiné hodnoty vrátí 422","schema":{"type":"string","enum":["income_tax","prehled_sp","prehled_zp"]},"example":"income_tax"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"year":{"type":"integer","description":"Zdaňovací období (rok); výchozí aktuální rok"},"filing_type":{"type":"string","description":"Druh podání (viz varianty); výchozí B"},"date":{"type":"string","format":"date","description":"Datum podání uvedené v XML; výchozí dnešní datum"},"reasons_found_on":{"type":"string","format":"date","description":"Den zjištění důvodů (dodatečné přiznání, opravný přehled ČSSZ)"}}}}}},"responses":{"201":{"description":"Uložené podání (bez XML).","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"report není income_tax, prehled_sp ani prehled_zp („Podání k DPH ukládejte přes /filings“) XML nelze sestavit – stejné důvody jako u GET …/taxes/{report}/xml","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"dane","x-saldo-access":"writer","x-saldo-side-effects":"Vytvoří záznam podání (kind dpfo nebo dppo podle firmy, případně prehled_sp nebo prehled_zp) ve stavu draft s XML a daty a zapíše událost filing.created. Nic nikam neposílá, nic neúčtuje.","x-saldo-repeat":"Každé volání vytvoří nové podání; duplicity se nekontrolují.","x-saldo-errors":[{"status":422,"when":"report není income_tax, prehled_sp ani prehled_zp („Podání k DPH ukládejte přes /filings“)"},{"status":422,"when":"XML nelze sestavit – stejné důvody jako u GET …/taxes/{report}/xml"}],"x-saldo-response-fields":[{"name":"id","description":"ID podání"},{"name":"kind","description":"dpfo, dppo, prehled_sp nebo prehled_zp"},{"name":"period","description":"Rok (YYYY)"},{"name":"filing_type","description":"Druh podání"},{"name":"status","description":"draft"},{"name":"data","description":"Snímek výpočtu (u daně výsledek výpočtu, u přehledu řádky přehledu)"},{"name":"proof_state","description":"draft"},{"name":"has_xml","description":"true"}],"x-saldo-variants":[{"param":"report","value":"income_tax","summary":"Uložení přiznání k dani z příjmů","description":"Uloží přiznání DPFO (OSVČ) nebo DPPO (právnická osoba) za rok year. filing_type se uloží tak, jak přišel (B, O, D, E, N, S), XML ale zná jen B, O, D a E – N se v XML zapíše jako D a S jako B.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"last_known_tax":{"type":"number","description":"Poslední známá daň – povinná u dodatečného přiznání (D, E, N)"},"publish":{"type":"string","description":"Jen DPPO – řetězec \"false\" vynechá žádost o zveřejnění závěrky. Hodnota se porovnává jako text: JSON false se nerozpozná a závěrka se zveřejní. Bez pole se zveřejní.","enum":["false"]},"accounts_approved":{"type":"boolean","description":"Jen DPPO – závěrka je schválená; výchozí false"},"accounts_audited":{"type":"boolean","description":"Jen DPPO s auditem – závěrka je ověřená; výchozí false"}}},"example":{"year":2025}}}},"errors":[{"status":422,"when":"DPFO mimo roky 2024–2025, DPPO za celé zdaňovací období 2026, chybějící údaje nebo nevyrovnaná rozvaha"},{"status":422,"when":"filing_type mimo B, O, D, E, N, S – validace podání { error, errors }"}]},{"param":"report","value":"prehled_sp","summary":"Uložení přehledu OSVČ pro ČSSZ","description":"Uloží přehled pro ČSSZ za rok 2025; filing_type O uloží opravný přehled (typ O), cokoli jiného řádný (typ B).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","description":"Důvod opravného přehledu (povinný u O)"},"tax_return":{"type":"string","description":"Jak se podává daňové přiznání","enum":["standard","electronic","advisor","none","extended"]},"tax_return_extended_until":{"type":"string","format":"date","description":"Prodloužená lhůta – povinná u tax_return extended"}}},"example":{"year":2025}}}},"errors":[{"status":422,"when":"Rok jiný než 2025, chybějící údaje nebo nesplněné kontroly; odpověď { error, problems }"}]},{"param":"report","value":"prehled_zp","summary":"Uložení přehledu OSVČ pro zdravotní pojišťovnu","description":"Uloží přehled pro zdravotní pojišťovnu za rok 2025; filing_type O uloží opravný přehled, cokoli jiného řádný.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tax_return":{"type":"string","description":"Jak se podává daňové přiznání","enum":["standard","electronic","advisor","none","extended"]},"tax_return_extended_until":{"type":"string","format":"date","description":"Prodloužená lhůta – povinná u tax_return extended"}}},"example":{"year":2025}}}},"errors":[{"status":422,"when":"Rok jiný než 2025, chybějící údaje nebo nesplněné kontroly; odpověď { error, problems }"}]}]}},"/entities/{entity_id}/taxes/profile_from_bank":{"post":{"operationId":"fillTaxProfileFromBank","tags":["Daně, podání a doručenky"],"summary":"Doplnění daňového profilu OSVČ z bankovních pohybů","description":"Projde odchozí bankovní pohyby OSVČ za posledních 24 měsíců a podle plateb na účty správ sociálního zabezpečení a zdravotních pojišťoven najde kód OSSZ, variabilní symbol ČSSZ, zdravotní pojišťovnu a rodné číslo. Do daňového profilu zapíše jen údaje, které v něm chybějí (rodné číslo ne, je-li DIČ rodným číslem). U právnické osoby nebo bez nálezu vrátí prázdné applied a nic nezmění. Stejné návrhy ukazuje GET …/taxes/payments v missing[].suggestion.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky","schema":{"type":"integer"},"example":12}],"responses":{"200":{"description":"Doplněné údaje.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"dane","x-saldo-access":"manager","x-saldo-side-effects":"Uloží nalezené hodnoty do nastavení firmy (settings.tax_profile) a zapíše událost entity.updated („Z výpisu z banky doplněno: …“). Nic neúčtuje.","x-saldo-repeat":"Opakované volání už nic nedoplní, protože údaje v profilu jsou; vrátí prázdné applied.","x-saldo-response-fields":[{"name":"applied","description":"Pole → zobrazená hodnota: ossz_code, cssz_variable_symbol, health_insurer, birth_number (ve tvaru 850101/1233)"}],"x-saldo-example":{"note":"Ukázková OSVČ má profil vyplněný, proto vrátí prázdné applied."}}},"/entities/{entity_id}/filings":{"get":{"operationId":"listFilings","tags":["Daně, podání a doručenky"],"summary":"Seznam uložených podání","description":"Vrátí uložená podání firmy všech druhů (DPH, KH, SH, daň z příjmů, přehledy OSVČ i JMHZ) od nejnověji vytvořeného, bez XML. U každého podání je stav v Saldu (status draft nebo filed) a zvlášť stav doložení doručení proof_state – status filed je jen tvrzení uživatele, že podání odeslal.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky","schema":{"type":"integer"},"example":12}],"responses":{"200":{"description":"Pole podání.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"dane","x-saldo-access":"member","x-saldo-side-effects":"Nic nezapisuje.","x-saldo-limits":"Nejvýše 200 nejnovějších podání; stránkování není.","x-saldo-response-fields":[{"name":"[].id","description":"ID podání"},{"name":"[].kind","description":"dph, kh, sh, dpfo, dppo, prehled_sp, prehled_zp, jmhz; kind_label česky"},{"name":"[].period","description":"Období: YYYY-MM, YYYY-Qn nebo YYYY"},{"name":"[].filing_type","description":"B řádné, O opravné, D dodatečné, E opravné dodatečné, N následné, S storno"},{"name":"[].status","description":"draft (Připraveno) nebo filed (označeno jako odeslané)"},{"name":"[].filed_on","description":"Datum odeslání zadané uživatelem"},{"name":"[].first_filed_at","description":"Kdy bylo podání poprvé označeno jako odeslané"},{"name":"[].submission_version","description":"Kolikrát bylo podání označeno jako odeslané (zvyšuje se při každém přechodu na filed)"},{"name":"[].proof_state","description":"draft; awaiting_proof (odesláno bez ověřené doručenky či výjimky); verified (ověřená doručenka nebo potvrzení přijetí k aktuálnímu XML a verzi odeslání); exception (schváleno bez doručenky)"},{"name":"[].exception_approved_at","description":"Schválení bez doručenky: kdy, kdo (exception_approved_by_id) a proč (exception_reason)"},{"name":"[].evidence_count","description":"Počet přiložených důkazních souborů včetně vyřazených"},{"name":"[].data","description":"Snímek výkazu nebo výpočtu z doby přípravy"},{"name":"[].has_xml","description":"Zda je uložené XML"}]},"post":{"operationId":"createVatFiling","tags":["Daně, podání a doručenky"],"summary":"Uložení podání k DPH (přiznání, kontrolní nebo souhrnné hlášení)","description":"Sestaví výkaz a XML přiznání k DPH, kontrolního nebo souhrnného hlášení za období a uloží je jako podání ve stavu draft (Připraveno). Podání nikam neodchází; že bylo odesláno, potvrdí uživatel přes PATCH /filings/{id}. Datum podání v XML je vždy dnešní. Operace nekontroluje registraci k DPH.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky","schema":{"type":"integer"},"example":12}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["kind","period"],"properties":{"kind":{"type":"string","description":"Druh podání","enum":["dph","kh","sh"]},"period":{"type":"string","description":"Období YYYY-MM nebo YYYY-Qn; neplatná hodnota skončí chybou 500"},"filing_type":{"type":"string","description":"Druh podání; jiná hodnota se uloží jako B. Uloží se tak, jak přišel, XML ale S nezná a sestaví ho jako řádné; význam D, E, N je u každého formuláře jiný (viz GET …/taxes/{report}/xml)","enum":["B","O","D","E","N","S"],"default":"B"},"reasons_found_on":{"type":"string","format":"date","description":"Den zjištění důvodů – povinný u dodatečného či následného podání DPH a KH"}}},"example":{"kind":"dph","period":"2026-08","filing_type":"B"}}}},"responses":{"201":{"description":"Uložené podání bez XML (tvar jako v GET /filings).","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"kind není dph, kh ani sh („Tento typ podání zatím nelze připravit“) XML nelze sestavit – identifikovaná osoba u KH, právnická osoba se čtvrtletním KH, SH s filing_type E, chybí den zjištění důvodů, neplatné údaje firmy nebo dokladu","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"500":{"description":"Neplatný formát period","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"dane","x-saldo-access":"writer","x-saldo-side-effects":"Vytvoří podání (Filing) ve stavu draft s daty výkazu a XML a zapíše událost filing.created. Nic nikam neposílá, nic neúčtuje.","x-saldo-repeat":"Každé volání vytvoří nové podání, i za stejné období a druh.","x-saldo-errors":[{"status":422,"when":"kind není dph, kh ani sh („Tento typ podání zatím nelze připravit“)"},{"status":422,"when":"XML nelze sestavit – identifikovaná osoba u KH, právnická osoba se čtvrtletním KH, SH s filing_type E, chybí den zjištění důvodů, neplatné údaje firmy nebo dokladu"},{"status":500,"when":"Neplatný formát period"}],"x-saldo-response-fields":[{"name":"id","description":"ID podání"},{"name":"status","description":"draft"},{"name":"data","description":"Sestavený výkaz (přiznání, kontrolní nebo souhrnné hlášení)"},{"name":"proof_state","description":"draft"}]}},"/entities/{entity_id}/filings/{id}":{"get":{"operationId":"getFiling","tags":["Daně, podání a doručenky"],"summary":"Detail podání nebo jeho uložené XML","description":"Vrátí podání včetně uloženého XML v poli xml. S format=xml (nebo koncovkou .xml v cestě) vrátí přímo uložený soubor XML – přesně ten, který byl sestaven při přípravě podání.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky","schema":{"type":"integer"},"example":12},{"name":"id","in":"path","required":true,"description":"ID podání","schema":{"type":"integer"},"example":55},{"name":"format","in":"query","required":false,"description":"xml = vrátit soubor XML místo JSON","schema":{"type":"string","enum":["xml"]},"example":"xml"}],"responses":{"200":{"description":"Podání (pole jako v GET /filings) a navíc xml. S format=xml soubor application/xml s názvem {kind}-{period}.xml (Content-Disposition attachment).","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"dane","x-saldo-access":"member","x-saldo-side-effects":"Nic nezapisuje."},"patch":{"operationId":"updateFilingStatus","tags":["Daně, podání a doručenky"],"summary":"Označení podání jako odeslaného nebo vrácení mezi připravená","description":"Změní stav podání evidovaný v Saldu. status filed znamená, že uživatel prohlašuje, že podání odeslal (Saldo to neověřuje a samo nic neposílá); doložení doručení je samostatný krok přes …/evidences a …/verify. Při přechodu z draft na filed se zvýší submission_version, takže dřívější ověřené doručenky přestanou platit a proof_state je znovu awaiting_proof. status draft vrátí podání mezi připravená, smaže filed_on a zruší schválenou výjimku bez doručenky; přiložené soubory zůstanou.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky","schema":{"type":"integer"},"example":12},{"name":"id","in":"path","required":true,"description":"ID podání","schema":{"type":"integer"},"example":55}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","description":"Nový stav","enum":["draft","filed"]},"filed_on":{"type":"string","format":"date","description":"Datum odeslání (jen se status filed); bez něj zůstane dosavadní datum u už odeslaného podání, jinak dnešní datum"}}},"example":{"status":"filed","filed_on":"2026-09-24"}}}},"responses":{"200":{"description":"Podání po změně (tvar jako v GET /filings).","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"status není draft ani filed („Neplatný stav podání“)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"dane","x-saldo-access":"writer","x-saldo-side-effects":"Uloží status a filed_on, při prvním odeslání first_filed_at, při přechodu na filed zvýší submission_version; při návratu na draft vymaže schválenou výjimku. Zapíše událost filing.updated s předchozím datem odeslání a případně zrušenou výjimkou. Nic nikam neposílá.","x-saldo-repeat":"Opakované filed u už odeslaného podání verzi nezvyšuje (jen případně změní filed_on); každý přechod draft → filed ji zvýší. Každé volání zapíše událost.","x-saldo-errors":[{"status":422,"when":"status není draft ani filed („Neplatný stav podání“)"}]},"delete":{"operationId":"deleteFiling","tags":["Daně, podání a doručenky"],"summary":"Smazání připraveného podání","description":"Smaže podání, které nikdy nebylo označeno jako odeslané a nemá žádný důkazní soubor. Podání, které už někdy bylo ve stavu filed (i když je teď draft), zůstává kvůli historii.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky","schema":{"type":"integer"},"example":12},{"name":"id","in":"path","required":true,"description":"ID podání","schema":{"type":"integer"},"example":56}],"responses":{"204":{"description":"Bez obsahu."},"422":{"description":"Podání je nebo někdy bylo označeno jako odeslané („… nelze smazat; zachovejte jeho historii“) K podání jsou přiložené důkazní soubory („Podání s důkazními soubory nelze smazat“)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"dane","x-saldo-access":"writer","x-saldo-side-effects":"Zapíše událost filing.deleted a podání smaže včetně XML.","x-saldo-errors":[{"status":422,"when":"Podání je nebo někdy bylo označeno jako odeslané („… nelze smazat; zachovejte jeho historii“)"},{"status":422,"when":"K podání jsou přiložené důkazní soubory („Podání s důkazními soubory nelze smazat“)"}],"x-saldo-example":{"note":"Potřebuje podání ve stavu draft, které nikdy nebylo odeslané a nemá důkazy."}}},"/entities/{entity_id}/filings/{id}/exception":{"post":{"operationId":"approveFilingException","tags":["Daně, podání a doručenky"],"summary":"Schválení odeslaného podání bez doručenky","description":"Výslovně schválí, že odeslané podání se pro uzávěrku považuje za doložené, i když k němu není ověřená doručenka; proof_state pak je exception (ověřená doručenka má přednost a proof_state zůstává verified). Vyžaduje stav filed, potvrzení confirmed_without_receipt a důvod. Nové schválení nahradí předchozí.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky","schema":{"type":"integer"},"example":12},{"name":"id","in":"path","required":true,"description":"ID podání","schema":{"type":"integer"},"example":55}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["confirmed_without_receipt","reason"],"properties":{"confirmed_without_receipt":{"type":"boolean","description":"Musí být true"},"reason":{"type":"string","description":"Důvod schválení, alespoň 10 znaků"}}},"example":{"confirmed_without_receipt":true,"reason":"Podání je v portálu potvrzené, doručenka zatím nedorazila."}}}},"responses":{"200":{"description":"Podání po schválení (proof_state exception, pokud nemá ověřenou doručenku).","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Podání není ve stavu filed („Nejprve označte podání jako odeslané“) confirmed_without_receipt není true („Potvrďte schválení bez doručenky“) Důvod je kratší než 10 znaků","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"dane","x-saldo-access":"manager","x-saldo-side-effects":"Uloží exception_approved_at, exception_approved_by_id a exception_reason a zapíše událost filing.exception_approved s důvodem a případně nahrazenou výjimkou.","x-saldo-repeat":"Každé volání přepíše schválení novým (čas, osoba, důvod) a zapíše novou událost.","x-saldo-errors":[{"status":422,"when":"Podání není ve stavu filed („Nejprve označte podání jako odeslané“)"},{"status":422,"when":"confirmed_without_receipt není true („Potvrďte schválení bez doručenky“)"},{"status":422,"when":"Důvod je kratší než 10 znaků"}]},"delete":{"operationId":"revokeFilingException","tags":["Daně, podání a doručenky"],"summary":"Zrušení schválení podání bez doručenky","description":"Zruší schválenou výjimku; podání bez ověřené doručenky se vrátí do stavu awaiting_proof.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky","schema":{"type":"integer"},"example":12},{"name":"id","in":"path","required":true,"description":"ID podání","schema":{"type":"integer"},"example":55}],"responses":{"200":{"description":"Podání po zrušení výjimky.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Výjimka není schválená („Výjimka není schválená“)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"dane","x-saldo-access":"manager","x-saldo-side-effects":"Vymaže údaje výjimky a zapíše událost filing.exception_revoked s jejím původním obsahem.","x-saldo-repeat":"Druhé volání vrátí 422, protože výjimka už schválená není.","x-saldo-errors":[{"status":422,"when":"Výjimka není schválená („Výjimka není schválená“)"}],"x-saldo-example":{"note":"Předpokládá výjimku schválenou přes POST …/exception, jinak vrátí 422."}}},"/entities/{entity_id}/filings/{filing_id}/evidences":{"get":{"operationId":"listFilingEvidences","tags":["Daně, podání a doručenky"],"summary":"Důkazní soubory podání (doručenky a potvrzení)","description":"Vrátí všechny soubory přiložené k podání jako doklad o doručení, včetně vyřazených, v pořadí nahrání. U každého je stav ověření; verified je true jen u nevyřazeného ověřeného souboru s uloženým originálem, jehož ověření patří k aktuálnímu XML a aktuální verzi odeslání podání.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky","schema":{"type":"integer"},"example":12},{"name":"filing_id","in":"path","required":true,"description":"ID podání","schema":{"type":"integer"},"example":55}],"responses":{"200":{"description":"Objekt s polem evidences.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"dane","x-saldo-access":"member","x-saldo-side-effects":"Nic nezapisuje.","x-saldo-response-fields":[{"name":"evidences[].id","description":"ID důkazního souboru"},{"name":"evidences[].kind","description":"delivery_receipt (doručenka), acceptance (potvrzení přijetí), other (jiný podklad); kind_label česky"},{"name":"evidences[].filename","description":"Původní název souboru; content_type, byte_size, sha256"},{"name":"evidences[].delivered_on","description":"Datum doručení zadané při ověření"},{"name":"evidences[].delivery_reference","description":"Identifikátor podání nebo zprávy zadaný při ověření"},{"name":"evidences[].verified_at","description":"Kdy a kdo (verified_by_id) ověřil; filing_xml_sha256 a submission_version, ke kterým ověření patří; verification_note"},{"name":"evidences[].voided_at","description":"Vyřazení: kdy, kdo (voided_by_id), důvod (void_reason)"},{"name":"evidences[].verified","description":"Ověření platí pro aktuální XML a verzi odeslání a soubor není vyřazený"},{"name":"evidences[].has_file","description":"Zda je originál uložený"}]},"post":{"operationId":"attachFilingEvidence","tags":["Daně, podání a doručenky"],"summary":"Přiložení doručenky nebo potvrzení k podání","description":"Uloží originální soubor dokladující doručení odeslaného podání (PDF, XML nebo ZFO z datové schránky). Typ se určí podle přípony a obsah se zkontroluje (PDF musí mít strukturu PDF, XML být platné XML, ZFO podepsaná obálka CMS – pečeť ani vztah k podání se nekontrolují). Přiložení samo doručení nedokládá: proof_state zůstane awaiting_proof, dokud vlastník nebo účetní soubor neověří přes …/verify.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky","schema":{"type":"integer"},"example":12},{"name":"filing_id","in":"path","required":true,"description":"ID podání","schema":{"type":"integer"},"example":55}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"Soubor .pdf, .xml nebo .zfo, 1 B až 15 MB"},"kind":{"type":"string","description":"Druh podkladu; neznámá hodnota se bere jako delivery_receipt","enum":["delivery_receipt","acceptance","other"],"default":"delivery_receipt"}}}}}},"responses":{"201":{"description":"Nový důkazní soubor (tvar jako v GET …/evidences). Stejný soubor znovu vrátí 200 s existujícím záznamem.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Podání není ve stavu filed („Nejprve označte podání jako odeslané“) Přípona není .pdf, .xml ani .zfo nebo obsah neodpovídá formátu K podání je už 10 nevyřazených důkazních souborů","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"400":{"description":"Chybí soubor v poli file („Vyberte doručenku nebo potvrzení“)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"413":{"description":"Soubor je prázdný nebo větší než 15 MB","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"dane","x-saldo-access":"writer","x-saldo-side-effects":"Uloží originál a záznam s jeho SHA-256, typem a nahrávající osobou a zapíše událost filing.evidence_attached. Stav podání ani proof_state nemění.","x-saldo-limits":"Soubor nejvýše 15 MB; nejvýše 10 nevyřazených souborů na podání (vyřazené se nepočítají).","x-saldo-repeat":"Soubor se stejným obsahem (SHA-256) u téhož podání se znovu neuloží – vrátí 200 s existujícím záznamem, i když je vyřazený, a nezapíše událost.","x-saldo-errors":[{"status":422,"when":"Podání není ve stavu filed („Nejprve označte podání jako odeslané“)"},{"status":400,"when":"Chybí soubor v poli file („Vyberte doručenku nebo potvrzení“)"},{"status":413,"when":"Soubor je prázdný nebo větší než 15 MB"},{"status":422,"when":"Přípona není .pdf, .xml ani .zfo nebo obsah neodpovídá formátu"},{"status":422,"when":"K podání je už 10 nevyřazených důkazních souborů"}],"x-saldo-example":{"note":"Ukázka nejdřív označí připravené kontrolní hlášení jako odeslané a přiloží k němu soubor, který u něj ještě není."}}},"/entities/{entity_id}/filings/{filing_id}/evidences/{id}":{"get":{"operationId":"getFilingEvidence","tags":["Daně, podání a doručenky"],"summary":"Detail důkazního souboru podání","description":"Vrátí jeden důkazní soubor podání s jeho stavem ověření a vyřazení (bez obsahu souboru).","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky","schema":{"type":"integer"},"example":12},{"name":"filing_id","in":"path","required":true,"description":"ID podání","schema":{"type":"integer"},"example":55},{"name":"id","in":"path","required":true,"description":"ID důkazního souboru","schema":{"type":"integer"},"example":7}],"responses":{"200":{"description":"Důkazní soubor (pole jako v GET …/evidences).","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"dane","x-saldo-access":"member","x-saldo-side-effects":"Nic nezapisuje."}},"/entities/{entity_id}/filings/{filing_id}/evidences/{id}/file":{"get":{"operationId":"downloadFilingEvidence","tags":["Daně, podání a doručenky"],"summary":"Stažení originálu doručenky","description":"Vrátí uložený originál přesně tak, jak byl nahrán, i u vyřazeného souboru. Vždy jako příloha typu application/octet-stream s hlavičkami Cache-Control private, no-store a X-Content-Type-Options nosniff.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky","schema":{"type":"integer"},"example":12},{"name":"filing_id","in":"path","required":true,"description":"ID podání","schema":{"type":"integer"},"example":55},{"name":"id","in":"path","required":true,"description":"ID důkazního souboru","schema":{"type":"integer"},"example":7}],"responses":{"200":{"description":"Obsah souboru s původním názvem (Content-Disposition attachment).","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"404":{"description":"K záznamu není uložený soubor","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"dane","x-saldo-access":"member","x-saldo-side-effects":"Nic nezapisuje.","x-saldo-errors":[{"status":404,"when":"K záznamu není uložený soubor"}]}},"/entities/{entity_id}/filings/{filing_id}/evidences/{id}/verify":{"post":{"operationId":"verifyFilingEvidence","tags":["Daně, podání a doručenky"],"summary":"Ověření doručenky k odeslanému podání","description":"Vlastník nebo účetní potvrdí, že soubor dokládá doručení právě tohoto podání (subjekt, druh a období souhlasí), a zadá datum doručení a identifikátor podání nebo zprávy. Ověření se váže k aktuálnímu XML podání (SHA-256) a verzi odeslání; po novém označení podání jako odeslaného přestane platit. Podklad druhu other ověřit nelze – pro něj slouží schválení výjimky. Opakované ověření již ověřeného souboru vyžaduje důvod opravy.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky","schema":{"type":"integer"},"example":12},{"name":"filing_id","in":"path","required":true,"description":"ID podání","schema":{"type":"integer"},"example":55},{"name":"id","in":"path","required":true,"description":"ID důkazního souboru","schema":{"type":"integer"},"example":7}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["confirmed_match","delivery_reference","delivered_on"],"properties":{"confirmed_match":{"type":"boolean","description":"Musí být true – potvrzení shody subjektu, druhu a období s podáním"},"delivery_reference":{"type":"string","description":"Identifikátor podání nebo zprávy (např. ID datové zprávy)"},"delivered_on":{"type":"string","format":"date","description":"Datum doručení; neplatné datum vrátí 422"},"verification_note":{"type":"string","description":"Poznámka k ověření"},"correction_reason":{"type":"string","description":"Důvod opravy, alespoň 10 znaků – povinný, pokud už soubor ověřený byl"}}},"example":{"confirmed_match":true,"delivery_reference":"DS-4816235","delivered_on":"2026-09-24","verification_note":"Doručenka z datové schránky"}}}},"responses":{"200":{"description":"Důkazní soubor po ověření (verified true); proof_state podání je verified.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Soubor je vyřazený („Vyřazený podklad nelze potvrdit“) Soubor je druhu other („Jiný podklad není doručenkou; použijte výslovné schválení účetní“) Chybí původní soubor Podání není ve stavu filed („Podání musí být označené jako odeslané“) confirmed_match není true, chybí delivery_reference nebo delivered_on Opakované ověření bez důvodu opravy alespoň 10 znaky Neplatné datum delivered_on (error „invalid date“)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"dane","x-saldo-access":"manager","x-saldo-side-effects":"Uloží datum doručení, identifikátor, poznámku, ověřující osobu a čas a SHA-256 XML a verzi odeslání podání. Zapíše událost filing.evidence_verified s novým i předchozím ověřením. Podání ani soubor nikam neposílá.","x-saldo-repeat":"Opakované ověření přepíše údaje, ale jen s důvodem opravy; každé zapíše novou událost.","x-saldo-errors":[{"status":422,"when":"Soubor je vyřazený („Vyřazený podklad nelze potvrdit“)"},{"status":422,"when":"Soubor je druhu other („Jiný podklad není doručenkou; použijte výslovné schválení účetní“)"},{"status":422,"when":"Chybí původní soubor"},{"status":422,"when":"Podání není ve stavu filed („Podání musí být označené jako odeslané“)"},{"status":422,"when":"confirmed_match není true, chybí delivery_reference nebo delivered_on"},{"status":422,"when":"Opakované ověření bez důvodu opravy alespoň 10 znaky"},{"status":422,"when":"Neplatné datum delivered_on (error „invalid date“)"}],"x-saldo-example":{"note":"Předpokládá dosud neověřený soubor; u ověřeného je nutný i correction_reason."}}},"/entities/{entity_id}/filings/{filing_id}/evidences/{id}/void":{"post":{"operationId":"voidFilingEvidence","tags":["Daně, podání a doručenky"],"summary":"Vyřazení chybného důkazního souboru","description":"Označí soubor jako vyřazený (např. doručenka patří k jinému podání). Originál ani údaje o dřívějším ověření se nemažou, ověření ale přestane platit a proof_state podání se přepočítá. Vyřazený soubor se nepočítá do limitu 10 souborů.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky","schema":{"type":"integer"},"example":12},{"name":"filing_id","in":"path","required":true,"description":"ID podání","schema":{"type":"integer"},"example":55},{"name":"id","in":"path","required":true,"description":"ID důkazního souboru","schema":{"type":"integer"},"example":7}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["reason"],"properties":{"reason":{"type":"string","description":"Důvod vyřazení, alespoň 10 znaků"}}},"example":{"reason":"Doručenka patří k jinému podání"}}}},"responses":{"200":{"description":"Důkazní soubor po vyřazení.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Soubor je už vyřazený („Podklad je již vyřazený“) Důvod je kratší než 10 znaků","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"dane","x-saldo-access":"manager","x-saldo-side-effects":"Uloží voided_at, voided_by_id a void_reason a zapíše událost filing.evidence_voided s předchozím ověřením.","x-saldo-errors":[{"status":422,"when":"Soubor je už vyřazený („Podklad je již vyřazený“)"},{"status":422,"when":"Důvod je kratší než 10 znaků"}]}},"/entities/{entity_id}/filings/{filing_id}/evidences/{id}/correct":{"post":{"operationId":"correctFilingEvidence","tags":["Daně, podání a doručenky"],"summary":"Oprava druhu nebo obnovení vyřazeného důkazního souboru","description":"Opraví druh podkladu nebo obnoví omylem vyřazený soubor, aniž by se mazal originál či dřívější události. Oprava vždy zruší vyřazení i dosavadní ověření – soubor je potřeba znovu ověřit přes …/verify.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky","schema":{"type":"integer"},"example":12},{"name":"filing_id","in":"path","required":true,"description":"ID podání","schema":{"type":"integer"},"example":55},{"name":"id","in":"path","required":true,"description":"ID důkazního souboru","schema":{"type":"integer"},"example":7}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["kind","reason"],"properties":{"kind":{"type":"string","description":"Správný druh podkladu; u nevyřazeného souboru musí být jiný než dosavadní","enum":["delivery_receipt","acceptance","other"]},"reason":{"type":"string","description":"Důvod opravy, alespoň 10 znaků"}}},"example":{"kind":"acceptance","reason":"Soubor je potvrzení přijetí, ne doručenka"}}}},"responses":{"200":{"description":"Důkazní soubor po opravě (nevyřazený, neověřený).","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Důvod je kratší než 10 znaků Neplatný druh („Neplatný typ podkladu“) Stejný druh u nevyřazeného souboru („Zvolte jiný typ nebo obnovte vyřazený podklad“) Obnovení vyřazeného souboru by překročilo 10 nevyřazených souborů","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"dane","x-saldo-access":"manager","x-saldo-side-effects":"Změní kind, vymaže údaje o vyřazení i ověření a zapíše událost filing.evidence_corrected s předchozím stavem a důvodem.","x-saldo-errors":[{"status":422,"when":"Důvod je kratší než 10 znaků"},{"status":422,"when":"Neplatný druh („Neplatný typ podkladu“)"},{"status":422,"when":"Stejný druh u nevyřazeného souboru („Zvolte jiný typ nebo obnovte vyřazený podklad“)"},{"status":422,"when":"Obnovení vyřazeného souboru by překročilo 10 nevyřazených souborů"}]}},"/entities/{entity_id}/calendar":{"get":{"operationId":"getTaxCalendar","tags":["Daně, podání a doručenky"],"summary":"Daňový kalendář firmy (JSON nebo iCalendar)","description":"Vrátí daňové a pojistné lhůty firmy za rok: DPH a hlášení, daň z příjmů a zálohy, pojistné OSVČ, paušální daň, mzdové odvody a hlášení, daň z nemovitých věcí, silniční daň a účetní závěrku – podle profilu odvozeného z nastavení a dat firmy. Termíny připadající na víkend nebo svátek jsou posunuté na nejbližší následující pracovní den. S format=ics (nebo koncovkou .ics) vrátí soubor iCalendar s celodenními událostmi a připomenutím 3 dny předem. Soubor se stahuje s přihlášením (relace nebo API klíč v hlavičce); veřejný odkaz pro odběr v kalendáři neexistuje.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky","schema":{"type":"integer"},"example":12},{"name":"year","in":"query","required":false,"description":"Kalendářní rok; výchozí (i při nečíselné hodnotě) aktuální rok","schema":{"type":"integer","minimum":2000,"maximum":2100},"example":2026},{"name":"format","in":"query","required":false,"description":"ics = soubor iCalendar místo JSON","schema":{"type":"string","enum":["ics"]},"example":"ics"}],"responses":{"200":{"description":"JSON s rokem, profilem a událostmi. S format=ics soubor text/calendar; charset=utf-8 s názvem danovy-kalendar-{rok}.ics.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Pro rok nejsou v Saldu zákonné sazby (Saldo je má pro roky 2024–2026)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"dane","x-saldo-access":"member","x-saldo-side-effects":"Nic nezapisuje.","x-saldo-errors":[{"status":422,"when":"Pro rok nejsou v Saldu zákonné sazby (Saldo je má pro roky 2024–2026)"}],"x-saldo-response-fields":[{"name":"year","description":"Rok"},{"name":"profile","description":"Z čeho kalendář vychází: legal_form, vat, recap_statement, recap_goods, fiscal_year_start, employees, advisor, databox, electronic, flat_tax, audit, real_estate, road_tax"},{"name":"events","description":"Lhůty seřazené podle data: date, statutory_date, shifted, key, title, detail, description, category (income_tax, vat, insurance, payroll, property, accounts, other), basis"}]}},"/entities/{entity_id}/assets":{"get":{"operationId":"listAssets","tags":["Majetek, mzdy a cesty"],"summary":"Seznam dlouhodobého majetku s odpisy za rok","description":"Vrátí všechny karty dlouhodobého majetku firmy včetně drobného a vyřazeného majetku, seřazené podle data uvedení do užívání a ID. Ke každé kartě připojí účet oprávek a odpisy za zvolený kalendářní rok: daňový odpis podle odpisové skupiny (celá částka, u osobního automobilu M1 před krácením na uznatelnou část), účetní odpis (součet měsíčních odpisů v roce) a zůstatek daňové vstupní ceny na konci roku.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":12},{"name":"year","in":"query","required":false,"description":"Kalendářní rok pro pole tax_this_year, accounting_this_year a remaining_tax. Bez parametru nebo při nečíselné hodnotě aktuální rok; hodnoty mimo rozsah se zarovnají na 2000 až 2100.","schema":{"type":"integer","minimum":2000,"maximum":2100},"example":2026}],"responses":{"200":{"description":"Pole karet majetku.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"500":{"description":"Některá odpisovaná karta má zbytkovou hodnotu mimo 0 až pořizovací cenu, nebo při zadané odpisové skupině rok vyřazení před rokem uvedení do užívání – výpočet plánu selže a seznam se nevrátí (známá chyba, viz createAsset)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"majetek-mzdy-cesty","x-saldo-access":"member","x-saldo-side-effects":"Nic nezapisuje.","x-saldo-errors":[{"status":500,"when":"Některá odpisovaná karta má zbytkovou hodnotu mimo 0 až pořizovací cenu, nebo při zadané odpisové skupině rok vyřazení před rokem uvedení do užívání – výpočet plánu selže a seznam se nevrátí (známá chyba, viz createAsset)"}],"x-saldo-response-fields":[{"name":"id, name, inventory_number, note","description":"Identifikace karty"},{"name":"category","description":"tangible (hmotný), intangible (nehmotný) nebo low_value (drobný – neodpisuje se)"},{"name":"account_code, accumulated_account","description":"Účet majetku a z něj odvozený účet oprávek"},{"name":"acquired_on, in_use_from, disposed_on, disposal_kind","description":"Pořízení, uvedení do užívání a vyřazení"},{"name":"price, residual_value, useful_life_months","description":"Pořizovací cena, zbytková hodnota a doba účetního odpisování v měsících"},{"name":"tax_group, tax_method, vehicle_m1","description":"Parametry daňového odpisování"},{"name":"document_id","description":"Doklad o pořízení, nebo null"},{"name":"tax_this_year","description":"Daňový odpis v zadaném roce; 0, když se v roce daňově neodpisuje"},{"name":"accounting_this_year","description":"Účetní odpis v zadaném roce; 0, když se v roce neodpisuje"},{"name":"remaining_tax","description":"Zůstatek daňové vstupní ceny po odpisu roku; null, když rok v daňovém plánu není"}]},"post":{"operationId":"createAsset","tags":["Majetek, mzdy a cesty"],"summary":"Zařazení majetku do evidence","description":"Založí kartu dlouhodobého majetku a vrátí ji s odpisovými plány. Účetní odpisy jsou rovnoměrné měsíční od měsíce následujícího po uvedení do užívání po dobu useful_life_months ze základu pořizovací cena minus zbytková hodnota, zaokrouhlené na celé koruny nahoru (u majetku uvedeného do užívání před 1. 1. 2026 matematicky); poslední měsíc dorovná zbytek. Daňový plán se počítá jen se zadanou odpisovou skupinou, z pořizovací ceny, od roku uvedení do užívání, rovnoměrně (§ 31 ZDP) nebo zrychleně (§ 32 ZDP). Drobný majetek (low_value) žádný plán nemá. API nepodporuje technické zhodnocení, přerušení odpisování, zvýšený odpis v prvním roce, daňové odpisy nehmotného majetku podle § 32a ZDP, fyzickou inventuru ani evidenci zásob.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":12}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["asset"],"properties":{"asset":{"type":"object","required":["name","in_use_from","price"],"properties":{"name":{"type":"string","description":"Název majetku, nejvýše 200 znaků"},"inventory_number":{"type":"string","description":"Inventární číslo (jen evidence, jedinečnost se nekontroluje)"},"category":{"type":"string","description":"Druh majetku: tangible hmotný, intangible nehmotný, low_value drobný (bez odpisových plánů a bez zaúčtování odpisů). Hmotný a nehmotný se počítají stejně – se zadanou skupinou se i nehmotný majetek odpisuje daňově podle § 31 nebo § 32 ZDP.","enum":["tangible","intangible","low_value"],"default":"tangible"},"account_code":{"type":"string","description":"Účet majetku: začíná nulou a má 3 až 9 číslic (např. 022). Z prvních tří číslic se odvodí účet oprávek: 013→073, 014→074, 015→075, 019→079, 021→081, 022→082, 025→085, 026→086, 029→089, jinak 082.","default":"022"},"acquired_on":{"type":"string","format":"date","description":"Datum pořízení; jen evidence, odpisy se počítají od in_use_from"},"in_use_from":{"type":"string","format":"date","description":"Datum uvedení do užívání – účetní odpisy začínají následujícím měsícem, daňové rokem uvedení"},"price":{"type":"number","description":"Pořizovací (vstupní) cena v Kč, větší než 0; základ účetních i daňových odpisů"},"tax_group":{"type":"integer","description":"Odpisová skupina podle přílohy č. 1 ZDP; null = daňově se neodpisuje","enum":[1,2,3,4,5,6]},"tax_method":{"type":"string","description":"Daňové odpisování: straight rovnoměrné (§ 31 ZDP), accelerated zrychlené (§ 32 ZDP)","enum":["straight","accelerated"],"default":"straight"},"useful_life_months":{"type":"integer","description":"Doba účetního odpisování v měsících","default":36,"minimum":1,"maximum":1200},"residual_value":{"type":"number","description":"Zbytková hodnota vyloučená z účetních odpisů; musí ležet mezi 0 a pořizovací cenou. API to při uložení neověří – hodnotu mimo rozsah uloží a u hmotného a nehmotného majetku pak výpočet plánů skončí chybou 500 (viz chyby).","default":0},"disposed_on":{"type":"string","format":"date","description":"Datum vyřazení: účetní odpisy běží včetně měsíce vyřazení, daňový odpis roku vyřazení je poloviční (v roce uvedení do užívání nulový). Vyřazení samo nic nezaúčtuje. Rok vyřazení nesmí předcházet roku uvedení do užívání; API to neověří a při zadané odpisové skupině výpočet daňového plánu skončí chybou 500 (viz chyby)."},"disposal_kind":{"type":"string","description":"Důvod vyřazení, volný text bez vlivu na výpočet; aplikace používá sale, scrap, damage a gift"},"document_id":{"type":"integer","description":"ID dokladu o pořízení v této firmě; neexistující ID se uloží jako null"},"note":{"type":"string","description":"Poznámka"},"vehicle_m1":{"type":"boolean","description":"Osobní automobil kategorie M1: je-li uveden do užívání od zdaňovacího období začínajícího 1. 1. 2024, do daňových výdajů jde jen poměrná část odpisu 2 000 000 Kč / vstupní cena (pole deductible v daňovém plánu).","default":false}}}}},"example":{"asset":{"name":"Server Dell PowerEdge T160","inventory_number":"DM-010","category":"tangible","account_code":"022","acquired_on":"2026-02-10","in_use_from":"2026-02-15","price":145000,"tax_group":1,"tax_method":"straight","useful_life_months":48,"residual_value":0}}}}},"responses":{"201":{"description":"Založená karta majetku s odpisovými plány.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"500":{"description":"Hmotný nebo nehmotný majetek se zbytkovou hodnotou mimo 0 až pořizovací cenu, nebo s odpisovou skupinou a rokem vyřazení před rokem uvedení do užívání. Karta i událost asset.created se přesto uloží a dokud se hodnoty neopraví (PATCH) nebo karta nesmaže, vrací chybu 500 i seznam, detail a plán majetku a zaúčtování odpisů (známá chyba: výpočet plánu vyhodí výjimku místo chyby 422).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"majetek-mzdy-cesty","x-saldo-access":"writer","x-saldo-side-effects":"Vytvoří kartu majetku a zapíše událost asset.created do historie firmy. Nic nezaúčtuje – ani pořízení, ani odpisy; odpisy se zaúčtují až voláním POST /entities/{entity_id}/assets/depreciate.","x-saldo-repeat":"Každé volání založí novou kartu; duplicity se nekontrolují.","x-saldo-errors":[{"status":500,"when":"Hmotný nebo nehmotný majetek se zbytkovou hodnotou mimo 0 až pořizovací cenu, nebo s odpisovou skupinou a rokem vyřazení před rokem uvedení do užívání. Karta i událost asset.created se přesto uloží a dokud se hodnoty neopraví (PATCH) nebo karta nesmaže, vrací chybu 500 i seznam, detail a plán majetku a zaúčtování odpisů (známá chyba: výpočet plánu vyhodí výjimku místo chyby 422)."}],"x-saldo-response-fields":[{"name":"id, name, category, account_code, accumulated_account, in_use_from, price, …","description":"Pole karty jako v seznamu majetku"},{"name":"tax","description":"Daňový plán po letech: year, rate_or_coefficient, kind (first_year, following_year, disposal), amount, deductible, accumulated, remaining"},{"name":"accounting","description":"Účetní plán po měsících: month (první den měsíce), year, amount, accumulated, remaining (pořizovací cena minus oprávky)"},{"name":"accounting_yearly","description":"Účetní plán sečtený po kalendářních letech: year, amount, accumulated, remaining"}]}},"/entities/{entity_id}/assets/{id}":{"get":{"operationId":"getAsset","tags":["Majetek, mzdy a cesty"],"summary":"Detail majetku s odpisovými plány","description":"Vrátí kartu majetku s daňovým odpisovým plánem po letech, účetním plánem po měsících a jeho ročním souhrnem. Stejná data vrací GET /entities/{entity_id}/assets/{id}/schedule.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":12},{"name":"id","in":"path","required":true,"description":"ID karty majetku","schema":{"type":"integer"},"example":5}],"responses":{"200":{"description":"Karta majetku s plány tax, accounting a accounting_yearly (stejná struktura jako při založení).","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"500":{"description":"Karta má zbytkovou hodnotu mimo 0 až pořizovací cenu, nebo při zadané odpisové skupině rok vyřazení před rokem uvedení do užívání (známá chyba, viz createAsset)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"majetek-mzdy-cesty","x-saldo-access":"member","x-saldo-side-effects":"Nic nezapisuje.","x-saldo-errors":[{"status":500,"when":"Karta má zbytkovou hodnotu mimo 0 až pořizovací cenu, nebo při zadané odpisové skupině rok vyřazení před rokem uvedení do užívání (známá chyba, viz createAsset)"}],"x-saldo-response-fields":[{"name":"tax","description":"Daňový plán po letech; prázdný bez odpisové skupiny a u drobného majetku"},{"name":"accounting","description":"Účetní plán po měsících; prázdný u drobného majetku"},{"name":"accounting_yearly","description":"Účetní odpisy po kalendářních letech"}]},"patch":{"operationId":"updateAsset","tags":["Majetek, mzdy a cesty"],"summary":"Úprava nebo vyřazení karty majetku","description":"Změní zaslaná pole karty (neposlaná zůstanou beze změny) a vrátí kartu s přepočtenými plány. Vyřazení se zadává polem disposed_on (a disposal_kind). Už zaúčtované odpisy se nezmění – pro jejich přepočet zavolejte POST /entities/{entity_id}/assets/depreciate za dotčený rok.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":12},{"name":"id","in":"path","required":true,"description":"ID karty majetku","schema":{"type":"integer"},"example":5}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["asset"],"properties":{"asset":{"type":"object","properties":{"name":{"type":"string","description":"Název majetku, nejvýše 200 znaků"},"inventory_number":{"type":"string","description":"Inventární číslo"},"category":{"type":"string","description":"Druh majetku (low_value = drobný bez odpisů)","enum":["tangible","intangible","low_value"]},"account_code":{"type":"string","description":"Účet majetku začínající nulou, 3 až 9 číslic"},"acquired_on":{"type":"string","format":"date","description":"Datum pořízení"},"in_use_from":{"type":"string","format":"date","description":"Datum uvedení do užívání"},"price":{"type":"number","description":"Pořizovací cena v Kč, větší než 0"},"tax_group":{"type":"integer","description":"Odpisová skupina; null zruší daňové odpisy","enum":[1,2,3,4,5,6]},"tax_method":{"type":"string","description":"Rovnoměrné nebo zrychlené daňové odpisování","enum":["straight","accelerated"]},"useful_life_months":{"type":"integer","description":"Doba účetního odpisování v měsících","minimum":1,"maximum":1200},"residual_value":{"type":"number","description":"Zbytková hodnota, mezi 0 a pořizovací cenou; hodnotu mimo rozsah API uloží a výpočet plánů skončí chybou 500 (viz chyby)"},"disposed_on":{"type":"string","format":"date","description":"Datum vyřazení; null vyřazení zruší. Rok vyřazení před rokem uvedení do užívání API uloží a při zadané odpisové skupině výpočet skončí chybou 500"},"disposal_kind":{"type":"string","description":"Důvod vyřazení (volný text; aplikace používá sale, scrap, damage, gift)"},"document_id":{"type":"integer","description":"Doklad o pořízení; neexistující ID se uloží jako null"},"note":{"type":"string","description":"Poznámka"},"vehicle_m1":{"type":"boolean","description":"Osobní automobil M1 s krácením daňově uznatelného odpisu"}}}}},"example":{"asset":{"note":"Umístění – kancelář Brno","useful_life_months":48}}}}},"responses":{"200":{"description":"Upravená karta s přepočtenými plány tax, accounting a accounting_yearly.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"500":{"description":"Karta má po úpravě zbytkovou hodnotu mimo 0 až pořizovací cenu, nebo při zadané odpisové skupině rok vyřazení před rokem uvedení do užívání – změny i událost asset.updated se přesto uloží (známá chyba, viz createAsset)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"majetek-mzdy-cesty","x-saldo-access":"writer","x-saldo-side-effects":"Uloží změny karty a zapíše událost asset.updated. Zaúčtované odpisy ani jiné účetní zápisy nemění; vyřazení se nezaúčtuje.","x-saldo-repeat":"Opakování se stejnými daty kartu nezmění, ale pokaždé zapíše událost asset.updated.","x-saldo-errors":[{"status":500,"when":"Karta má po úpravě zbytkovou hodnotu mimo 0 až pořizovací cenu, nebo při zadané odpisové skupině rok vyřazení před rokem uvedení do užívání – změny i událost asset.updated se přesto uloží (známá chyba, viz createAsset)"}]},"delete":{"operationId":"deleteAsset","tags":["Majetek, mzdy a cesty"],"summary":"Smazání majetku včetně jeho odpisových zápisů","description":"Smaže kartu majetku spolu se všemi účetními zápisy jejích odpisů ze všech let. Leží-li kterýkoli z těchto zápisů v uzamčeném období, nic nesmaže. Majetek, který má v účetnictví zůstat, místo mazání vyřaďte polem disposed_on.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":12},{"name":"id","in":"path","required":true,"description":"ID karty majetku","schema":{"type":"integer"},"example":5}],"responses":{"204":{"description":"Prázdná odpověď."},"422":{"description":"Některý odpisový zápis majetku leží v uzamčeném období – „Období do D. M. RRRR je uzamčeno – zaúčtování nelze změnit“","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"majetek-mzdy-cesty","x-saldo-access":"writer","x-saldo-side-effects":"Smaže kartu a všechny její odpisové zápisy (zdroj asset) bez ohledu na rok a zapíše událost asset.deleted. Doklad o pořízení a jeho zaúčtování zůstanou.","x-saldo-repeat":"Druhé smazání vrátí 404.","x-saldo-errors":[{"status":422,"when":"Některý odpisový zápis majetku leží v uzamčeném období – „Období do D. M. RRRR je uzamčeno – zaúčtování nelze změnit“"}]}},"/entities/{entity_id}/assets/depreciate":{"post":{"operationId":"postAssetDepreciation","tags":["Majetek, mzdy a cesty"],"summary":"Zaúčtování ročních účetních odpisů majetku","description":"Zaúčtuje účetní odpisy všech karet majetku za kalendářní rok year. Každé kartě nejdřív smaže dosavadní odpisové zápisy s datem v tomto roce a pak vytvoří jeden zápis k 31. 12. roku: MD 551 / D účet oprávek (07x nebo 08x podle účtu majetku) ve výši součtu měsíčních účetních odpisů připadajících na kalendářní rok. Karty bez odpisu v roce (drobný majetek, doodepsaný nebo dosud nezařazený) se jen vynechají. Daňové odpisy se neúčtují – slouží jen výpočtu daně z příjmů. Funguje jen v podvojném účetnictví; hospodářský rok firmy se nezohledňuje.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":12},{"name":"year","in":"query","required":false,"description":"Kalendářní rok odpisů. Bez parametru nebo při nečíselné hodnotě aktuální rok; hodnoty mimo rozsah se zarovnají na 2000 až 2100. Budoucí rok se neodmítá.","schema":{"type":"integer","minimum":2000,"maximum":2100},"example":2026}],"responses":{"200":{"description":"Souhrn zaúčtovaných odpisů.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Firma nevede podvojné účetnictví – „Odpisy se účtují jen v podvojném účetnictví“ 31. 12. zadaného roku leží v uzamčeném období – „Rok RRRR je uzamčený – odpisy už nelze měnit“","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"500":{"description":"Některá karta má zbytkovou hodnotu mimo 0 až pořizovací cenu, nebo při zadané odpisové skupině rok vyřazení před rokem uvedení do užívání – transakce se vrátí a nic se nezaúčtuje (známá chyba, viz createAsset)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"majetek-mzdy-cesty","x-saldo-access":"writer","x-saldo-side-effects":"V jedné transakci smaže odpisové zápisy (zdroj asset) s datem v daném roce a vytvoří nové zápisy MD 551 / D 07x–08x k 31. 12.; zapíše událost asset.depreciated. Nic nevyplácí ani nepodává.","x-saldo-repeat":"Opakované volání za stejný rok smaže dřívější odpisové zápisy roku a vytvoří je znovu podle aktuálních karet (bez změny karet se stejnými částkami); každé volání zapíše novou událost do historie.","x-saldo-errors":[{"status":422,"when":"Firma nevede podvojné účetnictví – „Odpisy se účtují jen v podvojném účetnictví“"},{"status":422,"when":"31. 12. zadaného roku leží v uzamčeném období – „Rok RRRR je uzamčený – odpisy už nelze měnit“"},{"status":500,"when":"Některá karta má zbytkovou hodnotu mimo 0 až pořizovací cenu, nebo při zadané odpisové skupině rok vyřazení před rokem uvedení do užívání – transakce se vrátí a nic se nezaúčtuje (známá chyba, viz createAsset)"}],"x-saldo-response-fields":[{"name":"year","description":"Zaúčtovaný rok"},{"name":"posted","description":"Vytvořené zápisy: asset_id, name, amount"},{"name":"total","description":"Součet zaúčtovaných odpisů v Kč"}]}},"/entities/{entity_id}/assets/{id}/schedule":{"get":{"operationId":"getAssetSchedule","tags":["Majetek, mzdy a cesty"],"summary":"Odpisové plány majetku","description":"Vrátí totéž co detail majetku (GET /entities/{entity_id}/assets/{id}): kartu s daňovým plánem po letech (tax), účetním plánem po měsících (accounting) a účetními odpisy po kalendářních letech (accounting_yearly).","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":12},{"name":"id","in":"path","required":true,"description":"ID karty majetku","schema":{"type":"integer"},"example":5}],"responses":{"200":{"description":"Karta majetku s plány tax, accounting a accounting_yearly.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"500":{"description":"Karta má zbytkovou hodnotu mimo 0 až pořizovací cenu, nebo při zadané odpisové skupině rok vyřazení před rokem uvedení do užívání (známá chyba, viz createAsset)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"majetek-mzdy-cesty","x-saldo-access":"member","x-saldo-side-effects":"Nic nezapisuje.","x-saldo-errors":[{"status":500,"when":"Karta má zbytkovou hodnotu mimo 0 až pořizovací cenu, nebo při zadané odpisové skupině rok vyřazení před rokem uvedení do užívání (známá chyba, viz createAsset)"}],"x-saldo-response-fields":[{"name":"tax","description":"year, rate_or_coefficient (sazba v % nebo koeficient), kind, amount, deductible (u M1 po krácení), accumulated, remaining"},{"name":"accounting","description":"month, year, amount, accumulated, remaining"},{"name":"accounting_yearly","description":"year, amount, accumulated, remaining"}]}},"/entities/{entity_id}/employees":{"get":{"operationId":"listEmployees","tags":["Majetek, mzdy a cesty"],"summary":"Seznam pracovníků","description":"Vrátí všechny pracovníky firmy včetně těch s ukončeným vztahem, seřazené podle příjmení a jména. Obsahuje i osobní údaje z karty (údaje pro JMHZ v details, číslo účtu), které vidí každý člen firmy včetně role viewer.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":12}],"responses":{"200":{"description":"Pole karet pracovníků.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"majetek-mzdy-cesty","x-saldo-access":"member","x-saldo-side-effects":"Nic nezapisuje.","x-saldo-response-fields":[{"name":"id, first_name, last_name, full_name, personal_number","description":"Identifikace pracovníka"},{"name":"contract","description":"hpp, dpc nebo dpp"},{"name":"gross_wage","description":"Sjednaná měsíční mzda nebo odměna v Kč"},{"name":"started_on, ended_on","description":"Trvání pracovněprávního vztahu"},{"name":"declaration, disability, ztpp, student","description":"Údaje pro slevy na dani a pojistné"},{"name":"health_insurer, bank_account, email, note","description":"Kontaktní a evidenční údaje"},{"name":"children","description":"Děti pro daňové zvýhodnění"},{"name":"details","description":"Údaje pro JMHZ a další příznaky (objekt); null, dokud nebyly zadány"}]},"post":{"operationId":"createEmployee","tags":["Majetek, mzdy a cesty"],"summary":"Nový pracovník","description":"Založí kartu pracovníka s druhem pracovněprávního vztahu (HPP, DPČ nebo DPP), sjednanou mzdou a údaji pro výpočet mzdy a pro hlášení JMHZ. Karta sama nevytvoří výplatní pásku ani nepřihlásí pracovníka u ČSSZ či zdravotní pojišťovny – pásky vzniknou voláním POST /entities/{entity_id}/payslips/generate.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":12}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["employee"],"properties":{"employee":{"type":"object","required":["first_name","last_name"],"properties":{"first_name":{"type":"string","description":"Jméno, nejvýše 80 znaků"},"last_name":{"type":"string","description":"Příjmení, nejvýše 80 znaků"},"personal_number":{"type":"string","description":"Osobní číslo"},"contract":{"type":"string","description":"hpp pracovní poměr, dpc dohoda o pracovní činnosti, dpp dohoda o provedení práce","enum":["hpp","dpc","dpp"],"default":"hpp"},"gross_wage":{"type":"number","description":"Sjednaná měsíční hrubá mzda (HPP) nebo měsíční odměna (DPČ, DPP), nejméně 0. Z ní vychází generování pásek; u HPP a DPČ se při vztahu jen po část měsíce krátí podle pracovních dnů (pondělí až pátek), u DPP ne.","default":0},"started_on":{"type":"string","format":"date","description":"Datum nástupu; neplatné datum se uloží jako prázdné"},"ended_on":{"type":"string","format":"date","description":"Datum ukončení; pásky se generují jen za měsíce, kdy vztah trval"},"declaration":{"type":"boolean","description":"Podepsané prohlášení poplatníka. Bez něj se měsíčně neuplatní slevy ani daňové zvýhodnění a z příjmu pod zákonným limitem (DPP, malý rozsah) se sráží 15% srážková daň.","default":true},"disability":{"type":"string","description":"Invalidita: first I. nebo II. stupně (základní sleva), third III. stupně (rozšířená sleva); prázdné = žádná","enum":["first","third"]},"ztpp":{"type":"boolean","description":"Držitel průkazu ZTP/P (sleva na dani, bez minimálního vyměřovacího základu ZP)","default":false},"student":{"type":"boolean","description":"Student – projeví se jen ve zdravotním pojištění (bez minimálního vyměřovacího základu)","default":false},"health_insurer":{"type":"string","description":"Kód zdravotní pojišťovny (111 VZP, 201 VoZP, 205 ČPZP, 207 OZP, 209 ZPŠ, 211 ZPMV, 213 RBP)","enum":["111","201","205","207","209","211","213"]},"bank_account":{"type":"string","description":"Číslo účtu pracovníka (jen evidence, Saldo mzdy nevyplácí)"},"email":{"type":"string","description":"E-mail v platném tvaru"},"note":{"type":"string","description":"Poznámka"},"children":{"type":"array","description":"Děti pro daňové zvýhodnění; odeslaný seznam nahradí uložený celý","items":{"type":"object","properties":{"order":{"type":"integer","description":"Pořadí dítěte (1, 2, 3); určuje výši zvýhodnění. Karta ho neověřuje – nečíselná hodnota se uloží a výpočet mzdy pak skončí chybou 500"},"ztpp":{"type":"boolean","description":"Dítě je držitelem průkazu ZTP/P"},"months":{"type":"array","description":"Měsíce 1–12, za které se zvýhodnění uplatní; bez pole každý měsíc","items":{"type":"integer"}},"first_name":{"type":"string","description":"Jméno dítěte (pro JMHZ)"},"last_name":{"type":"string","description":"Příjmení dítěte (pro JMHZ)"},"birth_date":{"type":"string","format":"date","description":"Datum narození dítěte (pro JMHZ)"},"birth_number":{"type":"string","description":"Rodné číslo dítěte (pro JMHZ)"}}}},"details":{"type":"object","description":"Údaje pro JMHZ a další příznaky. Při úpravě se slučují s uloženými: odeslaný klíč přepíše uložený, prázdná hodnota (null, \"\" nebo prázdný objekt) klíč odstraní, neposlané klíče zůstanou; neznámé klíče se zahodí.","properties":{"oic":{"type":"string","description":"OIČ (IK MPSV) z registrace zaměstnance – 10 číslic"},"employment_id":{"type":"string","description":"ID pracovněprávního vztahu z registrace – až 22 číslic"},"birth_date":{"type":"string","format":"date","description":"Datum narození"},"birth_number":{"type":"string","description":"Rodné číslo; spojuje karty téže osoby pro roční maximální vyměřovací základ"},"activity_code":{"type":"string","description":"Druh činnosti podle registrace (1–9 pracovní poměr, A–J DPČ, T–ZC DPP)"},"eldp_code":{"type":"string","description":"Kód ELDP"},"primary":{"type":"boolean","description":"Primární pracovněprávní vztah u zaměstnavatele"},"workplace":{"type":"object","description":"Místo výkonu práce","properties":{"municipality":{"type":"string","description":"Obec"},"municipality_code":{"type":"string","description":"Kód obce, 6 číslic (číselník ČSÚ)"},"country":{"type":"string","description":"Stát, dvoupísmenný kód (např. CZ)"}}},"weekly_hours":{"type":"number","description":"Sjednaná týdenní pracovní doba (hodin)"},"standard_weekly_hours":{"type":"number","description":"Stanovená týdenní pracovní doba podle § 79 zákoníku práce"},"monthly_hours":{"type":"number","description":"Sjednaný rozsah dohody za měsíc (hodin)"},"hourly_rate":{"type":"number","description":"Hodinová odměna z dohody (Kč)"},"average_hourly_earnings":{"type":"number","description":"Průměrný hodinový výdělek (Kč)"},"garnishment":{"type":"boolean","description":"Srážky ze mzdy (exekuce, insolvence, dohoda o srážkách)"},"shared_children":{"type":"boolean","description":"Tytéž děti vyživuje i jiná osoba ve společné domácnosti"},"other_parent":{"type":"object","description":"Jiná osoba vyživující tytéž děti","properties":{"first_name":{"type":"string","description":"Jméno"},"last_name":{"type":"string","description":"Příjmení"},"birth_date":{"type":"string","format":"date","description":"Datum narození"},"birth_number":{"type":"string","description":"Rodné číslo"}}},"functional_emoluments":{"type":"boolean","description":"Funkční požitky podle § 6 odst. 10 ZDP"},"pensioner":{"type":"boolean","description":"Poživatel starobního důchodu – sleva 6,5 % na sociálním pojistném zaměstnance (od 2025)"},"health_minimum_exempt":{"type":"boolean","description":"Po celý měsíc neplatí minimální vyměřovací základ zdravotního pojištění"}}}}}}},"example":{"employee":{"first_name":"Jana","last_name":"Nováková","contract":"hpp","gross_wage":42000,"started_on":"2026-03-01","declaration":true,"health_insurer":"111","children":[{"first_name":"Tomáš","last_name":"Novák","birth_date":"2018-05-12","order":1}],"details":{"weekly_hours":40,"workplace":{"municipality":"Brno","municipality_code":"582786","country":"CZ"}}}}}}},"responses":{"201":{"description":"Založená karta pracovníka (stejná pole jako v seznamu).","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"majetek-mzdy-cesty","x-saldo-access":"writer","x-saldo-side-effects":"Vytvoří kartu pracovníka a zapíše událost employee.created. Pásky ani účetní zápisy nevytváří.","x-saldo-repeat":"Každé volání založí nového pracovníka; duplicity se nekontrolují."}},"/entities/{entity_id}/employees/{id}":{"patch":{"operationId":"updateEmployee","tags":["Majetek, mzdy a cesty"],"summary":"Úprava karty pracovníka","description":"Změní zaslaná pole karty. Pole children se nahradí celým odeslaným seznamem; details se slučují s uloženými (odeslané klíče přepíší, prázdné hodnoty odstraní, neposlané zůstanou; příznaky se převedou na true/false). Změna se do existujících pásek promítne až jejich přepočtem (POST /entities/{entity_id}/payslips/generate nebo PATCH pásky s gross či bonuses).","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":12},{"name":"id","in":"path","required":true,"description":"ID pracovníka","schema":{"type":"integer"},"example":3}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["employee"],"properties":{"employee":{"type":"object","properties":{"first_name":{"type":"string","description":"Jméno, nejvýše 80 znaků"},"last_name":{"type":"string","description":"Příjmení, nejvýše 80 znaků"},"personal_number":{"type":"string","description":"Osobní číslo"},"contract":{"type":"string","description":"hpp pracovní poměr, dpc dohoda o pracovní činnosti, dpp dohoda o provedení práce","enum":["hpp","dpc","dpp"]},"gross_wage":{"type":"number","description":"Sjednaná měsíční hrubá mzda (HPP) nebo měsíční odměna (DPČ, DPP), nejméně 0"},"started_on":{"type":"string","format":"date","description":"Datum nástupu; neplatné datum se uloží jako prázdné"},"ended_on":{"type":"string","format":"date","description":"Datum ukončení; pásky se generují jen za měsíce, kdy vztah trval"},"declaration":{"type":"boolean","description":"Podepsané prohlášení poplatníka"},"disability":{"type":"string","description":"Invalidita: first I. nebo II. stupně, third III. stupně; prázdné = žádná","enum":["first","third"]},"ztpp":{"type":"boolean","description":"Držitel průkazu ZTP/P"},"student":{"type":"boolean","description":"Student – projeví se jen ve zdravotním pojištění"},"health_insurer":{"type":"string","description":"Kód zdravotní pojišťovny","enum":["111","201","205","207","209","211","213"]},"bank_account":{"type":"string","description":"Číslo účtu pracovníka (jen evidence)"},"email":{"type":"string","description":"E-mail v platném tvaru"},"note":{"type":"string","description":"Poznámka"},"children":{"type":"array","description":"Děti pro daňové zvýhodnění; odeslaný seznam nahradí uložený celý","items":{"type":"object","properties":{"order":{"type":"integer","description":"Pořadí dítěte (1, 2, 3); nečíselná hodnota se uloží a výpočet mzdy pak skončí chybou 500"},"ztpp":{"type":"boolean","description":"Dítě je držitelem průkazu ZTP/P"},"months":{"type":"array","description":"Měsíce 1–12, za které se zvýhodnění uplatní; bez pole každý měsíc","items":{"type":"integer"}},"first_name":{"type":"string","description":"Jméno dítěte"},"last_name":{"type":"string","description":"Příjmení dítěte"},"birth_date":{"type":"string","format":"date","description":"Datum narození dítěte"},"birth_number":{"type":"string","description":"Rodné číslo dítěte"}}}},"details":{"type":"object","description":"Údaje pro JMHZ a příznaky se stejnými klíči jako při založení (oic, employment_id, birth_date, birth_number, activity_code, eldp_code, primary, workplace, weekly_hours, standard_weekly_hours, monthly_hours, hourly_rate, average_hourly_earnings, garnishment, shared_children, other_parent, functional_emoluments, pensioner, health_minimum_exempt). Odeslané klíče přepíší uložené, prázdná hodnota (null, \"\" nebo prázdný objekt) klíč odstraní, neposlané klíče zůstanou, příznaky se převedou na true/false a neznámé klíče se zahodí."}}}}},"example":{"employee":{"gross_wage":54000,"details":{"weekly_hours":40,"pensioner":false}}}}}},"responses":{"200":{"description":"Upravená karta pracovníka.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"majetek-mzdy-cesty","x-saldo-access":"writer","x-saldo-side-effects":"Uloží kartu pracovníka. Událost do historie nezapisuje; výplatní pásky ani zaúčtování nemění.","x-saldo-repeat":"Opakování se stejnými daty vede ke stejnému stavu."},"delete":{"operationId":"deleteEmployee","tags":["Majetek, mzdy a cesty"],"summary":"Smazání pracovníka bez výplatních pásek","description":"Smaže kartu pracovníka, který nemá žádnou výplatní pásku. Pracovníka s páskami nelze smazat – ukončete vztah polem ended_on. Cestovní příkazy s tímto pracovníkem zůstanou (s uloženým jménem cestujícího, employee_name bude null).","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":12},{"name":"id","in":"path","required":true,"description":"ID pracovníka","schema":{"type":"integer"},"example":3}],"responses":{"204":{"description":"Prázdná odpověď."},"422":{"description":"Pracovník má aspoň jednu výplatní pásku – „Pracovník má výplatní pásky – nastavte datum ukončení“","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"majetek-mzdy-cesty","x-saldo-access":"writer","x-saldo-side-effects":"Smaže kartu pracovníka. Událost do historie nezapisuje.","x-saldo-repeat":"Druhé smazání vrátí 404.","x-saldo-errors":[{"status":422,"when":"Pracovník má aspoň jednu výplatní pásku – „Pracovník má výplatní pásky – nastavte datum ukončení“"}],"x-saldo-example":{"note":"Maže pracovníka bez výplatních pásek; pracovníka s páskami API odmítne s chybou 422."}}},"/entities/{entity_id}/payslips":{"get":{"operationId":"listPayslips","tags":["Majetek, mzdy a cesty"],"summary":"Výplatní pásky za rok nebo měsíc","description":"Vrátí výplatní pásky firmy za kalendářní rok, volitelně jen za jeden měsíc, seřazené podle měsíce a ID pracovníka. Páska nese hrubou a čistou mzdu, náklady zaměstnavatele, stav (draft koncept, approved schváleno, posted zaúčtováno) a v data celý výpočet: pojistné, daň, účetní předpis, krácení, docházku a upozornění.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":12},{"name":"year","in":"query","required":false,"description":"Rok pásek; bez parametru nebo při nečíselné hodnotě aktuální rok, mimo rozsah se zarovná na 2000 až 2100.","schema":{"type":"integer","minimum":2000,"maximum":2100},"example":2026},{"name":"month","in":"query","required":false,"description":"Měsíc 1–12; bez něj vrátí pásky celého roku.","schema":{"type":"integer"},"example":8}],"responses":{"200":{"description":"Pole výplatních pásek.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"majetek-mzdy-cesty","x-saldo-access":"member","x-saldo-side-effects":"Nic nezapisuje.","x-saldo-response-fields":[{"name":"id, employee_id, employee_name, year, month","description":"Páska a pracovník"},{"name":"gross, net, employer_cost","description":"Hrubá mzda, čistá mzda a celkové náklady zaměstnavatele v Kč"},{"name":"status","description":"draft, approved nebo posted"},{"name":"data","description":"Výpočet: insured, assessment_base, employee, employer, health_min_base_topup, tax, net, payout, postings, warnings, base_gross, bonuses, případně proration a attendance"}]}},"/entities/{entity_id}/payslips/calculate":{"post":{"operationId":"calculatePayslip","tags":["Majetek, mzdy a cesty"],"summary":"Orientační výpočet mzdy bez uložení","description":"Spočítá výplatní pásku z anonymních vstupů bez vazby na pracovníka a nic neuloží: pojistné zaměstnance i zaměstnavatele, zálohu nebo srážkovou daň se slevami a daňovým zvýhodněním, čistou mzdu, částku k výplatě, náklady zaměstnavatele a účetní předpis. Na rozdíl od veřejné kalkulačky POST /calc/payroll nepřijímá agreed_wage, ytd_social_base, pensioner_discount ani health_minimum_exempt (ignorují se).","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":12}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"year":{"type":"integer","description":"Rok sazeb; bez hodnoty aktuální rok"},"month":{"type":"integer","description":"Měsíc 1–12; bez hodnoty aktuální měsíc. Výsledek tohoto výpočtu na měsíci nezávisí, jiná hodnota ale skončí chybou 500"},"contract":{"type":"string","description":"Druh pracovněprávního vztahu; jiná hodnota skončí chybou 500","enum":["hpp","dpc","dpp"],"default":"hpp"},"gross":{"type":"number","description":"Hrubá mzda v Kč, nezáporná (záporná skončí chybou 500); bez hodnoty nebo nečíselná 0"},"declaration":{"type":"boolean","description":"Podepsané prohlášení poplatníka","default":true},"disability":{"type":"string","description":"Stupeň invalidity; first/second a 1/2 = I. a II. stupeň, third a 3 = III. stupeň, 0 nebo prázdné = žádná","enum":["first","second","third","1","2","3","0"]},"ztpp":{"type":"boolean","description":"Držitel průkazu ZTP/P","default":false},"student":{"type":"boolean","description":"Student","default":false},"children":{"type":"array","description":"Děti pro daňové zvýhodnění (uplatní se ve všech měsících)","items":{"type":"object","properties":{"order":{"type":"integer","description":"Pořadí dítěte (1, 2, 3)"},"ztpp":{"type":"boolean","description":"Dítě je držitelem průkazu ZTP/P"}}}}}},"example":{"year":2026,"month":9,"contract":"hpp","gross":52000,"declaration":true,"children":[{"order":1}]}}}},"responses":{"200":{"description":"Výpočet výplatní pásky.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Pro zadaný rok nejsou v Saldu zákonné sazby – „Pro rok RRRR nejsou k dispozici zákonné sazby“","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"500":{"description":"Vstup, který výpočet odmítne, ale API předem neověří: záporná gross, month mimo 1–12 (i nečíselný), neznámý contract nebo disability, nečíselné children[].order (známá chyba: výjimka místo chyby 422)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"majetek-mzdy-cesty","x-saldo-access":"member","x-saldo-side-effects":"Nic nezapisuje.","x-saldo-errors":[{"status":422,"when":"Pro zadaný rok nejsou v Saldu zákonné sazby – „Pro rok RRRR nejsou k dispozici zákonné sazby“"},{"status":500,"when":"Vstup, který výpočet odmítne, ale API předem neověří: záporná gross, month mimo 1–12 (i nečíselný), neznámý contract nebo disability, nečíselné children[].order (známá chyba: výjimka místo chyby 422)"}],"x-saldo-response-fields":[{"name":"gross","description":"Hrubá mzda"},{"name":"insured","description":"Účast na pojištění: social, health"},{"name":"assessment_base","description":"Vyměřovací základy: social, health"},{"name":"employee, employer","description":"Pojistné zaměstnance a zaměstnavatele: social, health, total"},{"name":"health_min_base_topup","description":"Doplatek zdravotního pojistného do minimálního vyměřovacího základu"},{"name":"tax","description":"Daň: base, rounded_base, rate_split, advance_before_credits, credits, child_benefit (total, as_credit, bonus), advance, withholding, kind (advance nebo withholding)"},{"name":"net","description":"Čistá mzda"},{"name":"payout","description":"K výplatě: čistá mzda plus daňový bonus"},{"name":"employer_cost","description":"Hrubá mzda plus pojistné zaměstnavatele"},{"name":"postings","description":"Účetní předpis, který by se zaúčtoval: debit, credit, amount, text"},{"name":"warnings","description":"Upozornění (česky)"}]}},"/entities/{entity_id}/payslips/generate":{"post":{"operationId":"generatePayslips","tags":["Majetek, mzdy a cesty"],"summary":"Vygenerování výplatních pásek za měsíc","description":"Vytvoří nebo přepočítá výplatní pásky všech pracovníků, jejichž vztah v daném měsíci trval aspoň jeden den. Základem je mzda z karty pracovníka; u HPP a DPČ trvajících jen část měsíce se krátí podle pracovních dnů (pondělí až pátek), u DPP ne. Zachová uložené prémie, docházku a roční zúčtování pásky, ruční změnu hrubé mzdy přepíše a nezaúčtované pásky vrátí do stavu draft. Zaúčtované pásky ponechá beze změny. Rok se zadává v query, měsíc v těle.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":12},{"name":"year","in":"query","required":false,"description":"Rok pásek; bez parametru nebo při nečíselné hodnotě aktuální rok, mimo rozsah se zarovná na 2000 až 2100.","schema":{"type":"integer","minimum":2000,"maximum":2100},"example":2026}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["month"],"properties":{"month":{"type":"integer","description":"Měsíc pásek 1–12; chybějící nebo nečíselný měsíc, 0 nebo číslo nad 12 vrátí 400. Záporné číslo API neodmítne – s aktivními pracovníky skončí chybou 500 (známá chyba)","minimum":1,"maximum":12}}},"example":{"month":12}}}},"responses":{"201":{"description":"Pásky měsíce po generování.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Pro rok nejsou v Saldu zákonné sazby – „Pro rok RRRR nejsou k dispozici zákonné sazby“","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"500":{"description":"Výpočet některé pásky selže (např. nečíselné pořadí dítěte na kartě pracovníka nebo záporný měsíc) – známá chyba; pásky pracovníků zpracovaných před ním zůstanou uložené","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"majetek-mzdy-cesty","x-saldo-access":"writer","x-saldo-side-effects":"Vytvoří nebo přepíše nezaúčtované výplatní pásky měsíce (stav draft) a zapíše událost payroll.generated. Nic nezaúčtuje, nevyplatí ani nepodá (JMHZ se připravuje zvlášť). Uzamčení období se nekontroluje, protože pásky samy nejsou účetními zápisy. Pásky se ukládají po jedné bez společné transakce.","x-saldo-repeat":"Duplicitní pásky nevzniknou (jedna páska na pracovníka a měsíc); opakované volání znovu přepočítá nezaúčtované pásky a zapíše novou událost.","x-saldo-errors":[{"status":422,"when":"Pro rok nejsou v Saldu zákonné sazby – „Pro rok RRRR nejsou k dispozici zákonné sazby“"},{"status":500,"when":"Výpočet některé pásky selže (např. nečíselné pořadí dítěte na kartě pracovníka nebo záporný měsíc) – známá chyba; pásky pracovníků zpracovaných před ním zůstanou uložené"}],"x-saldo-response-fields":[{"name":"year, month","description":"Období"},{"name":"payslips","description":"Pásky pracovníků, jejichž vztah v měsíci trval (nové, přepočtené i nezměněné zaúčtované), ve tvaru jako v seznamu"}],"x-saldo-example":{"note":"Prosinec aktuálního roku ukázková firma ještě nemá, takže příklad vytvoří nové pásky ve stavu draft."}}},"/entities/{entity_id}/payslips/{id}":{"patch":{"operationId":"updatePayslip","tags":["Majetek, mzdy a cesty"],"summary":"Úprava výplatní pásky – mzda, prémie, stav a docházka","description":"Pole se posílají přímo v těle bez obalu. gross nebo bonuses pásku přepočítají podle aktuální karty pracovníka a vrátí ji do stavu draft: gross nastaví novou základní mzdu a zruší krácení, bonuses nastaví prémie. Přepočet bez bonuses nastaví prémie na 0, přepočet jen s bonuses zachová dosavadní základ i krácení. status přepne draft/approved (jiné hodnoty se ignorují). attendance nahradí uloženou docházku, která slouží jen pro JMHZ a výpočet mzdy nemění. U zaúčtované pásky lze měnit jen docházku.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":12},{"name":"id","in":"path","required":true,"description":"ID výplatní pásky","schema":{"type":"integer"},"example":41}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"gross":{"type":"number","description":"Nová základní hrubá mzda pásky v Kč (bez prémií); nečíselná hodnota se počítá jako 0; záporný součet s bonuses skončí chybou 500 (viz chyby)"},"bonuses":{"type":"number","description":"Prémie a odměny přičtené k základní mzdě v Kč"},"status":{"type":"string","description":"Stav pásky; zaúčtování provede POST …/post_entries","enum":["draft","approved"]},"attendance":{"type":"object","description":"Docházka pro JMHZ; prázdné hodnoty se vynechají, desetinná čárka je dovolena, jiné klíče se zahodí","properties":{"worked_hours":{"type":"number","description":"Odpracované hodiny"},"overtime_hours":{"type":"number","description":"Přesčasové hodiny (z odpracovaných)"},"overtime_pay":{"type":"number","description":"Příplatky za práci přesčas (Kč)"},"vacation_hours":{"type":"number","description":"Hodiny čerpané dovolené"},"vacation_pay":{"type":"number","description":"Náhrada mzdy za dovolenou (Kč)"},"unpaid_hours":{"type":"number","description":"Hodiny neplaceného volna"}}}}},"example":{"attendance":{"worked_hours":160,"overtime_hours":4,"vacation_hours":8,"vacation_pay":2150}}}}},"responses":{"200":{"description":"Upravená výplatní páska (tvar jako v seznamu).","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Páska je zaúčtovaná a požadavek mění něco jiného než docházku – „Zaúčtovanou pásku nelze měnit – smažte ji a vytvořte znovu“","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"500":{"description":"Přepočet selže – záporný součet gross a bonuses nebo nečíselné pořadí dítěte na kartě (známá chyba); docházka z téhož požadavku už zůstane uložená","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"majetek-mzdy-cesty","x-saldo-access":"writer","x-saldo-side-effects":"Uloží pásku (přepočet, stav, docházku) a zapíše událost payroll.updated. Účetní zápisy nemění – změněnou pásku je třeba znovu zaúčtovat. Uzamčení období se nekontroluje.","x-saldo-repeat":"Opakování se stejnými hodnotami vede ke stejnému výsledku; každé volání zapíše událost payroll.updated.","x-saldo-errors":[{"status":422,"when":"Páska je zaúčtovaná a požadavek mění něco jiného než docházku – „Zaúčtovanou pásku nelze měnit – smažte ji a vytvořte znovu“"},{"status":500,"when":"Přepočet selže – záporný součet gross a bonuses nebo nečíselné pořadí dítěte na kartě (známá chyba); docházka z téhož požadavku už zůstane uložená"}],"x-saldo-example":{"note":"Docházku lze zapsat i do zaúčtované pásky; změna gross nebo bonuses vyžaduje nezaúčtovanou pásku."}},"delete":{"operationId":"deletePayslip","tags":["Majetek, mzdy a cesty"],"summary":"Smazání výplatní pásky","description":"Smaže výplatní pásku včetně jejích účetních zápisů; u zaúčtované pásky pak přepočte zápis zaokrouhlení sociálního pojistného zaměstnavatele za měsíc. V uzamčeném období nelze.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":12},{"name":"id","in":"path","required":true,"description":"ID výplatní pásky","schema":{"type":"integer"},"example":41}],"responses":{"204":{"description":"Prázdná odpověď."},"422":{"description":"Poslední den měsíce pásky leží v uzamčeném období – „Období je uzamčeno – pásku nelze smazat“","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"majetek-mzdy-cesty","x-saldo-access":"writer","x-saldo-side-effects":"V jedné transakci smaže účetní zápisy pásky (zdroj payroll), pásku samotnou a u zaúčtované pásky přepočte zápis zaokrouhlení sociálního pojistného zaměstnavatele za měsíc; zapíše událost payroll.deleted.","x-saldo-repeat":"Druhé smazání vrátí 404.","x-saldo-errors":[{"status":422,"when":"Poslední den měsíce pásky leží v uzamčeném období – „Období je uzamčeno – pásku nelze smazat“"}]}},"/entities/{entity_id}/payslips/{id}/post_entries":{"post":{"operationId":"postPayslipEntries","tags":["Majetek, mzdy a cesty"],"summary":"Zaúčtování výplatní pásky","description":"Zaúčtuje mzdový předpis pásky k poslednímu dni jejího měsíce a nastaví stav posted; schválení se nevyžaduje. Zápisy vzniknou z výpočtu pásky (data.postings): hrubá mzda MD 521 / D 331, pojistné zaměstnavatele MD 524 / D 336, pojistné zaměstnance MD 331 / D 336, záloha nebo srážková daň MD 331 / D 342, daňový bonus MD 342 / D 331. Pak přepočte zápis zaokrouhlení sociálního pojistného zaměstnavatele za měsíc (rozdíl mezi součtem z pásek a pojistným zaokrouhleným jednou z úhrnu vyměřovacích základů, jako v hlášení ČSSZ). Mzdu nevyplácí ani neodvádí pojistné a daň – úhrady se párují z banky.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":12},{"name":"id","in":"path","required":true,"description":"ID výplatní pásky","schema":{"type":"integer"},"example":41}],"responses":{"200":{"description":"Zaúčtovaná výplatní páska se stavem posted.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Firma nevede podvojné účetnictví – „Mzdy se účtují jen v podvojném účetnictví“ Poslední den měsíce pásky leží v uzamčeném období – „Období je uzamčeno“","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"majetek-mzdy-cesty","x-saldo-access":"writer","x-saldo-side-effects":"V jedné transakci smaže dřívější zápisy pásky, vytvoří nové účetní zápisy (zdroj payroll) s datem posledního dne měsíce, nastaví stav posted a přepočte zápis zaokrouhlení sociálního pojistného zaměstnavatele za měsíc; zapíše událost payroll.posted.","x-saldo-repeat":"Opakované zaúčtování nahradí zápisy pásky stejnými novými; stav zůstane posted.","x-saldo-errors":[{"status":422,"when":"Firma nevede podvojné účetnictví – „Mzdy se účtují jen v podvojném účetnictví“"},{"status":422,"when":"Poslední den měsíce pásky leží v uzamčeném období – „Období je uzamčeno“"}]}},"/entities/{entity_id}/payslips/jmhz":{"get":{"operationId":"getJmhzOverview","tags":["Majetek, mzdy a cesty"],"summary":"Kontrola a stav hlášení JMHZ za měsíc","description":"Zkontroluje data pro jednotné měsíční hlášení zaměstnavatele (JMHZ) za měsíc a vrátí jeho stav: chyby, které brání sestavení XML, upozornění, lhůtu pro podání (20. den následujícího měsíce posunutý na pracovní den, za leden až březen 2026 do 30. 6. 2026), lhůtu pro storno, souhrny daně a pojistného z pásek, druh hlášení, které by se teď vytvořilo, a historii uložených podání. Hlášení se podává za měsíce od ledna 2026 a až po skončení měsíce.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":12},{"name":"year","in":"query","required":false,"description":"Rok hlášení; bez parametru nebo při nečíselné hodnotě aktuální rok, mimo rozsah se zarovná na 2000 až 2100.","schema":{"type":"integer","minimum":2000,"maximum":2100},"example":2026},{"name":"month","in":"query","required":true,"description":"Měsíc hlášení","schema":{"type":"integer","minimum":1,"maximum":12},"example":8}],"responses":{"200":{"description":"Stav a kontrola hlášení JMHZ.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Chybí nebo je neplatný měsíc – „Měsíc hlášení musí být číslo 1 až 12.“","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"majetek-mzdy-cesty","x-saldo-access":"member","x-saldo-side-effects":"Nic nezapisuje.","x-saldo-errors":[{"status":422,"when":"Chybí nebo je neplatný měsíc – „Měsíc hlášení musí být číslo 1 až 12.“"}],"x-saldo-response-fields":[{"name":"year, month, period","description":"Období; period ve tvaru RRRR-MM"},{"name":"state","description":"none (nic uloženo), draft (připraveno), filed (řádné označeno jako podané), cancelled (stornováno)"},{"name":"kind","description":"Druh, který by se teď vytvořil: regular, nebo corrective po podaném řádném hlášení"},{"name":"ready","description":"true, když kontrola nenašla chyby"},{"name":"errors, warnings","description":"Nálezy kontroly: level, code, subject, field, message, employee_id"},{"name":"due_date, cancellation_deadline, can_cancel","description":"Lhůta podání, poslední den pro storno a zda lze ještě stornovat"},{"name":"totals","description":"Souhrny: tax, insurance, payslips a employer_rounding; null pro rok bez sazeb"},{"name":"employments, persons","description":"Počet pracovněprávních vztahů a osob v hlášení"},{"name":"submission_id, proof_state","description":"GUID řádného podání a stav doložení posledního podaného hlášení"},{"name":"plan","description":"Jen pro opravné hlášení: corrected, added, cancelled, stale (vztahy podle názvu)"},{"name":"filings","description":"Uložená podání JMHZ měsíce od nejnovějšího: id, filing_type (B, O, S), status, proof_state, filed_on, submission_id, forms (počet formulářů), filled_at"}],"x-saldo-example":{"note":"Ukázková firma má pro leden vyplněné údaje pro JMHZ, kontrola proto nenašla chyby (ready true) a vrací jen upozornění na uplynulou lhůtu a chybějící OIČ."}}},"/entities/{entity_id}/payslips/jmhz/xml":{"get":{"operationId":"downloadJmhzXml","tags":["Majetek, mzdy a cesty"],"summary":"Stažení XML hlášení JMHZ a jeho uložení jako podání","description":"Sestaví XML jednotného měsíčního hlášení zaměstnavatele podle schématu ČSSZ jmhzPodani 1.4.3, uloží je jako podání JMHZ ve stavu draft a vrátí jako soubor. Řádné hlášení (regular) jde vytvořit, dokud řádné hlášení měsíce není označené jako podané, a znovu po podaném stornu; opravné (corrective) a storno (cancellation) navazují na podané řádné hlášení a přebírají jeho GUID. Opravné hlášení opraví známé formuláře, přidá nové a formuláře vztahů, které z hlášení zmizely, do lhůty pro storno stornuje. Storno ruší celé hlášení a lze je jen do 20. dne následujícího měsíce. ČSSZ nic neodesílá – podání se označí jako podané až přes PATCH /entities/{entity_id}/filings/{id} se status filed.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":12},{"name":"year","in":"query","required":false,"description":"Rok hlášení; bez parametru nebo při nečíselné hodnotě aktuální rok, mimo rozsah se zarovná na 2000 až 2100.","schema":{"type":"integer","minimum":2000,"maximum":2100},"example":2026},{"name":"month","in":"query","required":true,"description":"Měsíc hlášení","schema":{"type":"integer","minimum":1,"maximum":12},"example":8},{"name":"kind","in":"query","required":false,"description":"Druh hlášení – řádné, opravné nebo storno","schema":{"type":"string","enum":["regular","corrective","cancellation"],"default":"regular"},"example":"regular"}],"responses":{"200":{"description":"XML hlášení jako příloha jmhz-RRRR-MM-radne.xml, jmhz-RRRR-MM-opravne.xml nebo jmhz-RRRR-MM-storno.xml.","content":{"application/xml":{"schema":{"type":"string","format":"binary"}}}},"422":{"description":"Kontrola JMHZ našla chyby (neukončený měsíc, období před lednem 2026, chybějící údaje, storno po lhůtě) – error „Hlášení nelze sestavit – nejprve opravte chyby z kontroly JMHZ.“ a pole issues s nálezy kontroly Chybí nebo je neplatný měsíc – „Měsíc hlášení musí být číslo 1 až 12.“ Neznámý druh – „Druh hlášení musí být regular, corrective nebo cancellation.“ Řádné hlášení je už podané – „Řádné hlášení za M/RRRR je podané – změny podejte opravným hlášením…“ Opravné hlášení nebo storno bez řádného hlášení – „Za M/RRRR zatím není řádné hlášení – … navazuje na podané řádné hlášení.“ Řádné hlášení není označené jako podané – „Řádné hlášení za M/RRRR není označené jako podané – …“ Hlášení je stornované a chce se opravné nebo storno – „Hlášení za M/RRRR je stornované – podejte nové řádné hlášení.“","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"403":{"description":"API klíč jen pro čtení Hlavička Sec-Fetch-Site je jiná než same-origin nebo none","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"majetek-mzdy-cesty","x-saldo-access":"writer","x-saldo-access-note":"Přestože jde o GET, požadavek zakládá podání, a proto ho odmítne i API klíč jen pro čtení (403 READ_ONLY_KEY) a požadavek z cizího webu podle hlavičky Sec-Fetch-Site (403 CROSS_SITE).","x-saldo-read-only-key":"refused","x-saldo-side-effects":"Vytvoří nebo přepíše podání JMHZ (kind jmhz, period RRRR-MM, filing_type B řádné, O opravné, S storno, stav draft) s XML, GUID podání, seznamem formulářů a časem vyplnění; zapíše událost payroll.jmhz. ČSSZ nic neodesílá ani nepodává, účetnictví nemění.","x-saldo-limits":"Jeden soubor pojme nejvýše 1 500 formulářů pracovněprávních vztahů; větší hlášení tento endpoint nesestaví a skončí chybou 500.","x-saldo-repeat":"Dokud je podání daného druhu ve stavu draft, opakované stažení přepíše totéž podání novým XML a časem vyplnění a zachová GUID podání. GUID formulářů zůstanou u řádného hlášení a u formulářů známých z podaných hlášení; vztahy nově přidané v opravném hlášení dostanou při každém stažení nové GUID. Nové podání vznikne, jen když rozpracované podání daného druhu neexistuje (například další opravné hlášení po podaném opravném nebo nové řádné po podaném stornu).","x-saldo-errors":[{"status":422,"when":"Kontrola JMHZ našla chyby (neukončený měsíc, období před lednem 2026, chybějící údaje, storno po lhůtě) – error „Hlášení nelze sestavit – nejprve opravte chyby z kontroly JMHZ.“ a pole issues s nálezy kontroly"},{"status":422,"when":"Chybí nebo je neplatný měsíc – „Měsíc hlášení musí být číslo 1 až 12.“"},{"status":422,"when":"Neznámý druh – „Druh hlášení musí být regular, corrective nebo cancellation.“"},{"status":422,"when":"Řádné hlášení je už podané – „Řádné hlášení za M/RRRR je podané – změny podejte opravným hlášením…“"},{"status":422,"when":"Opravné hlášení nebo storno bez řádného hlášení – „Za M/RRRR zatím není řádné hlášení – … navazuje na podané řádné hlášení.“"},{"status":422,"when":"Řádné hlášení není označené jako podané – „Řádné hlášení za M/RRRR není označené jako podané – …“"},{"status":422,"when":"Hlášení je stornované a chce se opravné nebo storno – „Hlášení za M/RRRR je stornované – podejte nové řádné hlášení.“"},{"status":403,"code":"READ_ONLY_KEY","when":"API klíč jen pro čtení"},{"status":403,"code":"CROSS_SITE","when":"Hlavička Sec-Fetch-Site je jiná než same-origin nebo none"}],"x-saldo-example":{"note":"Ukázková firma má pro leden vyplněné údaje pro JMHZ, příklad proto vrací XML řádného hlášení a uloží je jako podání ve stavu draft."}}},"/entities/{entity_id}/payslips/jmhz/validation":{"post":{"operationId":"validateJmhz","tags":["Majetek, mzdy a cesty"],"summary":"Předběžná kontrola hlášení JMHZ validační službou ČSSZ","description":"Sestaví XML hlášení JMHZ stejně jako stažení, ale neuloží je, a odešle je anonymní validační službě ČSSZ ePodaniValidace. Vrátí, zda služba hlášení přijala bez chyb, a její nálezy s přiřazeným pracovníkem. Nic nepodává. Parametry year, month a kind se posílají v těle JSON.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":12}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["month"],"properties":{"year":{"type":"integer","description":"Rok hlášení; bez hodnoty aktuální rok, mimo rozsah se zarovná","minimum":2000,"maximum":2100},"month":{"type":"integer","description":"Měsíc hlášení","minimum":1,"maximum":12},"kind":{"type":"string","description":"Druh hlášení; bez hodnoty regular, nebo corrective, je-li řádné hlášení podané","enum":["regular","corrective","cancellation"]}}},"example":{"year":2026,"month":1}}}},"responses":{"200":{"description":"Výsledek kontroly ČSSZ.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"502":{"description":"Validační služba ČSSZ je nedostupná, neodpověděla včas, vrátila chybu nebo odpověď bez výsledku (česká zpráva v error)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"422":{"description":"Kontrola JMHZ našla chyby – error „Hlášení nelze sestavit – nejprve opravte chyby z kontroly JMHZ.“ a pole issues Chybí nebo je neplatný měsíc – „Měsíc hlášení musí být číslo 1 až 12.“ Neznámý druh – „Druh hlášení musí být regular, corrective nebo cancellation.“ Druh neodpovídá stavu podání (řádné už podané, opravné nebo storno bez podaného řádného, stornované hlášení)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"majetek-mzdy-cesty","x-saldo-access":"writer","x-saldo-side-effects":"Odešle XML hlášení včetně osobních údajů zaměstnanců na produkční validační službu ČSSZ (https://epodani.cssz.cz/ePodaniValidace.svc), která je jen zkontroluje. Nic nepodá ani neuloží jako podání; zapíše událost payroll.jmhz_validation do historie.","x-saldo-limits":"Časové limity spojení se službou ČSSZ – navázání 10 s, odeslání 20 s, čekání na odpověď 45 s. Hlášení nad 1 500 formulářů se nesestaví (chyba 500).","x-saldo-repeat":"Každé volání znovu odešle XML ke kontrole a zapíše novou událost.","x-saldo-errors":[{"status":502,"when":"Validační služba ČSSZ je nedostupná, neodpověděla včas, vrátila chybu nebo odpověď bez výsledku (česká zpráva v error)"},{"status":422,"when":"Kontrola JMHZ našla chyby – error „Hlášení nelze sestavit – nejprve opravte chyby z kontroly JMHZ.“ a pole issues"},{"status":422,"when":"Chybí nebo je neplatný měsíc – „Měsíc hlášení musí být číslo 1 až 12.“"},{"status":422,"when":"Neznámý druh – „Druh hlášení musí být regular, corrective nebo cancellation.“"},{"status":422,"when":"Druh neodpovídá stavu podání (řádné už podané, opravné nebo storno bez podaného řádného, stornované hlášení)"}],"x-saldo-response-fields":[{"name":"ok","description":"true, když služba vrátila výsledek OK"},{"name":"request_id","description":"ID požadavku u ČSSZ"},{"name":"errors","description":"Nálezy služby: category, code (číslo chyby ČSSZ), message, form (GUID formuláře), employee (pracovník a vztah)"},{"name":"kind","description":"Kontrolovaný druh hlášení"},{"name":"checked_at","description":"Čas kontroly"}],"x-saldo-example":{"note":"Ukázková firma má pro leden vyplněné údaje pro JMHZ. Volání služby ČSSZ se při záznamu příkladu nahrazuje smyšlenou odpovědí ve formátu služby (výsledek OK)."}}},"/entities/{entity_id}/trips":{"get":{"operationId":"listTrips","tags":["Majetek, mzdy a cesty"],"summary":"Seznam cestovních příkazů","description":"Vrátí cestovní příkazy firmy od nejpozdějšího odjezdu, každý s uloženými vstupy a výsledkem výpočtu náhrad. S parametrem year jen cesty s odjezdem v hospodářském roce firmy začínajícím v tomto roce (u kalendářního roku 1. 1. až 31. 12.).","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":12},{"name":"year","in":"query","required":false,"description":"Rok odjezdu; bez parametru cesty všech let, nečíselná hodnota znamená aktuální rok.","schema":{"type":"integer","minimum":2000,"maximum":2100},"example":2026}],"responses":{"200":{"description":"Pole cestovních příkazů.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"majetek-mzdy-cesty","x-saldo-access":"member","x-saldo-side-effects":"Nic nezapisuje.","x-saldo-limits":"Vrátí nejvýše 500 cest, bez stránkování.","x-saldo-response-fields":[{"name":"id, employee_id, employee_name, traveller_name","description":"Příkaz a cestující"},{"name":"purpose, destination, departed_at, returned_at","description":"Účel, místo a čas cesty"},{"name":"status","description":"draft (koncept), approved (schváleno), paid (proplaceno) – jen označení"},{"name":"total","description":"Náhrady celkem v Kč (bez zahraničního stravného v cizí měně)"},{"name":"input, result","description":"Uložené vstupy formuláře a výsledek výpočtu (tvar jako u výpočtu); null u příkazu, který nevznikl přes API ani aplikaci (např. ukázková data), a total je pak 0"}]},"post":{"operationId":"createTrip","tags":["Majetek, mzdy a cesty"],"summary":"Nový cestovní příkaz s výpočtem náhrad","description":"Spočítá náhrady stejně jako POST /entities/{entity_id}/trips/calculate a uloží cestovní příkaz se vstupy, výsledkem a celkovou částkou. Stav se zadává v trip.status (výchozí draft).","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":12}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["trip"],"properties":{"trip":{"type":"object","required":["destination","departure","arrival"],"properties":{"employee_id":{"type":"integer","description":"Pracovník této firmy; neexistující vrátí 404"},"traveller_name":{"type":"string","description":"Jméno cestujícího; bez hodnoty jméno pracovníka"},"traveller":{"type":"string","description":"employee zaměstnanec (náhrady podle zákoníku práce), self_employed OSVČ (výdaje podle § 24 odst. 2 písm. k) ZDP). Bez hodnoty employee, je-li zadán employee_id nebo jde o právnickou osobu, jinak self_employed.","enum":["employee","self_employed"]},"purpose":{"type":"string","description":"Účel cesty; výpočet neovlivní"},"destination":{"type":"string","description":"Místo cesty; při uložení povinné, nejvýše 200 znaků"},"departure":{"type":"string","description":"Odjezd, datum a čas ISO 8601 (např. 2026-09-21T06:30). Zadávejte místní čas bez časového pásma – server jej uloží beze změny jako UTC a podle něj dělí cestu na kalendářní dny."},"arrival":{"type":"string","description":"Návrat ve stejném tvaru; musí být po odjezdu a nejvýš 366 dní po něm"},"km":{"type":"number","description":"Ujeté km soukromým vozidlem; bez hodnoty nebo 0 se náhrada za vozidlo nepočítá"},"vehicle_kind":{"type":"string","description":"Soukromé vozidlo; truck má u zaměstnance dvojnásobnou sazbu osobního auta, electric počítá s elektřinou","enum":["car","motorcycle","truck","electric"],"default":"car"},"consumption":{"type":"number","description":"Průměrná spotřeba na 100 km podle technického průkazu (l nebo kWh)"},"fuel":{"type":"string","description":"Druh paliva","enum":["petrol95","petrol98","diesel","lpg","electricity"],"default":"petrol95"},"fuel_price":{"type":"number","description":"Cena paliva za litr nebo kWh podle dokladu; bez ní průměrná cena z vyhlášky platná v den odjezdu. Palivo bez průměrné ceny (např. lpg) bez fuel_price dá náhradu za PHM 0 a upozornění."},"accommodation":{"type":"number","description":"Ubytování v Kč, nezáporné"},"other":{"type":"number","description":"Ostatní nutné vedlejší výdaje v Kč, nezáporné"},"foreign_country":{"type":"string","description":"Kód cílové země (ISO 3166-1 alpha-2, jiný než CZ); zapne zahraniční stravné"},"hours_abroad":{"type":"number","description":"Hodiny strávené v zahraničí, nejvýš délka cesty; přechod hranice se umístí doprostřed cesty. Bez hodnoty 0"},"meals":{"type":"array","description":"Bezplatně poskytnutá jídla, která krátí stravné. V této verzi každá položka pole skončí chybou 400 „invalid date“ (aplikace datum jídla nepřečte), proto výpočet s jídly zatím nejde","items":{"type":"object","required":["date"],"properties":{"date":{"type":"string","format":"date","description":"Den (RRRR-MM-DD)"},"count":{"type":"integer","description":"Počet jídel v daném dni"}}}},"status":{"type":"string","description":"draft koncept, approved schváleno, paid proplaceno – jen označení, nic neúčtuje ani nevyplácí","enum":["draft","approved","paid"],"default":"draft"}}}}},"example":{"trip":{"employee_id":1,"destination":"Brno","purpose":"Jednání s klientem","departure":"2026-09-21T06:30","arrival":"2026-09-21T19:10","km":420,"vehicle_kind":"car","consumption":6.1,"fuel":"diesel","status":"draft"}}}}},"responses":{"201":{"description":"Uložený cestovní příkaz (tvar jako v seznamu).","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"description":"employee_id nepatří pracovníkovi této firmy – „Záznam nebyl nalezen“","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"422":{"description":"Chybí nebo je nečitelný odjezd či návrat, návrat není po odjezdu nebo cesta trvá přes 366 dní (zprávy jako u výpočtu) Pro rok odjezdu nejsou v Saldu sazby – „Pro rok RRRR nejsou k dispozici zákonné sazby“","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"400":{"description":"Pole meals obsahuje jakoukoli položku – v této verzi vždy „invalid date“ (známá chyba zpracování jídel)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"500":{"description":"Vstup, který výpočet odmítne, ale API předem neověří (stejné případy jako u výpočtu); příkaz se neuloží – známá chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"majetek-mzdy-cesty","x-saldo-access":"writer","x-saldo-side-effects":"Vytvoří cestovní příkaz a zapíše událost trip.created. Nic nezaúčtuje ani nevyplatí; stav paid je jen označení.","x-saldo-repeat":"Každé volání založí nový příkaz; duplicity se nekontrolují.","x-saldo-errors":[{"status":404,"when":"employee_id nepatří pracovníkovi této firmy – „Záznam nebyl nalezen“"},{"status":422,"when":"Chybí nebo je nečitelný odjezd či návrat, návrat není po odjezdu nebo cesta trvá přes 366 dní (zprávy jako u výpočtu)"},{"status":422,"when":"Pro rok odjezdu nejsou v Saldu sazby – „Pro rok RRRR nejsou k dispozici zákonné sazby“"},{"status":400,"when":"Pole meals obsahuje jakoukoli položku – v této verzi vždy „invalid date“ (známá chyba zpracování jídel)"},{"status":500,"when":"Vstup, který výpočet odmítne, ale API předem neověří (stejné případy jako u výpočtu); příkaz se neuloží – známá chyba"}]}},"/entities/{entity_id}/trips/calculate":{"post":{"operationId":"calculateTrip","tags":["Majetek, mzdy a cesty"],"summary":"Výpočet cestovních náhrad bez uložení","description":"Spočítá náhrady za pracovní cestu (celou cestu od odjezdu do návratu bere jako jeden úsek) a nic neuloží: tuzemské stravné po kalendářních dnech krácené o poskytnutá jídla, zahraniční stravné v měně cílové země, základní náhradu za soukromé vozidlo, náhradu za pohonné hmoty, ubytování a ostatní výdaje. Zaměstnanci počítá minimální sazby stravného podle vyhlášky a celkovou částku zaokrouhlí na koruny nahoru; OSVČ počítá horní hranici sazeb a jen dny delší než 12 hodin. Sazby se berou podle roku odjezdu.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":12}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["trip"],"properties":{"trip":{"type":"object","required":["departure","arrival"],"properties":{"employee_id":{"type":"integer","description":"Pracovník firmy; výpočet ho nehledá (neexistující ID nevrátí 404), jen jeho zadání přepne výchozí traveller na employee"},"traveller_name":{"type":"string","description":"Jméno cestujícího; výpočet ho nepoužije"},"traveller":{"type":"string","description":"employee zaměstnanec (náhrady podle zákoníku práce), self_employed OSVČ (výdaje podle § 24 odst. 2 písm. k) ZDP). Bez hodnoty employee, je-li zadán employee_id nebo jde o právnickou osobu, jinak self_employed.","enum":["employee","self_employed"]},"purpose":{"type":"string","description":"Účel cesty; výpočet neovlivní"},"destination":{"type":"string","description":"Místo cesty; při uložení povinné, nejvýše 200 znaků"},"departure":{"type":"string","description":"Odjezd, datum a čas ISO 8601 (např. 2026-09-21T06:30). Zadávejte místní čas bez časového pásma – server jej uloží beze změny jako UTC a podle něj dělí cestu na kalendářní dny."},"arrival":{"type":"string","description":"Návrat ve stejném tvaru; musí být po odjezdu a nejvýš 366 dní po něm"},"km":{"type":"number","description":"Ujeté km soukromým vozidlem; bez hodnoty nebo 0 se náhrada za vozidlo nepočítá"},"vehicle_kind":{"type":"string","description":"Soukromé vozidlo; truck má u zaměstnance dvojnásobnou sazbu osobního auta, electric počítá s elektřinou","enum":["car","motorcycle","truck","electric"],"default":"car"},"consumption":{"type":"number","description":"Průměrná spotřeba na 100 km podle technického průkazu (l nebo kWh)"},"fuel":{"type":"string","description":"Druh paliva","enum":["petrol95","petrol98","diesel","lpg","electricity"],"default":"petrol95"},"fuel_price":{"type":"number","description":"Cena paliva za litr nebo kWh podle dokladu; bez ní průměrná cena z vyhlášky platná v den odjezdu. Palivo bez průměrné ceny (např. lpg) bez fuel_price dá náhradu za PHM 0 a upozornění."},"accommodation":{"type":"number","description":"Ubytování v Kč, nezáporné"},"other":{"type":"number","description":"Ostatní nutné vedlejší výdaje v Kč, nezáporné"},"foreign_country":{"type":"string","description":"Kód cílové země (ISO 3166-1 alpha-2, jiný než CZ); zapne zahraniční stravné"},"hours_abroad":{"type":"number","description":"Hodiny strávené v zahraničí, nejvýš délka cesty; přechod hranice se umístí doprostřed cesty. Bez hodnoty 0"},"meals":{"type":"array","description":"Bezplatně poskytnutá jídla, která krátí stravné. V této verzi každá položka pole skončí chybou 400 „invalid date“ (aplikace datum jídla nepřečte), proto výpočet s jídly zatím nejde","items":{"type":"object","required":["date"],"properties":{"date":{"type":"string","format":"date","description":"Den (RRRR-MM-DD)"},"count":{"type":"integer","description":"Počet jídel v daném dni"}}}}}}}},"example":{"trip":{"destination":"Brno","purpose":"Jednání s klientem","departure":"2026-09-21T06:30","arrival":"2026-09-22T19:10","km":420,"vehicle_kind":"car","consumption":6.1,"fuel":"diesel","accommodation":1200}}}}},"responses":{"200":{"description":"Výpočet cestovních náhrad.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Chybí nebo je nečitelný odjezd či návrat – „Zadejte odjezd i návrat“ Návrat není po odjezdu – „Návrat musí být po odjezdu“ Cesta je delší než 366 dní – „Cesta smí trvat nejvýš 366 dní“ Pro rok odjezdu nejsou v Saldu sazby – „Pro rok RRRR nejsou k dispozici zákonné sazby“","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"400":{"description":"Pole meals obsahuje jakoukoli položku – v této verzi vždy „invalid date“ (známá chyba zpracování jídel)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"500":{"description":"Vstup, který výpočet odmítne, ale API předem neověří: neznámé vehicle_kind nebo fuel, záporné km, accommodation nebo other, foreign_country CZ, hours_abroad delší než cesta, datum a čas mimo rozsah (např. měsíc 13) – známá chyba: výjimka místo chyby 422","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"majetek-mzdy-cesty","x-saldo-access":"member","x-saldo-side-effects":"Nic nezapisuje.","x-saldo-limits":"Cesta smí trvat nejvýš 366 dní; více úseků ani časy přechodu hranice API nepřijímá.","x-saldo-errors":[{"status":422,"when":"Chybí nebo je nečitelný odjezd či návrat – „Zadejte odjezd i návrat“"},{"status":422,"when":"Návrat není po odjezdu – „Návrat musí být po odjezdu“"},{"status":422,"when":"Cesta je delší než 366 dní – „Cesta smí trvat nejvýš 366 dní“"},{"status":422,"when":"Pro rok odjezdu nejsou v Saldu sazby – „Pro rok RRRR nejsou k dispozici zákonné sazby“"},{"status":400,"when":"Pole meals obsahuje jakoukoli položku – v této verzi vždy „invalid date“ (známá chyba zpracování jídel)"},{"status":500,"when":"Vstup, který výpočet odmítne, ale API předem neověří: neznámé vehicle_kind nebo fuel, záporné km, accommodation nebo other, foreign_country CZ, hours_abroad delší než cesta, datum a čas mimo rozsah (např. měsíc 13) – známá chyba: výjimka místo chyby 422"}],"x-saldo-response-fields":[{"name":"duration_hours","description":"Délka cesty v hodinách"},{"name":"per_diem","description":"Tuzemské stravné: band, rate, reductions, amount a days (po dnech: date, hours, band short/medium/long, rate, meals, reductions, amount)"},{"name":"foreign_per_diem","description":"Zahraniční stravné (nebo null): country, country_name, currency, base_rate, days, amount, pocket_money_max, pocket_money, exchange_rate a amount_czk (vždy null)"},{"name":"mileage","description":"Základní náhrada: base_rate, km, amount"},{"name":"fuel","description":"Náhrada za PHM: type, price, consumption, amount"},{"name":"accommodation, other","description":"Zadané výdaje"},{"name":"total","description":"Náhrady celkem v Kč; zahraniční stravné v cizí měně v něm není"},{"name":"basis","description":"Právní základ použitých sazeb"},{"name":"warnings","description":"Upozornění (česky)"}]}},"/entities/{entity_id}/trips/{id}":{"patch":{"operationId":"updateTrip","tags":["Majetek, mzdy a cesty"],"summary":"Přepočet a úprava cestovního příkazu","description":"Znovu spočítá náhrady z odeslaného formuláře a přepíše jím celý příkaz: pole, která v trip chybí, se vymažou (například purpose nebo vazba na pracovníka); stav zůstane, pokud trip.status nepošlete. Posílejte proto vždy celý formulář.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":12},{"name":"id","in":"path","required":true,"description":"ID cestovního příkazu","schema":{"type":"integer"},"example":7}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["trip"],"properties":{"trip":{"type":"object","required":["destination","departure","arrival"],"properties":{"employee_id":{"type":"integer","description":"Pracovník této firmy; neexistující vrátí 404"},"traveller_name":{"type":"string","description":"Jméno cestujícího; bez hodnoty jméno pracovníka"},"traveller":{"type":"string","description":"employee zaměstnanec (náhrady podle zákoníku práce), self_employed OSVČ (výdaje podle § 24 odst. 2 písm. k) ZDP). Bez hodnoty employee, je-li zadán employee_id nebo jde o právnickou osobu, jinak self_employed.","enum":["employee","self_employed"]},"purpose":{"type":"string","description":"Účel cesty; výpočet neovlivní"},"destination":{"type":"string","description":"Místo cesty; při uložení povinné, nejvýše 200 znaků"},"departure":{"type":"string","description":"Odjezd, datum a čas ISO 8601 (např. 2026-09-21T06:30). Zadávejte místní čas bez časového pásma – server jej uloží beze změny jako UTC a podle něj dělí cestu na kalendářní dny."},"arrival":{"type":"string","description":"Návrat ve stejném tvaru; musí být po odjezdu a nejvýš 366 dní po něm"},"km":{"type":"number","description":"Ujeté km soukromým vozidlem; bez hodnoty nebo 0 se náhrada za vozidlo nepočítá"},"vehicle_kind":{"type":"string","description":"Soukromé vozidlo; truck má u zaměstnance dvojnásobnou sazbu osobního auta, electric počítá s elektřinou","enum":["car","motorcycle","truck","electric"],"default":"car"},"consumption":{"type":"number","description":"Průměrná spotřeba na 100 km podle technického průkazu (l nebo kWh)"},"fuel":{"type":"string","description":"Druh paliva","enum":["petrol95","petrol98","diesel","lpg","electricity"],"default":"petrol95"},"fuel_price":{"type":"number","description":"Cena paliva za litr nebo kWh podle dokladu; bez ní průměrná cena z vyhlášky platná v den odjezdu. Palivo bez průměrné ceny (např. lpg) bez fuel_price dá náhradu za PHM 0 a upozornění."},"accommodation":{"type":"number","description":"Ubytování v Kč, nezáporné"},"other":{"type":"number","description":"Ostatní nutné vedlejší výdaje v Kč, nezáporné"},"foreign_country":{"type":"string","description":"Kód cílové země (ISO 3166-1 alpha-2, jiný než CZ); zapne zahraniční stravné"},"hours_abroad":{"type":"number","description":"Hodiny strávené v zahraničí, nejvýš délka cesty; přechod hranice se umístí doprostřed cesty. Bez hodnoty 0"},"meals":{"type":"array","description":"Bezplatně poskytnutá jídla, která krátí stravné. V této verzi každá položka pole skončí chybou 400 „invalid date“ (aplikace datum jídla nepřečte), proto výpočet s jídly zatím nejde","items":{"type":"object","required":["date"],"properties":{"date":{"type":"string","format":"date","description":"Den (RRRR-MM-DD)"},"count":{"type":"integer","description":"Počet jídel v daném dni"}}}},"status":{"type":"string","description":"Nový stav; bez hodnoty zůstane dosavadní","enum":["draft","approved","paid"]}}}}},"example":{"trip":{"employee_id":1,"destination":"Brno","purpose":"Workshop u klienta","departure":"2026-09-12T06:40","arrival":"2026-09-12T19:05","status":"approved"}}}}},"responses":{"200":{"description":"Přepočtený cestovní příkaz.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"description":"employee_id nepatří pracovníkovi této firmy – „Záznam nebyl nalezen“","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"422":{"description":"Chybí nebo je nečitelný odjezd či návrat, návrat není po odjezdu nebo cesta trvá přes 366 dní (zprávy jako u výpočtu) Pro rok odjezdu nejsou v Saldu sazby – „Pro rok RRRR nejsou k dispozici zákonné sazby“","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"400":{"description":"Pole meals obsahuje jakoukoli položku – v této verzi vždy „invalid date“ (známá chyba zpracování jídel)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"500":{"description":"Vstup, který výpočet odmítne, ale API předem neověří (stejné případy jako u výpočtu); příkaz se nezmění – známá chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"majetek-mzdy-cesty","x-saldo-access":"writer","x-saldo-side-effects":"Přepíše cestovní příkaz. Událost do historie nezapisuje a nic nezaúčtuje.","x-saldo-repeat":"Opakování se stejným formulářem vede ke stejnému výsledku.","x-saldo-errors":[{"status":404,"when":"employee_id nepatří pracovníkovi této firmy – „Záznam nebyl nalezen“"},{"status":422,"when":"Chybí nebo je nečitelný odjezd či návrat, návrat není po odjezdu nebo cesta trvá přes 366 dní (zprávy jako u výpočtu)"},{"status":422,"when":"Pro rok odjezdu nejsou v Saldu sazby – „Pro rok RRRR nejsou k dispozici zákonné sazby“"},{"status":400,"when":"Pole meals obsahuje jakoukoli položku – v této verzi vždy „invalid date“ (známá chyba zpracování jídel)"},{"status":500,"when":"Vstup, který výpočet odmítne, ale API předem neověří (stejné případy jako u výpočtu); příkaz se nezmění – známá chyba"}]},"delete":{"operationId":"deleteTrip","tags":["Majetek, mzdy a cesty"],"summary":"Smazání cestovního příkazu","description":"Smaže cestovní příkaz v jakémkoli stavu.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky (firmy)","schema":{"type":"integer"},"example":12},{"name":"id","in":"path","required":true,"description":"ID cestovního příkazu","schema":{"type":"integer"},"example":7}],"responses":{"204":{"description":"Prázdná odpověď."},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"majetek-mzdy-cesty","x-saldo-access":"writer","x-saldo-side-effects":"Smaže cestovní příkaz. Událost do historie nezapisuje; uzamčení období nekontroluje, protože příkaz nemá účetní zápisy.","x-saldo-repeat":"Druhé smazání vrátí 404."}},"/entities/{entity_id}/automation":{"get":{"operationId":"getAutomation","tags":["Automatizace, fronta a podklady"],"summary":"Nastavení automatizací a jejich výsledky za tento měsíc","description":"Vrátí přepínače automatizací firmy a co která automatizace udělala v aktuálním kalendářním měsíci, spolu s tím, co právě čeká: splatná opakování faktur, faktury k upomínce a nové kontakty ke kontrole. Nic nespouští.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky","schema":{"type":"integer"},"example":12}],"responses":{"200":{"description":"Nastavení a stav automatizací.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"automatizace","x-saldo-access":"member","x-saldo-side-effects":"Nic nezapisuje.","x-saldo-response-fields":[{"name":"month","description":"První den aktuálního měsíce; počty month níže platí pro něj"},{"name":"settings","description":"Přepínače bank_rules, auto_match, fio_on_open, recurring, reminders, partner_checks (výchozí true) a reminder_days (výchozí 7)"},{"name":"bank_rules","description":"rules, active (aktivní pravidla), month (použití pravidel), last_at"},{"name":"auto_match","description":"month (plateb spárovaných při importu výpisů), open (nespárovaných bankovních pohybů)"},{"name":"fio","description":"connected (účty napojené na Fio API), month (pohybů staženo z Fio), accounts s časem a chybou poslední synchronizace"},{"name":"recurring","description":"active, due (splatná k dnešku), upcoming (nejbližších 6 opakování se šablonou a částkou), month (dokladů vytvořených z opakování)"},{"name":"reminders","description":"days, count a totals podle měn (vydané faktury k upomínce), month (upomínek zaznamenaných tento měsíc – Saldo je samo neposílá), rows (prvních 8 faktur)"},{"name":"partner_checks","description":"new (kontakty za 30 dní), unchecked, demo, month (provedených kontrol), flagged (až 8 nespolehlivých, insolventních nebo v ARES nenalezených kontaktů)"}]},"patch":{"operationId":"updateAutomation","tags":["Automatizace, fronta a podklady"],"summary":"Zapnutí a vypnutí automatizací","description":"Změní přepínače automatizací firmy; neuvedené a neznámé klíče se nemění. bank_rules a auto_match řídí, zda se při importu bankovního výpisu použijí pravidla pro banku a spárují platby s doklady (auto_match platí i pro import ISDOC). recurring, reminders a partner_checks řídí, co udělá POST …/automation/run. fio_on_open čte jen aplikace, která podle něj při otevření banky stáhne pohyby z Fio; server podle něj nic nespouští.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky","schema":{"type":"integer"},"example":12}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["automation"],"properties":{"automation":{"type":"object","properties":{"bank_rules":{"type":"boolean","description":"Pravidla pro banku při importu výpisu"},"auto_match":{"type":"boolean","description":"Párování plateb s doklady při importu výpisu a ISDOC"},"fio_on_open":{"type":"boolean","description":"Stažení pohybů z Fio při otevření banky v aplikaci"},"recurring":{"type":"boolean","description":"Vytváření opakovaných faktur při běhu automatizací"},"reminders":{"type":"boolean","description":"Přehled faktur k upomínce při běhu automatizací"},"reminder_days":{"type":"integer","description":"Kolik dní po splatnosti (a od poslední upomínky) je faktura k upomínce; 1–90"},"partner_checks":{"type":"boolean","description":"Kontrola nových kontaktů v registrech při běhu automatizací"}}}}},"example":{"automation":{"reminder_days":14,"partner_checks":true}}}}},"responses":{"200":{"description":"Nastavení po změně.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"reminder_days není celé číslo 1–90 („Upomínky lze chystat 1 až 90 dní po splatnosti …“)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"automatizace","x-saldo-access":"manager","x-saldo-side-effects":"Pokud se něco změnilo, uloží nastavení firmy (settings.automation) a zapíše událost automation.updated se seznamem změn. Hodnoty přepínačů se převedou na true/false (jiná hodnota než pravdivá znamená false).","x-saldo-repeat":"Stejné hodnoty podruhé nic neuloží ani nezapíší.","x-saldo-errors":[{"status":422,"when":"reminder_days není celé číslo 1–90 („Upomínky lze chystat 1 až 90 dní po splatnosti …“)"}],"x-saldo-response-fields":[{"name":"settings","description":"Všech sedm přepínačů včetně nezměněných"}]}},"/entities/{entity_id}/automation/run":{"post":{"operationId":"runAutomation","tags":["Automatizace, fronta a podklady"],"summary":"Spuštění automatizací firmy","description":"Spustí automatizace, které aplikace pouští při otevření firmy: opakované faktury (recurring), kontrolu nových kontaktů v registrech (partner_checks) a přepočet faktur k upomínce (reminders). Každá běží jen, je-li v nastavení zapnutá; s only jen ta jedna. Upomínky se jen spočítají, nic se neodesílá. Hodnoty only bank_rules, auto_match, fio_on_open a reminder_days nespustí nic; neznámá hodnota se ignoruje a běží vše zapnuté.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky","schema":{"type":"integer"},"example":12}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"only":{"type":"string","description":"Spustit jen tuto automatizaci; účinek mají recurring, reminders a partner_checks","enum":["bank_rules","auto_match","fio_on_open","recurring","reminders","reminder_days","partner_checks"]},"force":{"type":"boolean","description":"Zkontrolovat kontakty i během 10minutové pauzy po předchozí kontrole","default":false}}},"example":{"only":"recurring"}}}},"responses":{"200":{"description":"Výsledek každé spuštěné automatizace; klíč chybí u automatizace, která neběžela.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"automatizace","x-saldo-access":"special","x-saldo-access-note":"Volat smí každý člen firmy. Automatizace ale spustí jen vlastník, účetní nebo editor; divákovi vrátí 200 s ran false a důvodem a nic neudělá (ne 403).","x-saldo-side-effects":"recurring: pro každé aktivní opakování s termínem dnes nebo dříve vytvoří doklad podle šablony (datum vystavení = termín, splatnost podle kontaktu nebo firmy, u cizí měny kurz ČNB, je-li dostupný). S auto_issue ho vystaví (v podvojném účetnictví i zaúčtuje), nebo pošle ke schválení, pokud ho pokrývá pravidlo schvalování; jinak zůstane koncept. Termín opakování posune (po ends_on ho deaktivuje); při chybě se doklad nevytvoří, opakování se neposune a chyba je ve failed. partner_checks: u kontaktů založených za posledních 30 dní ověří všechna dosud neověřená česká DIČ v registru plátců DPH (uloží spolehlivost a plátcovství), až 5 IČO v ISIR (uloží insolvenci) a až 5 IČO v ARES (doplní chybějící DIČ, ulici, obec a PSČ, zapíše událost partner.ares_checked); když něco ověřila nebo narazila na chybu, zapíše souhrnnou událost automation.partner_checks. U ukázkové firmy se registry nevolají. reminders nic nezapisuje. Volá externí služby ARES, ISIR, registr plátců DPH a ČNB.","x-saldo-limits":"Nejvýše 24 dokladů na jedno opakování v jednom běhu (dohánění zmeškaných termínů); ISIR a ARES nejvýše 5 kontaktů na běh; bez force se kontrola kontaktů přeskočí, pokud byla v posledních 10 minutách zapsána událost automation.partner_checks.","x-saldo-repeat":"Tentýž termín opakování nevytvoří dva doklady: běh si každý termín atomicky zarezervuje posunem data dalšího opakování. Další volání vytvoří doklad jen za termín, který mezitím nastal, nebo za termíny nad limit 24 z předchozího běhu. Kontrola kontaktů se do 10 minut po zapsané kontrole přeskočí (skipped); s force proběhne znovu, ale jen pro dosud neověřené kontakty.","x-saldo-response-fields":[{"name":"ran","description":"true; false u člena jen pro čtení"},{"name":"reason","description":"Jen při ran false: proč se nic nespustilo"},{"name":"recurring","description":"count, documents (id, number, kind, status, partner_name, total_payable, currency) a failed (recurrence_id, template, error)"},{"name":"partners","description":"vat, isir, ares (počty ověřených kontaktů), errors a flagged (id, name); nebo skipped true (pauza) či skipped a demo true (ukázková firma)"},{"name":"reminders","description":"count – počet vydaných faktur k upomínce"}],"x-saldo-example":{"note":"Ukázková firma má další opakování až příští měsíc, proto count je 0."}}},"/clients":{"get":{"operationId":"listClients","tags":["Automatizace, fronta a podklady"],"summary":"Přehled všech firem volajícího podle naléhavosti","description":"Vrátí všechny firmy, kde je volající přijatým členem (archivované na konci), s tím, co vyžaduje pozornost: stav přiznání k DPH za poslední skončené období a další lhůtu, pohledávky po splatnosti, nespárované bankovní pohyby, koncepty, uzamčení období a poslední aktivitu. Seřazeno podle naléhavosti (urgency), při shodě podle názvu. Stav DPH počítá jen s podáními druhu dph; podání označené jako odeslané bez ověřené doručenky nebo schválené výjimky je unverified, ne filed.","parameters":[],"responses":{"200":{"description":"Souhrn a seznam firem.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"automatizace","x-saldo-access":"user","x-saldo-side-effects":"Nic nezapisuje.","x-saldo-limits":"Nejvýše 200 firem; výběr proběhne podle archivace a názvu ještě před řazením podle naléhavosti, takže nad 200 firem se naléhavější firma dál v abecedě nemusí vrátit.","x-saldo-response-fields":[{"name":"today","description":"Dnešní datum"},{"name":"total","description":"Počet vrácených firem"},{"name":"truncated","description":"true, když má volající víc než 200 firem"},{"name":"limit","description":"Nejvyšší počet vrácených firem (200)"},{"name":"summary","description":"Jen nearchivované firmy: attention, critical, vat_due (DPH do 7 dnů nebo po lhůtě), overdue_count, overdue_amount (Kč), unmatched, drafts"},{"name":"clients[]","description":"id, name, ico, legal_form, legal_form_label, role, role_label, archived, demo, bookkeeping, vat, overdue (count, amount v Kč), unmatched, drafts, locked_until, last_activity, level, urgency"},{"name":"clients[].vat.state","description":"none (neregistrovaná), filed (odesláno a doloženo), unverified (odesláno bez doložení), draft (jen připraveno), optional (podání není povinné), late (nepodáno po lhůtě), open (nepodáno, lhůta běží)"},{"name":"clients[].vat","description":"Také period, deadline, days, filed_on, proof_state a další období next_period, next_deadline, next_days"},{"name":"clients[].level","description":"critical, warning, ok nebo archived"}]}},"/work_items":{"get":{"operationId":"listWorkItems","tags":["Automatizace, fronta a podklady"],"summary":"Fronta úkolů účetní napříč firmami","description":"Vrátí konkrétní kroky ve všech nearchivovaných firmách volajícího: koncepty účetních dokladů (draft), nespárované bankovní pohyby (bank), vystavené přijaté faktury, dobropisy a výdajové pokladní doklady bez přílohy od 1. 1. předchozího roku, kromě načtených z ISDOC (missing), u plátců DPH nepodaná přiznání k DPH za každé skončené období od příchodu firmy do Salda a za období před ním, pokud jeho lhůta tehdy ještě běžela (filing; počítá se i podání se stavem filed pokrývající jen část období), a podání označená jako odeslaná bez ověřené doručenky či schválené výjimky (proof, podání všech druhů). Nepodaná kontrolní a souhrnná hlášení fronta nesleduje. Před výpisem frontu synchronizuje s daty (refresh): nové a vrácené kroky otevře, otevřený krok vyřeší, jen když kontrola jeho vlastního zdroje ukáže, že je hotový, a zruší přidělení lidem, kteří ve firmě ztratili právo zápisu. S refresh=0 nebo s API klíčem jen pro čtení vrátí frontu tak, jak byla naposledy synchronizována.","parameters":[{"name":"entity_id","in":"query","required":false,"description":"Jen kroky této firmy (firma bez členství vrátí prázdný seznam)","schema":{"type":"integer"},"example":12},{"name":"assignee","in":"query","required":false,"description":"me (přidělené mně), unassigned (nepřidělené) nebo číselné ID uživatele; jiná hodnota nefiltruje","schema":{"type":"string"},"example":"me"},{"name":"priority","in":"query","required":false,"description":"Jen kroky s touto prioritou","schema":{"type":"string","enum":["high","normal","low"]},"example":"high"},{"name":"due","in":"query","required":false,"description":"overdue = termín už minul; week = termín nejpozději za 7 dní (včetně prošlých)","schema":{"type":"string","enum":["overdue","week"]},"example":"week"},{"name":"state","in":"query","required":false,"description":"resolved = vyřešené za posledních 90 dní, nejnovější první; jiná hodnota znamená open","schema":{"type":"string","enum":["open","resolved"],"default":"open"},"example":"open"},{"name":"refresh","in":"query","required":false,"description":"0 = bez synchronizace; jakákoli jiná hodnota nebo vynechání synchronizuje","schema":{"type":"string","enum":["0","1"],"default":"1"},"example":"1"}],"responses":{"200":{"description":"Kroky, počty a lidé, kterým lze kroky přidělit.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"Parametr entity_id, assignee, priority, due, state nebo refresh je pole či objekt („Parametr … musí být jedna hodnota“)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"automatizace","x-saldo-access":"user","x-saldo-side-effects":"Synchronizace zapisuje jen do fronty úkolů (nové kroky, aktualizace názvu, termínu a priority, vyřešení, znovuotevření s reopened_count, zrušení přidělení); účetní data nemění. S refresh=0 nebo klíčem jen pro čtení nic nezapisuje.","x-saldo-limits":"Nejvýše 200 nearchivovaných firem (podle názvu) a 1000 řádků. Nové kroky se hledají nejvýše po 500 na firmu a druh; krok proof jen u podání odeslaných za posledních 365 dní nebo bez data odeslání. Vyřešené kroky se vypisují 90 dní.","x-saldo-repeat":"Opakovaná synchronizace bez změny dat nic nového nezaloží.","x-saldo-errors":[{"status":400,"when":"Parametr entity_id, assignee, priority, due, state nebo refresh je pole či objekt („Parametr … musí být jedna hodnota“)"}],"x-saldo-response-fields":[{"name":"today","description":"Dnešní datum, ke kterému se počítá overdue"},{"name":"rows","description":"Kroky: id, entity_id, entity_name, kind, kind_label, title, detail, href (odkaz do aplikace), due_on, period, year, overdue, priority, priority_label, assignee_id, assignee, can_assign, state, first_seen_at, resolved_at, reopened_count"},{"name":"rows[].kind","description":"filing, proof, bank, draft, missing"},{"name":"truncated","description":"true, když je kroků víc než 1000"},{"name":"limit","description":"Nejvyšší počet vrácených kroků (1000)"},{"name":"counts","description":"Otevřené kroky ve všech firmách bez ohledu na filtr: open, mine, unassigned, high, overdue"},{"name":"firms","description":"Firmy ve frontě: id, name, manage (volající smí přidělovat)"},{"name":"people","description":"Lidé s právem zápisu v některé z firem"},{"name":"members","description":"ID firmy → lidé s právem zápisu v ní"}]}},"/work_items/{id}":{"patch":{"operationId":"assignWorkItem","tags":["Automatizace, fronta a podklady"],"summary":"Přidělení kroku z fronty úkolů","description":"Přidělí krok fronty úkolů odpovědné osobě, nebo přidělení zruší (assignee_id null). Přidělit lze jen členovi firmy s právem zápisu (vlastník, účetní, editor).","parameters":[{"name":"id","in":"path","required":true,"description":"ID kroku fronty","schema":{"type":"integer"},"example":301}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"assignee_id":{"type":"integer","description":"ID uživatele; null nebo prázdná hodnota přidělení zruší"}}},"example":{"assignee_id":2}}}},"responses":{"200":{"description":"Krok po přidělení (tvar jako rows[] v GET /work_items).","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"assignee_id je pole či objekt („Parametr assignee_id musí být jedna hodnota“)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"422":{"description":"Volající není vlastník ani účetní firmy („Úkoly smí přidělovat vlastník nebo účetní firmy“) Uživatel není členem firmy s právem zápisu („Úkol lze přidělit jen členovi firmy s právem zápisu“)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"automatizace","x-saldo-access":"special","x-saldo-access-note":"Krok musí patřit nearchivované firmě, kde je volající přijatým členem (jinak 404). Přidělovat smí jen vlastník nebo účetní té firmy; ostatním vrátí 422, ne 403.","x-saldo-side-effects":"Uloží odpovědnou osobu, kdo a kdy přidělil, a zapíše do historie firmy událost work_item.assigned. Účetní data nemění.","x-saldo-repeat":"Každé volání znovu uloží čas a autora přidělení a zapíše novou událost, i při stejné osobě.","x-saldo-errors":[{"status":400,"when":"assignee_id je pole či objekt („Parametr assignee_id musí být jedna hodnota“)"},{"status":422,"when":"Volající není vlastník ani účetní firmy („Úkoly smí přidělovat vlastník nebo účetní firmy“)"},{"status":422,"when":"Uživatel není členem firmy s právem zápisu („Úkol lze přidělit jen členovi firmy s právem zápisu“)"}]}},"/entities/{entity_id}/document_requests":{"get":{"operationId":"listDocumentRequests","tags":["Automatizace, fronta a podklady"],"summary":"Žádosti o podklady ve firmě","description":"Vrátí žádosti o chybějící doklad nebo vysvětlení k bankovnímu pohybu či dokladu, bez zpráv. Otevřené (waiting, delivered) jsou seřazené podle termínu (žádosti bez termínu na konci, při shodě nejnovější první), uzavřené (verified, cancelled) od posledně uzavřené; s filter=all jsou otevřené první. filter=action vrátí jen otevřené žádosti, které čekají na volajícího.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky","schema":{"type":"integer"},"example":12},{"name":"filter","in":"query","required":false,"description":"open = čekající a dodané; action = z nich ty, na které má volající odpovědět nebo které smí ověřit; closed = ověřené a zrušené; all = vše. Jiná hodnota znamená open.","schema":{"type":"string","enum":["open","action","closed","all"],"default":"open"},"example":"open"},{"name":"subject_type","in":"query","required":false,"description":"Jen žádosti k tomuto druhu položky – vyžaduje subject_ids","schema":{"type":"string","enum":["bank_transaction","document"]},"example":"bank_transaction"},{"name":"subject_ids","in":"query","required":false,"description":"ID položek oddělená čárkou (nejvýše 500); bez subject_type se ignorují, bez nich je výsledek prázdný","schema":{"type":"string"},"example":"4711,4712"}],"responses":{"200":{"description":"Žádosti a počty.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Neznámý subject_type („Neznámý druh položky“)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"automatizace","x-saldo-access":"member","x-saldo-side-effects":"Nic nezapisuje.","x-saldo-limits":"Nejvýše 500 žádostí; u filter=action se limit uplatní před výběrem žádostí čekajících na volajícího.","x-saldo-errors":[{"status":422,"when":"Neznámý subject_type („Neznámý druh položky“)"}],"x-saldo-response-fields":[{"name":"rows","description":"Žádosti: id, title, status, status_label, subject, requested_by, assignee_id, assignee, due_on, overdue, created_at, updated_at, closed_at, action_needed, can_reply, can_verify, can_cancel, files_count"},{"name":"rows[].status","description":"waiting (čeká na podklad), delivered (podklad dodán), verified (ověřeno), cancelled (zrušeno)"},{"name":"rows[].subject","description":"type, id, label, amount, currency, date, partner, href; u pohybu i message a tx_status; u smazané položky missing true"},{"name":"rows[].assignee_id","description":"Odpovědná osoba, jen dokud má ve firmě právo zápisu, jinak null. Určuje, na koho žádost čeká (action_needed); odpovědět smí kterýkoli člen s právem zápisu"},{"name":"truncated","description":"true, když žádostí je víc než limit"},{"name":"limit","description":"500"},{"name":"action_needed","description":"Počet všech otevřených žádostí firmy, které čekají na volajícího (bez ohledu na filtr)"},{"name":"members","description":"Členové s právem zápisu (id, name, role); žádost lze přidělit kterémukoli z nich kromě sebe"}]},"post":{"operationId":"createDocumentRequest","tags":["Automatizace, fronta a podklady"],"summary":"Žádost o doklad nebo vysvětlení k pohybu či dokladu","description":"Založí žádost o podklad k bankovnímu pohybu nebo účetnímu dokladu (i konceptu) s první zprávou. K jedné položce může být otevřená jen jedna žádost; k nabídce, objednávce a dodacímu listu žádost založit nelze. Odpovědnou osobou může být jiný člen firmy s právem zápisu, ne sám žadatel. Smazání pohybu nebo dokladu jeho otevřenou žádost zruší se systémovou zprávou.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky","schema":{"type":"integer"},"example":12}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["subject_type","subject_id","question"],"properties":{"subject_type":{"type":"string","description":"Druh položky","enum":["bank_transaction","document"]},"subject_id":{"type":"integer","description":"ID bankovního pohybu nebo dokladu v této firmě"},"question":{"type":"string","description":"Co je potřeba dodat, nejvýše 2000 znaků"},"title":{"type":"string","description":"Název žádosti, nejvýše 200 znaků (delší se zkrátí); výchozí „Doklad nebo vysvětlení k platbě“ nebo „Chybějící podklad k dokladu“"},"assignee_id":{"type":"integer","description":"ID uživatele, který má odpovědět – jiný člen s právem zápisu"},"due_on":{"type":"string","format":"date","description":"Termín, dnes nebo později"}}},"example":{"subject_type":"bank_transaction","subject_id":22,"title":"Doklad k platbě","question":"Prosím o fakturu nebo účtenku k této platbě."}}}},"responses":{"201":{"description":"Nová žádost se zprávami (tvar jako GET …/document_requests/{id}), status waiting.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Neznámý subject_type („Žádost lze založit k bankovnímu pohybu nebo dokladu“) Položka je nabídka, objednávka nebo dodací list K položce už je otevřená žádost („K této položce už je otevřená žádost … – pokračujte v ní“) Prázdná otázka nebo delší než 2000 znaků Termín v minulosti („Termín nemůže být v minulosti“) Odpovědnou osobou je sám žadatel, nebo člen bez práva zápisu","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"automatizace","x-saldo-access":"writer","x-saldo-side-effects":"Vytvoří žádost ve stavu waiting a zprávu s otázkou a zapíše událost document_request.created. Bankovní pohyb ani doklad nemění a nic neúčtuje.","x-saldo-repeat":"Druhá žádost ke stejné položce vrátí 422, dokud je první otevřená; po uzavření lze založit novou.","x-saldo-errors":[{"status":422,"when":"Neznámý subject_type („Žádost lze založit k bankovnímu pohybu nebo dokladu“)"},{"status":422,"when":"Položka je nabídka, objednávka nebo dodací list"},{"status":422,"when":"K položce už je otevřená žádost („K této položce už je otevřená žádost … – pokračujte v ní“)"},{"status":422,"when":"Prázdná otázka nebo delší než 2000 znaků"},{"status":422,"when":"Termín v minulosti („Termín nemůže být v minulosti“)"},{"status":422,"when":"Odpovědnou osobou je sám žadatel, nebo člen bez práva zápisu"}]}},"/entities/{entity_id}/document_requests/{id}":{"get":{"operationId":"getDocumentRequest","tags":["Automatizace, fronta a podklady"],"summary":"Detail žádosti o podklad se zprávami a soubory","description":"Vrátí žádost se všemi zprávami (otázka, odpovědi, ověření, zrušení) a jejich soubory a s tím, co smí volající udělat (can_reply, can_verify, can_cancel).","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky","schema":{"type":"integer"},"example":12},{"name":"id","in":"path","required":true,"description":"ID žádosti","schema":{"type":"integer"},"example":88}],"responses":{"200":{"description":"Žádost (pole jako v rows[] seznamu) a zprávy.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"automatizace","x-saldo-access":"member","x-saldo-side-effects":"Nic nezapisuje.","x-saldo-response-fields":[{"name":"messages","description":"Zprávy od nejstarší: id, kind (question, reply, verified, cancelled), user (null u systémové zprávy po smazání položky), at, body, files (id, filename, content_type, byte_size)"},{"name":"attachable_files","description":"Kolik souborů dodaných jinými než žadatelem by ověření s attach přiložilo k dokladu (0 u pohybu nebo když volající ověřit nesmí)"}]}},"/entities/{entity_id}/document_requests/counts":{"get":{"operationId":"countDocumentRequests","tags":["Automatizace, fronta a podklady"],"summary":"Počty otevřených žádostí a žádostí čekajících na volajícího","description":"Vrátí jen počty bez žádostí a zpráv – pro odznaky v aplikaci. action_needed počítá žádosti, na které má volající odpovědět (není žadatel a žádost je přidělená jemu nebo nikomu), a dodané žádosti, které smí ověřit; člen bez práva zápisu má vždy 0.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky","schema":{"type":"integer"},"example":12}],"responses":{"200":{"description":"Počty.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"automatizace","x-saldo-access":"member","x-saldo-side-effects":"Nic nezapisuje.","x-saldo-response-fields":[{"name":"open","description":"Otevřené žádosti firmy (waiting a delivered)"},{"name":"action_needed","description":"Z nich ty, které čekají na volajícího"}]}},"/entities/{entity_id}/document_requests/{id}/reply":{"post":{"operationId":"replyDocumentRequest","tags":["Automatizace, fronta a podklady"],"summary":"Odpověď na žádost o podklad, případně se soubory","description":"Přidá do otevřené žádosti odpověď s textem a/nebo soubory. Odpověď kohokoli jiného než žadatele žádost označí jako dodanou (delivered); odpověď žadatele (doplňující dotaz) ji vrátí do stavu waiting. Soubory zůstávají u žádosti – k dokladu se přiloží až při ověření s attach. Soubory se posílají jako multipart/form-data v poli files[] (nebo files[0], files[1] …); odpověď bez souborů lze poslat i jako JSON.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky","schema":{"type":"integer"},"example":12},{"name":"id","in":"path","required":true,"description":"ID žádosti","schema":{"type":"integer"},"example":88}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"body":{"type":"string","description":"Text odpovědi, nejvýše 2000 znaků; povinný, není-li přiložen soubor"},"files":{"type":"array","description":"Nejvýše 5 souborů PDF, JPEG, PNG, WebP, GIF, HEIC/HEIF nebo XML (typ se určí z obsahu), každý nejvýše 15 MB, dohromady nejvýše 20 MB","items":{"type":"string","format":"binary"}}}}}}},"responses":{"200":{"description":"Žádost se zprávami po odpovědi (tvar jako GET …/document_requests/{id}).","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Žádost je uzavřená („Žádost je uzavřená – případně založte novou“) Chybí text i soubor, nebo je text delší než 2000 znaků Víc než 5 souborů, prázdný soubor, soubor nad 15 MB, nepovolený typ nebo víc než 20 MB dohromady V poli files není soubor („Soubory se nepodařilo přečíst – pošlete je jako multipart/form-data v poli files[]“)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"automatizace","x-saldo-access":"writer","x-saldo-side-effects":"Uloží zprávu a soubory a změní stav žádosti (delivered s časem a autorem dodání, nebo waiting); zapíše událost document_request.delivered nebo document_request.followed_up. Doklad ani pohyb nemění, nic neúčtuje. Když cokoli selže, nahrané soubory se smažou.","x-saldo-limits":"5 souborů, 15 MB na soubor, 20 MB na odpověď, 2000 znaků textu.","x-saldo-repeat":"Každé volání přidá novou zprávu; stejné soubory se neslučují.","x-saldo-errors":[{"status":422,"when":"Žádost je uzavřená („Žádost je uzavřená – případně založte novou“)"},{"status":422,"when":"Chybí text i soubor, nebo je text delší než 2000 znaků"},{"status":422,"when":"Víc než 5 souborů, prázdný soubor, soubor nad 15 MB, nepovolený typ nebo víc než 20 MB dohromady"},{"status":422,"when":"V poli files není soubor („Soubory se nepodařilo přečíst – pošlete je jako multipart/form-data v poli files[]“)"}],"x-saldo-example":{"note":"V ukázce odpovídá sám žadatel (doplňující dotaz), proto se žádost vrátí do stavu waiting; odpověď jiného člena by ji označila jako delivered."}}},"/entities/{entity_id}/document_requests/{id}/verify":{"post":{"operationId":"verifyDocumentRequest","tags":["Automatizace, fronta a podklady"],"summary":"Ověření dodaného podkladu a uzavření žádosti","description":"Uzavře dodanou žádost jako ověřenou. U žádosti k dokladu s attach=true zkopíruje k dokladu jako přílohy soubory, které v odpovědích dodal někdo jiný než žadatel a které doklad ještě nemá (podle kontrolního součtu). Nic se neúčtuje a stav bankovního pohybu se nemění.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky","schema":{"type":"integer"},"example":12},{"name":"id","in":"path","required":true,"description":"ID žádosti","schema":{"type":"integer"},"example":88}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"attach":{"type":"boolean","description":"Přiložit dodané soubory k dokladu (jen u žádosti k dokladu)","default":false}}},"example":{"attach":false}}}},"responses":{"200":{"description":"Žádost se zprávami po ověření (status verified).","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Volající nesmí ověřit („Ověřit smí ten, kdo o podklad požádal; vlastník nebo účetní jen za žadatele, který už nemá právo zápisu“) Žádost je uzavřená („Žádost je už uzavřená“) Žádost není ve stavu delivered („Ověřit lze až dodaný podklad …“) Volající podklad sám dodal („Vámi dodaný podklad musí ověřit někdo jiný“) Doklad by měl víc než 20 příloh","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"automatizace","x-saldo-access":"special","x-saldo-access-note":"Vyžaduje právo zápisu. Ověřit smí žadatel, dokud má ve firmě právo zápisu; jinak vlastník nebo účetní. Nikdy člen, který podklad dodal. Nesplnění vrátí 422.","x-saldo-side-effects":"Zapíše zprávu verified, nastaví stav verified s časem a autorem ověření a zapíše událost document_request.verified; s attach přiloží soubory k dokladu a u každého zapíše událost document.attached. Nic neúčtuje.","x-saldo-limits":"Doklad může mít nejvýše 20 příloh.","x-saldo-repeat":"Druhé volání vrátí 422, protože žádost je uzavřená.","x-saldo-errors":[{"status":422,"when":"Volající nesmí ověřit („Ověřit smí ten, kdo o podklad požádal; vlastník nebo účetní jen za žadatele, který už nemá právo zápisu“)"},{"status":422,"when":"Žádost je uzavřená („Žádost je už uzavřená“)"},{"status":422,"when":"Žádost není ve stavu delivered („Ověřit lze až dodaný podklad …“)"},{"status":422,"when":"Volající podklad sám dodal („Vámi dodaný podklad musí ověřit někdo jiný“)"},{"status":422,"when":"Doklad by měl víc než 20 příloh"}],"x-saldo-example":{"note":"Potřebuje žádost ve stavu delivered, kterou založil volající a dodal jiný člen."}}},"/entities/{entity_id}/document_requests/{id}/cancel":{"post":{"operationId":"cancelDocumentRequest","tags":["Automatizace, fronta a podklady"],"summary":"Zrušení otevřené žádosti o podklad","description":"Uzavře otevřenou žádost jako zrušenou, s nepovinným důvodem.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky","schema":{"type":"integer"},"example":12},{"name":"id","in":"path","required":true,"description":"ID žádosti","schema":{"type":"integer"},"example":88}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","description":"Důvod zrušení; delší než 2000 znaků se zkrátí"}}},"example":{"reason":"Doklad dorazil poštou."}}}},"responses":{"200":{"description":"Žádost se zprávami po zrušení (status cancelled).","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Volající nesmí zrušit („Zrušit smí ten, kdo o podklad požádal; …“) Žádost je uzavřená („Žádost je už uzavřená“)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"automatizace","x-saldo-access":"special","x-saldo-access-note":"Vyžaduje právo zápisu. Zrušit smí žadatel, dokud má ve firmě právo zápisu; jinak vlastník nebo účetní. Nesplnění vrátí 422.","x-saldo-side-effects":"Zapíše zprávu cancelled s důvodem, nastaví stav cancelled a čas uzavření a zapíše událost document_request.cancelled.","x-saldo-repeat":"Druhé volání vrátí 422, protože žádost je uzavřená.","x-saldo-errors":[{"status":422,"when":"Volající nesmí zrušit („Zrušit smí ten, kdo o podklad požádal; …“)"},{"status":422,"when":"Žádost je uzavřená („Žádost je už uzavřená“)"}]}},"/entities/{entity_id}/document_requests/{id}/files/{file_id}":{"get":{"operationId":"downloadDocumentRequestFile","tags":["Automatizace, fronta a podklady"],"summary":"Stažení souboru ze žádosti o podklad","description":"Vrátí soubor přiložený k některé zprávě žádosti. PDF, JPEG, PNG, WebP a GIF se posílají k zobrazení (inline), HEIC, HEIF a XML jako příloha; vždy s hlavičkou Cache-Control private, no-store. Soubor, který k žádosti nepatří, vrátí 404.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"ID účetní jednotky","schema":{"type":"integer"},"example":12},{"name":"id","in":"path","required":true,"description":"ID žádosti","schema":{"type":"integer"},"example":88},{"name":"file_id","in":"path","required":true,"description":"ID souboru z messages[].files[].id","schema":{"type":"integer"},"example":902}],"responses":{"200":{"description":"Obsah souboru s uloženým Content-Type a původním názvem.","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"automatizace","x-saldo-access":"member","x-saldo-side-effects":"Nic nezapisuje."}},"/entities/{entity_id}/documents/export":{"get":{"operationId":"exportDocuments","tags":["Exporty a předání účetní"],"summary":"Export dokladů do POHODY nebo Money S3","description":"Vrátí soubor XML pro import dokladů do programu POHODA (dataPack 2.0 v kódování Windows-1250) nebo Money S3 (XML přenosy MoneyData v UTF-8). Exportují se buď doklady vybrané v ids (bez ohledu na období), nebo všechny vystavené doklady zvolených druhů, jejichž datum pro DPH spadá do období – u vydaných DUZP, jinak datum vystavení, u přijatých pozdější z DUZP a data přijetí (nebo pozdější datum pro DPH zadané u dokladu). Koncepty a stornované doklady exportovat nelze; POHODA navíc vyžaduje osmimístné IČO firmy. Soubor jen připravuje data k převzetí; doklady ani účetnictví v Saldu nemění.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"Účetní jednotka (firma).","schema":{"type":"integer"},"example":12},{"name":"format","in":"query","required":true,"description":"pohoda = POHODA XML, money = Money S3 XML.","schema":{"type":"string","enum":["pohoda","money"]},"example":"pohoda"},{"name":"ids","in":"query","required":false,"description":"Vybrané doklady (ids[]=… nebo čísla oddělená čárkou); s ids se období ani kinds nepoužijí. Doklad cizí firmy nebo neexistující vrátí 404.","schema":{"type":"array","items":{"type":"integer"}},"example":[431,432]},{"name":"kinds","in":"query","required":false,"description":"Druhy dokladů pro výběr podle období (kinds[]=… nebo oddělené čárkou); výchozí jsou všechny uvedené, jiné hodnoty se ignorují.","schema":{"type":"array","enum":["invoice_out","credit_out","proforma_out","advance_out","invoice_in","credit_in","proforma_in","advance_in"],"items":{"type":"string"}},"example":["invoice_out","credit_out"]},{"name":"year","in":"query","required":false,"description":"Účetní období začínající v tomto roce, když chybí from nebo to; výchozí je aktuální rok.","schema":{"type":"integer","minimum":2000,"maximum":2100},"example":2026},{"name":"from","in":"query","required":false,"description":"Začátek období (YYYY-MM-DD); výchozí je začátek účetního období year.","schema":{"type":"string","format":"date"},"example":"2026-09-01"},{"name":"to","in":"query","required":false,"description":"Konec období včetně; výchozí je konec účetního období year.","schema":{"type":"string","format":"date"},"example":"2026-09-30"}],"responses":{"200":{"description":"Soubor ke stažení (Content-Disposition attachment). Content-Type je application/xml; charset=windows-1250 u POHODY a application/xml; charset=utf-8 u Money S3. Název je pohoda-IČO-RRRRMMDD.xml nebo money-s3-IČO-RRRRMMDD.xml (u Money S3 bez IČO id firmy), s rozsahem RRRRMMDD-RRRRMMDD podle nejstaršího a nejnovějšího data vystavení.","content":{"application/xml":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"format chybí nebo není pohoda či money („Zvolte formát exportu: pohoda, nebo money“).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"422":{"description":"Soubor nejde vytvořit – odpověď {error, problems[]}, kde problems vyjmenuje každý problém a error je ten jediný, nebo „Soubor nelze vytvořit – počet problémů: N“. Důvody – v období nejsou žádné vystavené doklady vybraných druhů, vybraný doklad není vystavený (koncept, stornovaný), druh dokladu není podporovaný, nebo firma nemá IČO (jen POHODA).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"exporty","x-saldo-access":"member","x-saldo-side-effects":"Zapíše událost documents.exported (formát, počet dokladů, výběr) do historie změn; jinak nic nemění.","x-saldo-repeat":"Každé volání vrátí nový soubor a přidá další událost do historie.","x-saldo-errors":[{"status":400,"when":"format chybí nebo není pohoda či money („Zvolte formát exportu: pohoda, nebo money“)."},{"status":422,"when":"Soubor nejde vytvořit – odpověď {error, problems[]}, kde problems vyjmenuje každý problém a error je ten jediný, nebo „Soubor nelze vytvořit – počet problémů: N“. Důvody – v období nejsou žádné vystavené doklady vybraných druhů, vybraný doklad není vystavený (koncept, stornovaný), druh dokladu není podporovaný, nebo firma nemá IČO (jen POHODA)."}]}},"/entities/{entity_id}/documents/payables":{"get":{"operationId":"listPayables","tags":["Exporty a předání účetní"],"summary":"Neuhrazené přijaté faktury pro příkaz k úhradě","description":"Vrátí všechny vystavené a dosud neuhrazené (i částečně uhrazené) přijaté faktury a přijaté zálohové faktury seřazené podle splatnosti. U každé uvede, zda ji lze zařadit do příkazu k úhradě – ABO pro doklady v CZK, SEPA pro doklady v EUR – s účtem příjemce, nebo důvod, proč to nejde. Doklady už zařazené do dřívějšího příkazu se nijak neodlišují, protože příkaz úhradu nezapisuje.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"Účetní jednotka (firma).","schema":{"type":"integer"},"example":12}],"responses":{"200":{"description":"Objekt s polem rows.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"exporty","x-saldo-access":"member","x-saldo-side-effects":"Nic nezapisuje.","x-saldo-limits":"Bez stránkování – vrací všechny takové doklady.","x-saldo-response-fields":[{"name":"rows","description":"Doklady podle splatnosti, pak podle id."},{"name":"rows[].id","description":"Doklad; number je číslo v Saldu, original_number číslo dodavatele, kind a kind_label druh."},{"name":"rows[].variable_symbol","description":"Variabilní symbol; partner_name příjemce."},{"name":"rows[].due_date","description":"Splatnost; payment_state (unpaid, partial, overdue) a days_overdue."},{"name":"rows[].remaining","description":"Zbývá uhradit v měně dokladu (currency)."},{"name":"rows[].scheme","description":"abo (CZK), sepa (EUR), nebo null u jiné měny."},{"name":"rows[].account","description":"Účet příjemce – české číslo účtu; u SEPA nebo bez českého čísla IBAN (s BIC, je-li uveden); null, když dodavatel účet nemá."},{"name":"rows[].problem","description":"Důvod, proč doklad do příkazu nejde (chybí účet, neplatný IBAN, jiná měna…), jinak null."}]}},"/entities/{entity_id}/documents/payment_order":{"post":{"operationId":"createPaymentOrder","tags":["Exporty a předání účetní"],"summary":"Příkaz k úhradě ABO nebo SEPA z přijatých faktur","description":"Vytvoří soubor hromadného příkazu k úhradě pro banku z vybraných neuhrazených přijatých faktur a přijatých zálohových faktur: ABO (formát KPC) z účtu v CZK pro doklady v CZK, nebo SEPA pain.001.001.03 pro doklady v EUR. Platí se zbývající částka dokladu; datum platby je execution_date, bez něj pozdější ze splatnosti a dneška, v obou případech posunuté na nejbližší pracovní den. Soubor jen připravuje platby k nahrání do banky – úhradu v Saldu nezapíše ani doklad neoznačí jako uhrazený; uhrazený bude až spárováním s bankovním pohybem.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"Účetní jednotka (firma).","schema":{"type":"integer"},"example":12}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["ids","bank_account_id"],"properties":{"ids":{"type":"array","description":"Doklady k úhradě (pole id; čárkou oddělený řetězec se tu nepodporuje). Neexistující nebo cizí doklad vrátí 404.","items":{"type":"integer"}},"bank_account_id":{"type":"integer","description":"Bankovní účet firmy, ze kterého se platí (ne pokladna); cizí nebo neexistující vrátí 404."},"format":{"type":"string","description":"auto = podle měny dokladů (všechny CZK → ABO, všechny EUR → SEPA).","enum":["auto","abo","sepa"],"default":"auto"},"execution_date":{"type":"string","format":"date","description":"Datum splatnosti příkazu (YYYY-MM-DD), nejdříve dnes."}}},"example":{"ids":[144],"bank_account_id":2,"format":"abo"}}}},"responses":{"200":{"description":"Soubor ke stažení. ABO – Content-Type text/plain; charset=windows-1250, název prikaz-abo-RRRRMMDD.kpc; SEPA – application/xml; charset=utf-8, název prikaz-sepa-RRRRMMDD.xml (datum vytvoření).","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"format není auto, abo ani sepa („Formát příkazu je auto, abo, nebo sepa“).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"422":{"description":"Chybí bank_account_id („Vyberte bankovní účet, ze kterého se bude platit“). Příkaz nejde vytvořit – odpověď {error, problems[]}. Důvody – žádný doklad, zvolená pokladna, execution_date v minulosti, doklady v různých měnách u format=auto, doklad není vystavený, není přijatá faktura ani zálohová faktura, je už uhrazený, má jinou měnu než formát, příjemce nemá české číslo účtu (ABO) nebo platný IBAN (SEPA; BIC je nepovinný, uvedený ale musí být platný), účet neprošel kontrolou modulo 11, konstantní symbol má víc než 4 číslice, částka přesahuje limit formátu, nebo platební účet firmy nemá české číslo, není v CZK (ABO) či nemá platný IBAN (SEPA).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"exporty","x-saldo-access":"writer","x-saldo-side-effects":"Zapíše událost documents.payment_order do historie změn. Úhrady, stav dokladů ani účetní zápisy nemění.","x-saldo-limits":"Částka jednoho dokladu nejvýše 9 999 999 999,99 Kč (ABO) nebo 999 999 999,99 EUR (SEPA).","x-saldo-repeat":"Každé volání vytvoří nový soubor; tytéž doklady lze zařadit opakovaně, Saldo nehlídá, že už v jiném příkazu byly.","x-saldo-errors":[{"status":400,"when":"format není auto, abo ani sepa („Formát příkazu je auto, abo, nebo sepa“)."},{"status":422,"when":"Chybí bank_account_id („Vyberte bankovní účet, ze kterého se bude platit“)."},{"status":422,"when":"Příkaz nejde vytvořit – odpověď {error, problems[]}. Důvody – žádný doklad, zvolená pokladna, execution_date v minulosti, doklady v různých měnách u format=auto, doklad není vystavený, není přijatá faktura ani zálohová faktura, je už uhrazený, má jinou měnu než formát, příjemce nemá české číslo účtu (ABO) nebo platný IBAN (SEPA; BIC je nepovinný, uvedený ale musí být platný), účet neprošel kontrolou modulo 11, konstantní symbol má víc než 4 číslice, částka přesahuje limit formátu, nebo platební účet firmy nemá české číslo, není v CZK (ABO) či nemá platný IBAN (SEPA)."}]}},"/entities/{entity_id}/accounting_package/preview":{"get":{"operationId":"previewAccountingPackage","tags":["Exporty a předání účetní"],"summary":"Náhled balíčku pro účetní","description":"Spočítá, co by obsahoval balíček pro účetní za období – počty dokladů, konceptů, příloh, výpisů a podání, názvy sestav, velikost originálů – a co v Saldu chybí, bez sestavení balíčku a bez generování sestav. Období se zadává po měsících nebo po dnech a nesmí přesáhnout 800 dní.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"Účetní jednotka (firma).","schema":{"type":"integer"},"example":12},{"name":"from","in":"query","required":false,"description":"Začátek období – YYYY-MM (první den měsíce) nebo YYYY-MM-DD. Výchozí je začátek aktuálního účetního období (začíná-li v budoucnu, o 12 měsíců dřív).","schema":{"type":"string"},"example":"2026-09"},{"name":"to","in":"query","required":false,"description":"Konec období – YYYY-MM (poslední den měsíce) nebo YYYY-MM-DD; výchozí je dnešek.","schema":{"type":"string"},"example":"2026-09"}],"responses":{"200":{"description":"Obsah budoucího balíčku.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Začátek je po konci („Začátek období musí být před koncem“). Období je delší než 800 dní („Balíček lze vytvořit nejvýš za 800 dní – rozdělte období“).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"exporty","x-saldo-access":"manager","x-saldo-side-effects":"Nic nezapisuje.","x-saldo-limits":"Období nejvýše 800 dní; missing vrací nejvýše 50 položek.","x-saldo-errors":[{"status":422,"when":"Začátek je po konci („Začátek období musí být před koncem“)."},{"status":422,"when":"Období je delší než 800 dní („Balíček lze vytvořit nejvýš za 800 dní – rozdělte období“)."}],"x-saldo-response-fields":[{"name":"period","description":"Období {from, to}."},{"name":"counts","description":"documents, drafts, attachments, bank_statements, bank_files, filings, filing_files, reports."},{"name":"reports","description":"Cesty sestav v balíčku (např. sestavy/doklady.csv, sestavy/obratova-predvaha.csv)."},{"name":"source_bytes","description":"Velikost originálů (přílohy, výpisy, doručenky) v bajtech; too_large je true nad 1 GB."},{"name":"missing_count","description":"Počet chybějících podkladů; missing prvních 50 z nich (area, issue, reference, date, amount, currency, note)."},{"name":"notes","description":"Poznámky k balíčku (např. že vydané faktury nejsou jako neměnné originály, proč nevznikl POHODA XML)."}]}},"/entities/{entity_id}/accounting_package":{"get":{"operationId":"downloadAccountingPackage","tags":["Exporty a předání účetní"],"summary":"Stažení balíčku pro účetní (ZIP)","description":"Sestaví a vrátí ZIP za období (do 800 dní) se složkou saldo-IČO-od-do: sestavy/ (CSV se středníkem v UTF-8 s BOM – doklady, bankovní pohyby, v podvojném účetnictví deník, předvaha, saldokonto pohledávek a závazků a rozvaha s výsledovkou v JSON za každé dotčené účetní období, v daňové evidenci peněžní deník), doklady/ (původní přílohy a přijaté ISDOC dokladů s datem vystavení, DUZP nebo datem pro DPH v období nebo se zápisem či úhradou v období), doklady/koncepty/ (přílohy konceptů), banka/ (archivované datové soubory a PDF výpisů), podani/ (XML podání a doručenky), export/pohoda.xml (pokud jde vytvořit), chybejici-podklady.csv, README.txt, manifest.json s velikostí a SHA-256 každého souboru a SHA256SUMS. Balíček vzniká jen čtením dat; soubor, který v úložišti chybí nebo nesouhlasí s kontrolním součtem, se uvede v chybejici-podklady.csv a manifest označí balíček jako neúplný.","parameters":[{"name":"entity_id","in":"path","required":true,"description":"Účetní jednotka (firma).","schema":{"type":"integer"},"example":12},{"name":"from","in":"query","required":false,"description":"Začátek období – YYYY-MM nebo YYYY-MM-DD; výchozí je začátek aktuálního účetního období (začíná-li v budoucnu, o 12 měsíců dřív).","schema":{"type":"string"},"example":"2026-09"},{"name":"to","in":"query","required":false,"description":"Konec období – YYYY-MM (poslední den měsíce) nebo YYYY-MM-DD; výchozí je dnešek.","schema":{"type":"string"},"example":"2026-09"}],"responses":{"200":{"description":"ZIP ke stažení (Content-Disposition attachment; filename saldo-IČO-RRRR-MM-DD-RRRR-MM-DD.zip, bez IČO id firmy) s hlavičkami Content-Length, Cache-Control private, no-store a X-Content-Type-Options nosniff.","content":{"application/zip":{"schema":{"type":"string","format":"binary"}}}},"405":{"description":"Metoda HEAD – balíček se nesestaví, odpověď nese hlavičku Allow GET.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"403":{"description":"Hlavička Sec-Fetch-Site má jinou hodnotu než same-origin nebo none (odkaz z jiného webu). Klienti API, kteří tuto hlavičku neposílají, nejsou dotčeni.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"409":{"description":"Pro tutéž firmu se právě sestavuje jiný balíček („Balíček pro tuto firmu se právě vytváří…“).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"422":{"description":"Začátek je po konci („Začátek období musí být před koncem“), nebo je období delší než 800 dní. Originály za období mají víc než 1 GB („Přílohy a výpisy za období mají N MB, víc než 1024 MB – zvolte kratší období“).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"exporty","x-saldo-access":"manager","x-saldo-side-effects":"Nic v účetnictví nemění. Balíček se sestaví do dočasného souboru na serveru, který se po odeslání smaže (spolu s pozůstatky staršími 6 hodin), a zapíše se událost accounting_package.exported s obdobím, úplností a SHA-256 souboru manifest.json do historie změn.","x-saldo-limits":"Období nejvýše 800 dní, originály nejvýše 1 GB, pro jednu firmu se najednou sestavuje jen jeden balíček. Balíček se celý sestaví dřív, než začne odpověď.","x-saldo-repeat":"Každé stažení sestaví balíček znovu podle aktuálních dat a zapíše další událost; souběžný požadavek pro tutéž firmu dostane 409 PACKAGE_BUSY.","x-saldo-errors":[{"status":405,"when":"Metoda HEAD – balíček se nesestaví, odpověď nese hlavičku Allow GET."},{"status":403,"code":"CROSS_SITE","when":"Hlavička Sec-Fetch-Site má jinou hodnotu než same-origin nebo none (odkaz z jiného webu). Klienti API, kteří tuto hlavičku neposílají, nejsou dotčeni."},{"status":409,"code":"PACKAGE_BUSY","when":"Pro tutéž firmu se právě sestavuje jiný balíček („Balíček pro tuto firmu se právě vytváří…“)."},{"status":422,"when":"Začátek je po konci („Začátek období musí být před koncem“), nebo je období delší než 800 dní."},{"status":422,"when":"Originály za období mají víc než 1 GB („Přílohy a výpisy za období mají N MB, víc než 1024 MB – zvolte kratší období“)."}]}},"/entities/{id}/export":{"get":{"operationId":"exportEntityBackup","tags":["Exporty a předání účetní"],"summary":"Export účetních dat firmy v JSON (bez souborů)","description":"Vrátí jeden soubor JSON se všemi záznamy těchto tabulek firmy: údaje a nastavení firmy (bez loga), účty, kontakty, bankovní účty (bez tokenu Fio), doklady s položkami (bez tokenu sdílení), úhrady, bankovní pohyby, účetní zápisy, majetek, zaměstnanci, výplatní pásky, cesty, opakované faktury, podání včetně XML a bankovní pravidla. Neobsahuje soubory (přílohy dokladů, výpisy, doručenky), historii změn, členy, žádosti o podklady, historii schvalování, číselné řady ani archiv výpisů. Saldo nemá operaci, která by takový soubor nahrála zpět.","parameters":[{"name":"id","in":"path","required":true,"description":"Účetní jednotka (firma), jejímž jste přijatým členem.","schema":{"type":"integer"},"example":12}],"responses":{"200":{"description":"Soubor ke stažení (Content-Disposition attachment; filename saldo-IČO-RRRR-MM-DD.json, bez IČO id firmy), záznamy se všemi sloupci tabulek.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"4XX":{"description":"Chyba","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"},"errors":{"type":"object","additionalProperties":true}}}}}}},"x-saldo-group":"exporty","x-saldo-access":"member","x-saldo-side-effects":"Nic nezapisuje, ani do historie změn.","x-saldo-limits":"Celá firma v jedné odpovědi bez stránkování.","x-saldo-response-fields":[{"name":"format","description":"Vždy saldo-backup; version je 1, exported_at čas exportu."},{"name":"entity","description":"Sloupce firmy kromě logo_data (včetně settings s daňovým profilem)."},{"name":"accounts","description":"Účty; dále partners, bank_accounts, payments, bank_transactions, entries, assets, employees, payslips, trips, recurrences, filings, bank_rules."},{"name":"documents","description":"Doklady bez share_token, každý s polem lines (položky)."}]}}}}