Soubory, importy a opakování

Nahrávání souborů

Soubory se posílají jako multipart/form-data. Název pole uvádí reference u operace, obvykle file pro jeden soubor a files[] pro více souborů (import výpisu přijme vedle file ještě originál v statement_pdf). Ostatní pole stejného požadavku jsou textová pole formuláře.

curl -X POST -H "X-API-Key: $SALDO_API_KEY" \
  -F "file=@faktura-coworking.pdf" \
  https://techtools.cz/ucetnictvi-api/entities/1/documents/42/attachments

import { readFile } from 'node:fs/promises';
const form = new FormData();
form.append('file', new Blob([await readFile('faktura-coworking.pdf')], { type: 'application/pdf' }), 'faktura-coworking.pdf');
const response = await fetch('https://techtools.cz/ucetnictvi-api/entities/1/documents/42/attachments', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.SALDO_API_KEY },
  body: form
});

Limity souborů

Server přijme celý požadavek nejvýš do 21 MB, i když by součet limitů operace dovolil víc; větší odmítne kódem 413. Soubor nad limit operace vrátí podle operace 413 nebo 422, reference to uvádí v tabulce Chyby této operace.

Náhled a dávky

• Import výpisu s preview=1 vrátí období, zůstatky, kontroly a počet nových pohybů a nic neuloží.
• Náhled importu z jiného programu přečte soubor, rozpozná sloupce a u každého řádku ukáže, zda vznikne, je duplicitní, přeskočí se, nebo má chybu. Nic neuloží.
• Import po dávkách zpracuje jednu dávku řádků (offset, limit) pod kódem batch ve tvaru IMP-XXXXXX a vrátí next_offset, dokud není null. Dávka má nejvýš 500 řádků u kontaktů, 200 u neuhrazených faktur a 100 u dokladů a peněz; předvaha se zpracuje najednou (nejvýš 10 000 řádků).
• Vrácení importu smaže, co import vytvořil (kontakty, na které už odkazuje jiný doklad, ponechá), a obnoví počáteční stavy, které přepsal. Odmítne to v uzamčeném období, nebo když na importovaných datech něco navazuje (pozdější úhrada, navazující doklad, odečtená záloha, vzor opakované faktury).

Stahování souborů

Soubory se vracejí s hlavičkou Content-Disposition a názvem souboru. Odpovědi, které nejsou JSON, zpracujte jako binární data (response.blob() nebo response.arrayBuffer()).

Když požadavek pošlete znovu

API nemá obecnou hlavičku proti zdvojení. Po výpadku spojení proto nejdřív ověřte, zda se zápis provedl (například načtěte seznam), a až potom ho opakujte. Chování jednotlivých operací: