Přílohy a importy

GET Seznam příloh dokladu

/entities/{entity_id}/documents/{id}/attachments

Oprávnění

Každý člen firmy včetně role Jen čtení

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

Odpověď

200 application/json Objekt s polem attachments.

Chování

Co změní

Nic nezapisuje.

Limity

Doklad může mít nejvýše 20 příloh.

Příklad

curl \
  -H "X-API-Key: $SALDO_API_KEY" \
  https://techtools.cz/ucetnictvi-api/entities/1/documents/30/attachments

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

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, 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í“.

Parametry

Tělo požadavku

Formát multipart/form-data.

Odpověď

201 application/json Uložená příloha.

Chyby této operace

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 \
  -X POST \
  -H "X-API-Key: $SALDO_API_KEY" \
  -F "file=@faktura.pdf" \
  https://techtools.cz/ucetnictvi-api/entities/1/documents/30/attachments

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": 142,
  "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í

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

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 \
  -H "X-API-Key: $SALDO_API_KEY" \
  https://techtools.cz/ucetnictvi-api/entities/1/documents/30/attachments/1

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

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. 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.

Parametry

Odpověď

204 Bez obsahu.

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 \
  -X DELETE \
  -H "X-API-Key: $SALDO_API_KEY" \
  https://techtools.cz/ucetnictvi-api/entities/1/documents/30/attachments/1

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

V příručce

Vydané faktury › Importovat faktury z jiného programu

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.

Parametry

Tělo požadavku

Formát multipart/form-data.

Odpověď

200 application/json Výsledek pro každou fakturu (po rozbalení ZIPů) a souhrnné počty.

Chyby této operace

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ů – 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.

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 \
  -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_isdoc

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": 149,
      "number": "FP20260040",
      "kind": "invoice_in",
      "partner": "Kancelářské potřeby Hradec s.r.o.",
      "total": 6419.36,
      "currency": "CZK",
      "duplicate_of": null,
      "warnings": [],
      "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

Odpověď

200 application/json Historie importů a kontext firmy.

Chování

Co změní

Nic nezapisuje.

Limity

Vrací nejvýše 30 importů.

Příklad

curl \
  -H "X-API-Key: $SALDO_API_KEY" \
  https://techtools.cz/ucetnictvi-api/entities/1/imports

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; 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.

Parametry

Tělo požadavku

Formát multipart/form-data.

Odpověď

201 application/json Výsledky řádků dávky a údaje pro další dávku.

Chyby této operace

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 \
  -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/imports

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-2YFX7K",
  "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, 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.

Parametry

Tělo požadavku

Formát multipart/form-data.

Odpověď

200 application/json Náhled s řádky a souhrnem; přesné další klíče závisí na druhu.

Chyby této operace

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 \
  -X POST \
  -H "X-API-Key: $SALDO_API_KEY" \
  -F "type=contacts" \
  -F "file=@kontakty.csv" \
  https://techtools.cz/ucetnictvi-api/entities/1/imports/preview

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

Odpověď

200 application/json Co vrácení odstranilo a obnovilo.

Chyby této operace

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 \
  -X DELETE \
  -H "X-API-Key: $SALDO_API_KEY" \
  https://techtools.cz/ucetnictvi-api/entities/1/imports/IMP-UKAZKA

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
}