Automatizace, fronta a podklady

GET Nastavení automatizací a jejich výsledky za tento měsíc

/entities/{entity_id}/automation

Oprávnění

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

Klíč jen pro čtení

Stačí

Vrátí přepínače automatizací firmy a co která automatizace udělala v aktuálním kalendářním měsíci, spolu s tím, co právě čeká: splatná opakování faktur, faktury k upomínce a nové kontakty ke kontrole. Nic nespouští.

Parametry

Odpověď

200 application/json Nastavení a stav automatizací.

Chování

Co změní

Nic nezapisuje.

Příklad

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

const response = await fetch('https://techtools.cz/ucetnictvi-api/entities/1/automation', {
  headers: { 'X-API-Key': process.env.SALDO_API_KEY }
});
const data = await response.json();

{
  "month": "2026-09-01",
  "settings": {
    "bank_rules": true,
    "auto_match": true,
    "fio_on_open": true,
    "recurring": true,
    "reminders": true,
    "reminder_days": 7,
    "partner_checks": true
  },
  "bank_rules": {
    "rules": 5,
    "active": 5,
    "month": 36,
    "last_at": "2026-09-28T10:00:00.000Z"
  },
  "auto_match": {
    "month": 0,
    "open": 6
  },
  "fio": {
    "connected": 0,
    "month": 0,
    "accounts": []
  },
  "recurring": {
    "active": 1,
    "due": 0,
    "upcoming": [
      {
        "id": 1,
        "next_on": "2026-10-03",
        "frequency": "monthly",
        "auto_issue": false,
        "template_id": 22,
        "number": "FV20260022",
        "partner": "Kavárna U Zeleného stromu s.r.o.",
        "total": 77440.0,
        "currency": "CZK",
        "due": false
      }
    ],
    "month": 0
  },
  "reminders": {
    "days": 7,
    "count": 0,
    "totals": {},
    "month": 0,
    "rows": []
  },
  "partner_checks": {
    "new": 17,
    "unchecked": 22,
    "demo": true,
    "month": 0,
    "flagged": []
  }
}

PATCH Zapnutí a vypnutí automatizací

/entities/{entity_id}/automation

Oprávnění

Vlastník nebo účetní

Klíč jen pro čtení

Nestačí, vrátí 403 READ_ONLY_KEY

Změní přepínače automatizací firmy; neuvedené a neznámé klíče se nemění. bank_rules a auto_match řídí, zda se při importu bankovního výpisu použijí pravidla pro banku a spárují platby s doklady (auto_match platí i pro import ISDOC). recurring, reminders a partner_checks řídí, co udělá POST …/automation/run. fio_on_open čte jen aplikace, která podle něj při otevření banky stáhne pohyby z Fio; server podle něj nic nespouští.

Parametry

Tělo požadavku

Formát application/json.

Odpověď

200 application/json Nastavení po změně.

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í

Pokud se něco změnilo, uloží nastavení firmy (settings.automation) a zapíše událost automation.updated se seznamem změn. Hodnoty přepínačů se převedou na true/false (jiná hodnota než pravdivá znamená false).

Opakování

Stejné hodnoty podruhé nic neuloží ani nezapíší.

Příklad

curl \
  -X PATCH \
  -H "X-API-Key: $SALDO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"automation":{"reminder_days":14,"partner_checks":true}}' \
  https://techtools.cz/ucetnictvi-api/entities/1/automation

const response = await fetch('https://techtools.cz/ucetnictvi-api/entities/1/automation', {
  headers: { 'X-API-Key': process.env.SALDO_API_KEY, 'Content-Type': 'application/json' },
  method: 'PATCH',
  body: JSON.stringify({
    "automation": {
      "reminder_days": 14,
      "partner_checks": true
    }
  })
});
const data = await response.json();

{
  "settings": {
    "bank_rules": true,
    "auto_match": true,
    "fio_on_open": true,
    "recurring": true,
    "reminders": true,
    "reminder_days": 14,
    "partner_checks": true
  }
}

POST Spuštění automatizací firmy

/entities/{entity_id}/automation/run

Oprávnění

Zvláštní pravidlo

Pravidlo

Volat smí každý člen firmy. Automatizace ale spustí jen vlastník, účetní nebo editor; divákovi vrátí 200 s ran false a důvodem a nic neudělá (ne 403).

Klíč jen pro čtení

Nestačí, vrátí 403 READ_ONLY_KEY

Spustí automatizace, které aplikace pouští při otevření firmy: opakované faktury (recurring), kontrolu nových kontaktů v registrech (partner_checks) a přepočet faktur k upomínce (reminders). Každá běží jen, je-li v nastavení zapnutá; s only jen ta jedna. Upomínky se jen spočítají, nic se neodesílá. Hodnoty only bank_rules, auto_match, fio_on_open a reminder_days nespustí nic; neznámá hodnota se ignoruje a běží vše zapnuté.

Parametry

Tělo požadavku

Formát application/json.

Odpověď

