Reference API
Exporty a předání účetní
Soubory pro předání dat: balíček pro účetní s originály a kontrolními součty, export do POHODY a Money S3, platební příkazy ABO a SEPA a export dat firmy do JSON (bez souborů a historie změn; Saldo ho zpět nenačte). Exporty nemění účetnictví, nic neodesílají a nic neoznačí jako zaplacené.
GET Export dokladů do POHODY nebo Money S3
/entities/{entity_id}/documents/export
- Oprávnění
- Každý člen firmy včetně role Jen čtení
- Klíč jen pro čtení
- Stačí
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í.
Parametry
| Název | Kde | Typ | Povinný | Popis |
|---|---|---|---|---|
entity_id | cesta | celé číslo | ano | Účetní jednotka (firma). Příklad 12. |
format | dotaz | text | ano | pohoda = POHODA XML, money = Money S3 XML. Hodnoty: pohoda, money. Příklad pohoda. |
ids | dotaz | pole (celé číslo) | ne | 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. Příklad [431, 432]. |
kinds | dotaz | pole (text) | ne | Druhy dokladů pro výběr podle období (kinds[]=… nebo oddělené čárkou); výchozí jsou všechny uvedené, jiné hodnoty se ignorují. Hodnoty: invoice_out, credit_out, proforma_out, advance_out, invoice_in, credit_in, proforma_in, advance_in. Příklad ["invoice_out", "credit_out"]. |
year | dotaz | celé číslo | ne | Účetní období začínající v tomto roce, když chybí from nebo to; výchozí je aktuální rok. Rozsah od 2000 do 2100. Příklad 2026. |
from | dotaz | datum | ne | Začátek období (YYYY-MM-DD); výchozí je začátek účetního období year. Příklad 2026-09-01. |
to | dotaz | datum | ne | Konec období včetně; výchozí je konec účetního období year. Příklad 2026-09-30. |
Odpověď
200 application/xml 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í.
Chyby této operace
| Stav | Kód | Kdy |
|---|---|---|
| 400 | – | format chybí nebo není pohoda či money („Zvolte formát exportu: pohoda, nebo money“). |
| 422 | – | 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). |
Společné chyby všech operací (přihlášení, oprávnění, limity) popisuje Chyby a limity.
Chování
- Co změní
- Zapíše událost documents.exported (formát, počet dokladů, výběr) do historie změn; jinak nic nemění.
- Opakování
- Každé volání vrátí nový soubor a přidá další událost do historie.
Příklad
cURL
curl \
-H "X-API-Key: $SALDO_API_KEY" \
"https://techtools.cz/ucetnictvi-api/entities/1/documents/export?format=pohoda&ids=129"JavaScript
const response = await fetch('https://techtools.cz/ucetnictvi-api/entities/1/documents/export?format=pohoda&ids=129', {
headers: { 'X-API-Key': process.env.SALDO_API_KEY }
});
const data = await response.json();<?xml version="1.0" encoding="Windows-1250"?>
<dat:dataPack xmlns:dat="http://www.stormware.cz/schema/version_2/data.xsd" xmlns:inv="http://www.stormware.cz/schema/version_2/invoice.xsd" xmlns:int="http://www.stormware.cz/schema/version_2/intDoc.xsd" xmlns:typ="http://www.stormware.cz/schema/version_2/type.xsd" version="2.0" id="SALDO-1-6566230e3a3ce377" ico="99999994" application="Saldo" note="Export ze Saldo – Ukázková firma s.r.o., počet dokladů 1 (28. 9. 2026)">
<dat:dataPackItem version="2.0" id="SALDO-1-129">
<inv:invoice version="2.0">
<inv:invoiceHeader>
<inv:invoiceType>issuedInvoice</inv:invoiceType>
<inv:number>
<typ:numberRequested>FV20260025</typ:numberRequested>
</inv:number>
<inv:symVar>20260025</inv:symVar>
<inv:date>2026-09-28</inv:date>
<inv:dateTax>2026-09-28</inv:dateTax>
<inv:dateAccounting>2026-09-28</inv:dateAccounting>
<inv:dateDue>2026-10-12</inv:dateDue>
<inv:classificationVAT>
<typ:ids>UD</typ:ids>
</inv:classificationVAT>
<inv:text>Správa webu – září</inv:text>
<inv:partnerIdentity>
<typ:address>
<typ:company>Nordwood Studio s.r.o.</typ:company>
<typ:city>Praha 10</typ:city>
<typ:street>Korunní 1208/74</typ:street>
<typ:zip>10100</typ:zip>
<typ:ico>90000013</typ:ico>
<typ:dic>CZ90000013</typ:dic>
<typ:email>fakturace@example.cz</typ:email>
</typ:address>
</inv:partnerIdentity>
<inv:paymentType>
<typ:paymentType>draft</typ:paymentType>
</inv:paymentType>
<inv:account>
<typ:accountNo>2900001227</typ:accountNo>
<typ:bankCode>2010</typ:bankCode>
</inv:account>
</inv:invoiceHeader>
<inv:invoiceDetail>
<inv:invoiceItem>
<inv:text>Správa webu – září</inv:text>
<inv:quantity>12</inv:quantity>
<inv:unit>hod</inv:unit>
<inv:payVAT>false</inv:payVAT>
<inv:rateVAT>high</inv:rateVAT>
<inv:homeCurrency>
<typ:unitPrice>1650</typ:unitPrice>
<typ:price>19800.00</typ:price>
<typ:priceVAT>4158.00</typ:priceVAT>
</inv:homeCurrency>
</inv:invoiceItem>
</inv:invoiceDetail>
<inv:invoiceSummary>
<inv:roundingDocument>none</inv:roundingDocument>
<inv:roundingVAT>none</inv:roundingVAT>
<inv:homeCurrency>
<typ:priceHigh>19800.00</typ:priceHigh>
<typ:priceHighVAT>4158.00</typ:priceHighVAT>
<typ:priceHighSum>23958.00</typ:priceHighSum>
</inv:homeCurrency>
</inv:invoiceSummary>
</inv:invoice>
</dat:dataPackItem>
</dat:dataPack>
GET Neuhrazené přijaté faktury pro příkaz k úhradě
/entities/{entity_id}/documents/payables
- Oprávnění
- Každý člen firmy včetně role Jen čtení
- Klíč jen pro čtení
- Stačí
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. Doklad zařazený do dřívějšího příkazu za celý zbytek má in_order true a upozornění; dodavatel veden jako nespolehlivý plátce (z kontroly kontaktů) má upozornění na ručení (§ 109 ZDPH).
Parametry
| Název | Kde | Typ | Povinný | Popis |
|---|---|---|---|---|
entity_id | cesta | celé číslo | ano | Účetní jednotka (firma). Příklad 12. |
Odpověď
200 application/json Objekt s polem rows.
| Pole | Význam |
|---|---|
rows | Doklady podle splatnosti, pak podle id. |
rows[].id | Doklad; number je číslo v Saldu, original_number číslo dodavatele, kind a kind_label druh. |
rows[].variable_symbol | Variabilní symbol; partner_name příjemce. |
rows[].due_date | Splatnost; payment_state (unpaid, partial, overdue) a days_overdue. |
rows[].remaining | Zbývá uhradit v měně dokladu (currency). |
rows[].scheme | abo (CZK), sepa (EUR), nebo null u jiné měny. |
rows[].account | Účet příjemce – účet z dokladu (payee_account, payee_iban), jinak z kontaktu; české číslo účtu, u SEPA nebo bez českého čísla IBAN (s BIC, je-li uveden); null, když účet chybí. |
rows[].problem | Důvod, proč doklad do příkazu nejde (chybí účet, neplatný IBAN, jiná měna…), jinak null. |
rows[].in_order | true, když je doklad v dříve staženém příkazu za celý zbytek; ordered_on datum platby z příkazu a ordered_amount jeho částka (i u částečného zařazení). |
rows[].warnings | Upozornění, kvůli kterým aplikace doklad nepředvybere: účet na dokladu se liší od účtu kontaktu, dodavatel je nespolehlivý plátce DPH, dodavatel má neuhrazený přijatý dobropis, doklad už je v dříve staženém příkazu. Prázdné pole, když není co hlásit. |
Chování
- Co změní
- Nic nezapisuje.
- Limity
- Bez stránkování – vrací všechny takové doklady.
Příklad
cURL
curl \
-H "X-API-Key: $SALDO_API_KEY" \
https://techtools.cz/ucetnictvi-api/entities/1/documents/payablesJavaScript
const response = await fetch('https://techtools.cz/ucetnictvi-api/entities/1/documents/payables', {
headers: { 'X-API-Key': process.env.SALDO_API_KEY }
});
const data = await response.json();{
"rows": [
{
"id": 131,
"number": "FP20260039",
"kind": "invoice_in",
"kind_label": "Faktura přijatá",
"original_number": "2026090417",
"variable_symbol": "2026090417",
"partner_name": "Coworking Karlín s.r.o.",
"due_date": "2026-10-09",
"currency": "CZK",
"remaining": 17545.0,
"payment_state": "unpaid",
"days_overdue": 0,
"scheme": "abo",
"account": "2397734510/0100",
"problem": null,
"warnings": [],
"ordered_on": null,
"ordered_amount": null,
"in_order": false
}
]
}
GET Prověření dodavatelů v registru plátců DPH
/entities/{entity_id}/documents/payables/registry
- Oprávnění
- Každý člen firmy včetně role Jen čtení
- Klíč jen pro čtení
- Stačí
Pro zvolené přijaté faktury a zálohové faktury se zeptá registru plátců DPH finanční správy na dodavatele s českým DIČ: zda je nespolehlivý plátce a zda je účet příjemce z dokladu zveřejněný. Upozornění řekne, kdy za DPH ručíte – u nespolehlivého plátce vždy (s odkazem na úhradu DPH finančnímu úřadu podle § 109a ZDPH), u nezveřejněného účtu při platbě nad 540 000 Kč (§ 109 odst. 2 písm. c ZDPH). Doklady jiných firem a jiné druhy se ignorují. Nic neukládá.
Parametry
| Název | Kde | Typ | Povinný | Popis |
|---|---|---|---|---|
entity_id | cesta | celé číslo | ano | Účetní jednotka (firma). Příklad 12. |
ids | dotaz | text | ano | Čárkou oddělená id dokladů (nejvýše 200). Příklad 1540,1541. |
Odpověď
200 application/json Objekt s polem rows.
| Pole | Význam |
|---|---|
rows[].id | Doklad; dic DIČ dodavatele, checked = registr o dodavateli odpověděl. |
rows[].payer | Dodavatel je plátce DPH (nebo skupina); unreliable = nespolehlivý plátce. |
rows[].account | Účet příjemce z dokladu (české číslo účtu) a published = je zveřejněný v registru (null, když nešlo ověřit). |
rows[].warnings | Upozornění česky (nespolehlivý plátce, nezveřejněný účet s limitem ručení). |
Chyby této operace
| Stav | Kód | Kdy |
|---|---|---|
| 503 | – | Registr plátců DPH neodpovídá („Registr plátců DPH je nedostupný (…)“) nebo vrátil chybu. |
Společné chyby všech operací (přihlášení, oprávnění, limity) popisuje Chyby a limity.
Chování
- Co změní
- Nic nezapisuje; volá veřejný registr plátců DPH (MFČR, nejvýše 100 DIČ na dotaz).
Příklad
Odpověď registru je v příkladu syntetická.
cURL
curl \
-H "X-API-Key: $SALDO_API_KEY" \
"https://techtools.cz/ucetnictvi-api/entities/1/documents/payables/registry?ids=131"JavaScript
const response = await fetch('https://techtools.cz/ucetnictvi-api/entities/1/documents/payables/registry?ids=131', {
headers: { 'X-API-Key': process.env.SALDO_API_KEY }
});
const data = await response.json();{
"rows": [
{
"id": 131,
"dic": "CZ90000056",
"checked": true,
"payer": true,
"unreliable": false,
"account": "2397734510/0100",
"published": false,
"warnings": [
"Účet 2397734510/0100 není zveřejněný v registru plátců DPH"
]
}
]
}
Odpověď externí služby (registr plátců DPH) je v ukázce nahrazená smyšlenými údaji ve formátu, který služba vrací.
POST Příkaz k úhradě ABO nebo SEPA z přijatých faktur
/entities/{entity_id}/documents/payment_order
- Oprávnění
- Vlastník, účetní nebo editor
- Klíč jen pro čtení
- Nestačí, vrátí 403
READ_ONLY_KEY
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. U každého dokladu si poznamená datum platby (ordered_on) a zařazenou částku (ordered_amount), aby ho listPayables příště označil jako už zařazený.
Parametry
| Název | Kde | Typ | Povinný | Popis |
|---|---|---|---|---|
entity_id | cesta | celé číslo | ano | Účetní jednotka (firma). Příklad 12. |
Tělo požadavku
Formát application/json.
| Pole | Typ | Povinné | Popis |
|---|---|---|---|
ids | pole (celé číslo) | ano | Doklady k úhradě (pole id nebo čárkou oddělený řetězec). Neexistující nebo cizí doklad vrátí 404. |
bank_account_id | celé číslo | ano | Bankovní účet firmy, ze kterého se platí (ne pokladna); cizí nebo neexistující vrátí 404. |
format | text | ne | auto = podle měny dokladů (všechny CZK → ABO, všechny EUR → SEPA). Hodnoty: auto, abo, sepa. Výchozí auto. |
execution_date | datum | ne | Datum splatnosti příkazu (YYYY-MM-DD), nejdříve dnes. |
Odpověď
200 application/octet-stream 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í).
Chyby této operace
| Stav | Kód | Kdy |
|---|---|---|
| 400 | – | format není auto, abo ani sepa („Formát příkazu je auto, abo, nebo sepa“). |
| 422 | – | Chybí bank_account_id („Vyberte bankovní účet, ze kterého se bude platit“). |
| 422 | – | Zvolená pokladna („Z pokladny … nelze platit příkazem k úhradě – vyberte bankovní účet“). |
| 422 | – | 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). |
Společné chyby všech operací (přihlášení, oprávnění, limity) popisuje Chyby a limity.
Chování
- Co změní
- Zapíše událost documents.payment_order do historie změn a u dokladů ordered_on a ordered_amount. Úhrady, stav úhrady ani účetní zápisy nemění.
- Limity
- Částka jednoho dokladu nejvýše 9 999 999 999,99 Kč (ABO) nebo 999 999 999,99 EUR (SEPA).
- Opakování
- Každé volání vytvoří nový soubor; tytéž doklady lze zařadit opakovaně (ordered_on a ordered_amount se přepíší), listPayables je ale označí jako už zařazené.
Příklad
cURL
curl \
-X POST \
-H "X-API-Key: $SALDO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"ids":[131],"bank_account_id":2,"format":"abo"}' \
https://techtools.cz/ucetnictvi-api/entities/1/documents/payment_orderJavaScript
const response = await fetch('https://techtools.cz/ucetnictvi-api/entities/1/documents/payment_order', {
headers: { 'X-API-Key': process.env.SALDO_API_KEY, 'Content-Type': 'application/json' },
method: 'POST',
body: JSON.stringify({
"ids": [
131
],
"bank_account_id": 2,
"format": "abo"
})
});
const data = await response.json();UHL1280926UKAZKOVA FIRMA S.R.O2900001227001999111111222222
1 1501 001000 2010
2 2900001227 00000001754500 091026
2397734510 000001754500 2026090417 01000000 0000000000 AV:Uhrada faktury 2026090417
3 +
5 +
GET Náhled balíčku pro účetní
/entities/{entity_id}/accounting_package/preview
- Oprávnění
- Vlastník nebo účetní
- Klíč jen pro čtení
- Stačí
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í.
Parametry
| Název | Kde | Typ | Povinný | Popis |
|---|---|---|---|---|
entity_id | cesta | celé číslo | ano | Účetní jednotka (firma). Příklad 12. |
from | dotaz | text | ne | 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). Příklad 2026-09. |
to | dotaz | text | ne | Konec období – YYYY-MM (poslední den měsíce) nebo YYYY-MM-DD; výchozí je dnešek. Příklad 2026-09. |
Odpověď
200 application/json Obsah budoucího balíčku.
| Pole | Význam |
|---|---|
period | Období {from, to}. |
counts | documents, drafts, attachments, request_files (soubory ze žádostí o podklady), bank_statements, bank_files, filings, filing_files, reports. |
reports | Cesty sestav v balíčku (např. sestavy/doklady.csv, sestavy/obratova-predvaha.csv). |
source_bytes | Velikost originálů (přílohy, výpisy, doručenky) v bajtech; too_large je true nad 1 GB. |
missing_count | Počet chybějících podkladů; missing prvních 50 z nich (area, issue, reference, date, amount, currency, note). |
notes | Poznámky k balíčku (např. že vydané faktury mají originál PDF jen tehdy, když ho Saldo uložilo, proč nevznikl POHODA XML). |
Chyby této operace
| Stav | Kód | Kdy |
|---|---|---|
| 422 | – | Začátek je po konci („Začátek období musí být před koncem“). |
| 422 | – | Období je delší než 800 dní („Balíček lze vytvořit nejvýš za 800 dní – rozdělte období“). |
Společné chyby všech operací (přihlášení, oprávnění, limity) popisuje Chyby a limity.
Chování
- Co změní
- Nic nezapisuje.
- Limity
- Období nejvýše 800 dní; missing vrací nejvýše 50 položek.
Příklad
cURL
curl \
-H "X-API-Key: $SALDO_API_KEY" \
"https://techtools.cz/ucetnictvi-api/entities/1/accounting_package/preview?from=2026-08&to=2026-08"JavaScript
const response = await fetch('https://techtools.cz/ucetnictvi-api/entities/1/accounting_package/preview?from=2026-08&to=2026-08', {
headers: { 'X-API-Key': process.env.SALDO_API_KEY }
});
const data = await response.json();{
"period": {
"from": "2026-08-01",
"to": "2026-08-31"
},
"counts": {
"documents": 9,
"drafts": 0,
"attachments": 0,
"request_files": 0,
"bank_statements": 1,
"bank_files": 1,
"filings": 1,
"filing_files": 2,
"reports": 7
},
"reports": [
"sestavy/doklady.csv",
"sestavy/bankovni-pohyby.csv"
],
"source_bytes": 1677,
"too_large": false,
"missing_count": 9,
"missing": [
{
"area": "Doklady",
"issue": "Přijatý doklad nemá přiložený originál",
"reference": "FP20260029",
"date": "2026-08-02",
"amount": 17545.0,
"currency": "CZK",
"note": "Coworking Karlín s.r.o."
},
{
"area": "Doklady",
"issue": "Přijatý doklad nemá přiložený originál",
"reference": "FP20260030",
"date": "2026-08-05",
"amount": 4719.0,
"currency": "CZK",
"note": "Serverovna Holešovice s.r.o."
}
],
"notes": [
"Vydané faktury mají ve složce originál PDF ve verzi předané odběrateli, pokud ho Saldo uložilo (při stažení, odeslání nebo sdílení); ostatní jsou jen v sestavy/doklady.csv a export/pohoda.xml.",
"Balíček vznikl jen čtením dat; nic se nezaúčtovalo ani nezměnilo."
]
}
Dlouhé seznamy jsou v ukázce zkrácené na první položky.
GET Stažení balíčku pro účetní (ZIP)
/entities/{entity_id}/accounting_package
- Oprávnění
- Vlastník nebo účetní
- Klíč jen pro čtení
- Stačí
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ů), podklady/ (soubory dodané v nezrušených žádostech o podklady k pohybům a dokladům období), 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ý.
Parametry
| Název | Kde | Typ | Povinný | Popis |
|---|---|---|---|---|
entity_id | cesta | celé číslo | ano | Účetní jednotka (firma). Příklad 12. |
from | dotaz | text | ne | 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). Příklad 2026-09. |
to | dotaz | text | ne | Konec období – YYYY-MM (poslední den měsíce) nebo YYYY-MM-DD; výchozí je dnešek. Příklad 2026-09. |
Odpověď
200 application/zip 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.
Chyby této operace
| Stav | Kód | Kdy |
|---|---|---|
| 405 | – | Metoda HEAD – balíček se nesestaví, odpověď nese hlavičku Allow GET. |
| 403 | CROSS_SITE | 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. |
| 409 | PACKAGE_BUSY | Pro tutéž firmu se právě sestavuje jiný balíček („Balíček pro tuto firmu se právě vytváří…“). |
| 422 | – | Začátek je po konci („Začátek období musí být před koncem“), nebo je období delší než 800 dní. |
| 422 | – | 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í“). |
Společné chyby všech operací (přihlášení, oprávnění, limity) popisuje Chyby a limity.
Chování
- Co změní
- 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.
- Limity
- 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ěď.
- Opakování
- 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.
Příklad
cURL
curl \
-H "X-API-Key: $SALDO_API_KEY" \
"https://techtools.cz/ucetnictvi-api/entities/1/accounting_package?from=2026-08&to=2026-08"JavaScript
const response = await fetch('https://techtools.cz/ucetnictvi-api/entities/1/accounting_package?from=2026-08&to=2026-08', {
headers: { 'X-API-Key': process.env.SALDO_API_KEY }
});
const data = await response.json();application/zip, 23776 bajtů (soubor saldo-99999994-2026-08-01-2026-08-31.zip)
GET Export účetních dat firmy v JSON (bez souborů)
/entities/{id}/export
- Oprávnění
- Vlastník nebo účetní
- Klíč jen pro čtení
- Nestačí, vrátí 403
READ_ONLY_KEY
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, bankovní pravidla, časové rozlišení s dohady a rezervami a inventurní soupisy, a (od verze 2) členové (uživatelské jméno a role), verze dokladů, historie změn, historie schvalování, žádosti o podklady se zprávami a údaje archivu výpisů a podkladů k podáním s názvy souborů. Neobsahuje soubory (přílohy dokladů, výpisy, doručenky – ty jsou v úplném archivu GET /entities/{entity_id}/archive) ani číselné řady. Obsahuje mzdy a rodná čísla, proto ho stáhne jen vlastník nebo účetní a ne klíčem jen pro čtení. Do nové firmy ho obnoví POST /entities/restore (restoreEntity).
Parametry
| Název | Kde | Typ | Povinný | Popis |
|---|---|---|---|---|
id | cesta | celé číslo | ano | Účetní jednotka (firma), jejímž jste přijatým členem. Příklad 12. |
Odpověď
200 application/json 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.
| Pole | Význam |
|---|---|
format | Vždy saldo-backup; version je 2, exported_at čas exportu. |
entity | Sloupce firmy kromě logo_data (včetně settings s daňovým profilem). |
accounts | Účty; dále partners, bank_accounts, payments, bank_transactions, entries, assets, employees, payslips, trips, recurrences, filings, bank_rules, series (číselné řady a jejich další čísla), accruals (časové rozlišení, dohady a rezervy), inventories (inventurní soupisy). |
documents | Doklady bez share_token, každý s polem lines (položky). |
members | Členové { username, role, accepted_at, invited_by_id } bez e-mailů. |
document_versions | Verze dokladů; dále events (historie změn), document_approvals, document_requests (s messages a files), bank_statement_archives a filing_evidences (s files { filename, content_type, byte_size, checksum }). |
Chyby této operace
| Stav | Kód | Kdy |
|---|---|---|
| 403 | – | Volající není vlastník ani účetní („Export celé firmy obsahuje mzdy a rodná čísla – stáhne ho jen vlastník nebo účetní“) |
| 403 | – | API klíč jen pro čtení (code READ_ONLY_KEY) |
Společné chyby všech operací (přihlášení, oprávnění, limity) popisuje Chyby a limity.
Chování
- Co změní
- Zapíše do historie změn událost entity.exported.
- Limity
- Celá firma v jedné odpovědi bez stránkování.
Příklad
cURL
curl \
-H "X-API-Key: $SALDO_API_KEY" \
https://techtools.cz/ucetnictvi-api/entities/1/exportJavaScript
const response = await fetch('https://techtools.cz/ucetnictvi-api/entities/1/export', {
headers: { 'X-API-Key': process.env.SALDO_API_KEY }
});
const data = await response.json();{
"format": "saldo-backup",
"version": 2,
"exported_at": "2026-09-28 10:00:00 UTC",
"entity": {
"id": 1,
"accent_color": null,
"archived": false,
"bookkeeping": "double_entry",
"city": "Praha",
"company_id": null,
"country": "CZ",
"created_at": "2026-09-28 10:00:00 UTC",
"currency": "CZK",
"databox": null,
"default_due_days": 14,
"dic": "CZ99999994",
"email": "demo@example.cz",
"first_name": null,
"fiscal_year_start": 1,
"flat_expense_rate": null,
"house_number": "859",
"ico": "99999994",
"invoice_footer": null,
"last_name": null,
"legal_form": "sro",
"locked_until": null,
"nace": "621000",
"name": "Ukázková firma s.r.o.",
"orientation_number": "22",
"owner_id": 1,
"phone": "+420 777 000 000",
"register_note": "Zapsáno v obchodním rejstříku vedeném Městským soudem v Praze, oddíl C, vložka 999999 (ukázková data).",
"responsible_id": null,
"settings": {
"round_total": "always",
"demo": true,
"statement_category": "mikro",
"submitter": {
"first_name": "Jana",
"last_name": "Ukázková",
"relation": "jednatelka"
},
"tax_profile": {
"children": [
{
"order": 1,
"first_name": "Eliška",
"last_name": "Ukázková",
"birth_number": "1855120003"
}
],
"main_activity": true,
"birth_number": "8001010006"
},
"ossz_code": "110",
"cssz_variable_symbol": "1234567890",
"jmhz_workplace": {
"municipality": "Praha",
"municipality_code": "554782",
"country": "CZ"
}
},
"street": "Na Příkopě",
"tax_office_code": "451",
"tax_office_workplace": "2001",
"title": null,
"updated_at": "2026-09-28 10:00:00 UTC",
"vat_registered_on": "2023-01-01",
"vat_status": "monthly",
"web": null,
"zip": "11000"
},
"accounts": [
{
"id": 1,
"active": true,
"code": "012",
"created_at": "2026-09-28 10:00:00 UTC",
"entity_id": 1,
"kind": "asset",
"name": "Nehmotné výsledky vývoje",
"statement_line": null,
"tax_relevant": true,
"updated_at": "2026-09-28 10:00:00 UTC"
},
{
"id": 2,
"active": true,
"code": "013",
"created_at": "2026-09-28 10:00:00 UTC",
"entity_id": 1,
"kind": "asset",
"name": "Software",
"statement_line": null,
"tax_relevant": true,
"updated_at": "2026-09-28 10:00:00 UTC"
}
],
"partners": [
{
"id": 11,
"bank_account": "4434938563/0300",
"bic": null,
"checked_at": null,
"city": "Praha 1",
"company_id": null,
"country": "CZ",
"created_at": "2026-09-28 10:00:00 UTC",
"default_account_code": null,
"dic": "CZ90000099",
"due_days": null,
"email": null,
"entity_id": 1,
"iban": null,
"ico": "90000099",
"insolvency_checked_at": null,
"insolvency_note": null,
"insolvent": null,
"name": "Alfa Computers s.r.o.",
"note": null,
"phone": null,
"street": "Vodičkova 30",
"unreliable": null,
"updated_at": "2026-09-28 10:00:00 UTC",
"vat_payer": null,
"vies_checked_at": null,
"vies_name": null,
"vies_valid": null,
"web": null,
"zip": "11000"
},
{
"id": 3,
"bank_account": null,
"bic": null,
"checked_at": null,
"city": "Olomouc",
"company_id": null,
"country": "CZ",
"created_at": "2026-09-28 10:00:00 UTC",
"default_account_code": null,
"dic": "CZ90000030",
"due_days": 21,
"email": "fakturace@example.cz",
"entity_id": 1,
"iban": null,
"ico": "90000030",
"insolvency_checked_at": null,
"insolvency_note": null,
"insolvent": null,
"name": "Atelier Lumen s.r.o.",
"note": null,
"phone": null,
"street": "Masarykova 45",
"unreliable": null,
"updated_at": "2026-09-28 10:00:00 UTC",
"vat_payer": null,
"vies_checked_at": null,
"vies_name": null,
"vies_valid": null,
"web": null,
"zip": "77900"
}
],
"bank_accounts": [
{
"id": 1,
"account_code": "211001",
"archived": false,
"bank_code": null,
"bic": null,
"created_at": "2026-09-28 10:00:00 UTC",
"currency": "CZK",
"entity_id": 1,
"iban": null,
"is_default": false,
"kind": "cash",
"name": "Pokladna",
"number": null,
"opening_balance": 15000.0,
"opening_date": "2026-01-01",
"sync_error": null,
"synced_at": null,
"updated_at": "2026-09-28 10:00:00 UTC"
},
{
"id": 2,
"account_code": "221001",
"archived": false,
"bank_code": "2010",
"bic": "FIOBCZPP",
"created_at": "2026-09-28 10:00:00 UTC",
"currency": "CZK",
"entity_id": 1,
"iban": "CZ3820100000002900001227",
"is_default": true,
"kind": "bank",
"name": "Provozní účet",
"number": "2900001227",
"opening_balance": 420000.0,
"opening_date": "2026-01-01",
"sync_error": null,
"synced_at": null,
"updated_at": "2026-09-28 10:00:00 UTC"
}
],
"documents": [
{
"id": 132,
"accounting_date": "2026-09-28",
"approval_amount_czk": null,
"approval_fingerprint": null,
"approval_state": null,
"bank_account_id": 2,
"capture_key": null,
"constant_symbol": null,
"cost_center": null,
"created_at": "2026-09-28 10:00:00 UTC",
"created_by_id": 1,
"currency": "CZK",
"description": "Návrh úvodní stránky",
"due_date": "2026-10-12",
"entity_id": 1,
"exchange_rate": 1.0,
"internal_note": null,
"issue_date": "2026-09-28",
"kh_section": null,
"kind": "invoi
…
Dlouhé seznamy jsou v ukázce zkrácené na první položky.
GET Obsah úplného archivu firmy a zda jde firmu smazat
/entities/{entity_id}/archive/preview
- Oprávnění
- Vlastník nebo účetní
- Klíč jen pro čtení
- Nestačí, vrátí 403
READ_ONLY_KEY
Spočítá, co bude v úplném archivu firmy (doklady, verze, záznamy historie, soubory a jejich velikost), bez sestavení archivu, a v deletion vrátí, zda vlastník smí firmu teď smazat: allowed a reason (demo, empty = bez účetních záznamů, expired = záznamy starší než 10 let, archived = archiv stažený v posledních 30 dnech a po poslední změně, archive_required), keep_until (do kdy záznamy uchovat), archived_at a changed_at.
Parametry
| Název | Kde | Typ | Povinný | Popis |
|---|---|---|---|---|
entity_id | cesta | celé číslo | ano | ID firmy. Příklad 1. |
Odpověď
200 application/json Počty, velikost a stav smazání.
| Pole | Význam |
|---|---|
counts | documents, entries, versions, events, files, attachments, bank_files, filing_files, request_files, originals (originály PDF vydaných faktur) |
source_bytes | Součet velikostí ukládaných souborů v bajtech |
too_large | Soubory mají víc než 2 GB a archiv Saldo nesestaví |
deletion | { allowed, reason, keep_until, archived_at, changed_at } |
Chyby této operace
| Stav | Kód | Kdy |
|---|---|---|
| 403 | – | Volající není vlastník ani účetní, nebo API klíč jen pro čtení |
Společné chyby všech operací (přihlášení, oprávnění, limity) popisuje Chyby a limity.
Chování
- Co změní
- Nic nezapisuje.
Příklad
cURL
curl \
-H "X-API-Key: $SALDO_API_KEY" \
https://techtools.cz/ucetnictvi-api/entities/1/archive/previewJavaScript
const response = await fetch('https://techtools.cz/ucetnictvi-api/entities/1/archive/preview', {
headers: { 'X-API-Key': process.env.SALDO_API_KEY }
});
const data = await response.json();{
"counts": {
"documents": 79,
"entries": 324,
"versions": 76,
"events": 341,
"files": 5,
"attachments": 1,
"bank_files": 2,
"filing_files": 1,
"request_files": 1,
"originals": 0
},
"source_bytes": 2103,
"too_large": false,
"deletion": {
"allowed": true,
"reason": "demo"
}
}
GET Úplný archiv firmy (ZIP) se soubory a historií
/entities/{entity_id}/archive
- Oprávnění
- Vlastník nebo účetní
- Klíč jen pro čtení
- Nestačí, vrátí 403
READ_ONLY_KEY
Sestaví a pošle jeden ZIP: zaloha.json (jako GET /entities/{id}/export, verze 2), přílohy všech dokladů (doklady/), datové soubory a PDF výpisů (banka/), XML podání a doručenky (podani/), soubory ze žádostí o podklady (podklady/), ISDOC každé verze vydaného dokladu a uložené originály PDF (verze-dokladu/), README.txt, manifest.json (velikost, SHA-256 a původ každého souboru, problems) a SHA256SUMS. Soubor, který v úložišti chybí nebo nesouhlasí s kontrolním součtem, v archivu chybí a je v problems. Stažení je podmínkou smazání firmy se záznamy mladšími než 10 let (DELETE /entities/{id}).
Parametry
| Název | Kde | Typ | Povinný | Popis |
|---|---|---|---|---|
entity_id | cesta | celé číslo | ano | ID firmy. Příklad 1. |
Odpověď
200 application/zip ZIP ke stažení (saldo-archiv-IČO-RRRR-MM-DD.zip) se všemi soubory ve složce stejného jména.
Chyby této operace
| Stav | Kód | Kdy |
|---|---|---|
| 403 | – | Volající není vlastník ani účetní, API klíč jen pro čtení, nebo Sec-Fetch-Site jiný než same-origin či none |
| 405 | – | Metoda HEAD |
| 409 | – | Pro firmu se právě sestavuje archiv nebo balíček pro účetní (code PACKAGE_BUSY) |
| 422 | – | Soubory mají víc než 2 GB |
Společné chyby všech operací (přihlášení, oprávnění, limity) popisuje Chyby a limity.
Chování
- Co změní
- Archiv vznikne jen čtením. Do historie změn zapíše událost entity.archive_downloaded s otiskem manifestu. Dočasný soubor se po odeslání smaže.
- Limity
- Nejvýš 2 GB souborů; jeden archiv nebo balíček téže firmy najednou.
Příklad
cURL
curl \
-H "X-API-Key: $SALDO_API_KEY" \
https://techtools.cz/ucetnictvi-api/entities/1/archiveJavaScript
const response = await fetch('https://techtools.cz/ucetnictvi-api/entities/1/archive', {
headers: { 'X-API-Key': process.env.SALDO_API_KEY }
});
const data = await response.json();application/zip, 142749 bajtů (soubor saldo-archiv-99999994-2026-09-28.zip)
POST Obnoví firmu ze zálohy do nové firmy
/entities/restore
- Oprávnění
- Přihlášený uživatel nebo jeho API klíč, bez vazby na jednu firmu
- Pravidlo
- Přihlášení nebo API klíč pro čtení i zápis pro všechny firmy; klíč omezený na jednu firmu vrátí 403.
- Klíč jen pro čtení
- Nestačí, vrátí 403
READ_ONLY_KEY
Založí novou firmu volajícího (vlastník) z účetních dat v JSON (GET /entities/{id}/export) nebo z úplného archivu firmy (GET /entities/{entity_id}/archive) a přenese do ní účty, číselné řady, kontakty, bankovní účty, doklady s položkami, úhrady, pohyby, zápisy, majetek, pracovníky, výplatní pásky, cesty, opakované faktury (vypnuté), podání, bankovní pravidla, verze dokladů, historii změn, schvalování a žádosti o podklady. Z archivu ZIP přiloží i soubory, jejichž SHA-256 souhlasí s manifestem. Všechny vazby se přečíslují na nové záznamy; vazba na záznam, který v záloze není, se vynechá a nikdy neukáže do jiné firmy. Autoři záznamů zůstanou jen u volajícího a členů původní firmy, kterou volající spravuje, ostatní se vynechají. Nová firma dostane k názvu „– obnova datum“; členy, logo ani token Fio obnova nepřenáší a žádnou existující firmu nemění.
Tělo požadavku
Formát multipart/form-data.
| Pole | Typ | Povinné | Popis |
|---|---|---|---|
file | soubor | ano | Soubor saldo-backup (JSON) nebo úplný archiv firmy (ZIP), nejvýš 20 MB. |
Odpověď
201 application/json Nová firma a souhrn obnovy.
| Pole | Význam |
|---|---|
entity | Nová firma ve tvaru GET /entities/{id} (role owner) |
counts | Počty obnovených záznamů po tabulkách (documents, payments, entries, …) |
files | { attached, skipped[] } – přiložené soubory z archivu a cesty těch, které chyběly nebo nesouhlasily |
notes | Upozornění, např. vypnuté opakované faktury, nepřenesení členové |
Chyby této operace
| Stav | Kód | Kdy |
|---|---|---|
| 400 | – | Chybí soubor |
| 413 | – | Soubor je větší než 20 MB |
| 422 | – | Soubor není záloha Salda, archiv nejde přečíst nebo chybí zaloha.json, nebo je záloha z novější verze |
Společné chyby všech operací (přihlášení, oprávnění, limity) popisuje Chyby a limity.
Chování
- Co změní
- Vytvoří novou firmu s členstvím volajícího a všemi obnovenými záznamy; do historie nové firmy zapíše událost entity.restored. Nic jiného nemění.
- Limity
- Soubor nejvýš 20 MB; archiv nejvýš 10 000 souborů a 300 MB po rozbalení.
- Opakování
- Každé volání založí další firmu.
Příklad
Ukázka obnoví účetní data ukázkové OSVČ z JSON exportu.
cURL
curl \
-X POST \
-H "X-API-Key: $SALDO_API_KEY" \
-F "file=@zaloha.json" \
https://techtools.cz/ucetnictvi-api/entities/restoreJavaScript
const form = new FormData();
form.append('file', fileInput.files[0], 'zaloha.json');
const response = await fetch('https://techtools.cz/ucetnictvi-api/entities/restore', {
headers: { 'X-API-Key': process.env.SALDO_API_KEY },
method: 'POST',
body: form
});
const data = await response.json();{
"entity": {
"id": 4,
"accent_color": null,
"archived": false,
"bookkeeping": "tax_records",
"city": "Praha",
"company_id": null,
"country": "CZ",
"created_at": "2026-09-28T10:00:00.000Z",
"currency": "CZK",
"databox": null,
"default_due_days": 14,
"dic": "CZ8001010006",
"email": "demo@example.cz",
"first_name": "Jan",
"fiscal_year_start": 1,
"flat_expense_rate": null,
"house_number": "1",
"ico": "99999986",
"invoice_footer": null,
"last_name": "Ukázka",
"legal_form": "osvc",
"locked_until": null,
"nace": "741200",
"name": "Jan Ukázka – grafické studio (ukázka) – obnova 28. 9. 2026",
"orientation_number": null,
"owner_id": 1,
"phone": "+420 777 000 000",
"register_note": "Fyzická osoba zapsaná v živnostenském rejstříku.",
"responsible_id": null,
"street": "Vinohradská",
"tax_office_code": "451",
"tax_office_workplace": "2002",
"title": null,
"updated_at": "2026-09-28T10:00:00.000Z",
"vat_registered_on": null,
"vat_status": "none",
"web": null,
"zip": "12000",
"settings": {
"round_total": "always",
"invoice_language": "cs",
"number_format": "{prefix}{yyyy}{nnnn}",
"reminder_days": [
3,
14
],
"show_qr": true,
"invoice_style": "plain",
"invoice_font": "auto",
"invoice_density": "normal",
"invoice_table": "auto",
"invoice_corners": "auto",
"invoice_logo_size": "m",
"invoice_logo_name": false,
"invoice_row_numbers": false,
"invoice_paid_stamp": true,
"invoice_contacts": true,
"invoice_credit": true,
"demo": true,
"statement_category": "mikro",
"submitter": {
"first_name": "Jana",
"last_name": "Ukázková",
"relation": "jednatelka"
},
"tax_profile": {
"children": [
{
"order": 1,
"first_name": "Eliška",
"last_name": "Ukázková",
"birth_number": "1855120003"
}
],
"main_activity": true,
"birth_number": "8001010006",
"ossz_code": "110",
"cssz_variable_symbol": "12345678",
"health_insurer": "111"
},
"restored": {
"entity_id": 2,
"exported_at": "2026-09-28 10:00:00 UTC",
"restored_at": "2026-09-28T10:00:00Z"
}
},
"has_logo": false,
"legal_form_label": "OSVČ",
"bookkeeping_label": "Daňová evidence",
"vat_status_label": "Neplátce DPH",
"vat_payer": false,
"double_entry": false,
"role": "owner",
"can_write": true,
"can_manage": true,
"payroll_access": true,
"member_user_id": 1,
"membership_id": 6,
"ownership_offer": null
},
"counts": {
"accounts": 28,
"series": 6,
"partners": 11,
"bank_accounts": 2,
"employees": 0,
"documents": 56,
"document_lines": 56,
"bank_transactions": 67,
"payments": 47,
"assets": 1,
"payslips": 0,
"trips": 0,
"rides": 0,
"recurrences": 1,
"filings": 0,
"vat_adjustments": 0,
"vat_registrations": 0,
"profit_distributions": 0,
"accruals": 0,
"inventories": 0,
"entries": 0,
"bank_rules": 2,
"billing_agreements": 0,
"time_entries": 0,
"billed_months": 0,
"document_versions": 56,
"document_approvals": 0,
"document_requests": 0,
"messages": 0,
"bank_statement_archives": 0,
"filing_evidences": 0,
"events": 195
},
"files": {
"attached": 0,
"skipped": []
},
"notes": [
"Opakované faktury jsou v obnovené firmě vypnuté, aby se nevystavily podruhé."
]
}
Dlouhé seznamy jsou v ukázce zkrácené na první položky.