Reference API
Přílohy a importy
Soubory u dokladů, import faktur ve formátu ISDOC a převod kontaktů, faktur a počátečních stavů z jiných programů po dávkách, s náhledem před importem a s možností import vrátit.
GET Seznam příloh dokladu
/entities/{entity_id}/documents/{id}/attachments
- Oprávnění
- Každý člen firmy včetně role Jen čtení
- Pravidlo
- Role Nahrává doklady (submitter): jen u vlastních dokladů, cizí doklad vrátí 404.
- Klíč jen pro čtení
- Stačí
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é.
Parametry
| Název | Kde | Typ | Povinný | Popis |
|---|---|---|---|---|
entity_id | cesta | celé číslo | ano | Účetní jednotka (firma), jejímž jste přijatým členem. Příklad 12. |
id | cesta | celé číslo | ano | Doklad firmy. Příklad 431. |
Odpověď
200 application/json Objekt s polem attachments.
| Pole | Význam |
|---|---|
attachments | Přílohy dokladu (nejvýše 20). |
attachments[].id | Identifikátor přílohy pro stažení nebo smazání. |
attachments[].filename | Původní název souboru. |
attachments[].content_type | Typ souboru rozpoznaný z obsahu při nahrání. |
attachments[].byte_size | Velikost v bajtech. |
attachments[].inline | true u PDF, JPEG, PNG, WebP a GIF (prohlížeč je zobrazí), false u HEIC, HEIF, XML, ZIP a textu (stáhnou se). |
attachments[].created_at | Čas nahrání. |
Chování
- Co změní
- Nic nezapisuje.
- Limity
- Doklad může mít nejvýše 20 příloh.
Příklad
cURL
curl \
-H "X-API-Key: $SALDO_API_KEY" \
https://techtools.cz/ucetnictvi-api/entities/1/documents/30/attachmentsJavaScript
const response = await fetch('https://techtools.cz/ucetnictvi-api/entities/1/documents/30/attachments', {
headers: { 'X-API-Key': process.env.SALDO_API_KEY }
});
const data = await response.json();{
"attachments": [
{
"id": 1,
"filename": "faktura-coworking.pdf",
"content_type": "application/pdf",
"byte_size": 142,
"inline": true,
"created_at": "2026-09-28T10:00:00.000Z"
}
]
}
POST Přiložení souboru k dokladu
/entities/{entity_id}/documents/{id}/attachments
- Oprávnění
- Vlastník, účetní nebo editor
- Pravidlo
- Role Nahrává doklady (submitter): jen ke vlastnímu konceptu, cizí doklad vrátí 404.
- Klíč jen pro čtení
- Nestačí, vrátí 403
READ_ONLY_KEY
Uloží jeden soubor jako přílohu dokladu. Typ se určuje podle obsahu souboru; přípona rozhoduje jen u prostého textu a XML, které obsah nepozná, a 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. Text pojmenovaný .pdf nebo .jpg se odmítne. Stejný soubor (podle kontrolního součtu) se k jednomu dokladu nepřiloží dvakrát. 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í“.
Parametry
| Název | Kde | Typ | Povinný | Popis |
|---|---|---|---|---|
entity_id | cesta | celé číslo | ano | Účetní jednotka (firma). Příklad 12. |
id | cesta | celé číslo | ano | Doklad firmy. Příklad 431. |
Tělo požadavku
Formát multipart/form-data.
| Pole | Typ | Povinné | Popis |
|---|---|---|---|
file | soubor | ano | Soubor přílohy, nejvýše 15 MB; název souboru se uloží (nejvýše posledních 180 znaků). |
Odpověď
201 application/json Uložená příloha.
| Pole | Význam |
|---|---|
id | Identifikátor přílohy. |
filename | Uložený název souboru. |
content_type | Rozpoznaný typ souboru. |
byte_size | Velikost v bajtech. |
inline | Zda se soubor při stažení zobrazí v prohlížeči (PDF a běžné obrázky). |
created_at | Čas nahrání. |
Chyby této operace
| Stav | Kód | Kdy |
|---|---|---|
| 400 | – | Chybí pole file se souborem (odpověď „Vyberte soubor k přiložení“). |
| 422 | – | Doklad už má 20 příloh („Doklad už má 20 příloh – nejdřív nějakou odeberte“). |
| 422 | – | Soubor je prázdný („Soubor je prázdný“). |
| 422 | – | Soubor je větší než 15 MB („Soubor je větší než 15 MB“). |
| 422 | – | Obsah souboru není žádný z povolených typů („Přiložit lze PDF, obrázek (JPG, PNG, WebP, HEIC) nebo XML – obsah souboru tomu neodpovídá“ – text hlášky nevyjmenovává GIF, HEIF, ZIP a prostý text, které se přijmou). |
| 422 | – | Stejný soubor už u dokladu je („Tento soubor už u dokladu je“). |
| 403 | SUBMITTER_ONLY | Role Nahrává doklady přikládá soubor k zaúčtovanému dokladu |
Společné chyby všech operací (přihlášení, oprávnění, limity) popisuje Chyby a limity.
Chování
- Co změní
- 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.
- Limity
- 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.
- Opakování
- Každé volání přidá novou přílohu; stejný soubor se znovu uloží jako další příloha (duplicity se nekontrolují).
Příklad
cURL
curl \
-X POST \
-H "X-API-Key: $SALDO_API_KEY" \
-F "file=@faktura.pdf" \
https://techtools.cz/ucetnictvi-api/entities/1/documents/30/attachmentsJavaScript
const form = new FormData();
form.append('file', fileInput.files[0], 'faktura.pdf');
const response = await fetch('https://techtools.cz/ucetnictvi-api/entities/1/documents/30/attachments', {
headers: { 'X-API-Key': process.env.SALDO_API_KEY },
method: 'POST',
body: form
});
const data = await response.json();{
"id": 6,
"filename": "faktura.pdf",
"content_type": "application/pdf",
"byte_size": 152,
"inline": true,
"created_at": "2026-09-28T10:00:00.000Z"
}
GET Stažení přílohy dokladu
/entities/{entity_id}/documents/{id}/attachments/{attachment_id}
- Oprávnění
- Každý člen firmy včetně role Jen čtení
- Pravidlo
- Role Nahrává doklady (submitter): jen u vlastních dokladů, cizí doklad vrátí 404.
- Klíč jen pro čtení
- Stačí
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.
Parametry
| Název | Kde | Typ | Povinný | Popis |
|---|---|---|---|---|
entity_id | cesta | celé číslo | ano | Účetní jednotka (firma). Příklad 12. |
id | cesta | celé číslo | ano | Doklad firmy. Příklad 431. |
attachment_id | cesta | celé číslo | ano | Příloha tohoto dokladu (id ze seznamu příloh). Příklad 88. |
Odpověď
200 application/octet-stream Binární obsah souboru; Content-Type je skutečný typ přílohy (např. application/pdf, image/jpeg, application/xml).
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/documents/30/attachments/1JavaScript
const response = await fetch('https://techtools.cz/ucetnictvi-api/entities/1/documents/30/attachments/1', {
headers: { 'X-API-Key': process.env.SALDO_API_KEY }
});
const data = await response.json();application/pdf, 142 bajtů (soubor faktura-coworking.pdf)
DELETE Smazání přílohy dokladu
/entities/{entity_id}/documents/{id}/attachments/{attachment_id}
- Oprávnění
- Vlastník, účetní nebo editor
- Pravidlo
- Role Nahrává doklady (submitter): jen u vlastního konceptu, cizí doklad vrátí 404.
- Klíč jen pro čtení
- Nestačí, vrátí 403
READ_ONLY_KEY
Odebere přílohu z dokladu a hned smaže i uložený soubor; smazání nelze vrátit. U vystaveného nebo stornovaného dokladu, jehož účetní datum nebo datum pro DPH leží v uzamčeném období, smazání odmítne (originály uzavřeného období se uchovávají, § 31 zákona o účetnictví a § 35 zákona o DPH); detail dokladu to ukazuje v attachments_locked. U schvalovaného dokladu, který byl schválený, se stav schválení přepočítá stejně jako po přiložení souboru.
Parametry
| Název | Kde | Typ | Povinný | Popis |
|---|---|---|---|---|
entity_id | cesta | celé číslo | ano | Účetní jednotka (firma). Příklad 12. |
id | cesta | celé číslo | ano | Doklad firmy. Příklad 431. |
attachment_id | cesta | celé číslo | ano | Příloha tohoto dokladu. Příklad 88. |
Odpověď
204 Bez obsahu.
Chyby této operace
| Stav | Kód | Kdy |
|---|---|---|
| 422 | – | Doklad patří do uzamčeného období (code PERIOD_LOCKED, „Doklad patří do uzamčeného období do … – jeho přílohy se archivují a nejde je smazat. …“) |
| 403 | SUBMITTER_ONLY | Role Nahrává doklady maže přílohu zaúčtovaného dokladu |
Společné chyby všech operací (přihlášení, oprávnění, limity) popisuje Chyby a limity.
Chování
- Co změní
- 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.
- Opakování
- Druhé volání se stejným attachment_id vrátí 404.
Příklad
cURL
curl \
-X DELETE \
-H "X-API-Key: $SALDO_API_KEY" \
https://techtools.cz/ucetnictvi-api/entities/1/documents/30/attachments/1JavaScript
const response = await fetch('https://techtools.cz/ucetnictvi-api/entities/1/documents/30/attachments/1', {
headers: { 'X-API-Key': process.env.SALDO_API_KEY },
method: 'DELETE'
});
const data = await response.json();soubor, 0 bajtů
POST Import faktur ve formátu ISDOC
/entities/{entity_id}/documents/import_isdoc
- Oprávnění
- Vlastník, účetní nebo editor
- Klíč jen pro čtení
- Nestačí, vrátí 403
READ_ONLY_KEY
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 výchozí účet kontaktu (jinak účet podle dřívějších dokladů kontaktu, jinak 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; stejně tak přijatý doklad, jehož odběratel má jiné IČO (bez IČO jiné DIČ) než firma, doklad s DUZP před začátkem účetnictví firmy v Saldu nebo starší než 3 roky a doklad, jehož součet nesouhlasí s částkou v souboru o víc než 1 Kč. Režim DPH se převezme ze souboru: LocalReverseCharge s kódem předmětu plnění = reverse_charge s rc_code a sazbou z položek; dodavatel ze zahraničí bez DPH = eu_services, eu_goods, triangular nebo import podle VATNote, bez české sazby nebo bez poznatelného režimu jen koncept se sazbou 21 %; zahraniční DPH = koncept s odpočtem none; řádek s VATApplicable false = not_subject. Když doklad nejde vystavit (například v uzamčeném období), nevznikne ani koncept a faktura má stav error; stejně tak vydaná faktura s číslem dokladu, který je v Saldu stornovaný. Datum přijetí je received_date, nejdřív datum vystavení dokladu. Je-li zapnutá automatizace auto_match (výchozí stav), vystavené doklady se ihned spárují s platbami, které už jsou v bance.
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 multipart/form-data.
| Pole | Typ | Povinné | Popis |
|---|---|---|---|
files | pole (text) | ano | 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. |
direction | text | ne | 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. Hodnoty: sale, purchase. |
received_date | datum | ne | Datum přijetí přijatých dokladů (výchozí dnešek, nejvýš dnešek a nejdřív 400 dní zpět); u dokladu vystaveného později se použije datum vystavení. Určuje období odpočtu DPH. |
Odpověď
200 application/json Výsledek pro každou fakturu (po rozbalení ZIPů) a souhrnné počty.
| Pole | Význam |
|---|---|
results | Jeden záznam na fakturu v pořadí nahrání. |
results[].status | 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). |
results[].upload | Pořadí nahraného souboru (od 0), ze kterého faktura pochází – u ZIPu mají všechny jeho faktury stejné. |
results[].filename | Název souboru faktury (u ZIPu název souboru uvnitř archivu). |
results[].document_id | Vytvořený doklad (imported) nebo existující doklad (duplicate). |
results[].number | Čí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). |
results[].kind | Druh vytvořeného dokladu (invoice_out, credit_out, proforma_out, advance_out, invoice_in, credit_in, proforma_in, advance_in). |
results[].partner | Název protistrany ze souboru. |
results[].total | Částka k úhradě vytvořeného dokladu v jeho měně. |
results[].currency | Měna dokladu. |
results[].duplicate_of | 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. |
results[].warnings | Upozornění (nesedící součet, doklad ponechán jako koncept, čeká na schválení, PDF se nepřiložilo…). |
results[].error | Důvod u stavu error a no_isdoc. |
results[].paid | true, pokud se doklad hned celý uhradil spárováním s bankovním pohybem. |
imported | Počet výsledků ve stavu imported. |
paid | Počet dokladů uhrazených spárováním s bankou. |
Chyby této operace
| Stav | Kód | Kdy |
|---|---|---|
| 400 | – | Nebyl nahrán žádný soubor („Vyberte soubory .isdoc nebo .isdocx“). |
| 413 | – | Po rozbalení ZIPů je faktur víc než 200 („Najednou lze nahrát nejvýše 200 dokladů“). |
Společné chyby všech operací (přihlášení, oprávnění, limity) popisuje Chyby a limity.
Chování
- Co změní
- 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.
- Limity
- Zpracuje nejvýše 50 nahraných souborů; každý další a každý soubor větší než 15 MB dostane vlastní výsledek ve stavu error („Najednou lze poslat nejvýše 50 souborů – tento nahrajte znovu“, „Soubor je větší než 15 MB“) a ostatní se zpracují. Po rozbalení ZIPů nejvýše 200 faktur. Aplikace posílá soubory po skupinách (nejvýše 50 souborů a 18 MB v jednom požadavku), takže najednou jde nahrát libovolný počet. 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.
- Opakování
- 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.
Příklad
Přijatá faktura od cizího dodavatele – vznikne přijatý doklad, případně s novým kontaktem.
cURL
curl \
-X POST \
-H "X-API-Key: $SALDO_API_KEY" \
-F "direction=purchase" \
-F "files[]=@faktura-dodavatel.isdoc" \
https://techtools.cz/ucetnictvi-api/entities/1/documents/import_isdocJavaScript
const form = new FormData();
form.append('files[]', fileInput.files[0], 'faktura-dodavatel.isdoc');
form.append('direction', 'purchase');
const response = await fetch('https://techtools.cz/ucetnictvi-api/entities/1/documents/import_isdoc', {
headers: { 'X-API-Key': process.env.SALDO_API_KEY },
method: 'POST',
body: form
});
const data = await response.json();{
"results": [
{
"filename": "faktura-dodavatel.isdoc",
"status": "imported",
"document_id": 136,
"number": null,
"kind": "invoice_in",
"partner": "Kancelářské potřeby Hradec s.r.o.",
"total": 6419.0,
"currency": "CZK",
"duplicate_of": null,
"warnings": [
"Odběratelem na faktuře je Novák Stavby s.r.o. (IČO 07082440), ne vaše firma – doklad zůstal jako koncept a DPH se neodečte. Pokud patří jiné firmě, smažte ho a nahrajte ho tam.",
"Účet na faktuře 19-2000145399/0800 se liší od účtu u kontaktu 123456789/0800 – než zaplatíte, ověřte ho u dodavatele jinou cestou než e-mailem s fakturou (podvodné „změnili jsme banku“). Příkaz k úhradě použije účet z faktury."
],
"upload": 0
}
],
"imported": 1,
"paid": 0
}
GET Historie importů a údaje pro převod dat
/entities/{entity_id}/imports
- Oprávnění
- Každý člen firmy včetně role Jen čtení
- Klíč jen pro čtení
- Stačí
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.
Parametry
| Název | Kde | Typ | Povinný | Popis |
|---|---|---|---|---|
entity_id | cesta | celé číslo | ano | Účetní jednotka (firma). Příklad 12. |
Odpověď
200 application/json Historie importů a kontext firmy.
| Pole | Význam |
|---|---|
imports | Nejvýše 30 importů, nejnovější první. |
imports[].batch | Označení importu IMP-XXXXXX (pro vrácení). |
imports[].type | contacts, documents, trial_balance, open_items nebo money; type_label je český název. |
imports[].format | Rozpoznaný formát (csv, pohoda, money_s3, form) a filename název souboru. |
imports[].counts | Součty všech dávek importu – created, duplicate, skipped, error. |
imports[].created_at | Čas první dávky; user je přihlašovací jméno toho, kdo import spustil, summary text z historie změn. |
imports[].undone | Zda byl import vrácen; undone_at a undo_summary popisují vrácení. |
bookkeeping | Způsob vedení (double_entry nebo tax_records); double_entry a vat_payer jako boolean. |
opening_date | První den aktuálního účetního období (výchozí datum počátečních stavů). |
money_accounts | Aktivní bankovní účty a pokladny: id, name, kind, currency, number, account_code, opening_balance, opening_date. |
Chování
- Co změní
- Nic nezapisuje.
- Limity
- Vrací nejvýše 30 importů.
Příklad
cURL
curl \
-H "X-API-Key: $SALDO_API_KEY" \
https://techtools.cz/ucetnictvi-api/entities/1/importsJavaScript
const response = await fetch('https://techtools.cz/ucetnictvi-api/entities/1/imports', {
headers: { 'X-API-Key': process.env.SALDO_API_KEY }
});
const data = await response.json();{
"imports": [
{
"batch": "IMP-UKAZKA",
"type": "contacts",
"type_label": "Adresář",
"format": "csv",
"filename": "kontakty.csv",
"counts": {
"created": 4,
"duplicate": 1,
"skipped": 0,
"error": 0
},
"created_at": "2026-09-28T10:00:00.000Z",
"user": "ukazka",
"summary": "Import – Adresář (CSV (UTF-8, čárka)): nových 4, přeskočeno 1, chyb 0 (IMP-UKAZKA)",
"undone": false,
"undone_at": null,
"undo_summary": null
}
],
"bookkeeping": "double_entry",
"double_entry": true,
"vat_payer": true,
"opening_date": "2026-01-01",
"money_accounts": [
{
"id": 2,
"name": "Provozní účet",
"kind": "bank",
"currency": "CZK",
"number": "2900001227/2010",
"account_code": "221001",
"opening_balance": 420000.0,
"opening_date": "2026-01-01"
},
{
"id": 6,
"name": "Rezervní účet",
"kind": "bank",
"currency": "CZK",
"number": "2900005005/2010",
"account_code": "221002",
"opening_balance": 0.0,
"opening_date": "2026-01-01"
}
]
}
Dlouhé seznamy jsou v ukázce zkrácené na první položky.
POST Import jedné dávky dat z jiného programu
/entities/{entity_id}/imports
- Oprávnění
- Vlastník, účetní nebo editor
- Klíč jen pro čtení
- Nestačí, vrátí 403
READ_ONLY_KEY
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 (v podvojném účetnictví se zdrojem opening bez účetních zápisů a s úhradou payment_method opening, saldokonto je počítá částkou z počátečního stavu 311 a 321); 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í počáteční stavy svého účetního roku (počáteční stavy jiných let zůstanou) a chybějící analytiky založí v účtovém rozvrhu.
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 multipart/form-data.
| Pole | Typ | Povinné | Popis |
|---|---|---|---|
type | text | ano | Co se importuje. Hodnoty: contacts, documents, trial_balance, open_items, money, accounts, assets. |
file | soubor | ne | Tentýž soubor jako u náhledu (do 20 MB), povinný kromě type=money. |
mapping | objekt | ne | Přiřazení sloupců CSV jako u náhledu (řetězec JSON). |
options | objekt | ne | Volby jako u náhledu (řetězec JSON). |
batch | text | ne | 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 | celé číslo | ne | Index prvního řádku dávky (od 0), výchozí 0; u trial_balance se nepoužije. |
limit | celé číslo | ne | 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). |
Odpověď
201 application/json Výsledky řádků dávky a údaje pro další dávku.
| Pole | Význam |
|---|---|
batch | Označení importu IMP-XXXXXX; posílejte ho s dalšími dávkami. |
results | Řá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). |
counts | Počty této dávky – created, duplicate, skipped, error. |
next_offset | offset pro další dávku; null, když je soubor hotový. |
total | Počet řádků celého souboru. |
warnings | Upozornění k souboru. |
Chyby této operace
| Stav | Kód | Kdy |
|---|---|---|
| 422 | – | batch nemá tvar IMP-XXXXXX („Neplatné označení importu“). |
| 422 | – | Import s tímto batch už byl vrácen, nebo patří k jinému druhu dat („… – spusťte nový“). |
| 422 | – | 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. |
| 422 | – | Stejné chyby souboru, druhu a voleb jako u náhledu (previewImport). |
| 422 | – | documents – soubor je z účetnictví firmy s jiným IČO a chybí options.foreign_ico_confirmed („Soubor je z účetnictví firmy s IČO …, ne z … Pokud jde opravdu o doklady této firmy, potvrďte to v náhledu importu.“). |
Společné chyby všech operací (přihlášení, oprávnění, limity) popisuje Chyby a limity.
Chování
- Co změní
- 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.
- Limity
- 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.
- Opakování
- 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.
Příklad
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.
cURL
curl \
-X POST \
-H "X-API-Key: $SALDO_API_KEY" \
-F "type=contacts" \
-F "limit=500" \
-F "file=@kontakty.csv" \
https://techtools.cz/ucetnictvi-api/entities/1/importsJavaScript
const form = new FormData();
form.append('file', fileInput.files[0], 'kontakty.csv');
form.append('type', 'contacts');
form.append('limit', '500');
const response = await fetch('https://techtools.cz/ucetnictvi-api/entities/1/imports', {
headers: { 'X-API-Key': process.env.SALDO_API_KEY },
method: 'POST',
body: form
});
const data = await response.json();{
"batch": "IMP-ZLB16V",
"results": [
{
"index": 0,
"line": 2,
"label": "Pekárna Ďáblice s.r.o.",
"status": "duplicate",
"message": "Už v adresáři jako Pekárna Ďáblice s.r.o."
},
{
"index": 1,
"line": 3,
"label": "Kavárna U Kocoura",
"status": "duplicate",
"message": "Už v adresáři (Kavárna U Kocoura)"
}
],
"counts": {
"created": 0,
"duplicate": 5,
"skipped": 0,
"error": 0
},
"next_offset": null,
"total": 5,
"warnings": []
}
Dlouhé seznamy jsou v ukázce zkrácené na první položky.
POST Náhled importu dat z jiného programu
/entities/{entity_id}/imports/preview
- Oprávnění
- Vlastník, účetní nebo editor
- Klíč jen pro čtení
- Nestačí, vrátí 403
READ_ONLY_KEY
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, sešitu Excelu .xlsx, POHODA XML nebo Money S3 XML), documents (faktury z POHODA XML nebo Money S3 XML, podle obsahu souboru), 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; v podvojném účetnictví se nezaúčtují a warnings porovná jejich součet s počátečním stavem 311 a 321), accounts (účtový rozvrh z CSV nebo Excelu, jen podvojné účetnictví; existující účty přeskočí), assets (karty dlouhodobého majetku z CSV nebo Excelu bez zaúčtování; duplicity podle inventárního čísla nebo názvu, ceny a data zařazení) 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.
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 multipart/form-data.
| Pole | Typ | Povinné | Popis |
|---|---|---|---|
type | text | ano | Co se importuje. Hodnoty: contacts, documents, trial_balance, open_items, money, accounts, assets. |
file | soubor | ne | 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. Sešit Excelu (XLSX, první list) přijímají contacts, trial_balance, open_items, accounts a assets; documents ho odmítne. |
mapping | objekt | ne | Jen u CSV a Excelu (contacts, trial_balance, open_items, accounts, assets): 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: accounts – account, name, kind, tax, statement_line; assets – inventory_number, name, account, price, in_use_from, acquired_on, tax_group, tax_method, useful_life (měsíce), useful_years (roky), category, residual_value, serial_number, location, responsible_person; 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, remaining_czk (zbývá v Kč u cizí měny, určí kurz dokladu), base, vat, currency, variable_symbol. V multipart se posílá jako řetězec JSON. |
options | objekt | ne | 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) a foreign_ico_confirmed (true = soubor s IČO jiné firmy přesto importovat, viz foreign_ico v odpovědi); 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). V poli formuláře options[…] platí text „true“ a „false“ jako logická hodnota. |
Odpověď
200 application/json Náhled s řádky a souhrnem; přesné další klíče závisí na druhu.
| Pole | Význam |
|---|---|
type | Druh importu; type_label je český název. |
format | Rozpoznaný formát (csv, pohoda, money_s3, form); format_label ho popisuje, u CSV i s kódováním a oddělovačem. |
filename | Název nahraného souboru. |
rows | Řá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. |
summary | Počty řádků – total, create, duplicate, skip, error. |
warnings | Upozornění k celému souboru (např. soubor z jiné firmy podle IČO, výsledkové účty v předvaze). |
columns | U CSV sloupce souboru – index, header, field (přiřazené pole), sample (první neprázdná hodnota). |
fields | U CSV pole importu – key, label, required. |
mapping | U CSV použité přiřazení {pole: index sloupce nebo null}. |
totals | Jen trial_balance – debit, credit, difference a balanced (zda MD = Dal). |
existing | Jen trial_balance – dosavadní počáteční stavy, které import nahradí (count, amount, date, accounts). |
money_accounts | Jen trial_balance – bankovní účty a pokladny firmy; money_mapping {kód účtu ze souboru: id účtu}. |
date | U trial_balance, open_items a money použité datum počátečních stavů či převodu. |
merge_analytics | Jen trial_balance – použitá volba slučování analytik. |
side | Jen open_items – použitá volba strany (receivables, payables nebo null). |
payments | Jen documents – zda se převezmou úhrady; entity_ico a file_ico jsou IČO firmy a IČO ze souboru; foreign_ico je true, když se liší – import pak vyžaduje options.foreign_ico_confirmed. |
Chyby této operace
| Stav | Kód | Kdy |
|---|---|---|
| 422 | – | Neznámý type („Zvolte, co importujete: contacts, documents, trial_balance, open_items, money, accounts nebo assets“). |
| 422 | – | Chybí soubor („Vyberte soubor k importu“), soubor je tabulka Excelu, nebo je větší než 20 MB. |
| 422 | – | 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. |
| 422 | – | documents – soubor není XML, neobsahuje faktury POHODA, nebo obsahuje pokladní doklady; contacts – XML není adresář POHODA ani firmy Money S3. |
| 422 | – | trial_balance – firma nevede podvojné účetnictví, soubor je XML, nebo datum počátečních stavů leží v uzamčeném období; open_items – soubor je XML. |
Společné chyby všech operací (přihlášení, oprávnění, limity) popisuje Chyby a limity.
Chování
- Co změní
- Nic nezapisuje. U documents s cizí měnou bez kurzu v souboru načte kurz ČNB.
- Limity
- 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.
Příklad
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.
cURL
curl \
-X POST \
-H "X-API-Key: $SALDO_API_KEY" \
-F "type=contacts" \
-F "file=@kontakty.csv" \
https://techtools.cz/ucetnictvi-api/entities/1/imports/previewJavaScript
const form = new FormData();
form.append('file', fileInput.files[0], 'kontakty.csv');
form.append('type', 'contacts');
const response = await fetch('https://techtools.cz/ucetnictvi-api/entities/1/imports/preview', {
headers: { 'X-API-Key': process.env.SALDO_API_KEY },
method: 'POST',
body: form
});
const data = await response.json();{
"type": "contacts",
"type_label": "Adresář",
"format": "csv",
"format_label": "CSV (UTF-8, čárka)",
"filename": "kontakty.csv",
"rows": [
{
"index": 0,
"line": 2,
"status": "duplicate",
"message": "Už v adresáři jako Pekárna Ďáblice s.r.o.",
"warnings": [],
"label": "Pekárna Ďáblice s.r.o.",
"detail": "IČO 27082440 · Kostelecká 12, Praha 8 · objednavky@pekarna.example"
},
{
"index": 1,
"line": 3,
"status": "duplicate",
"message": "Už v adresáři (Kavárna U Kocoura)",
"warnings": [],
"label": "Kavárna U Kocoura",
"detail": "Vodičkova 5, Praha 1 · kocour@example.cz"
}
],
"summary": {
"total": 5,
"create": 0,
"duplicate": 5,
"skip": 0,
"error": 0
},
"warnings": [],
"columns": [
{
"index": 0,
"header": "Název",
"field": "name",
"sample": "Pekárna Ďáblice s.r.o."
},
{
"index": 1,
"header": "IČO",
"field": "ico",
"sample": "27082440"
}
],
"fields": [
{
"key": "name",
"label": "Název",
"required": true
},
{
"key": "first_name",
"label": "Jméno",
"required": false
}
],
"mapping": {
"name": 0,
"first_name": null,
"last_name": null,
"ico": 1,
"dic": 2,
"street": 3,
"city": 4,
"zip": 5,
"country": 6,
"email": 7,
"phone": 8,
"web": null,
"bank_account": 9,
"bank_code": null,
"iban": 10,
"bic": null,
"due_days": 11,
"note": 12
}
}
Dlouhé seznamy jsou v ukázce zkrácené na první položky.
DELETE Vrácení importu
/entities/{entity_id}/imports/{batch}
- Oprávnění
- Vlastník, účetní nebo editor
- Klíč jen pro čtení
- Nestačí, vrátí 403
READ_ONLY_KEY
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).
Parametry
| Název | Kde | Typ | Povinný | Popis |
|---|---|---|---|---|
entity_id | cesta | celé číslo | ano | Účetní jednotka (firma). Příklad 12. |
batch | cesta | text | ano | Označení importu IMP- a 6 znaků A–Z0–9 (z historie importů). Příklad IMP-7K2Q9D. |
Odpověď
200 application/json Co vrácení odstranilo a obnovilo.
| Pole | Význam |
|---|---|
documents | Počet smazaných dokladů. |
partners | Počet smazaných kontaktů. |
entries | Počet smazaných počátečních stavů z předvahy. |
kept_partners | Názvy kontaktů založených importem, které zůstaly, protože mají doklady. |
restored_accounts | Počet bankovních účtů a pokladen s obnoveným počátečním stavem. |
restored_entries | Počet obnovených dřívějších počátečních stavů. |
assets | Počet smazaných karet majetku. |
kept_assets | Názvy karet majetku z importu, které zůstaly, protože k nim jsou zaúčtované odpisy. |
Chyby této operace
| Stav | Kód | Kdy |
|---|---|---|
| 422 | – | batch nemá tvar IMP-XXXXXX („Neplatné označení importu“). |
| 422 | – | Import neexistuje („Import nebyl nalezen“), nebo už byl vrácen („Tento import už byl vrácen“). |
| 422 | – | 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í“). |
| 422 | – | 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. |
Společné chyby všech operací (přihlášení, oprávnění, limity) popisuje Chyby a limity.
Chování
- Co změní
- 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.
- Opakování
- Druhé vrácení téhož importu vrátí 422 „Tento import už byl vrácen“.
Příklad
cURL
curl \
-X DELETE \
-H "X-API-Key: $SALDO_API_KEY" \
https://techtools.cz/ucetnictvi-api/entities/1/imports/IMP-UKAZKAJavaScript
const response = await fetch('https://techtools.cz/ucetnictvi-api/entities/1/imports/IMP-UKAZKA', {
headers: { 'X-API-Key': process.env.SALDO_API_KEY },
method: 'DELETE'
});
const data = await response.json();{
"documents": 0,
"partners": 4,
"entries": 0,
"kept_partners": [],
"restored_accounts": 0,
"restored_entries": 0,
"assets": 0,
"kept_assets": []
}