200 application/json Výsledek každé spuštěné automatizace; klíč chybí u automatizace, která neběžela.

Chování

Co změní

recurring: pro každé aktivní opakování s termínem dnes nebo dříve vytvoří doklad podle šablony (datum vystavení = termín, splatnost podle kontaktu nebo firmy, u cizí měny kurz ČNB, je-li dostupný). S auto_issue ho vystaví (v podvojném účetnictví i zaúčtuje), nebo pošle ke schválení, pokud ho pokrývá pravidlo schvalování; jinak zůstane koncept. Termín opakování posune (po ends_on ho deaktivuje); při chybě se doklad nevytvoří, opakování se neposune a chyba je ve failed. partner_checks: u kontaktů založených za posledních 30 dní ověří všechna dosud neověřená česká DIČ v registru plátců DPH (uloží spolehlivost a plátcovství), až 5 IČO v ISIR (uloží insolvenci) a až 5 IČO v ARES (doplní chybějící DIČ, ulici, obec a PSČ, zapíše událost partner.ares_checked); když něco ověřila nebo narazila na chybu, zapíše souhrnnou událost automation.partner_checks. U ukázkové firmy se registry nevolají. reminders nic nezapisuje. Volá externí služby ARES, ISIR, registr plátců DPH a ČNB.

Limity

Nejvýše 24 dokladů na jedno opakování v jednom běhu (dohánění zmeškaných termínů); ISIR a ARES nejvýše 5 kontaktů na běh; bez force se kontrola kontaktů přeskočí, pokud byla v posledních 10 minutách zapsána událost automation.partner_checks.

Opakování

Tentýž termín opakování nevytvoří dva doklady: běh si každý termín atomicky zarezervuje posunem data dalšího opakování. Další volání vytvoří doklad jen za termín, který mezitím nastal, nebo za termíny nad limit 24 z předchozího běhu. Kontrola kontaktů se do 10 minut po zapsané kontrole přeskočí (skipped); s force proběhne znovu, ale jen pro dosud neověřené kontakty.

Příklad

Ukázková firma má další opakování až příští měsíc, proto count je 0.

curl \
  -X POST \
  -H "X-API-Key: $SALDO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"only":"recurring"}' \
  https://techtools.cz/ucetnictvi-api/entities/1/automation/run

const response = await fetch('https://techtools.cz/ucetnictvi-api/entities/1/automation/run', {
  headers: { 'X-API-Key': process.env.SALDO_API_KEY, 'Content-Type': 'application/json' },
  method: 'POST',
  body: JSON.stringify({
    "only": "recurring"
  })
});
const data = await response.json();

{
  "recurring": {
    "count": 0,
    "failed": [],
    "documents": []
  },
  "ran": true
}

GET Přehled všech firem volajícího podle naléhavosti

/clients

Oprávnění

Přihlášený uživatel nebo jeho API klíč, bez vazby na jednu firmu

Klíč jen pro čtení

Stačí

Vrátí všechny firmy, kde je volající přijatým členem (archivované na konci), s tím, co vyžaduje pozornost: stav přiznání k DPH za poslední skončené období a další lhůtu, pohledávky po splatnosti, nespárované bankovní pohyby, koncepty, uzamčení období a poslední aktivitu. Seřazeno podle naléhavosti (urgency), při shodě podle názvu. Stav DPH počítá jen s podáními druhu dph; podání označené jako odeslané bez ověřené doručenky nebo schválené výjimky je unverified, ne filed.

Odpověď

200 application/json Souhrn a seznam firem.

Chování

Co změní

Nic nezapisuje.

Limity

Nejvýše 200 firem; výběr proběhne podle archivace a názvu ještě před řazením podle naléhavosti, takže nad 200 firem se naléhavější firma dál v abecedě nemusí vrátit.

Příklad

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

const response = await fetch('https://techtools.cz/ucetnictvi-api/clients', {
  headers: { 'X-API-Key': process.env.SALDO_API_KEY }
});
const data = await response.json();

{
  "today": "2026-09-28",
  "total": 2,
  "truncated": false,
  "limit": 200,
  "summary": {
    "attention": 2,
    "critical": 0,
    "vat_due": 1,
    "overdue_count": 2,
    "overdue_amount": 132600.0,
    "unmatched": 9,
    "drafts": 2
  },
  "clients": [
    {
      "id": 1,
      "name": "Ukázková firma s.r.o.",
      "ico": "99999994",
      "legal_form": "sro",
      "legal_form_label": "s.r.o.",
      "role": "owner",
      "role_label": "Vlastník",
      "archived": false,
      "demo": true,
      "bookkeeping": "double_entry",
      "vat": {
        "status": "monthly",
        "label": "Plátce DPH – měsíčně",
        "payer": true,
        "period": "2026-08",
        "period_label": "srpen 2026",
        "deadline": "2026-09-25",
        "days": -3,
        "filing": "filed",
        "filed_on": "2026-09-24",
        "proof_state": "awaiting_proof",
        "state": "unverified",
        "next_period": "2026-09",
        "next_period_label": "září 2026",
        "next_deadline": "2026-10-26",
        "next_days": 28
      },
      "overdue": {
        "count": 1,
        "amount": 72600.0
      },
      "unmatched": 6,
      "drafts": 2,
      "locked_until": null,
      "last_activity": {
        "at": "2026-09-28T10:00:00.000Z",
        "action": "filing.evidence_attached",
        "summary": "DPH 2026-08: přiložen potvrzeni-podani.pdf",
        "user": "ukazka"
      },
      "level": "warning",
      "urgency": 85
    },
    {
      "id": 2,
      "name": "Jan Ukázka – grafické studio (ukázka)",
      "ico": "99999986",
      "legal_form": "osvc",
      "legal_form_label": "OSVČ",
      "role": "owner",
      "role_label": "Vlastník",
      "archived": false,
      "demo": true,
      "bookkeeping": "tax_records",
      "vat": {
        "status": "none",
        "label": "Neplátce DPH",
        "payer": false,
        "state": "none"
      },
      "overdue": {
        "count": 1,
        "amount": 60000.0
      },
      "unmatched": 3,
      "drafts": 0,
      "locked_until": null,
      "last_activity": {
        "at": "2026-09-28T10:00:00.000Z",
        "action": "bank.rule_applied",
        "summary": "Pravidlo „Zdravotní pojištění“: pohyb -3306,00 CZK ze dne 7. 9. 2026 zaúčtován na V91",
        "user": "ukazka"
      },
      "level": "warning",
      "urgency": 25
    }
  ]
}

GET Fronta úkolů účetní napříč firmami

/work_items

Oprávnění

Přihlášený uživatel nebo jeho API klíč, bez vazby na jednu firmu

Klíč jen pro čtení

Stačí

V příručce

Daně a pojistné › Úkol Doložit doručení

Vrátí konkrétní kroky ve všech nearchivovaných firmách volajícího: koncepty účetních dokladů (draft), nespárované bankovní pohyby (bank), vystavené přijaté faktury, dobropisy a výdajové pokladní doklady bez přílohy od 1. 1. předchozího roku, kromě načtených z ISDOC (missing), u plátců DPH nepodaná přiznání k DPH za každé skončené období od příchodu firmy do Salda a za období před ním, pokud jeho lhůta tehdy ještě běžela (filing; počítá se i podání se stavem filed pokrývající jen část období), a podání označená jako odeslaná bez ověřené doručenky či schválené výjimky (proof, podání všech druhů). Nepodaná kontrolní a souhrnná hlášení fronta nesleduje. Před výpisem frontu synchronizuje s daty (refresh): nové a vrácené kroky otevře, otevřený krok vyřeší, jen když kontrola jeho vlastního zdroje ukáže, že je hotový, a zruší přidělení lidem, kteří ve firmě ztratili právo zápisu. S refresh=0 nebo s API klíčem jen pro čtení vrátí frontu tak, jak byla naposledy synchronizována.

Parametry

Odpověď

200 application/json Kroky, počty a lidé, kterým lze kroky přidělit.

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í

Synchronizace zapisuje jen do fronty úkolů (nové kroky, aktualizace názvu, termínu a priority, vyřešení, znovuotevření s reopened_count, zrušení přidělení); účetní data nemění. S refresh=0 nebo klíčem jen pro čtení nic nezapisuje.

Limity

Nejvýše 200 nearchivovaných firem (podle názvu) a 1000 řádků. Nové kroky se hledají nejvýše po 500 na firmu a druh; krok proof jen u podání odeslaných za posledních 365 dní nebo bez data odeslání. Vyřešené kroky se vypisují 90 dní.

Opakování

Opakovaná synchronizace bez změny dat nic nového nezaloží.

Příklad

curl \
  -H "X-API-Key: $SALDO_API_KEY" \
  "https://techtools.cz/ucetnictvi-api/work_items?state=open"

const response = await fetch('https://techtools.cz/ucetnictvi-api/work_items?state=open', {
  headers: { 'X-API-Key': process.env.SALDO_API_KEY }
});
const data = await response.json();

{
  "today": "2026-09-28",
  "rows": [
    {
      "id": 3,
      "entity_id": 1,
      "entity_name": "Ukázková firma s.r.o.",
      "kind": "bank",
      "kind_label": "Bankovní výjimka",
      "title": "Spárovat nebo zaúčtovat pohyb 1 500,00 Kč",
      "detail": "Vratka přeplatku · 15. 7. 2026",
      "href": "#/banka?account=2",
      "due_on": "2026-08-15",
      "period": null,
      "year": null,
      "overdue": true,
      "priority": "high",
      "priority_label": "Vysoká",
      "assignee_id": null,
      "assignee": null,
      "can_assign": true,
      "state": "open",
      "first_seen_at": "2026-09-28T10:00:00.000Z",
      "resolved_at": null,
      "reopened_count": 0
    },
    {
      "id": 4,
      "entity_id": 1,
      "entity_name": "Ukázková firma s.r.o.",
      "kind": "bank",
      "kind_label": "Bankovní výjimka",
      "title": "Spárovat nebo zaúčtovat pohyb 12 100,00 Kč",
      "detail": "Nordwood Studio s.r.o. · Úhrada faktury · 12. 8. 2026",
      "href": "#/banka?account=2",
      "due_on": "2026-09-15",
      "period": null,
      "year": null,
      "overdue": true,
      "priority": "high",
      "priority_label": "Vysoká",
      "assignee_id": null,
      "assignee": null,
      "can_assign": true,
      "state": "open",
      "first_seen_at": "2026-09-28T10:00:00.000Z",
      "resolved_at": null,
      "reopened_count": 0
    }
  ],
  "truncated": false,
  "limit": 1000,
  "counts": {
    "open": 97,
    "mine": 0,
    "unassigned": 97,
    "high": 3,
    "overdue": 3
  },
  "firms": [
    {
      "id": 2,
      "name": "Jan Ukázka – grafické studio (ukázka)",
      "manage": true
    },
    {
      "id": 1,
      "name": "Ukázková firma s.r.o.",
      "manage": true
    }
  ],
  "people": [
    {
      "id": 2,
      "name": "ucetni_ukazka"
    },
    {
      "id": 1,
      "name": "ukazka"
    }
  ],
  "members": {
    "1": [
      {
        "id": 1,
        "name": "ukazka"
      },
      {
        "id": 2,
        "name": "ucetni_ukazka"
      }
    ],
    "2": [
      {
        "id": 1,
        "name": "ukazka"
      }
    ]
  }
}

Dlouhé seznamy jsou v ukázce zkrácené na první položky.

PATCH Přidělení kroku z fronty úkolů

/work_items/{id}

Oprávnění

Zvláštní pravidlo

Pravidlo

Krok musí patřit nearchivované firmě, kde je volající přijatým členem (jinak 404). Přidělovat smí jen vlastník nebo účetní té firmy; ostatním vrátí 422, ne 403.

Klíč jen pro čtení

Nestačí, vrátí 403 READ_ONLY_KEY

Přidělí krok fronty úkolů odpovědné osobě, nebo přidělení zruší (assignee_id null). Přidělit lze jen členovi firmy s právem zápisu (vlastník, účetní, editor).

Parametry

Tělo požadavku

Formát application/json.

Odpověď

200 application/json Krok po přidělení (tvar jako rows[] v GET /work_items).

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ží odpovědnou osobu, kdo a kdy přidělil, a zapíše do historie firmy událost work_item.assigned. Účetní data nemění.

Opakování

Každé volání znovu uloží čas a autora přidělení a zapíše novou událost, i při stejné osobě.

Příklad

curl \
  -X PATCH \
  -H "X-API-Key: $SALDO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"assignee_id":2}' \
  https://techtools.cz/ucetnictvi-api/work_items/1

const response = await fetch('https://techtools.cz/ucetnictvi-api/work_items/1', {
  headers: { 'X-API-Key': process.env.SALDO_API_KEY, 'Content-Type': 'application/json' },
  method: 'PATCH',
  body: JSON.stringify({
    "assignee_id": 2
  })
});
const data = await response.json();

{
  "id": 1,
  "entity_id": 1,
  "entity_name": "Ukázková firma s.r.o.",
  "kind": "draft",
  "kind_label": "Koncept dokladu",
  "title": "Dokončit a vystavit koncept: Přijatá faktura 2026090418",
  "detail": "Coworking Karlín s.r.o. · 17 545,00 Kč · 25. 9. 2026",
  "href": "#/doklad/146",
  "due_on": null,
  "period": null,
  "year": null,
  "overdue": false,
  "priority": "low",
  "priority_label": "Nízká",
  "assignee_id": 2,
  "assignee": "ucetni_ukazka",
  "can_assign": true,
  "state": "open",
  "first_seen_at": "2026-09-28T10:00:00.000Z",
  "resolved_at": null,
  "reopened_count": 0
}

GET Žádosti o podklady ve firmě

/entities/{entity_id}/document_requests

Oprávnění

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

Klíč jen pro čtení

Stačí

Vrátí žádosti o chybějící doklad nebo vysvětlení k bankovnímu pohybu či dokladu, bez zpráv. Otevřené (waiting, delivered) jsou seřazené podle termínu (žádosti bez termínu na konci, při shodě nejnovější první), uzavřené (verified, cancelled) od posledně uzavřené; s filter=all jsou otevřené první. filter=action vrátí jen otevřené žádosti, které čekají na volajícího.

Parametry

Odpověď

200 application/json Žádosti a 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í

Nic nezapisuje.

Limity

Nejvýše 500 žádostí; u filter=action se limit uplatní před výběrem žádostí čekajících na volajícího.

Příklad

curl \
  -H "X-API-Key: $SALDO_API_KEY" \
  "https://techtools.cz/ucetnictvi-api/entities/1/document_requests?filter=all"

const response = await fetch('https://techtools.cz/ucetnictvi-api/entities/1/document_requests?filter=all', {
  headers: { 'X-API-Key': process.env.SALDO_API_KEY }
});
const data = await response.json();

{
  "rows": [
    {
      "id": 1,
      "title": "Doklad k příchozí platbě",
      "status": "delivered",
      "status_label": "Podklad dodán",
      "subject": {
        "type": "bank_transaction",
        "id": 64,
        "label": "Platba 18 150,00 Kč z 25. 9. 2026",
        "amount": 18150.0,
        "currency": "CZK",
        "date": "2026-09-25",
        "partner": "Atelier Lumen s.r.o.",
        "message": "Úhrada – viz smlouva",
        "tx_status": "unmatched",
        "href": "#/banka?tx=64"
      },
      "requested_by": "ukazka",
      "assignee_id": 2,
      "assignee": "ucetni_ukazka",
      "due_on": "2026-10-05",
      "overdue": false,
      "created_at": "2026-09-28T10:00:00.000Z",
      "updated_at": "2026-09-28T10:00:00.000Z",
      "closed_at": null,
      "action_needed": true,
      "can_reply": true,
      "can_verify": true,
      "can_cancel": true,
      "files_count": 1
    }
  ],
  "truncated": false,
  "limit": 500,
  "action_needed": 1,
  "members": [
    {
      "id": 1,
      "name": "ukazka",
      "role": "owner"
    },
    {
      "id": 2,
      "name": "ucetni_ukazka",
      "role": "accountant"
    }
  ]
}

POST Žádost o doklad nebo vysvětlení k pohybu či dokladu

/entities/{entity_id}/document_requests

Oprávnění

Vlastník, účetní nebo editor

Klíč jen pro čtení

Nestačí, vrátí 403 READ_ONLY_KEY

Založí žádost o podklad k bankovnímu pohybu nebo účetnímu dokladu (i konceptu) s první zprávou. K jedné položce může být otevřená jen jedna žádost; k nabídce, objednávce a dodacímu listu žádost založit nelze. Odpovědnou osobou může být jiný člen firmy s právem zápisu, ne sám žadatel. Smazání pohybu nebo dokladu jeho otevřenou žádost zruší se systémovou zprávou.

Parametry

Tělo požadavku

Formát application/json.

Odpověď

201 application/json Nová žádost se zprávami (tvar jako GET …/document_requests/{id}), status waiting.

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ří žádost ve stavu waiting a zprávu s otázkou a zapíše událost document_request.created. Bankovní pohyb ani doklad nemění a nic neúčtuje.

Opakování

Druhá žádost ke stejné položce vrátí 422, dokud je první otevřená; po uzavření lze založit novou.

Příklad

curl \
  -X POST \
  -H "X-API-Key: $SALDO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"subject_type":"bank_transaction","subject_id":22,"title":"Doklad k platbě","question":"Prosím o fakturu nebo účtenku k této platbě."}' \
  https://techtools.cz/ucetnictvi-api/entities/1/document_requests

const response = await fetch('https://techtools.cz/ucetnictvi-api/entities/1/document_requests', {
  headers: { 'X-API-Key': process.env.SALDO_API_KEY, 'Content-Type': 'application/json' },
  method: 'POST',
  body: JSON.stringify({
    "subject_type": "bank_transaction",
    "subject_id": 22,
    "title": "Doklad k platbě",
    "question": "Prosím o fakturu nebo účtenku k této platbě."
  })
});
const data = await response.json();

{
  "id": 2,
  "title": "Doklad k platbě",
  "status": "waiting",
  "status_label": "Čeká na podklad",
  "subject": {
    "type": "bank_transaction",
    "id": 22,
    "label": "Platba 77 440,00 Kč z 22. 9. 2026",
    "amount": 77440.0,
    "currency": "CZK",
    "date": "2026-09-22",
    "partner": "Kavárna U Zeleného stromu s.r.o.",
    "message": "Úhrada faktury FV20260022",
    "tx_status": "matched",
    "href": "#/banka?tx=22"
  },
  "requested_by": "ukazka",
  "assignee_id": null,
  "assignee": null,
  "due_on": null,
  "overdue": false,
  "created_at": "2026-09-28T10:00:00.000Z",
  "updated_at": "2026-09-28T10:00:00.000Z",
  "closed_at": null,
  "action_needed": false,
  "can_reply": true,
  "can_verify": false,
  "can_cancel": true,
  "files_count": 0,
  "attachable_files": 0,
  "messages": [
    {
      "id": 3,
      "kind": "question",
      "user": "ukazka",
      "at": "2026-09-28T10:00:00.000Z",
      "body": "Prosím o fakturu nebo účtenku k této platbě.",
      "files": []
    }
  ]
}

GET Detail žádosti o podklad se zprávami a soubory

/entities/{entity_id}/document_requests/{id}

Oprávnění

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

Klíč jen pro čtení

Stačí

Vrátí žádost se všemi zprávami (otázka, odpovědi, ověření, zrušení) a jejich soubory a s tím, co smí volající udělat (can_reply, can_verify, can_cancel).

Parametry

Odpověď

200 application/json Žádost (pole jako v rows[] seznamu) a zprávy.

Chování

Co změní

Nic nezapisuje.

Příklad

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

const response = await fetch('https://techtools.cz/ucetnictvi-api/entities/1/document_requests/1', {
  headers: { 'X-API-Key': process.env.SALDO_API_KEY }
});
const data = await response.json();

{
  "id": 1,
  "title": "Doklad k příchozí platbě",
  "status": "delivered",
  "status_label": "Podklad dodán",
  "subject": {
    "type": "bank_transaction",
    "id": 64,
    "label": "Platba 18 150,00 Kč z 25. 9. 2026",
    "amount": 18150.0,
    "currency": "CZK",
    "date": "2026-09-25",
    "partner": "Atelier Lumen s.r.o.",
    "message": "Úhrada – viz smlouva",
    "tx_status": "unmatched",
    "href": "#/banka?tx=64"
  },
  "requested_by": "ukazka",
  "assignee_id": 2,
  "assignee": "ucetni_ukazka",
  "due_on": "2026-10-05",
  "overdue": false,
  "created_at": "2026-09-28T10:00:00.000Z",
  "updated_at": "2026-09-28T10:00:00.000Z",
  "closed_at": null,
  "action_needed": true,
  "can_reply": true,
  "can_verify": true,
  "can_cancel": true,
  "files_count": 1,
  "attachable_files": 0,
  "messages": [
    {
      "id": 1,
      "kind": "question",
      "user": "ukazka",
      "at": "2026-09-28T10:00:00.000Z",
      "body": "Pošlete prosím fakturu nebo smlouvu k platbě 7 260 Kč.",
      "files": []
    },
    {
      "id": 2,
      "kind": "reply",
      "user": "ucetni_ukazka",
      "at": "2026-09-28T10:00:00.000Z",
      "body": "Posílám smlouvu.",
      "files": [
        {
          "id": 4,
          "filename": "faktura.pdf",
          "content_type": "application/pdf",
          "byte_size": 142
        }
      ]
    }
  ]
}

GET Počty otevřených žádostí a žádostí čekajících na volajícího

/entities/{entity_id}/document_requests/counts

Oprávnění

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

Klíč jen pro čtení

Stačí

Vrátí jen počty bez žádostí a zpráv – pro odznaky v aplikaci. action_needed počítá žádosti, na které má volající odpovědět (není žadatel a žádost je přidělená jemu nebo nikomu), a dodané žádosti, které smí ověřit; člen bez práva zápisu má vždy 0.

Parametry

Odpověď

200 application/json Počty.

Chování

Co změní

Nic nezapisuje.

Příklad

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

const response = await fetch('https://techtools.cz/ucetnictvi-api/entities/1/document_requests/counts', {
  headers: { 'X-API-Key': process.env.SALDO_API_KEY }
});
const data = await response.json();

{
  "open": 1,
  "action_needed": 1
}

POST Odpověď na žádost o podklad, případně se soubory

/entities/{entity_id}/document_requests/{id}/reply

Oprávnění

Vlastník, účetní nebo editor

Klíč jen pro čtení

Nestačí, vrátí 403 READ_ONLY_KEY

Přidá do otevřené žádosti odpověď s textem a/nebo soubory. Odpověď kohokoli jiného než žadatele žádost označí jako dodanou (delivered); odpověď žadatele (doplňující dotaz) ji vrátí do stavu waiting. Soubory zůstávají u žádosti – k dokladu se přiloží až při ověření s attach. Soubory se posílají jako multipart/form-data v poli files[] (nebo files[0], files[1] …); odpověď bez souborů lze poslat i jako JSON.

Parametry

Tělo požadavku

Formát multipart/form-data.

Odpověď

200 application/json Žádost se zprávami po odpovědi (tvar jako GET …/document_requests/{id}).

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ží zprávu a soubory a změní stav žádosti (delivered s časem a autorem dodání, nebo waiting); zapíše událost document_request.delivered nebo document_request.followed_up. Doklad ani pohyb nemění, nic neúčtuje. Když cokoli selže, nahrané soubory se smažou.

Limity

5 souborů, 15 MB na soubor, 20 MB na odpověď, 2000 znaků textu.

Opakování

Každé volání přidá novou zprávu; stejné soubory se neslučují.

Příklad

V ukázce odpovídá sám žadatel (doplňující dotaz), proto se žádost vrátí do stavu waiting; odpověď jiného člena by ji označila jako delivered.

curl \
  -X POST \
  -H "X-API-Key: $SALDO_API_KEY" \
  -F "body=Posílám účtenku z čerpací stanice." \
  -F "files[]=@uctenka.jpg" \
  https://techtools.cz/ucetnictvi-api/entities/1/document_requests/1/reply

const form = new FormData();
form.append('files[]', fileInput.files[0], 'uctenka.jpg');
form.append('body', 'Posílám účtenku z čerpací stanice.');
const response = await fetch('https://techtools.cz/ucetnictvi-api/entities/1/document_requests/1/reply', {
  headers: { 'X-API-Key': process.env.SALDO_API_KEY },
  method: 'POST',
  body: form
});
const data = await response.json();

{
  "id": 1,
  "title": "Doklad k příchozí platbě",
  "status": "waiting",
  "status_label": "Čeká na podklad",
  "subject": {
    "type": "bank_transaction",
    "id": 64,
    "label": "Platba 18 150,00 Kč z 25. 9. 2026",
    "amount": 18150.0,
    "currency": "CZK",
    "date": "2026-09-25",
    "partner": "Atelier Lumen s.r.o.",
    "message": "Úhrada – viz smlouva",
    "tx_status": "unmatched",
    "href": "#/banka?tx=64"
  },
  "requested_by": "ukazka",
  "assignee_id": 2,
  "assignee": "ucetni_ukazka",
  "due_on": "2026-10-05",
  "overdue": false,
  "created_at": "2026-09-28T10:00:00.000Z",
  "updated_at": "2026-09-28T10:00:00.000Z",
  "closed_at": null,
  "action_needed": false,
  "can_reply": true,
  "can_verify": false,
  "can_cancel": true,
  "files_count": 2,
  "attachable_files": 0,
  "messages": [
    {
      "id": 1,
      "kind": "question",
      "user": "ukazka",
      "at": "2026-09-28T10:00:00.000Z",
      "body": "Pošlete prosím fakturu nebo smlouvu k platbě 7 260 Kč.",
      "files": []
    },
    {
      "id": 2,
      "kind": "reply",
      "user": "ucetni_ukazka",
      "at": "2026-09-28T10:00:00.000Z",
      "body": "Posílám smlouvu.",
      "files": [
        {
          "id": 4,
          "filename": "faktura.pdf",
          "content_type": "application/pdf",
          "byte_size": 142
        }
      ]
    }
  ]
}

Dlouhé seznamy jsou v ukázce zkrácené na první položky.

POST Ověření dodaného podkladu a uzavření žádosti

/entities/{entity_id}/document_requests/{id}/verify

Oprávnění

Zvláštní pravidlo

Pravidlo

Vyžaduje právo zápisu. Ověřit smí žadatel, dokud má ve firmě právo zápisu; jinak vlastník nebo účetní. Nikdy člen, který podklad dodal. Nesplnění vrátí 422.

Klíč jen pro čtení

Nestačí, vrátí 403 READ_ONLY_KEY

Uzavře dodanou žádost jako ověřenou. U žádosti k dokladu s attach=true zkopíruje k dokladu jako přílohy soubory, které v odpovědích dodal někdo jiný než žadatel a které doklad ještě nemá (podle kontrolního součtu). Nic se neúčtuje a stav bankovního pohybu se nemění.

Parametry

Tělo požadavku

Formát application/json.

Odpověď

200 application/json Žádost se zprávami po ověření (status verified).

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í

Zapíše zprávu verified, nastaví stav verified s časem a autorem ověření a zapíše událost document_request.verified; s attach přiloží soubory k dokladu a u každého zapíše událost document.attached. Nic neúčtuje.

Limity

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

Opakování

Druhé volání vrátí 422, protože žádost je uzavřená.

Příklad

Potřebuje žádost ve stavu delivered, kterou založil volající a dodal jiný člen.

curl \
  -X POST \
  -H "X-API-Key: $SALDO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"attach":false}' \
  https://techtools.cz/ucetnictvi-api/entities/1/document_requests/1/verify

const response = await fetch('https://techtools.cz/ucetnictvi-api/entities/1/document_requests/1/verify', {
  headers: { 'X-API-Key': process.env.SALDO_API_KEY, 'Content-Type': 'application/json' },
  method: 'POST',
  body: JSON.stringify({
    "attach": false
  })
});
const data = await response.json();

{
  "id": 1,
  "title": "Doklad k příchozí platbě",
  "status": "verified",
  "status_label": "Ověřeno",
  "subject": {
    "type": "bank_transaction",
    "id": 64,
    "label": "Platba 18 150,00 Kč z 25. 9. 2026",
    "amount": 18150.0,
    "currency": "CZK",
    "date": "2026-09-25",
    "partner": "Atelier Lumen s.r.o.",
    "message": "Úhrada – viz smlouva",
    "tx_status": "unmatched",
    "href": "#/banka?tx=64"
  },
  "requested_by": "ukazka",
  "assignee_id": 2,
  "assignee": "ucetni_ukazka",
  "due_on": "2026-10-05",
  "overdue": false,
  "created_at": "2026-09-28T10:00:00.000Z",
  "updated_at": "2026-09-28T10:00:00.000Z",
  "closed_at": "2026-09-28T10:00:00.000Z",
  "action_needed": false,
  "can_reply": false,
  "can_verify": false,
  "can_cancel": false,
  "files_count": 1,
  "attachable_files": 0,
  "messages": [
    {
      "id": 1,
      "kind": "question",
      "user": "ukazka",
      "at": "2026-09-28T10:00:00.000Z",
      "body": "Pošlete prosím fakturu nebo smlouvu k platbě 7 260 Kč.",
      "files": []
    },
    {
      "id": 2,
      "kind": "reply",
      "user": "ucetni_ukazka",
      "at": "2026-09-28T10:00:00.000Z",
      "body": "Posílám smlouvu.",
      "files": [
        {
          "id": 4,
          "filename": "faktura.pdf",
          "content_type": "application/pdf",
          "byte_size": 142
        }
      ]
    }
  ]
}

Dlouhé seznamy jsou v ukázce zkrácené na první položky.

POST Zrušení otevřené žádosti o podklad

/entities/{entity_id}/document_requests/{id}/cancel

Oprávnění

Zvláštní pravidlo

Pravidlo

Vyžaduje právo zápisu. Zrušit smí žadatel, dokud má ve firmě právo zápisu; jinak vlastník nebo účetní. Nesplnění vrátí 422.

Klíč jen pro čtení

Nestačí, vrátí 403 READ_ONLY_KEY

Uzavře otevřenou žádost jako zrušenou, s nepovinným důvodem.

Parametry

Tělo požadavku

Formát application/json.

Odpověď

200 application/json Žádost se zprávami po zrušení (status cancelled).

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í

Zapíše zprávu cancelled s důvodem, nastaví stav cancelled a čas uzavření a zapíše událost document_request.cancelled.

Opakování

Druhé volání vrátí 422, protože žádost je uzavřená.

Příklad

curl \
  -X POST \
  -H "X-API-Key: $SALDO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason":"Doklad dorazil poštou."}' \
  https://techtools.cz/ucetnictvi-api/entities/1/document_requests/1/cancel

const response = await fetch('https://techtools.cz/ucetnictvi-api/entities/1/document_requests/1/cancel', {
  headers: { 'X-API-Key': process.env.SALDO_API_KEY, 'Content-Type': 'application/json' },
  method: 'POST',
  body: JSON.stringify({
    "reason": "Doklad dorazil poštou."
  })
});
const data = await response.json();

{
  "id": 1,
  "title": "Doklad k příchozí platbě",
  "status": "cancelled",
  "status_label": "Zrušeno",
  "subject": {
    "type": "bank_transaction",
    "id": 64,
    "label": "Platba 18 150,00 Kč z 25. 9. 2026",
    "amount": 18150.0,
    "currency": "CZK",
    "date": "2026-09-25",
    "partner": "Atelier Lumen s.r.o.",
    "message": "Úhrada – viz smlouva",
    "tx_status": "unmatched",
    "href": "#/banka?tx=64"
  },
  "requested_by": "ukazka",
  "assignee_id": 2,
  "assignee": "ucetni_ukazka",
  "due_on": "2026-10-05",
  "overdue": false,
  "created_at": "2026-09-28T10:00:00.000Z",
  "updated_at": "2026-09-28T10:00:00.000Z",
  "closed_at": "2026-09-28T10:00:00.000Z",
  "action_needed": false,
  "can_reply": false,
  "can_verify": false,
  "can_cancel": false,
  "files_count": 1,
  "attachable_files": 0,
  "messages": [
    {
      "id": 1,
      "kind": "question",
      "user": "ukazka",
      "at": "2026-09-28T10:00:00.000Z",
      "body": "Pošlete prosím fakturu nebo smlouvu k platbě 7 260 Kč.",
      "files": []
    },
    {
      "id": 2,
      "kind": "reply",
      "user": "ucetni_ukazka",
      "at": "2026-09-28T10:00:00.000Z",
      "body": "Posílám smlouvu.",
      "files": [
        {
          "id": 4,
          "filename": "faktura.pdf",
          "content_type": "application/pdf",
          "byte_size": 142
        }
      ]
    }
  ]
}

Dlouhé seznamy jsou v ukázce zkrácené na první položky.

GET Stažení souboru ze žádosti o podklad

/entities/{entity_id}/document_requests/{id}/files/{file_id}

Oprávnění

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

Klíč jen pro čtení

Stačí

Vrátí soubor přiložený k některé zprávě žádosti. PDF, JPEG, PNG, WebP a GIF se posílají k zobrazení (inline), HEIC, HEIF a XML jako příloha; vždy s hlavičkou Cache-Control private, no-store. Soubor, který k žádosti nepatří, vrátí 404.

Parametry

Odpověď

200 application/octet-stream Obsah souboru s uloženým Content-Type a původním názvem.

Chování

Co změní

Nic nezapisuje.

Příklad

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

const response = await fetch('https://techtools.cz/ucetnictvi-api/entities/1/document_requests/1/files/4', {
  headers: { 'X-API-Key': process.env.SALDO_API_KEY }
});
const data = await response.json();

application/pdf, 142 bajtů (soubor faktura.pdf)