Reference API
Účet, firmy a přístupy
Práce s vlastním účtem a firmami: API klíče, pozvánky do cizích firem, vyhledání firmy podle IČO, číselník bank a formátů výpisů, založení firmy i ukázkové firmy, nastavení, první kroky, uzamčení období, členové s rolemi a historie změn.
GET Seznam vlastních API klíčů
/api_keys
- Oprávnění
- Jen přihlášení v prohlížeči, API klíčem ne
- Pravidlo
- Jen s přihlášením v prohlížeči (cookie _techtools4_session). Požadavek s API klíčem v X-API-Key nebo Authorization: Bearer vrátí 403 „API klíče se spravují jen po přihlášení v prohlížeči“.
Vrátí všechny API klíče přihlášeného uživatele od nejnovějšího, včetně zrušených. Token se po vytvoření už nikdy nevrací, jen jeho poslední čtyři znaky v hint. Čas posledního použití se při ověření klíče ukládá nejvýše jednou za 5 minut.
Odpověď
200 application/json Objekt s polem keys.
| Pole | Význam |
|---|---|
keys[].id | ID klíče |
keys[].name | Název klíče |
keys[].hint | Konec tokenu ve tvaru …abcd |
keys[].read_only | Klíč smí jen číst (GET a HEAD) |
keys[].created_at | Vytvoření |
keys[].last_used_at | Poslední použití (s přesností na 5 minut) nebo null |
keys[].revoked_at | Čas zrušení nebo null |
keys[].active | Klíč není zrušený |
keys[].entity_id | Firma, na kterou je klíč omezený, nebo null (všechny firmy) |
keys[].entity_name | Název té firmy nebo null |
Chyby této operace
| Stav | Kód | Kdy |
|---|---|---|
| 403 | – | Požadavek s API klíčem místo přihlášení v prohlížeči |
Společné chyby všech operací (přihlášení, oprávnění, limity) popisuje Chyby a limity.
Chování
- Co změní
- Nic nezapisuje.
Příklad
Volá se s přihlášením v prohlížeči, ne s API klíčem.
JavaScript v prohlížeči
const response = await fetch('https://techtools.cz/ucetnictvi-api/api_keys', {
credentials: 'include'
});
const data = await response.json();{
"keys": [
{
"id": 1,
"name": "Dokumentace API",
"hint": "…2Udf",
"read_only": false,
"created_at": "2026-09-28T10:00:00.000Z",
"last_used_at": "2026-09-28T10:00:00.000Z",
"revoked_at": null,
"active": true,
"entity_id": null,
"entity_name": null
},
{
"id": 3,
"name": "Starý skript",
"hint": "…TouC",
"read_only": true,
"created_at": "2026-09-28T10:00:00.000Z",
"last_used_at": null,
"revoked_at": null,
"active": true,
"entity_id": null,
"entity_name": null
}
]
}
POST Vytvoří API klíč
/api_keys
- Oprávnění
- Jen přihlášení v prohlížeči, API klíčem ne
- Pravidlo
- Jen s přihlášením v prohlížeči; zápis navíc potřebuje hlavičku X-Saldo: 1. Požadavek s API klíčem vrátí 403.
Vytvoří osobní API klíč pro skripty a AI agenty a jednou vrátí jeho token (saldo_ a 40 znaků). Klíč jedná s právy svého uživatele ve všech firmách, kde je uživatel přijatým členem, nebo s entity_id jen v jedné z nich: GET /entities pak vrátí jen tu firmu, ID jiné firmy odpoví 404 a operace napříč firmami (/clients, /work_items, založení firmy) 403 KEY_LIMITED_TO_FIRM; veřejné operace a /lookup fungují. Klíč jen pro čtení odmítne každý požadavek kromě GET a HEAD a nestáhne export celé firmy ani úplný archiv. Token se posílá v hlavičce X-API-Key nebo jako Authorization: Bearer. Akce provedené klíčem nesou v historii změn firmy jeho název.
Tělo požadavku
Formát application/json.
| Pole | Typ | Povinné | Popis |
|---|---|---|---|
name | text | ne | Název klíče; prázdný nebo chybějící název se uloží jako „API klíč“. Nejvýše 80 znaků. |
read_only | ano/ne | ne | Klíč smí jen číst. Výchozí false. |
entity_id | celé číslo | ne | Omezí klíč na tuto firmu; musí jít o firmu, kde je uživatel přijatým členem. Bez hodnoty platí pro všechny firmy. |
Odpověď
201 application/json Vytvořený klíč ve stejném tvaru jako v seznamu a navíc token. Token už znovu získat nelze.
| Pole | Význam |
|---|---|
token | Celý token klíče; vrací se jen v této odpovědi |
id | ID klíče |
hint | Poslední čtyři znaky tokenu ve tvaru …abcd |
read_only | Klíč smí jen číst |
active | true |
Chyby této operace
| Stav | Kód | Kdy |
|---|---|---|
| 422 | – | Uživatel už má 20 aktivních klíčů („Můžete mít nejvýš 20 aktivních klíčů“) |
| 422 | – | entity_id není firma, kde je uživatel přijatým členem |
| 403 | – | Požadavek s API klíčem místo přihlášení v prohlížeči |
Společné chyby všech operací (přihlášení, oprávnění, limity) popisuje Chyby a limity.
Chování
- Co změní
- Vytvoří API klíč. Uloží jen otisk SHA-256 tokenu a jeho poslední čtyři znaky, samotný token neukládá. Záznam do historie změn nevzniká.
- Limity
- Nejvýše 20 aktivních (nezrušených) klíčů na uživatele.
- Opakování
- Každé volání vytvoří nový klíč s novým tokenem.
Příklad
Volá se s přihlášením v prohlížeči a hlavičkou X-Saldo: 1.
JavaScript v prohlížeči
const response = await fetch('https://techtools.cz/ucetnictvi-api/api_keys', {
headers: { 'X-Saldo': '1', 'Content-Type': 'application/json' },
method: 'POST',
body: JSON.stringify({
"name": "Účetní agent",
"read_only": true
}),
credentials: 'include'
});
const data = await response.json();{
"id": 4,
"name": "Účetní agent",
"hint": "…4BVu",
"read_only": true,
"created_at": "2026-09-28T10:00:00.000Z",
"last_used_at": null,
"revoked_at": null,
"active": true,
"entity_id": null,
"entity_name": null,
"token": "saldo_…"
}
DELETE Zruší API klíč
/api_keys/{id}
- Oprávnění
- Jen přihlášení v prohlížeči, API klíčem ne
- Pravidlo
- Jen s přihlášením v prohlížeči a hlavičkou X-Saldo: 1. Klíč nelze zrušit jím samým ani jiným API klíčem (403).
Zruší vlastní API klíč. Klíč okamžitě přestane platit (požadavky s ním vrátí 401 INVALID_API_KEY), ale v seznamu zůstane se stavem active: false. Klíč jiného uživatele vrátí 404.
Parametry
| Název | Kde | Typ | Povinný | Popis |
|---|---|---|---|---|
id | cesta | celé číslo | ano | ID klíče ze seznamu GET /api_keys. Příklad 3. |
Odpověď
200 application/json Zrušený klíč ve stejném tvaru jako v seznamu (active: false, revoked_at).
Chyby této operace
| Stav | Kód | Kdy |
|---|---|---|
| 403 | – | Požadavek s API klíčem místo přihlášení v prohlížeči |
Společné chyby všech operací (přihlášení, oprávnění, limity) popisuje Chyby a limity.
Chování
- Co změní
- Nastaví čas zrušení klíče; klíč se nemaže.
- Opakování
- Opakované zrušení téhož klíče vrátí znovu 200 a čas prvního zrušení ponechá.
Příklad
Volá se s přihlášením v prohlížeči a hlavičkou X-Saldo: 1.
JavaScript v prohlížeči
const response = await fetch('https://techtools.cz/ucetnictvi-api/api_keys/3', {
headers: { 'X-Saldo': '1' },
method: 'DELETE',
credentials: 'include'
});
const data = await response.json();{
"id": 3,
"name": "Starý skript",
"hint": "…TouC",
"read_only": true,
"created_at": "2026-09-28T10:00:00.000Z",
"last_used_at": null,
"revoked_at": "2026-09-28T10:00:00.000Z",
"active": false,
"entity_id": null,
"entity_name": null
}
GET Pozvánky do firem čekající na přijetí
/invitations
- Oprávnění
- Přihlášený uživatel nebo jeho API klíč, bez vazby na jednu firmu
- Klíč jen pro čtení
- Stačí
Vrátí pozvánky přihlášeného uživatele do cizích firem, které ještě nepřijal, od nejstarší. Dokud pozvánku nepřijme, firma se mu v GET /entities nezobrazí a k jejím datům nemá přístup.
Odpověď
200 application/json Pole pozvánek.
| Pole | Význam |
|---|---|
id | ID pozvánky (členství) pro přijetí nebo odmítnutí |
entity_id | ID firmy |
entity_name | Název firmy |
legal_form | Právní forma |
legal_form_label | Název právní formy |
role | Nabízená role: accountant, editor nebo viewer |
role_label | Název role |
invited_by | Uživatelské jméno toho, kdo pozval |
invited_at | Čas pozvání |
Chování
- Co změní
- Nic nezapisuje.
Příklad
cURL
curl \
-H "X-API-Key: $SALDO_API_KEY" \
https://techtools.cz/ucetnictvi-api/invitationsJavaScript
const response = await fetch('https://techtools.cz/ucetnictvi-api/invitations', {
headers: { 'X-API-Key': process.env.SALDO_API_KEY }
});
const data = await response.json();[
{
"id": 5,
"entity_id": 3,
"entity_name": "Kolegyně Ukázková s.r.o.",
"legal_form": "sro",
"legal_form_label": "s.r.o.",
"role": "accountant",
"role_label": "Účetní",
"invited_by": "kolegyne_ukazka",
"invited_at": "2026-09-28T10:00:00.000Z"
}
]
POST Přijme pozvánku do firmy
/invitations/{id}/accept
- Oprávnění
- Přihlášený uživatel nebo jeho API klíč, bez vazby na jednu firmu
- Pravidlo
- Jen pozvánka adresovaná volajícímu. Cizí, už přijatá nebo neexistující pozvánka vrátí 404.
- Klíč jen pro čtení
- Nestačí, vrátí 403
READ_ONLY_KEY
Přijme pozvánku a uživatel tím získá přístup k firmě s rolí z pozvánky. Vrátí firmu ve stejném tvaru jako GET /entities.
Parametry
| Název | Kde | Typ | Povinný | Popis |
|---|---|---|---|---|
id | cesta | celé číslo | ano | ID pozvánky z GET /invitations. Příklad 5. |
Odpověď
200 application/json Firma s rolí volajícího (role, can_write, can_manage).
Chování
- Co změní
- Označí členství jako přijaté. Do historie změn firmy zapíše událost member.accepted.
- Opakování
- Druhé přijetí téže pozvánky vrátí 404.
Příklad
cURL
curl \
-X POST \
-H "X-API-Key: $SALDO_API_KEY" \
https://techtools.cz/ucetnictvi-api/invitations/5/acceptJavaScript
const response = await fetch('https://techtools.cz/ucetnictvi-api/invitations/5/accept', {
headers: { 'X-API-Key': process.env.SALDO_API_KEY },
method: 'POST'
});
const data = await response.json();{
"id": 3,
"accent_color": null,
"archived": false,
"bookkeeping": "double_entry",
"city": null,
"company_id": null,
"country": "CZ",
"created_at": "2026-09-28T10:00:00.000Z",
"currency": "CZK",
"databox": null,
"default_due_days": 14,
"dic": null,
"email": null,
"first_name": null,
"fiscal_year_start": 1,
"flat_expense_rate": null,
"house_number": null,
"ico": null,
"invoice_footer": null,
"last_name": null,
"legal_form": "sro",
"locked_until": null,
"nace": null,
"name": "Kolegyně Ukázková s.r.o.",
"orientation_number": null,
"owner_id": 3,
"phone": null,
"register_note": null,
"responsible_id": null,
"street": null,
"tax_office_code": null,
"tax_office_workplace": null,
"title": null,
"updated_at": "2026-09-28T10:00:00.000Z",
"vat_registered_on": null,
"vat_status": "none",
"web": null,
"zip": null,
"settings": {
"round_total": "cash",
"invoice_language": "cs",
"number_format": "{prefix}{yyyy}{nnnn}",
"reminder_days": [
3,
14
],
"show_qr": true,
"invoice_style": "plain",
"invoice_font": "auto",
"invoice_density": "normal",
"invoice_table": "auto",
"invoice_corners": "auto",
"invoice_logo_size": "m",
"invoice_logo_name": false,
"invoice_row_numbers": false,
"invoice_paid_stamp": true,
"invoice_contacts": true,
"invoice_credit": true
},
"has_logo": false,
"legal_form_label": "s.r.o.",
"bookkeeping_label": "Podvojné účetnictví",
"vat_status_label": "Neplátce DPH",
"vat_payer": false,
"double_entry": true,
"role": "accountant",
"can_write": true,
"can_manage": true,
"payroll_access": true,
"member_user_id": 1,
"membership_id": 5,
"ownership_offer": null
}
Dlouhé seznamy jsou v ukázce zkrácené na první položky.
DELETE Odmítne pozvánku do firmy
/invitations/{id}
- Oprávnění
- Přihlášený uživatel nebo jeho API klíč, bez vazby na jednu firmu
- Pravidlo
- Jen pozvánka adresovaná volajícímu. Cizí, už přijatá nebo neexistující pozvánka vrátí 404; z přijatého členství se odchází přes DELETE /entities/{entity_id}/members/{id}.
- Klíč jen pro čtení
- Nestačí, vrátí 403
READ_ONLY_KEY
Odmítne pozvánku a smaže ji. Firma pak může uživatele pozvat znovu.
Parametry
| Název | Kde | Typ | Povinný | Popis |
|---|---|---|---|---|
id | cesta | celé číslo | ano | ID pozvánky z GET /invitations. Příklad 5. |
Odpověď
204 Bez obsahu.
Chování
- Co změní
- Smaže pozvánku. Do historie změn firmy zapíše událost member.declined.
- Opakování
- Druhé odmítnutí téže pozvánky vrátí 404.
Příklad
Potřebuje vlastní čekající pozvánku; přijetí a odmítnutí spotřebují tutéž.
cURL
curl \
-X DELETE \
-H "X-API-Key: $SALDO_API_KEY" \
https://techtools.cz/ucetnictvi-api/invitations/5JavaScript
const response = await fetch('https://techtools.cz/ucetnictvi-api/invitations/5', {
headers: { 'X-API-Key': process.env.SALDO_API_KEY },
method: 'DELETE'
});
const data = await response.json();soubor, 0 bajtů
GET Číselník českých bank s kódy a BIC
/lookup/banks
- Oprávnění
- Přihlášený uživatel nebo jeho API klíč, bez vazby na jednu firmu
- Klíč jen pro čtení
- Stačí
Vrátí kódy bank platebního styku v ČR s názvem banky a BIC podle číselníku ČNB (stav uvedený v kódu: 24. 8. 2026). Některé banky BIC nemají.
Odpověď
200 application/json Pole bank seřazené podle kódu.
| Pole | Význam |
|---|---|
code | Čtyřmístný kód banky |
name | Název banky |
bic | BIC (SWIFT) nebo null |
Chování
- Co změní
- Nic nezapisuje.
Příklad
cURL
curl \
-H "X-API-Key: $SALDO_API_KEY" \
https://techtools.cz/ucetnictvi-api/lookup/banksJavaScript
const response = await fetch('https://techtools.cz/ucetnictvi-api/lookup/banks', {
headers: { 'X-API-Key': process.env.SALDO_API_KEY }
});
const data = await response.json();[
{
"code": "0100",
"name": "Komerční banka, a.s.",
"bic": "KOMBCZPP"
},
{
"code": "0300",
"name": "Československá obchodní banka, a. s.",
"bic": "CEKOCZPP"
}
]
Dlouhé seznamy jsou v ukázce zkrácené na první položky.
GET Formáty bankovních výpisů, které umí import
/lookup/statement_formats
- Oprávnění
- Přihlášený uživatel nebo jeho API klíč, bez vazby na jednu firmu
- Klíč jen pro čtení
- Stačí
Vrátí formáty datových exportů výpisů, které import čte přesně (GPC/ABO, XML camt.053, MT940, CSV), a údaje o čtení PDF výpisů: je v betě a banks vyjmenovává banky, jejichž rozvržení PDF je ověřené. PDF jiných bank se čtou také, ale bez ověření.
Odpověď
200 application/json Objekt s exports a pdf.
| Pole | Význam |
|---|---|
exports | Názvy datových formátů |
pdf.beta | Čtení PDF je v betě (true) |
pdf.banks[] | Banky s ověřeným PDF výpisem: code, name |
Chování
- Co změní
- Nic nezapisuje.
Příklad
cURL
curl \
-H "X-API-Key: $SALDO_API_KEY" \
https://techtools.cz/ucetnictvi-api/lookup/statement_formatsJavaScript
const response = await fetch('https://techtools.cz/ucetnictvi-api/lookup/statement_formats', {
headers: { 'X-API-Key': process.env.SALDO_API_KEY }
});
const data = await response.json();{
"exports": [
"GPC/ABO",
"XML camt.053"
],
"pdf": {
"beta": true,
"banks": [
{
"code": "3030",
"name": "Air Bank"
},
{
"code": "0710",
"name": "Česká národní banka"
}
]
}
}
Dlouhé seznamy jsou v ukázce zkrácené na první položky.
GET Registr bank a jejich napojení přes API
/lookup/bank_providers
- 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
- Banka a pokladna › Propojení s bankou
Vrátí každou banku s kódem (všechny kódy z číselníku ČNB, Revolut a Wise) a její možnosti napojení se stavem supported (funguje hned), needs_partner (adaptér je hotový, chybí registrace TechTools u banky nebo agregátora), planned a vždy files (výpis ze souboru). U možnosti jsou kroky, co si klient u banky zařídí, poznámka k ceně, odkaz na návod, pole přihlašovacích údajů, verified a sources; co zdroj nedoložil, je v unverified. Zdroj dat: config/ucetnictvi/banks/providers.yml.
Odpověď
200 application/json { verified, banks }
| Pole | Význam |
|---|---|
banks[].status | Nejlepší možnost banky; label česky: Přímo přes API, Připravujeme, Jen výpisy ze souboru |
banks[].options[] | provider, name, status, label, auth, fields, steps, price, guide_url, verified, sources, unverified |
Chování
- Co změní
- Nic nezapisuje.
Příklad
cURL
curl \
-H "X-API-Key: $SALDO_API_KEY" \
https://techtools.cz/ucetnictvi-api/lookup/bank_providersJavaScript
const response = await fetch('https://techtools.cz/ucetnictvi-api/lookup/bank_providers', {
headers: { 'X-API-Key': process.env.SALDO_API_KEY }
});
const data = await response.json();{
"verified": "2026-10-07",
"banks": [
{
"code": "0800",
"name": "Česká spořitelna",
"bic": "GIBACZPX",
"status": "needs_partner",
"label": "Připravujeme",
"options": [
{
"provider": "csas",
"name": "Premium API České spořitelny",
"status": "needs_partner",
"label": "Připravujeme",
"auth": "oauth",
"aggregator": false,
"fields": [],
"steps": [
"Požádejte banku o aktivaci Premium API k firemnímu účtu (George Business nebo bankéř).",
"V Saldu zvolte „Přihlásit se do banky“ a v George udělte souhlas k vybraným účtům."
],
"price": {
"note": "300 Kč za účet a měsíc podle ceníku banky",
"sources": [
"Veřejný ceník České spořitelny (ověřeno v tiketu SALD-18)"
]
},
"guide_url": "https://developers.erstegroup.com",
"verified": "2026-10-07",
"sources": [
"https://developers.erstegroup.com"
],
"unverified": [
"Doba platnosti souhlasu v George (počítáme 180 dní",
"skutečný konec vrací banka)."
]
},
{
"provider": "saltedge",
"name": "PSD2 přes Salt Edge",
"status": "needs_partner",
"label": "Připravujeme",
"auth": "oauth",
"aggregator": true,
"fields": [],
"steps": [
"V Saldu zvolíte „Přihlásit se do banky“.",
"Přihlásíte se do internetového bankovnictví a udělíte souhlas se čtením pohybů (PSD2)."
],
"price": {
"note": "Pro klienta banky bez poplatku za PSD2 přístup; poplatek agregátorovi hradí TechTools.",
"sources": [
"https://saltedge.com/products/spectre"
]
},
"guide_url": "https://docs.saltedge.com/v6/",
"verified": "2026-10-07",
"sources": [
"https://docs.saltedge.com/v6/",
"https://saltedge.com/products/spectre"
],
"unverified": [
"Zda Salt Edge tuto banku pokrývá.",
"Seznam českých bank"
]
}
]
},
{
"code": "0300",
"name": "ČSOB",
"bic": "CEKOCZPP",
"status": "needs_partner",
"label": "Připravujeme",
"options": [
{
"provider": "csob",
"name": "csob",
"status": "planned",
"label": "Připravujeme",
"aggregator": false,
"fields": [],
"steps": [
"Ve smlouvě ČSOB CEB zapněte službu Business Connector.",
"Pořiďte si komunikační certifikát (I.CA, PostSignum nebo od banky) a zaregistrujte ho v CEB."
],
"price": {
"note": "Business Connector je pro firmy a OSVČ zdarma",
"sources": [
"https://www.pruvodcepodnikanim.cz/clanek/business-connector/"
]
},
"guide_url": "https://www.pruvodcepodnikanim.cz/clanek/business-connector/",
"verified": "2026-10-07",
"sources": [
"https://www.pruvodcepodnikanim.cz/clanek/business-connector/"
],
"unverified": [
"Zda ČSOB pro vlastní klientskou aplikaci přiděluje výrobci identifikátor (ClientAppGuid)."
]
},
{
"provider": "saltedge",
"name": "PSD2 přes Salt Edge",
"status": "needs_partner",
"label": "Připravujeme",
"auth": "oauth",
"aggregator": true,
"fields": [],
"steps": [
"V Saldu zvolíte „Přihlásit se do banky“.",
"Přihlásíte se do internetového bankovnictví a udělíte souhlas se čtením pohybů (PSD2)."
],
"price": {
"note": "Pro klienta banky bez poplatku za PSD2 přístup; poplatek agregátorovi hradí TechTools.",
"sources": [
"https://saltedge.com/products/spectre"
]
},
"guide_url": "https://docs.saltedge.com/v6/",
"verified": "2026-10-07",
"sources": [
"https://docs.saltedge.com/v6/",
"https://saltedge.com/products/spectre"
],
"unverified": [
"Zda Salt Edge tuto banku pokrývá.",
"Seznam českých bank"
]
}
]
}
]
}
Dlouhé seznamy jsou v ukázce zkrácené na první položky.
GET Firma podle IČO s návrhem nastavení Salda
/lookup/{ico}
- Oprávnění
- Přihlášený uživatel nebo jeho API klíč, bez vazby na jednu firmu
- Klíč jen pro čtení
- Stačí
Najde subjekt podle IČO v ARES, doplní statistiky ARES RES (počet zaměstnanců, převažující činnost) a stav v registru plátců DPH a navrhne nastavení firmy v Saldu: segment, právní formu, způsob vedení (OSVČ daňová evidence, ostatní podvojné účetnictví), vztah k DPH, finanční úřad a pracoviště, CZ-NACE, u OSVČ výdajový paušál a tipy na moduly. Neznámé IČO není chyba: vrátí 200 s found: false a code NOT_FOUND. Když ARES RES nebo registr plátců neodpoví, návrh se vrátí bez nich a důvod je ve warnings.
Parametry
| Název | Kde | Typ | Povinný | Popis |
|---|---|---|---|---|
ico | cesta | text | ano | IČO, 1 až 8 číslic; kratší se doplní nulami zleva. Musí mít platnou kontrolní číslici. Jiné znaky nebo víc než 8 číslic routa nepřijme (404). Příklad 99999994. |
Odpověď
200 application/json Karta firmy a návrh nastavení, nebo { ico, found: false, code: NOT_FOUND, error }.
| Pole | Význam |
|---|---|
found | Subjekt byl nalezen |
looked_up_at | Čas dotazu (odpověď může být z mezipaměti) |
company | Název, DIČ, právní forma, vznik a zánik, adresa, u OSVČ jméno, plátce DPH, nespolehlivost, velikost, CZ-NACE (nejvýše 8), společníci (nejvýše 10) a register_note – věta o zápisu ve veřejném rejstříku ze spisové značky (soud, oddíl, vložka), nebo null |
bank_accounts | Účty zveřejněné v registru plátců DPH (nejvýše 5): number, bank_code, bank_name, display |
suggestion | Návrh: segment, legal_form, bookkeeping, vat_status, employees, tax_office_code, tax_office_workplace, tax_office_label, nace, nace_code, nace_name, u OSVČ income_kind, flat_rate, flat_rate_reason, hints |
sources | Které zdroje odpověděly: ares, res, vat_registry |
warnings | Upozornění (zaniklý subjekt, nedostupný zdroj) |
Chyby této operace
| Stav | Kód | Kdy |
|---|---|---|
| 422 | INVALID_ICO | IČO nemá platnou kontrolní číslici |
| 502 | ARES_UNAVAILABLE | ARES neodpovídá nebo vrátil chybu |
| 429 | RATE_LIMITED | Víc než 40 hledání za minutu jedním uživatelem („Příliš mnoho hledání – zkuste to za minutu znovu“) |
Společné chyby všech operací (přihlášení, oprávnění, limity) popisuje Chyby a limity.
Chování
- Co změní
- Nic nezapisuje. Volá ARES (ekonomické subjekty, RES, případně číselník CZ-NACE) a registr plátců DPH Ministerstva financí. Výsledek na 5 minut uloží do mezipaměti.
- Limity
- 40 hledání za minutu na uživatele. Odpověď pro stejné IČO je 5 minut z mezipaměti. Časový limit dotazu do ARES je 8 s.
Příklad
ARES, ARES RES a registr plátců DPH jsou v příkladu nahrazené testovacími daty.
cURL
curl \
-H "X-API-Key: $SALDO_API_KEY" \
https://techtools.cz/ucetnictvi-api/lookup/99999994JavaScript
const response = await fetch('https://techtools.cz/ucetnictvi-api/lookup/99999994', {
headers: { 'X-API-Key': process.env.SALDO_API_KEY }
});
const data = await response.json();{
"ico": "99999994",
"found": true,
"looked_up_at": "2026-09-28T10:00:00.000Z",
"company": {
"name": "Ukázková firma s.r.o.",
"dic": "CZ99999994",
"legal_form_code": "112",
"legal_form_name": "Společnost s ručením omezeným",
"founded": "2019-03-01",
"dissolved": null,
"region": "Hlavní město Praha",
"address": "Na Příkopě 859/22, 11000 Praha",
"street": "Na Příkopě",
"house_number": "859",
"orientation_number": "22",
"city": "Praha",
"zip": "11000",
"vat_payer": true,
"unreliable": false,
"employees_code": "120",
"employees_label": "1–5 zaměstnanců",
"nace": [
{
"code": "62100",
"name": null
},
{
"code": "62200",
"name": "Poradenství v oblasti počítačů a správa počítačových systémů"
}
],
"members": [],
"register_note": null
},
"bank_accounts": [
{
"number": "9999999429",
"bank_code": "0800",
"bank_name": "Česká spořitelna, a.s.",
"display": "9999999429/0800"
}
],
"suggestion": {
"segment": "small",
"legal_form": "sro",
"bookkeeping": "double_entry",
"vat_status": "quarterly",
"employees": "small",
"tax_office_code": 451,
"tax_office_workplace": 2001,
"tax_office_label": "Územní pracoviště pro Prahu 1",
"nace": "621000",
"nace_code": "62100",
"nace_name": null,
"hints": {
"projects": "Hodí se sledovat, co vydělává která zakázka."
}
},
"sources": {
"ares": true,
"res": true,
"vat_registry": true
},
"warnings": []
}
Dlouhé seznamy jsou v ukázce zkrácené na první položky. Odpověď externí služby (ARES, registr plátců DPH) je v ukázce nahrazená smyšlenými údaji ve formátu, který služba vrací.
GET Firmy, ke kterým má uživatel přístup
/entities
- Oprávnění
- Přihlášený uživatel nebo jeho API klíč, bez vazby na jednu firmu
- Pravidlo
- U firmy, kde má volající roli Nahrává doklady, vrátí jen id, name, ico, legal_form, legal_form_label, archived, role, submitter: true, membership_id, member_user_id a příznaky can_write, can_manage, payroll_access (false); settings je prázdné.
- Klíč jen pro čtení
- Stačí
Vrátí všechny účetní jednotky, kde je volající přijatým členem, nejdřív aktivní a potom archivované, v obou skupinách podle názvu. Každá firma obsahuje své údaje, nastavení doplněné o výchozí hodnoty a roli volajícího. Logo se tu nevrací, jen příznak has_logo. Editor a role viewer dostanou daňový profil (settings.tax_profile) bez rodných čísel, dat narození a účtu pro vratku (OSVČ, manžel, děti). API klíč omezený na jednu firmu vrátí jen ji.
Odpověď
200 application/json Pole firem.
| Pole | Význam |
|---|---|
id | ID firmy (entity_id v dalších cestách) |
name | Název |
legal_form | Právní forma a legal_form_label |
bookkeeping | Způsob vedení a bookkeeping_label |
vat_status | Vztah k DPH a vat_status_label |
locked_until | Období uzamčené do tohoto dne včetně, nebo null |
settings | Nastavení doplněné o výchozí hodnoty |
has_logo | Firma má logo |
vat_payer | Plátce DPH (měsíční nebo čtvrtletní) |
double_entry | Vede podvojné účetnictví |
role | Role volajícího: owner, accountant, editor nebo viewer |
can_write | Volající smí zapisovat (u archivované firmy false) |
can_manage | Volající je vlastník nebo účetní |
payroll_access | Volající vidí mzdy a údaje zaměstnanců (vlastník a účetní vždy, editor a viewer podle Vidí mzdy) |
member_user_id | ID uživatele volajícího |
membership_id | ID členství volajícího |
ownership_offer | Nabídka vlastnictví pro volajícího (mode, offered_by, offered_at, keep_role), nebo null |
Chování
- Co změní
- Nic nezapisuje.
Příklad
cURL
curl \
-H "X-API-Key: $SALDO_API_KEY" \
https://techtools.cz/ucetnictvi-api/entitiesJavaScript
const response = await fetch('https://techtools.cz/ucetnictvi-api/entities', {
headers: { 'X-API-Key': process.env.SALDO_API_KEY }
});
const data = await response.json();[
{
"id": 2,
"accent_color": null,
"archived": false,
"bookkeeping": "tax_records",
"city": "Praha",
"company_id": null,
"country": "CZ",
"created_at": "2026-09-28T10:00:00.000Z",
"currency": "CZK",
"databox": null,
"default_due_days": 14,
"dic": "CZ8001010006",
"email": "demo@example.cz",
"first_name": "Jan",
"fiscal_year_start": 1,
"flat_expense_rate": null,
"house_number": "1",
"ico": "99999986",
"invoice_footer": null,
"last_name": "Ukázka",
"legal_form": "osvc",
"locked_until": null,
"nace": "741200",
"name": "Jan Ukázka – grafické studio (ukázka)",
"orientation_number": null,
"owner_id": 1,
"phone": "+420 777 000 000",
"register_note": "Fyzická osoba zapsaná v živnostenském rejstříku.",
"responsible_id": null,
"street": "Vinohradská",
"tax_office_code": "451",
"tax_office_workplace": "2002",
"title": null,
"updated_at": "2026-09-28T10:00:00.000Z",
"vat_registered_on": null,
"vat_status": "none",
"web": null,
"zip": "12000",
"settings": {
"round_total": "always",
"invoice_language": "cs",
"number_format": "{prefix}{yyyy}{nnnn}",
"reminder_days": [
3,
14
],
"show_qr": true,
"invoice_style": "plain",
"invoice_font": "auto",
"invoice_density": "normal",
"invoice_table": "auto",
"invoice_corners": "auto",
"invoice_logo_size": "m",
"invoice_logo_name": false,
"invoice_row_numbers": false,
"invoice_paid_stamp": true,
"invoice_contacts": true,
"invoice_credit": true,
"demo": true,
"statement_category": "mikro",
"submitter": {
"first_name": "Jana",
"last_name": "Ukázková",
"relation": "jednatelka"
},
"tax_profile": {
"children": [
{
"order": 1,
"first_name": "Eliška",
"last_name": "Ukázková",
"birth_number": "1855120003"
}
],
"main_activity": true,
"birth_number": "8001010006",
"ossz_code": "110",
"cssz_variable_symbol": "12345678",
"health_insurer": "111"
}
},
"has_logo": false,
"legal_form_label": "OSVČ",
"bookkeeping_label": "Daňová evidence",
"vat_status_label": "Neplátce DPH",
"vat_payer": false,
"double_entry": false,
"role": "owner",
"can_write": true,
"can_manage": true,
"payroll_access": true,
"member_user_id": 1,
"membership_id": 2,
"ownership_offer": null
},
{
"id": 1,
"accent_color": null,
"archived": false,
"bookkeeping": "double_entry",
"city": "Praha",
"company_id": null,
"country": "CZ",
"created_at": "2026-09-28T10:00:00.000Z",
"currency": "CZK",
"databox": null,
"default_due_days": 14,
"dic": "CZ99999994",
"email": "demo@example.cz",
"first_name": null,
"fiscal_year_start": 1,
"flat_expense_rate": null,
"house_number": "859",
"ico": "99999994",
"invoice_footer": null,
"last_name": null,
"legal_form": "sro",
"locked_until": null,
"nace": "621000",
"name": "Ukázková firma s.r.o.",
"orientation_number": "22",
"owner_id": 1,
"phone": "+420 777 000 000",
"register_note": "Zapsáno v obchodním rejstříku vedeném Městským soudem v Praze, oddíl C, vložka 999999 (ukázková data).",
"responsible_id": null,
"street": "Na Příkopě",
"tax_office_code": "451",
"tax_office_workplace": "2001",
"title": null,
"updated_at": "2026-09-28T10:00:00.000Z",
"vat_registered_on": "2023-01-01",
"vat_status": "monthly",
"web": null,
"zip": "11000",
"settings": {
"round_total": "always",
"invoice_language": "cs",
"number_format": "{prefix}{yyyy}{nnnn}",
"reminder_days": [
3,
14
],
"show_qr": true,
"invoice_style": "plain",
"invoice_font": "auto",
"invoice_density": "normal",
"invoice_table": "auto",
"invoice_corners": "auto",
"invoice_logo_size": "m",
"invoice_logo_name": false,
"invoice_row_numbers": false,
"invoice_paid_stamp": true,
"invoice_contacts": true,
"invoice_credit": true,
"demo": true,
"statement_category": "mikro",
"submitter": {
"first_name": "Jana",
"last_name": "Ukázková",
"relation": "jednatelka"
},
"tax_profile": {
"children": [
{
"order": 1,
"first_name": "Eliška",
"last_name": "Ukázková",
"birth_number": "1855120003"
}
],
"main_activity": true,
"birth_number": "8001010006"
},
"ossz_code": "110",
"cssz_variable_symbol": "1234567890",
"jmhz_workplace": {
"municipality": "Praha",
"municipality_code": "554782",
"country": "CZ"
}
},
"has_logo": false,
"legal_form_label": "s.r.o.",
"bookkeeping_label": "Podvojné účetnictví",
"vat_status_label": "Plátce DPH – měsíčně",
"vat_payer": true,
"double_entry": true,
"role": "owner",
"can_write": true,
"can_manage": true,
"payroll_access": true,
"member_user_id": 1,
"membership_id": 1,
"ownership_offer": null
}
]
Dlouhé seznamy jsou v ukázce zkrácené na první položky.
POST Založí novou firmu
/entities
- Oprávnění
- Přihlášený uživatel nebo jeho API klíč, bez vazby na jednu firmu
- Pravidlo
- Firmu může založit kterýkoli přihlášený uživatel nebo API klíč; stane se jejím vlastníkem.
- Klíč jen pro čtení
- Nestačí, vrátí 403
READ_ONLY_KEY
Založí účetní jednotku, volajícího z ní udělá vlastníka a připraví ji k použití: účtový rozvrh, pokladnu a volitelně bankovní účet s počátečním stavem. Právnická osoba (každá forma kromě osvc) musí vést podvojné účetnictví; jiný způsob vedení Saldo odmítne, nepřepne ho samo. Výdajový paušál se uloží jen při vedení flat_expenses. Při vyplněném settings.profile (průvodce založením) doplní čas dokončení průvodce, chybí-li, a podle osvc_activity zapíše hlavní nebo vedlejší činnost do daňového profilu, pokud tax_profile.main_activity nepřišlo. Stejné IČO lze založit vícekrát.
Tělo požadavku
Formát application/json.
| Pole | Typ | Povinné | Popis |
|---|---|---|---|
entity | objekt | ano | |
entity. | text | ano | Název firmy nebo jméno OSVČ; řídicí znaky se nahradí mezerou. Nejvýše 200 znaků. |
entity. | text | ne | Právní forma. Hodnoty: osvc, sro, as, vos, ks, druzstvo, spolek, other. Výchozí sro. |
entity. | text | ne | IČO; nečíselné znaky se odstraní a kratší číslo doplní nulami na 8 číslic. Kontrolní číslice se neověřuje. |
entity. | text | ne | DIČ; převede se na velká písmena bez mezer a k 8–10 číslicím se doplní CZ. |
entity. | text | ne | Titul (OSVČ). |
entity. | text | ne | Jméno (OSVČ). |
entity. | text | ne | Příjmení (OSVČ). |
entity. | text | ne | Ulice. |
entity. | text | ne | Číslo popisné. |
entity. | text | ne | Číslo orientační. |
entity. | text | ne | Obec. |
entity. | text | ne | PSČ. |
entity. | text | ne | Stát. Výchozí CZ. |
entity. | text | ne | E-mail na dokladech. |
entity. | text | ne | Telefon. |
entity. | text | ne | Web. |
entity. | text | ne | ID datové schránky. |
entity. | text | ne | Zápis v rejstříku, tiskne se na doklady. |
entity. | text | ne | Způsob vedení; jiný než double_entry jen pro osvc. Hodnoty: double_entry, tax_records, flat_expenses, flat_tax. Výchozí double_entry. |
entity. | celé číslo | ne | Výdajový paušál v procentech; uloží se jen s bookkeeping flat_expenses. Hodnoty: 80, 60, 40, 30. |
entity. | text | ne | Vztah k DPH. Hodnoty: none, monthly, quarterly, identified. Výchozí none. |
entity. | datum | ne | Datum registrace k DPH. |
entity. | text | ne | Kód finančního úřadu (číselník tax_offices z GET /codebooks). |
entity. | text | ne | Kód územního pracoviště. |
entity. | text | ne | Převažující činnost CZ-NACE (pro přiznání). |
entity. | celé číslo | ne | Měsíc začátku účetního období. Výchozí 1. Rozsah od 1 do 12. |
entity. | text | ne | Účetní měna, tři velká písmena. Výchozí CZK. |
entity. | celé číslo | ne | Výchozí splatnost vydaných faktur ve dnech. Výchozí 14. Rozsah od 0 do 365. |
entity. | text | ne | Patička dokladů. |
entity. | text | ne | Barva dokladů ve tvaru #RRGGBB. |
entity. | ano/ne | ne | Firma je archivovaná (v seznamech až na konci). Výchozí false. |
entity. | objekt | ne | Nastavení. Chybou 422 se kontrolují jen odpovědi průvodce (profile) a vzhled faktury; modules a přepínače vzhledu se převedou na true/false, ostatní povolené klíče se uloží, jak přijdou, a nepovolené se zahodí. |
entity. | text | ne | Zaokrouhlení vydaných dokladů na celé koruny – always vždy, cash jen při platbě v hotovosti, jiná hodnota nikdy. Výchozí cash. |
entity. | text | ne | Jazyk nových dokladů, cs nebo en (jiná hodnota vrátí 422). Výchozí cs. |
entity. | text | ne | Maska čísla dokladu se značkami {prefix}, {yyyy}, {yy}, {mm} a {n…} (počet n = počet číslic pořadí); bez {n…} se nová hodnota neuloží (422). Výchozí {prefix}{yyyy}{nnnn}. |
entity. | ano/ne | ne | Tisknout QR Platbu. Výchozí true. |
entity. | text | ne | Vzhled faktury. Hodnoty: plain, linka, summary, sidebar, swiss, block, studio, nordic, classic, mono, executive, corporate, modern, elegant, technical, edge, duo, poster, letter, outline, soft, bigtotal, night, glanceink, sideright, sideink, heritage, frame, geometric, atelier, serifclean, ledger, compact, dense, wholesale, guilloche. Výchozí plain. |
entity. | text | ne | Písmo faktury (auto = podle vzhledu). Hodnoty: auto, inter, plex, manrope, dm, franklin, serif, lora. Výchozí auto. |
entity. | text | ne | Hustota faktury. Hodnoty: normal, compact, airy. Výchozí normal. |
entity. | text | ne | Styl tabulky položek. Hodnoty: auto, lines, zebra, grid, minimal, headfill, headline. Výchozí auto. |
entity. | text | ne | Rohy prvků faktury. Hodnoty: auto, sharp, round. Výchozí auto. |
entity. | text | ne | Velikost loga. Hodnoty: s, m, l. Výchozí m. |
entity. | ano/ne | ne | Tisknout název firmy vedle loga. Výchozí false. |
entity. | ano/ne | ne | Číslovat řádky. Výchozí false. |
entity. | ano/ne | ne | Razítko Zaplaceno na uhrazených dokladech. Výchozí true. |
entity. | ano/ne | ne | Tisknout kontakty firmy. Výchozí true. |
entity. | ano/ne | ne | Tisknout odkaz na Saldo. Výchozí true. |
entity. | text | ne | Kategorie účetní jednotky pro výkazy (mikro, mala, stredni, velka); výchozí mikro. |
entity. | text | ne | Předmět podnikání do záhlaví tištěných výkazů (bez něj CZ-NACE firmy). |
entity. | text | ne | Kdo podepisuje účetní závěrku (podpisový záznam na výtisku výkazů). |
entity. | ano/ne | ne | Výsledek hospodaření minulých let držet na účtu 431 do schválení valnou hromadou (jinak 428 nebo 429); rozdělení výsledku pak převede 431 na 428, 364, 421 a další. |
entity. | text | ne | Podpis na dokladech. |
entity. | číslo | ne | Koeficient krácení nároku na odpočet DPH v procentech 0–100 (desetinná čárka se převede na tečku); v přiznání, zaúčtování i peněžním deníku se zaokrouhlí nahoru na celé procento, od 95 % platí 100 %. |
entity. | text | ne | Analytika DPH na vstupu (účet 343… z účtového rozvrhu firmy); prázdné = 343. |
entity. | text | ne | Analytika DPH na výstupu (účet 343… z účtového rozvrhu firmy); prázdné = 343. |
entity. | ano/ne | ne | Samovyměřenou DPH s nárokem na odpočet účtovat MD vat_input_account / D vat_output_account (obě musí být vyplněné a různé). |
entity. | ano/ne | ne | Přiznání podává daňový poradce. |
entity. | ano/ne | ne | Povinný audit. |
entity. | ano/ne | ne | Platí daň z nemovitých věcí (kalendář lhůt). |
entity. | ano/ne | ne | Platí silniční daň (kalendář lhůt). |
entity. | text | ne | Druh příjmů OSVČ pro výdajový paušál (crafts, trade, other, rental). |
entity. | text | ne | Variabilní symbol plateb ČSSZ. |
entity. | text | ne | Kód okresní správy sociálního zabezpečení. |
entity. | celé číslo | ne | Pásmo paušální daně. |
entity. | pole (celé číslo) | ne | Po kolika dnech po splatnosti připomínat. Výchozí [3, 14, 30]. |
entity. | text | ne | Forma vlastnictví pro JMHZ. |
entity. | pole (text) | ne | Kolektivní smlouvy pro JMHZ. |
entity. | objekt | ne | Pracoviště pro JMHZ – municipality, municipality_code, country. |
entity. | objekt | ne | Povinný podíl OZP pro JMHZ – employees, disabled, share. |
entity. | objekt | ne | Osoba podávající přiznání – first_name, last_name, phone, relation. |
entity. | objekt | ne | Zmocněnec nebo daňový poradce, který podání podepisuje: type (F fyzická, P právnická osoba), code (1, 2, 3, 4a, 4b, 4c, 5a, 5b, 6a, 6b, 7a, 7b), u F first_name, last_name a birth_date nebo registration_number, u P name a ico; valid_until = konec plné moci (po něm se do XML neuvádí). Neúplný údaj vrátí 422; všechny hodnoty prázdné zástupce zruší. Saldo ho zapíše do VetaP (zast_*) u DPH, KH, SH, DPFO i DPPO. |
entity. | objekt | ne | Společné údaje OSVČ pro všechny roky: rodné číslo, datum narození, OSSZ, variabilní symbol ČSSZ, zdravotní pojišťovna, rok zahájení podnikání, způsob vrácení přeplatku a výchozí okolnosti (hlavní činnost, manžel(ka), děti, invalidita). Údaje vázané na rok (zálohy, odpočty, měsíce činnosti, příjmy ze zaměstnání…) i údaje firmy k DPPO se ukládají přes PATCH /entities/{entity_id}/taxes/profile?year=; poslané sem (i corporate_profile) skončí chybou 422 TAX_DATA_BY_YEAR. |
entity. | objekt | ne | Odpovědi průvodce založením: segment (osvc, startup, small, growing, accountant), osvc_activity (main, secondary), employees (none, small, many), keeper (self, accountant, is_accountant), příznaky cash, assets, travel, projects, advances, commercial (boolean), foreign (pole z eu, non_eu; jiné hodnoty se zahodí), completed_at. Neznámá hodnota výčtu vrátí 422. |
entity. | objekt | ne | Zapnuté moduly: advances, cash, commercial, internal, payroll, assets, trips, projects, closing, multi_currency, forecast (boolean). Chybějící modul je zapnutý, neznámé klíče se zahodí. |
entity. | objekt | ne | Stav prvních kroků – hidden (boolean) a dismissed (pole klíčů). |
bank | objekt | ne | Volitelný bankovní účet: name, number, bank_code, iban, bic, currency, opening_balance, opening_date. Založí se jen s number nebo iban. |
bank. | text | ne | Název účtu; výchozí „Bankovní účet“ |
bank. | text | ne | Číslo účtu bez kódu banky |
bank. | text | ne | Kód banky (4 číslice) |
bank. | text | ne | IBAN |
bank. | text | ne | BIC |
bank. | text | ne | Měna účtu; výchozí CZK |
bank. | číslo | ne | Počáteční stav |
bank. | datum | ne | Datum počátečního stavu; výchozí začátek účetního roku |
Odpověď
201 application/json Založená firma ve stejném tvaru jako v GET /entities (role owner).
Chyby této operace
| Stav | Kód | Kdy |
|---|---|---|
| 422 | – | Právnická osoba s jiným vedením než double_entry (chyba u bookkeeping: „právnická osoba vede podvojné účetnictví“) |
| 422 | – | Neznámá odpověď průvodce v settings.profile („profil: … musí být jedno z …“) |
| 422 | – | Neznámá hodnota vzhledu faktury („vzhled faktury: … musí být jedno z …“) |
| 422 | – | Kurz ČNB pro počáteční stav bankovního účtu v cizí měně se nepodařilo načíst |
Společné chyby všech operací (přihlášení, oprávnění, limity) popisuje Chyby a limity.
Chování
- Co změní
- Vytvoří firmu, členství vlastníka, účtový rozvrh (u daňové evidence kategorie příjmů a výdajů), pokladnu s analytickým účtem 211xxx a s údaji banky bankovní účet s analytickým účtem 221xxx. U podvojného účetnictví zaúčtuje nenulový počáteční stav bankovního účtu k datu počátečního stavu; u cizí měny přepočte kurzem ČNB (volá ČNB). Do historie změn zapíše událost entity.created.
- Opakování
- Každé volání založí novou firmu.
Příklad
cURL
curl \
-X POST \
-H "X-API-Key: $SALDO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"entity":{"name":"Nová firma s.r.o.","legal_form":"sro","ico":"12345679","dic":"CZ12345679","vat_status":"quarterly","settings":{"invoice_style":"technical","modules":{"payroll":false}}},"bank":{"name":"Provozní účet","number":"2900001227","bank_code":"2010","opening_balance":50000,"opening_date":"2026-01-01"}}' \
https://techtools.cz/ucetnictvi-api/entitiesJavaScript
const response = await fetch('https://techtools.cz/ucetnictvi-api/entities', {
headers: { 'X-API-Key': process.env.SALDO_API_KEY, 'Content-Type': 'application/json' },
method: 'POST',
body: JSON.stringify({
"entity": {
"name": "Nová firma s.r.o.",
"legal_form": "sro",
"ico": "12345679",
"dic": "CZ12345679",
"vat_status": "quarterly",
"settings": {
"invoice_style": "technical",
"modules": {
"payroll": false
}
}
},
"bank": {
"name": "Provozní účet",
"number": "2900001227",
"bank_code": "2010",
"opening_balance": 50000,
"opening_date": "2026-01-01"
}
})
});
const data = await response.json();{
"id": 4,
"accent_color": null,
"archived": false,
"bookkeeping": "double_entry",
"city": null,
"company_id": null,
"country": "CZ",
"created_at": "2026-09-28T10:00:00.000Z",
"currency": "CZK",
"databox": null,
"default_due_days": 14,
"dic": "CZ12345679",
"email": null,
"first_name": null,
"fiscal_year_start": 1,
"flat_expense_rate": null,
"house_number": null,
"ico": "12345679",
"invoice_footer": null,
"last_name": null,
"legal_form": "sro",
"locked_until": null,
"nace": null,
"name": "Nová firma s.r.o.",
"orientation_number": null,
"owner_id": 1,
"phone": null,
"register_note": null,
"responsible_id": null,
"street": null,
"tax_office_code": null,
"tax_office_workplace": null,
"title": null,
"updated_at": "2026-09-28T10:00:00.000Z",
"vat_registered_on": null,
"vat_status": "quarterly",
"web": null,
"zip": null,
"settings": {
"round_total": "cash",
"invoice_language": "cs",
"number_format": "{prefix}{yyyy}{nnnn}",
"reminder_days": [
3,
14
],
"show_qr": true,
"invoice_style": "technical",
"invoice_font": "auto",
"invoice_density": "normal",
"invoice_table": "auto",
"invoice_corners": "auto",
"invoice_logo_size": "m",
"invoice_logo_name": false,
"invoice_row_numbers": false,
"invoice_paid_stamp": true,
"invoice_contacts": true,
"invoice_credit": true,
"modules": {
"payroll": false
}
},
"has_logo": false,
"legal_form_label": "s.r.o.",
"bookkeeping_label": "Podvojné účetnictví",
"vat_status_label": "Plátce DPH – čtvrtletně",
"vat_payer": true,
"double_entry": true,
"role": "owner",
"can_write": true,
"can_manage": true,
"payroll_access": true,
"member_user_id": 1,
"membership_id": 6,
"ownership_offer": null
}
Dlouhé seznamy jsou v ukázce zkrácené na první položky.
POST Založí ukázkovou firmu s daty od začátku roku
/entities/demo
- Oprávnění
- Přihlášený uživatel nebo jeho API klíč, bez vazby na jednu firmu
- Klíč jen pro čtení
- Nestačí, vrátí 403
READ_ONLY_KEY
Založí ukázkovou firmu označenou jako ukázka (settings.demo), ve které si lze Saldo vyzkoušet, s daty od začátku letošního roku do dneška: kontakty, vydané a přijaté doklady včetně dobropisu a zálohové faktury (u plátce DPH i s daňovým dokladem k přijaté platbě), pokladní doklady, bankovní účet s pohyby (většina spárovaná s doklady, několik čeká na spárování), pokladnu, majetek, platby úřadům s bankovními pravidly, opakovanou fakturu, projekty a střediska; u varianty sro také zaměstnance, výplatní pásky a cestovní příkaz. Doklady jsou vystavené a zaúčtované jako skutečné. Varianta sro je měsíční plátce DPH s podvojným účetnictvím, varianta osvc neplátce s daňovou evidencí. První kroky jsou u ukázky skryté.
Parametry
| Název | Kde | Typ | Povinný | Popis |
|---|---|---|---|---|
variant | dotaz | text | ne | Druh ukázkové firmy; jiná hodnota znamená sro. Lze poslat i v těle požadavku. Hodnoty: sro, osvc. Výchozí sro. Příklad osvc. |
Odpověď
201 application/json Založená ukázková firma ve stejném tvaru jako v GET /entities (role owner).
Chyby této operace
| Stav | Kód | Kdy |
|---|---|---|
| 422 | – | Uživatel už vlastní 3 ukázkové firmy („Ukázkové firmy můžete mít nejvýš 3 – nejprve některou smažte“) |
Společné chyby všech operací (přihlášení, oprávnění, limity) popisuje Chyby a limity.
Chování
- Co změní
- Vytvoří firmu se členstvím vlastníka a s daty od začátku roku; vystavené doklady, úhrady a výplatní pásky zaúčtuje. Nic neposílá mimo Saldo.
- Limity
- Nejvýše 3 ukázkové firmy na vlastníka.
- Opakování
- Každé volání založí další ukázkovou firmu až do limitu.
Příklad
Volající smí mít nejvýš dvě ukázkové firmy předem.
cURL
curl \
-X POST \
-H "X-API-Key: $SALDO_API_KEY" \
"https://techtools.cz/ucetnictvi-api/entities/demo?variant=osvc"JavaScript
const response = await fetch('https://techtools.cz/ucetnictvi-api/entities/demo?variant=osvc', {
headers: { 'X-API-Key': process.env.SALDO_API_KEY },
method: 'POST'
});
const data = await response.json();{
"id": 4,
"accent_color": null,
"archived": false,
"bookkeeping": "tax_records",
"city": "Praha",
"company_id": null,
"country": "CZ",
"created_at": "2026-09-28T10:00:00.000Z",
"currency": "CZK",
"databox": null,
"default_due_days": 14,
"dic": "CZ8001010006",
"email": "demo@example.cz",
"first_name": "Jan",
"fiscal_year_start": 1,
"flat_expense_rate": null,
"house_number": "1",
"ico": "99999986",
"invoice_footer": null,
"last_name": "Ukázka",
"legal_form": "osvc",
"locked_until": null,
"nace": "741200",
"name": "Jan Ukázka – grafické studio (ukázka)",
"orientation_number": null,
"owner_id": 1,
"phone": "+420 777 000 000",
"register_note": "Fyzická osoba zapsaná v živnostenském rejstříku.",
"responsible_id": null,
"street": "Vinohradská",
"tax_office_code": "451",
"tax_office_workplace": "2002",
"title": null,
"updated_at": "2026-09-28T10:00:00.000Z",
"vat_registered_on": null,
"vat_status": "none",
"web": null,
"zip": "12000",
"settings": {
"round_total": "always",
"invoice_language": "cs",
"number_format": "{prefix}{yyyy}{nnnn}",
"reminder_days": [
3,
14
],
"show_qr": true,
"invoice_style": "plain",
"invoice_font": "auto",
"invoice_density": "normal",
"invoice_table": "auto",
"invoice_corners": "auto",
"invoice_logo_size": "m",
"invoice_logo_name": false,
"invoice_row_numbers": false,
"invoice_paid_stamp": true,
"invoice_contacts": true,
"invoice_credit": true,
"demo": true,
"statement_category": "mikro",
"submitter": {
"first_name": "Jana",
"last_name": "Ukázková",
"relation": "jednatelka"
},
"tax_profile": {
"children": [
{
"order": 1,
"first_name": "Eliška",
"last_name": "Ukázková",
"birth_number": "1855120003"
}
],
"main_activity": true,
"birth_number": "8001010006",
"ossz_code": "110",
"cssz_variable_symbol": "12345678",
"health_insurer": "111"
}
},
"has_logo": false,
"legal_form_label": "OSVČ",
"bookkeeping_label": "Daňová evidence",
"vat_status_label": "Neplátce DPH",
"vat_payer": false,
"double_entry": false,
"role": "owner",
"can_write": true,
"can_manage": true,
"payroll_access": true,
"member_user_id": 1,
"membership_id": 6,
"ownership_offer": null
}
Dlouhé seznamy jsou v ukázce zkrácené na první položky.
GET Detail firmy s nastavením a logem
/entities/{id}
- Oprávnění
- Každý člen firmy včetně role Jen čtení
- Pravidlo
- Volajícímu s rolí Nahrává doklady vrátí jen id, name, ico, legal_form, legal_form_label, archived, role, submitter: true a příznaky (bez nastavení, údajů pro přiznání, adresy a loga).
- Klíč jen pro čtení
- Stačí
Vrátí jednu firmu ve stejném tvaru jako GET /entities a navíc logo jako data URI v logo_data. Editor, role viewer a každý klíč jen pro čtení dostanou daňový profil i údaje let (tax_years) bez rodných čísel, dat narození a účtu pro vratku.
Parametry
| Název | Kde | Typ | Povinný | Popis |
|---|---|---|---|---|
id | cesta | celé číslo | ano | ID firmy. Příklad 1. |
Odpověď
200 application/json Firma, nastavení s výchozími hodnotami, role volajícího a logo.
| Pole | Význam |
|---|---|
logo_data | Logo jako data:image/…;base64, nebo null |
settings | Nastavení doplněné o výchozí hodnoty |
role | Role volajícího |
payroll_access | Volající vidí mzdy a údaje zaměstnanců |
Chování
- Co změní
- Nic nezapisuje.
Příklad
cURL
curl \
-H "X-API-Key: $SALDO_API_KEY" \
https://techtools.cz/ucetnictvi-api/entities/1JavaScript
const response = await fetch('https://techtools.cz/ucetnictvi-api/entities/1', {
headers: { 'X-API-Key': process.env.SALDO_API_KEY }
});
const data = await response.json();{
"id": 1,
"accent_color": null,
"archived": false,
"bookkeeping": "double_entry",
"city": "Praha",
"company_id": null,
"country": "CZ",
"created_at": "2026-09-28T10:00:00.000Z",
"currency": "CZK",
"databox": null,
"default_due_days": 14,
"dic": "CZ99999994",
"email": "demo@example.cz",
"first_name": null,
"fiscal_year_start": 1,
"flat_expense_rate": null,
"house_number": "859",
"ico": "99999994",
"invoice_footer": null,
"last_name": null,
"legal_form": "sro",
"locked_until": null,
"nace": "621000",
"name": "Ukázková firma s.r.o.",
"orientation_number": "22",
"owner_id": 1,
"phone": "+420 777 000 000",
"register_note": "Zapsáno v obchodním rejstříku vedeném Městským soudem v Praze, oddíl C, vložka 999999 (ukázková data).",
"responsible_id": null,
"street": "Na Příkopě",
"tax_office_code": "451",
"tax_office_workplace": "2001",
"title": null,
"updated_at": "2026-09-28T10:00:00.000Z",
"vat_registered_on": "2023-01-01",
"vat_status": "monthly",
"web": null,
"zip": "11000",
"settings": {
"round_total": "always",
"invoice_language": "cs",
"number_format": "{prefix}{yyyy}{nnnn}",
"reminder_days": [
3,
14
],
"show_qr": true,
"invoice_style": "plain",
"invoice_font": "auto",
"invoice_density": "normal",
"invoice_table": "auto",
"invoice_corners": "auto",
"invoice_logo_size": "m",
"invoice_logo_name": false,
"invoice_row_numbers": false,
"invoice_paid_stamp": true,
"invoice_contacts": true,
"invoice_credit": true,
"demo": true,
"statement_category": "mikro",
"submitter": {
"first_name": "Jana",
"last_name": "Ukázková",
"relation": "jednatelka"
},
"tax_profile": {
"children": [
{
"order": 1,
"first_name": "Eliška",
"last_name": "Ukázková",
"birth_number": "1855120003"
}
],
"main_activity": true,
"birth_number": "8001010006"
},
"ossz_code": "110",
"cssz_variable_symbol": "1234567890",
"jmhz_workplace": {
"municipality": "Praha",
"municipality_code": "554782",
"country": "CZ"
}
},
"has_logo": false,
"legal_form_label": "s.r.o.",
"bookkeeping_label": "Podvojné účetnictví",
"vat_status_label": "Plátce DPH – měsíčně",
"vat_payer": true,
"double_entry": true,
"role": "owner",
"can_write": true,
"can_manage": true,
"payroll_access": true,
"member_user_id": 1,
"membership_id": 1,
"ownership_offer": null,
"logo_data": null
}
Dlouhé seznamy jsou v ukázce zkrácené na první položky.
PATCH Změní údaje a nastavení firmy
/entities/{id}
- Oprávnění
- Vlastník nebo účetní
- Klíč jen pro čtení
- Nestačí, vrátí 403
READ_ONLY_KEY
Změní údaje firmy, nastavení a logo. Pole jsou stejná jako při založení, navíc logo_data; uzamčení období se mění jen přes POST /entities/{id}/lock. Poslané settings se sloučí s dosavadním nastavením jen na nejvyšší úrovni: vnořený objekt (tax_profile, profile, modules, submitter, jmhz_*) se nahradí celý. Údaje k přiznání vázané na rok se ukládají přes PATCH /entities/{entity_id}/taxes/profile?year=. Vzhled faktury se ověřuje jen u změněných hodnot, takže dříve uložená neznámá hodnota uložení nebrání. Pravidlo podvojného účetnictví pro právnické osoby platí i při změně. Dokud je nějaké období uzamčené (locked_until), změna fiscal_year_start, bookkeeping, vat_status, vat_registered_on, flat_expense_rate, legal_form, settings.statement_category nebo settings.vat_coefficient vrátí 409 LOCKED_SETTINGS a uloží se až s confirm_locked=true; registrace k DPH od data po zámku (z vat_status none) projde bez potvrzení. Archivovaná firma (archived true) je jen pro čtení: zápisy v ní vrací 403 ARCHIVED a can_write je false; nastavení přijme jen samotné archived false (obnovení), jakákoli jiná změna vrátí 403 ARCHIVED.
Parametry
| Název | Kde | Typ | Povinný | Popis |
|---|---|---|---|---|
id | cesta | celé číslo | ano | ID firmy. Příklad 1. |
confirm_locked | dotaz | ano/ne | ne | true potvrdí změnu, která by přepočítala uzamčené období (lze poslat i v těle mimo objekt entity). Příklad true. |
Tělo požadavku
Formát application/json.
| Pole | Typ | Povinné | Popis |
|---|---|---|---|
entity | objekt | ano | |
entity. | text | ne | Název Nejvýše 200 znaků. |
entity. | text | ne | Právní forma Hodnoty: osvc, sro, as, vos, ks, druzstvo, spolek, other. |
entity. | text | ne | IČO (normalizuje se na 8 číslic) |
entity. | text | ne | DIČ |
entity. | text | ne | Titul |
entity. | text | ne | Jméno |
entity. | text | ne | Příjmení |
entity. | text | ne | Ulice |
entity. | text | ne | Číslo popisné |
entity. | text | ne | Číslo orientační |
entity. | text | ne | Obec |
entity. | text | ne | PSČ |
entity. | text | ne | Stát |
entity. | text | ne | |
entity. | text | ne | Telefon |
entity. | text | ne | Web |
entity. | text | ne | ID datové schránky |
entity. | text | ne | Zápis v rejstříku |
entity. | text | ne | Způsob vedení; jiný než double_entry jen pro osvc Hodnoty: double_entry, tax_records, flat_expenses, flat_tax. |
entity. | celé číslo | ne | Výdajový paušál; uloží se jen s flat_expenses Hodnoty: 80, 60, 40, 30. |
entity. | text | ne | Vztah k DPH Hodnoty: none, monthly, quarterly, identified. |
entity. | datum | ne | Datum registrace k DPH |
entity. | text | ne | Kód finančního úřadu |
entity. | text | ne | Kód územního pracoviště |
entity. | text | ne | CZ-NACE |
entity. | celé číslo | ne | Měsíc začátku účetního období Rozsah od 1 do 12. |
entity. | text | ne | Účetní měna |
entity. | celé číslo | ne | Výchozí splatnost Rozsah od 0 do 365. |
entity. | text | ne | Patička dokladů |
entity. | text | ne | Barva #RRGGBB |
entity. | ano/ne | ne | Archivovat firmu (jen pro čtení), false ji obnoví |
entity. | text | ne | Logo jako data:image/png, jpeg, webp nebo gif;base64,…; prázdný řetězec logo odstraní. Nejvýše 400000 znaků. |
entity. | objekt | ne | Stejné klíče jako při založení (POST /entities). Sloučí se jen na nejvyšší úrovni a výchozí hodnoty se při tom uloží do záznamu. |
Odpověď
200 application/json Uložená firma jako v GET /entities/{id}, včetně logo_data.
Chyby této operace
| Stav | Kód | Kdy |
|---|---|---|
| 403 | – | Volající není vlastník ani účetní („Nastavení smí měnit jen vlastník nebo účetní“) |
| 403 | ARCHIVED | Firma je archivovaná a požadavek není samotné obnovení (archived false) |
| 422 | – | Právnická osoba s jiným vedením než double_entry |
| 422 | – | Změněné IČO bez platné kontrolní číslice, DIČ jiné než CZ a 8 až 10 číslic, neznámý tax_office_code nebo tax_office_workplace jiného úřadu, neplatný e-mail nebo settings.reminder_days mimo 1–365 |
| 422 | – | Logo není obrázek PNG, JPEG, WebP nebo GIF v data URI nebo je delší než 400 000 znaků |
| 422 | – | Neznámá nová hodnota vzhledu faktury nebo odpovědi průvodce |
| 409 | – | Změna by přepočítala uzamčené období a chybí confirm_locked (code LOCKED_SETTINGS, fields a labels se seznamem polí) |
| 422 | – | settings.corporate_profile nebo údaje vázané na rok v settings.tax_profile (code TAX_DATA_BY_YEAR) |
Společné chyby všech operací (přihlášení, oprávnění, limity) popisuje Chyby a limity.
Chování
- Co změní
- Uloží firmu. Když se něco změnilo, zapíše do historie změn událost entity.updated se souhrnem změněných polí a details.changes (původní a nová hodnota; daňový profil a logo jen jako hidden s názvy změněných polí).
- Opakování
- Stejný požadavek vede ke stejnému stavu; opakování beze změny do historie nic nepřidá.
Příklad
cURL
curl \
-X PATCH \
-H "X-API-Key: $SALDO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"entity":{"accent_color":"#0f766e","settings":{"invoice_style":"technical","invoice_font":"plex","invoice_row_numbers":true}}}' \
https://techtools.cz/ucetnictvi-api/entities/1JavaScript
const response = await fetch('https://techtools.cz/ucetnictvi-api/entities/1', {
headers: { 'X-API-Key': process.env.SALDO_API_KEY, 'Content-Type': 'application/json' },
method: 'PATCH',
body: JSON.stringify({
"entity": {
"accent_color": "#0f766e",
"settings": {
"invoice_style": "technical",
"invoice_font": "plex",
"invoice_row_numbers": true
}
}
})
});
const data = await response.json();{
"accent_color": "#0f766e",
"ico": "99999994",
"dic": "CZ99999994",
"name": "Ukázková firma s.r.o.",
"flat_expense_rate": null,
"owner_id": 1,
"default_due_days": 14,
"vat_status": "monthly",
"tax_office_code": "451",
"tax_office_workplace": "2001",
"email": "demo@example.cz",
"id": 1,
"archived": false,
"bookkeeping": "double_entry",
"city": "Praha",
"company_id": null,
"country": "CZ",
"created_at": "2026-09-28T10:00:00.000Z",
"currency": "CZK",
"databox": null,
"first_name": null,
"fiscal_year_start": 1,
"house_number": "859",
"invoice_footer": null,
"last_name": null,
"legal_form": "sro",
"locked_until": null,
"nace": "621000",
"orientation_number": "22",
"phone": "+420 777 000 000",
"register_note": "Zapsáno v obchodním rejstříku vedeném Městským soudem v Praze, oddíl C, vložka 999999 (ukázková data).",
"responsible_id": null,
"street": "Na Příkopě",
"title": null,
"updated_at": "2026-09-28T10:00:00.000Z",
"vat_registered_on": "2023-01-01",
"web": null,
"zip": "11000",
"settings": {
"round_total": "always",
"invoice_language": "cs",
"number_format": "{prefix}{yyyy}{nnnn}",
"reminder_days": [
3,
14
],
"show_qr": true,
"invoice_style": "technical",
"invoice_font": "plex",
"invoice_density": "normal",
"invoice_table": "auto",
"invoice_corners": "auto",
"invoice_logo_size": "m",
"invoice_logo_name": false,
"invoice_row_numbers": true,
"invoice_paid_stamp": true,
"invoice_contacts": true,
"invoice_credit": true,
"demo": true,
"statement_category": "mikro",
"submitter": {
"first_name": "Jana",
"last_name": "Ukázková",
"relation": "jednatelka"
},
"tax_profile": {
"children": [
{
"order": 1,
"first_name": "Eliška",
"last_name": "Ukázková",
"birth_number": "1855120003"
}
],
"main_activity": true,
"birth_number": "8001010006"
},
"ossz_code": "110",
"cssz_variable_symbol": "1234567890",
"jmhz_workplace": {
"municipality": "Praha",
"municipality_code": "554782",
"country": "CZ"
}
},
"has_logo": false,
"legal_form_label": "s.r.o.",
"bookkeeping_label": "Podvojné účetnictví",
"vat_status_label": "Plátce DPH – měsíčně",
"vat_payer": true,
"double_entry": true,
"role": "owner",
"can_write": true,
"can_manage": true,
"payroll_access": true,
"member_user_id": 1,
"membership_id": 1,
"ownership_offer": null,
"logo_data": null
}
Dlouhé seznamy jsou v ukázce zkrácené na první položky.
DELETE Trvale smaže firmu se všemi daty
/entities/{id}
- Oprávnění
- Jen vlastník firmy
- Klíč jen pro čtení
- Nestačí, vrátí 403
READ_ONLY_KEY
Trvale smaže účetní jednotku a všechna její data včetně doručenek a jiných důkazních souborů k podáním (jsou v úplném archivu). Pro potvrzení je nutné poslat přesný název firmy. Firmu s víc vlastníky smazat nelze. Firmu se záznamy (vystavené doklady, zápisy, úhrady, pohyby, mzdy, podání), jejichž poslední rok skončil před méně než 10 lety, smaže jen tehdy, když někdo v posledních 30 dnech a po poslední změně stáhl úplný archiv (GET /entities/{entity_id}/archive); stav ukazuje deletion v náhledu archivu. Ukázkové a prázdné firmy archiv nepotřebují.
Parametry
| Název | Kde | Typ | Povinný | Popis |
|---|---|---|---|---|
id | cesta | celé číslo | ano | ID firmy. Příklad 2. |
Tělo požadavku
Formát application/json.
| Pole | Typ | Povinné | Popis |
|---|---|---|---|
confirm | text | ano | Přesný název firmy (mezery na začátku a na konci se ignorují). Lze poslat i jako parametr v URL. |
Odpověď
204 Bez obsahu.
Chyby této operace
| Stav | Kód | Kdy |
|---|---|---|
| 403 | – | Volající není vlastník („Smazat účetní jednotku smí jen vlastník“) |
| 422 | – | confirm neodpovídá názvu firmy („Pro potvrzení zadejte přesný název účetní jednotky“) |
| 422 | – | Firma má víc vlastníků (code OTHER_OWNERS) |
| 422 | – | Chybí čerstvý úplný archiv (code ARCHIVE_REQUIRED, keep_until = do kdy záznamy uchovat, archived_at) |
Společné chyby všech operací (přihlášení, oprávnění, limity) popisuje Chyby a limity.
Chování
- Co změní
- Smaže firmu i všechna data: doklady s přílohami, kontakty, bankovní účty a pohyby, archiv výpisů (soubory se mažou na pozadí), účtový rozvrh, číselné řady, účetní zápisy, majetek, zaměstnance, výplatní pásky, cesty, opakované faktury, podání s doručenkami, žádosti o podklady, frontu úkolů, bankovní pravidla, členství a historii změn. Nelze vrátit.
- Opakování
- Druhé volání vrátí 404.
Příklad
Smaže ukázkovou OSVČ; příklad potřebuje firmu, kterou lze smazat.
cURL
curl \
-X DELETE \
-H "X-API-Key: $SALDO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"confirm":"Jan Ukázka – grafické studio (ukázka)"}' \
https://techtools.cz/ucetnictvi-api/entities/2JavaScript
const response = await fetch('https://techtools.cz/ucetnictvi-api/entities/2', {
headers: { 'X-API-Key': process.env.SALDO_API_KEY, 'Content-Type': 'application/json' },
method: 'DELETE',
body: JSON.stringify({
"confirm": "Jan Ukázka – grafické studio (ukázka)"
})
});
const data = await response.json();soubor, 0 bajtů
POST Uzamkne nebo odemkne účetní období
/entities/{id}/lock
- Oprávnění
- Vlastník nebo účetní
- Klíč jen pro čtení
- Nestačí, vrátí 403
READ_ONLY_KEY
Nastaví den, do kterého je období uzamčené (včetně), nebo zámek zruší. V uzamčeném období Saldo odmítne (422) vystavení, změnu a storno dokladů podle jejich data zdanitelného plnění, data pro DPH, data vystavení nebo účetního data, účetní zápisy, úhrady, párování bankovních pohybů, zůstatky a kontrolu výpisů, výplatní pásky, odpisy, kurzové rozdíly, importy a změnu počátečních stavů; koncepty lze dál upravovat. Samotný zámek nic nekontroluje: přijme i datum v budoucnu a nezkoumá, zda v období zbývají koncepty nebo nespárované pohyby.
Parametry
| Název | Kde | Typ | Povinný | Popis |
|---|---|---|---|---|
id | cesta | celé číslo | ano | ID firmy. Příklad 1. |
Tělo požadavku
Formát application/json.
| Pole | Typ | Povinné | Popis |
|---|---|---|---|
locked_until | datum | ne | Poslední uzamčený den jako řetězec YYYY-MM-DD; prázdná hodnota nebo chybějící pole zámek zruší. Neplatné datum (i číslo nebo jiná hodnota než řetězec) vrátí 400. |
Odpověď
200 application/json Firma ve stejném tvaru jako v GET /entities s novým locked_until.
Chyby této operace
| Stav | Kód | Kdy |
|---|---|---|
| 403 | – | Volající není vlastník ani účetní („Období smí uzamknout jen vlastník nebo účetní“) |
| 403 | ARCHIVED | Firma je archivovaná |
Společné chyby všech operací (přihlášení, oprávnění, limity) popisuje Chyby a limity.
Chování
- Co změní
- Uloží locked_until. Do historie změn zapíše událost entity.locked (Uzamčeno období do … nebo Zámek období zrušen) s details.from a details.to.
- Opakování
- Stejné datum vede ke stejnému stavu; každé volání přidá do historie změn nový záznam.
Příklad
cURL
curl \
-X POST \
-H "X-API-Key: $SALDO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"locked_until":"2025-12-31"}' \
https://techtools.cz/ucetnictvi-api/entities/1/lockJavaScript
const response = await fetch('https://techtools.cz/ucetnictvi-api/entities/1/lock', {
headers: { 'X-API-Key': process.env.SALDO_API_KEY, 'Content-Type': 'application/json' },
method: 'POST',
body: JSON.stringify({
"locked_until": "2025-12-31"
})
});
const data = await response.json();{
"locked_until": "2025-12-31",
"ico": "99999994",
"dic": "CZ99999994",
"name": "Ukázková firma s.r.o.",
"flat_expense_rate": null,
"owner_id": 1,
"default_due_days": 14,
"vat_status": "monthly",
"tax_office_code": "451",
"tax_office_workplace": "2001",
"email": "demo@example.cz",
"id": 1,
"accent_color": null,
"archived": false,
"bookkeeping": "double_entry",
"city": "Praha",
"company_id": null,
"country": "CZ",
"created_at": "2026-09-28T10:00:00.000Z",
"currency": "CZK",
"databox": null,
"first_name": null,
"fiscal_year_start": 1,
"house_number": "859",
"invoice_footer": null,
"last_name": null,
"legal_form": "sro",
"nace": "621000",
"orientation_number": "22",
"phone": "+420 777 000 000",
"register_note": "Zapsáno v obchodním rejstříku vedeném Městským soudem v Praze, oddíl C, vložka 999999 (ukázková data).",
"responsible_id": null,
"street": "Na Příkopě",
"title": null,
"updated_at": "2026-09-28T10:00:00.000Z",
"vat_registered_on": "2023-01-01",
"web": null,
"zip": "11000",
"settings": {
"round_total": "always",
"invoice_language": "cs",
"number_format": "{prefix}{yyyy}{nnnn}",
"reminder_days": [
3,
14
],
"show_qr": true,
"invoice_style": "plain",
"invoice_font": "auto",
"invoice_density": "normal",
"invoice_table": "auto",
"invoice_corners": "auto",
"invoice_logo_size": "m",
"invoice_logo_name": false,
"invoice_row_numbers": false,
"invoice_paid_stamp": true,
"invoice_contacts": true,
"invoice_credit": true,
"demo": true,
"statement_category": "mikro",
"submitter": {
"first_name": "Jana",
"last_name": "Ukázková",
"relation": "jednatelka"
},
"tax_profile": {
"children": [
{
"order": 1,
"first_name": "Eliška",
"last_name": "Ukázková",
"birth_number": "1855120003"
}
],
"main_activity": true,
"birth_number": "8001010006"
},
"ossz_code": "110",
"cssz_variable_symbol": "1234567890",
"jmhz_workplace": {
"municipality": "Praha",
"municipality_code": "554782",
"country": "CZ"
}
},
"has_logo": false,
"legal_form_label": "s.r.o.",
"bookkeeping_label": "Podvojné účetnictví",
"vat_status_label": "Plátce DPH – měsíčně",
"vat_payer": true,
"double_entry": true,
"role": "owner",
"can_write": true,
"can_manage": true,
"payroll_access": true,
"member_user_id": 1,
"membership_id": 1,
"ownership_offer": null
}
Dlouhé seznamy jsou v ukázce zkrácené na první položky.
GET První kroky s firmou a jejich splnění
/entities/{id}/getting_started
- Oprávnění
- Každý člen firmy včetně role Jen čtení
- Klíč jen pro čtení
- Stačí
Vrátí seznam prvních kroků podle skutečných dat firmy a odpovědí průvodce: import z jiného programu (ne pro segment startup), banka, první vydaná faktura, přijaté doklady, vzhled faktury (logo), pravidelná faktura, bankovní pravidla, pozvání účetní (jen když průvodce uvádí, že účetnictví vede účetní) a údaje pro přiznání. Krok je splněný podle dat, ne podle kliknutí. U ukázkové firmy je celý seznam skrytý (hidden: true).
Parametry
| Název | Kde | Typ | Povinný | Popis |
|---|---|---|---|---|
id | cesta | celé číslo | ano | ID firmy. Příklad 1. |
Odpověď
200 application/json Kroky a souhrn.
| Pole | Význam |
|---|---|
items[].key | Klíč kroku: import, bank, first_invoice, received, invoice_look, recurring, bank_rules, accountant, tax_data |
items[].done | Krok je splněný |
items[].dismissed | Uživatel krok skryl |
items[].title | Název kroku |
items[].text | Vysvětlení |
items[].href | Adresa obrazovky v aplikaci |
items[].action | Popisek tlačítka |
items[].icon | Ikona Font Awesome |
done | Počet splněných neskrytých kroků |
total | Počet neskrytých kroků |
complete | Všechny neskryté kroky jsou splněné |
hidden | Seznam je skrytý (uživatelem nebo u ukázkové firmy) |
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/getting_startedJavaScript
const response = await fetch('https://techtools.cz/ucetnictvi-api/entities/1/getting_started', {
headers: { 'X-API-Key': process.env.SALDO_API_KEY }
});
const data = await response.json();{
"items": [
{
"key": "import",
"done": true,
"title": "Převeďte data z jiného programu",
"text": "Adresář, doklady a počáteční stavy z POHODY, Money nebo tabulky.",
"href": "#/import",
"action": "Importovat",
"icon": "fa-file-import",
"dismissed": false
},
{
"key": "bank",
"done": true,
"title": "Připojte banku nebo nahrajte výpis",
"text": "Vaše banka posílá pohyby přes API – stačí ji jednou propojit jen pro čtení.",
"href": "#/banka?propojit=1",
"action": "Propojit banku",
"icon": "fa-building-columns",
"dismissed": false
}
],
"done": 7,
"total": 8,
"complete": false,
"hidden": true
}
Dlouhé seznamy jsou v ukázce zkrácené na první položky.
POST Skryje jeden první krok nebo celý seznam
/entities/{id}/getting_started/dismiss
- Oprávnění
- Vlastník, účetní nebo editor
- Klíč jen pro čtení
- Nestačí, vrátí 403
READ_ONLY_KEY
Skryje jeden krok (key), nebo s all: true celý seznam prvních kroků. Stav se ukládá u firmy, platí tedy pro všechny její členy.
Parametry
| Název | Kde | Typ | Povinný | Popis |
|---|---|---|---|---|
id | cesta | celé číslo | ano | ID firmy. Příklad 1. |
Tělo požadavku
Formát application/json.
| Pole | Typ | Povinné | Popis |
|---|---|---|---|
key | text | ne | Krok ke skrytí; musí být v aktuálním seznamu firmy. Hodnoty: import, bank, first_invoice, received, invoice_look, recurring, bank_rules, accountant, tax_data. |
all | ano/ne | ne | Skrýt celý seznam; má přednost před key. Výchozí false. |
Odpověď
200 application/json Seznam prvních kroků po změně, stejně jako GET /entities/{id}/getting_started.
Chyby této operace
| Stav | Kód | Kdy |
|---|---|---|
| 422 | – | Chybí key nebo krok v seznamu firmy není („Neznámý krok … – obnovte stránku a zkuste to znovu“) |
Společné chyby všech operací (přihlášení, oprávnění, limity) popisuje Chyby a limity.
Chování
- Co změní
- Uloží stav seznamu do nastavení firmy (settings.checklist). Do historie změn nezapisuje.
- Opakování
- Opakované skrytí téhož kroku nic dalšího nezmění.
Příklad
cURL
curl \
-X POST \
-H "X-API-Key: $SALDO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"key":"import"}' \
https://techtools.cz/ucetnictvi-api/entities/1/getting_started/dismissJavaScript
const response = await fetch('https://techtools.cz/ucetnictvi-api/entities/1/getting_started/dismiss', {
headers: { 'X-API-Key': process.env.SALDO_API_KEY, 'Content-Type': 'application/json' },
method: 'POST',
body: JSON.stringify({
"key": "import"
})
});
const data = await response.json();{
"items": [
{
"key": "import",
"done": true,
"title": "Převeďte data z jiného programu",
"text": "Adresář, doklady a počáteční stavy z POHODY, Money nebo tabulky.",
"href": "#/import",
"action": "Importovat",
"icon": "fa-file-import",
"dismissed": true
},
{
"key": "bank",
"done": true,
"title": "Připojte banku nebo nahrajte výpis",
"text": "Vaše banka posílá pohyby přes API – stačí ji jednou propojit jen pro čtení.",
"href": "#/banka?propojit=1",
"action": "Propojit banku",
"icon": "fa-building-columns",
"dismissed": false
}
],
"done": 6,
"total": 7,
"complete": false,
"hidden": true
}
Dlouhé seznamy jsou v ukázce zkrácené na první položky.
DELETE Znovu zobrazí všechny první kroky
/entities/{id}/getting_started/dismiss
- Oprávnění
- Vlastník, účetní nebo editor
- Klíč jen pro čtení
- Nestačí, vrátí 403
READ_ONLY_KEY
Zruší skrytí jednotlivých kroků i celého seznamu. U ukázkové firmy zůstane seznam skrytý (hidden: true).
Parametry
| Název | Kde | Typ | Povinný | Popis |
|---|---|---|---|---|
id | cesta | celé číslo | ano | ID firmy. Příklad 1. |
Odpověď
200 application/json Seznam prvních kroků po změně, stejně jako GET /entities/{id}/getting_started.
Chování
- Co změní
- Vynuluje stav seznamu v nastavení firmy (settings.checklist). Do historie změn nezapisuje.
- Opakování
- Opakování nic dalšího nezmění.
Příklad
cURL
curl \
-X DELETE \
-H "X-API-Key: $SALDO_API_KEY" \
https://techtools.cz/ucetnictvi-api/entities/1/getting_started/dismissJavaScript
const response = await fetch('https://techtools.cz/ucetnictvi-api/entities/1/getting_started/dismiss', {
headers: { 'X-API-Key': process.env.SALDO_API_KEY },
method: 'DELETE'
});
const data = await response.json();{
"items": [
{
"key": "import",
"done": true,
"title": "Převeďte data z jiného programu",
"text": "Adresář, doklady a počáteční stavy z POHODY, Money nebo tabulky.",
"href": "#/import",
"action": "Importovat",
"icon": "fa-file-import",
"dismissed": false
},
{
"key": "bank",
"done": true,
"title": "Připojte banku nebo nahrajte výpis",
"text": "Vaše banka posílá pohyby přes API – stačí ji jednou propojit jen pro čtení.",
"href": "#/banka?propojit=1",
"action": "Propojit banku",
"icon": "fa-building-columns",
"dismissed": false
}
],
"done": 7,
"total": 8,
"complete": false,
"hidden": true
}
Dlouhé seznamy jsou v ukázce zkrácené na první položky.
GET Členové firmy a čekající pozvánky
/entities/{entity_id}/members
- Oprávnění
- Každý člen firmy včetně role Jen čtení
- Klíč jen pro čtení
- Stačí
Vrátí všechny členy firmy včetně pozvánek, které pozvaný ještě nepřijal, v pořadí přidání. E-mail se vrací jen u volajícího samotného.
Parametry
| Název | Kde | Typ | Povinný | Popis |
|---|---|---|---|---|
entity_id | cesta | celé číslo | ano | ID firmy. Příklad 1. |
Odpověď
200 application/json Pole členů.
| Pole | Význam |
|---|---|
id | ID členství (pro změnu role a odebrání) |
user_id | ID uživatele; u nepřijaté pozvánky podle e-mailu null |
username | Uživatelské jméno; u nepřijaté pozvánky podle e-mailu null |
display_name | Zobrazované jméno; u nepřijaté pozvánky podle e-mailu null |
email | E-mail, jen u volajícího; jinak null |
invited_as | E-mail, na který šla nepřijatá pozvánka podle e-mailu (jinak null); neprozradí, komu adresa patří |
role | owner, accountant, editor nebo viewer |
role_label | Název role |
payroll_access | Člen vidí mzdy a údaje zaměstnanců; u vlastníka a účetní vždy true |
pending | Pozvánka zatím nebyla přijata |
accepted_at | Čas přijetí |
invited_by | Kdo pozval |
is_self | Jde o volajícího |
ownership_offer | Čekající nabídka vlastnictví (mode transfer nebo co_owner, offered_by, offered_at, keep_role) nebo null |
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/membersJavaScript
const response = await fetch('https://techtools.cz/ucetnictvi-api/entities/1/members', {
headers: { 'X-API-Key': process.env.SALDO_API_KEY }
});
const data = await response.json();[
{
"id": 1,
"user_id": 1,
"username": "ukazka",
"display_name": null,
"email": "ukazka@example.cz",
"role": "owner",
"role_label": "Vlastník",
"payroll_access": true,
"pending": false,
"accepted_at": "2026-09-28T10:00:00.000Z",
"invited_by": null,
"is_self": true,
"ownership_offer": null,
"invited_as": null
},
{
"id": 3,
"user_id": 2,
"username": "ucetni_ukazka",
"display_name": null,
"email": null,
"role": "accountant",
"role_label": "Účetní",
"payroll_access": true,
"pending": false,
"accepted_at": "2026-09-28T10:00:00.000Z",
"invited_by": null,
"is_self": false,
"ownership_offer": null,
"invited_as": null
}
]
POST Pozve uživatele TechTools do firmy
/entities/{entity_id}/members
- Oprávnění
- Vlastník nebo účetní
- Klíč jen pro čtení
- Nestačí, vrátí 403
READ_ONLY_KEY - V příručce
- Nastavení a integrace › Přístup ke mzdám
Pozve existující účet TechTools podle celého uživatelského jména, nebo podle e-mailu (bez ohledu na velikost písmen). E-mail najde účet jen tehdy, když je to jeho schránka @techtools.cz nebo ověřený propojený e-mail; e-mail jen vepsaný v účtu se nepoužije. Pozvánka podle e-mailu odpoví vždy stejně 202 bez ohledu na to, zda adresa patří účtu nebo už je pozvaná, a v seznamu členů ukáže do přijetí jen tu adresu. Vznikne čekající pozvánka: pozvaný získá přístup, až ji přijme přes POST /invitations/{id}/accept. E-mail se pozvanému neposílá. Roli owner nelze přidělit (vlastníkem se člen stane jen předáním, viz offerOwnership) a neznámá role vrátí 422; chybějící role znamená viewer. Z jednoho účtu jde nejvýš 20 pozvání za hodinu, z jedné sítě 60 (počítá se každý pokus); pak 429 RATE_LIMITED s retry_after.
Parametry
| Název | Kde | Typ | Povinný | Popis |
|---|---|---|---|---|
entity_id | cesta | celé číslo | ano | ID firmy. Příklad 1. |
Tělo požadavku
Formát application/json.
| Pole | Typ | Povinné | Popis |
|---|---|---|---|
login | text | ano | Uživatelské jméno, nebo e-mail (hodnota se zavináčem): schránka @techtools.cz nebo ověřený propojený e-mail účtu; mezery okolo se ignorují. |
role | text | ne | Role; submitter = Nahrává doklady (jen vlastní koncepty přijatých dokladů a přidělené žádosti). owner nebo jiná hodnota vrátí 422 INVALID_ROLE, chybějící znamená viewer. Hodnoty: accountant, editor, viewer, submitter. Výchozí viewer. |
payroll_access | ano/ne | ne | Editor nebo viewer uvidí mzdy a údaje zaměstnanců. Bez hodnoty editor ano, viewer ne; vlastník a účetní vidí mzdy vždy a false u role accountant vrátí 422 PAYROLL_ALWAYS. Role submitter mzdy nevidí nikdy (hodnota se ignoruje). |
Odpověď
201 application/json Podle uživatelského jména nové členství ve stejném tvaru jako v GET /entities/{entity_id}/members, s pending: true. Podle e-mailu status 202 a vždy stejné tělo invited_as, role, role_label a pending: true.
Chyby této operace
| Stav | Kód | Kdy |
|---|---|---|
| 404 | – | Na TechTools není účet s tímto uživatelským jménem |
| 422 | – | Uživatel (podle uživatelského jména) už je členem firmy nebo je pozvaný |
| 429 | RATE_LIMITED | Víc než 20 pozvání z účtu nebo 60 ze sítě za hodinu; retry_after v sekundách |
| 422 | – | Role owner nebo neznámá role (code INVALID_ROLE) |
| 422 | PAYROLL_ALWAYS | payroll_access false u role accountant – účetní vidí mzdy vždy |
| 403 | ARCHIVED | Firma je archivovaná |
Společné chyby všech operací (přihlášení, oprávnění, limity) popisuje Chyby a limity.
Chování
- Co změní
- Vytvoří čekající pozvánku (členství bez přijetí). Do historie změn zapíše událost member.invited.
- Opakování
- Druhé pozvání téhož uživatele podle jména vrátí 422, podle e-mailu znovu 202 bez další pozvánky.
Příklad
Potřebuje uživatele TechTools, který ve firmě ještě není.
cURL
curl \
-X POST \
-H "X-API-Key: $SALDO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"login":"kolegyne_ukazka","role":"editor"}' \
https://techtools.cz/ucetnictvi-api/entities/1/membersJavaScript
const response = await fetch('https://techtools.cz/ucetnictvi-api/entities/1/members', {
headers: { 'X-API-Key': process.env.SALDO_API_KEY, 'Content-Type': 'application/json' },
method: 'POST',
body: JSON.stringify({
"login": "kolegyne_ukazka",
"role": "editor"
})
});
const data = await response.json();{
"id": 6,
"user_id": 3,
"username": "kolegyne_ukazka",
"display_name": null,
"email": null,
"role": "editor",
"role_label": "Editor",
"payroll_access": true,
"pending": true,
"accepted_at": null,
"invited_by": "ukazka",
"is_self": false,
"ownership_offer": null,
"invited_as": null
}
PATCH Změní roli člena nebo jeho přístup ke mzdám
/entities/{entity_id}/members/{id}
- Oprávnění
- Vlastník nebo účetní
- Klíč jen pro čtení
- Nestačí, vrátí 403
READ_ONLY_KEY - V příručce
- Nastavení a integrace › Přístup ke mzdám
Změní roli člena nebo čekající pozvánky a u editora a role viewer přístup ke mzdám (payroll_access). Nikoho nelze povýšit na vlastníka (k tomu slouží offerOwnership) a role jiného vlastníka změnit nejde. Vlastník smí změnit vlastní roli jen tehdy, když má firma dalšího přijatého vlastníka; zapsaným vlastníkem firmy se pak stane ten druhý. Neznámá role vrátí 422, chybějící role nechá roli beze změny. Účetní může změnit i vlastní roli, a tím přijít o správu firmy. Přístup ke mzdám zůstane uložený i při změně role a platí, kdykoli je člen editor nebo viewer.
Parametry
| Název | Kde | Typ | Povinný | Popis |
|---|---|---|---|---|
entity_id | cesta | celé číslo | ano | ID firmy. Příklad 1. |
id | cesta | celé číslo | ano | ID členství z GET /entities/{entity_id}/members. Příklad 3. |
Tělo požadavku
Formát application/json.
| Pole | Typ | Povinné | Popis |
|---|---|---|---|
role | text | ne | Nová role; owner nebo jiná hodnota vrátí 422 INVALID_ROLE, bez hodnoty se role nemění. Změna na submitter vypne přístup ke mzdám a zruší čekající nabídku vlastnictví. Hodnoty: accountant, editor, viewer, submitter. Výchozí viewer. |
payroll_access | ano/ne | ne | Editor nebo viewer vidí mzdy a údaje zaměstnanců; bez hodnoty se nemění. false u vlastníka nebo účetní vrátí 422 PAYROLL_ALWAYS. |
Odpověď
200 application/json Členství ve stejném tvaru jako v GET /entities/{entity_id}/members.
Chyby této operace
| Stav | Kód | Kdy |
|---|---|---|
| 422 | – | Členství patří jinému vlastníkovi nebo poslednímu vlastníkovi („Roli vlastníka nelze změnit“) |
| 422 | – | Role owner nebo neznámá role (code INVALID_ROLE) |
| 422 | PAYROLL_ALWAYS | payroll_access false u vlastníka nebo účetní – vidí mzdy vždy |
Společné chyby všech operací (přihlášení, oprávnění, limity) popisuje Chyby a limity.
Chování
- Co změní
- Uloží roli a přístup ke mzdám. Když se něco změnilo, zapíše do historie změn událost member.updated s původní a novou rolí (details.from, details.to) a seznamem změn (details.changes: role a payroll_access s from a to).
- Opakování
- Stejné hodnoty vedou ke stejnému stavu a nic do historie nezapíšou.
Příklad
cURL
curl \
-X PATCH \
-H "X-API-Key: $SALDO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"role":"editor"}' \
https://techtools.cz/ucetnictvi-api/entities/1/members/3JavaScript
const response = await fetch('https://techtools.cz/ucetnictvi-api/entities/1/members/3', {
headers: { 'X-API-Key': process.env.SALDO_API_KEY, 'Content-Type': 'application/json' },
method: 'PATCH',
body: JSON.stringify({
"role": "editor"
})
});
const data = await response.json();{
"id": 3,
"user_id": 2,
"username": "ucetni_ukazka",
"display_name": null,
"email": null,
"role": "editor",
"role_label": "Editor",
"payroll_access": true,
"pending": false,
"accepted_at": "2026-09-28T10:00:00.000Z",
"invited_by": null,
"is_self": false,
"ownership_offer": null,
"invited_as": null
}
DELETE Odebere člena, zruší pozvánku nebo opustí firmu
/entities/{entity_id}/members/{id}
- Oprávnění
- Zvláštní pravidlo
- Pravidlo
- Vlastní členství může zrušit každý člen včetně role viewer. Cizí členství nebo pozvánku jen vlastník nebo účetní; ostatní dostanou 403 „Tuto akci smí provést jen vlastník nebo účetní“.
- Klíč jen pro čtení
- Nestačí, vrátí 403
READ_ONLY_KEY
Smaže členství. Vlastní členství znamená opuštění firmy; cizí členství odebere člena nebo zruší čekající pozvánku. Vlastníka nelze odebrat a poslední vlastník nemůže firmu opustit. Když firmu opustí zapsaný vlastník, zapsaným vlastníkem se stane druhý vlastník.
Parametry
| Název | Kde | Typ | Povinný | Popis |
|---|---|---|---|---|
entity_id | cesta | celé číslo | ano | ID firmy. Příklad 1. |
id | cesta | celé číslo | ano | ID členství z GET /entities/{entity_id}/members. Příklad 3. |
Odpověď
204 Bez obsahu.
Chyby této operace
| Stav | Kód | Kdy |
|---|---|---|
| 403 | – | Cizí členství se pokouší odebrat člen, který není vlastník ani účetní |
| 422 | – | Poslední vlastník chce firmu opustit („Poslední vlastník nemůže firmu opustit“) |
| 422 | – | Odebírané členství patří vlastníkovi („Vlastníka nelze odebrat“) |
Společné chyby všech operací (přihlášení, oprávnění, limity) popisuje Chyby a limity.
Chování
- Co změní
- Smaže členství. Do historie změn zapíše událost member.left (opuštění) nebo member.removed (odebrání člena nebo zrušení pozvánky).
- Opakování
- Druhé volání vrátí 404.
Příklad
cURL
curl \
-X DELETE \
-H "X-API-Key: $SALDO_API_KEY" \
https://techtools.cz/ucetnictvi-api/entities/1/members/3JavaScript
const response = await fetch('https://techtools.cz/ucetnictvi-api/entities/1/members/3', {
headers: { 'X-API-Key': process.env.SALDO_API_KEY },
method: 'DELETE'
});
const data = await response.json();soubor, 0 bajtů
POST Nabídne členovi vlastnictví firmy
/entities/{entity_id}/members/{id}/ownership
- Oprávnění
- Jen vlastník firmy
- Klíč jen pro čtení
- Nestačí, vrátí 403
READ_ONLY_KEY
Vlastník nabídne přijatému členovi předání vlastnictví (mode transfer) nebo spoluvlastnictví (mode co_owner). Nabídka platí, až ji člen sám přijme (acceptOwnership); do té doby ji vlastník může zrušit a člen odmítnout (withdrawOwnership). U předání vlastník opíše přesný název firmy a zvolí roli, se kterou ve firmě zůstane (accountant, editor, viewer, nebo none = firmu opustí). Nová nabídka témuž členovi nahradí předchozí. Člen vidí nabídku v ownership_offer svého členství a firmy (GET /entities/{id}).
Parametry
| Název | Kde | Typ | Povinný | Popis |
|---|---|---|---|---|
entity_id | cesta | celé číslo | ano | ID firmy. Příklad 1. |
id | cesta | celé číslo | ano | ID přijatého členství z GET /entities/{entity_id}/members. Příklad 3. |
Tělo požadavku
Formát application/json.
| Pole | Typ | Povinné | Popis |
|---|---|---|---|
mode | text | ano | transfer = předání vlastnictví, co_owner = druhý vlastník se stejnými právy. Hodnoty: transfer, co_owner. |
keep_role | text | ne | Jen u transfer – role, kterou si dosavadní vlastník po předání ponechá; none = firmu opustí. Hodnoty: accountant, editor, viewer, none. Výchozí accountant. |
confirm | text | ne | Jen u transfer – přesný název firmy. |
Odpověď
200 application/json Členství ve stejném tvaru jako v GET /entities/{entity_id}/members s ownership_offer (mode, mode_label, offered_by, offered_at, keep_role, keep_role_label).
Chyby této operace
| Stav | Kód | Kdy |
|---|---|---|
| 422 | – | Volající není vlastník („Vlastnictví nabízí jen vlastník firmy“) |
| 422 | – | Člen ještě nepřijal pozvánku, už je vlastníkem, neznámý mode nebo keep_role |
| 422 | – | U transfer neodpovídá confirm názvu firmy („Pro potvrzení předání opište přesný název firmy“) |
Společné chyby všech operací (přihlášení, oprávnění, limity) popisuje Chyby a limity.
Chování
- Co změní
- Uloží nabídku k členství. Do historie změn zapíše událost entity.ownership (details.step offered).
- Opakování
- Opakované volání nabídku přepíše a přidá další záznam do historie.
Příklad
cURL
curl \
-X POST \
-H "X-API-Key: $SALDO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"mode":"co_owner"}' \
https://techtools.cz/ucetnictvi-api/entities/1/members/3/ownershipJavaScript
const response = await fetch('https://techtools.cz/ucetnictvi-api/entities/1/members/3/ownership', {
headers: { 'X-API-Key': process.env.SALDO_API_KEY, 'Content-Type': 'application/json' },
method: 'POST',
body: JSON.stringify({
"mode": "co_owner"
})
});
const data = await response.json();{
"id": 3,
"user_id": 2,
"username": "ucetni_ukazka",
"display_name": null,
"email": null,
"role": "accountant",
"role_label": "Účetní",
"payroll_access": true,
"pending": false,
"accepted_at": "2026-09-28T10:00:00.000Z",
"invited_by": null,
"is_self": false,
"ownership_offer": {
"mode": "co_owner",
"mode_label": "Druhý vlastník",
"offered_by": "ukazka",
"offered_at": "2026-09-28T10:00:00.000Z",
"keep_role": null,
"keep_role_label": null
},
"invited_as": null
}
DELETE Odmítne nebo zruší nabídku vlastnictví
/entities/{entity_id}/members/{id}/ownership
- Oprávnění
- Každý člen firmy včetně role Jen čtení
- Pravidlo
- Člen, kterému je nabídka určená, nebo vlastník firmy; jiní dostanou 422.
- Klíč jen pro čtení
- Nestačí, vrátí 403
READ_ONLY_KEY
Člen nabídku vlastnictví odmítne, nebo ji vlastník zruší. Role ani vlastnictví se nemění.
Parametry
| Název | Kde | Typ | Povinný | Popis |
|---|---|---|---|---|
entity_id | cesta | celé číslo | ano | ID firmy. Příklad 1. |
id | cesta | celé číslo | ano | ID členství s nabídkou. Příklad 3. |
Odpověď
200 application/json Členství ve stejném tvaru jako v GET /entities/{entity_id}/members, s ownership_offer null.
Chyby této operace
| Stav | Kód | Kdy |
|---|---|---|
| 422 | – | Členství nemá nabídku („Nabídka vlastnictví neexistuje“) |
| 422 | – | Volající není vlastník ani ten, komu je nabídka určená |
Společné chyby všech operací (přihlášení, oprávnění, limity) popisuje Chyby a limity.
Chování
- Co změní
- Smaže nabídku. Do historie změn zapíše událost entity.ownership (details.step declined nebo withdrawn).
- Opakování
- Druhé volání vrátí 422.
Příklad
Vlastník nabídku nejdřív pošle a pak ji zruší.
cURL
curl \
-X DELETE \
-H "X-API-Key: $SALDO_API_KEY" \
https://techtools.cz/ucetnictvi-api/entities/1/members/3/ownershipJavaScript
const response = await fetch('https://techtools.cz/ucetnictvi-api/entities/1/members/3/ownership', {
headers: { 'X-API-Key': process.env.SALDO_API_KEY },
method: 'DELETE'
});
const data = await response.json();{
"id": 3,
"user_id": 2,
"username": "ucetni_ukazka",
"display_name": null,
"email": null,
"role": "accountant",
"role_label": "Účetní",
"payroll_access": true,
"pending": false,
"accepted_at": "2026-09-28T10:00:00.000Z",
"invited_by": null,
"is_self": false,
"ownership_offer": null,
"invited_as": null
}
POST Přijme nabídnuté vlastnictví firmy
/entities/{entity_id}/members/{id}/ownership/accept
- Oprávnění
- Každý člen firmy včetně role Jen čtení
- Pravidlo
- Jen člen, kterému je nabídka určená (id je jeho vlastní členství); jiní dostanou 422.
- Klíč jen pro čtení
- Nestačí, vrátí 403
READ_ONLY_KEY
Člen, kterému vlastník nabídl vlastnictví, ho přijme. U spoluvlastnictví dostane roli owner a zapsaný vlastník firmy (owner_id) zůstává. U předání dostane roli owner, stane se zapsaným vlastníkem a dosavadní vlastník dostane zvolenou roli, nebo s keep_role none firmu opustí. Když odesílatel mezitím přestal být vlastníkem, nabídka propadne a volání vrátí 422.
Parametry
| Název | Kde | Typ | Povinný | Popis |
|---|---|---|---|---|
entity_id | cesta | celé číslo | ano | ID firmy. Příklad 1. |
id | cesta | celé číslo | ano | ID vlastního členství (membership_id v GET /entities/{id}). Příklad 3. |
Odpověď
200 application/json Firma ve stejném tvaru jako v GET /entities/{id} s novou rolí volajícího.
Chyby této operace
| Stav | Kód | Kdy |
|---|---|---|
| 422 | – | Nabídka neexistuje nebo je určená jinému („Nabídka vlastnictví neexistuje“) |
| 422 | – | Odesílatel už není vlastník („Nabídka už neplatí – kdo ji poslal, už není vlastníkem firmy“) |
Společné chyby všech operací (přihlášení, oprávnění, limity) popisuje Chyby a limity.
Chování
- Co změní
- Změní roli volajícího na owner, u předání i owner_id firmy a roli dosavadního vlastníka (nebo jeho členství smaže). Do historie změn zapíše událost entity.ownership (details.step accepted).
- Opakování
- Druhé volání vrátí 422, nabídka už neexistuje.
Příklad
Vlastník nejdřív nabídne účetní spoluvlastnictví; přijímá ji účetní vlastním klíčem.
cURL
curl \
-X POST \
-H "X-API-Key: $SALDO_API_KEY" \
https://techtools.cz/ucetnictvi-api/entities/1/members/3/ownership/acceptJavaScript
const response = await fetch('https://techtools.cz/ucetnictvi-api/entities/1/members/3/ownership/accept', {
headers: { 'X-API-Key': process.env.SALDO_API_KEY },
method: 'POST'
});
const data = await response.json();{
"id": 1,
"accent_color": null,
"archived": false,
"bookkeeping": "double_entry",
"city": "Praha",
"company_id": null,
"country": "CZ",
"created_at": "2026-09-28T10:00:00.000Z",
"currency": "CZK",
"databox": null,
"default_due_days": 14,
"dic": "CZ99999994",
"email": "demo@example.cz",
"first_name": null,
"fiscal_year_start": 1,
"flat_expense_rate": null,
"house_number": "859",
"ico": "99999994",
"invoice_footer": null,
"last_name": null,
"legal_form": "sro",
"locked_until": null,
"nace": "621000",
"name": "Ukázková firma s.r.o.",
"orientation_number": "22",
"owner_id": 1,
"phone": "+420 777 000 000",
"register_note": "Zapsáno v obchodním rejstříku vedeném Městským soudem v Praze, oddíl C, vložka 999999 (ukázková data).",
"responsible_id": null,
"street": "Na Příkopě",
"tax_office_code": "451",
"tax_office_workplace": "2001",
"title": null,
"updated_at": "2026-09-28T10:00:00.000Z",
"vat_registered_on": "2023-01-01",
"vat_status": "monthly",
"web": null,
"zip": "11000",
"settings": {
"round_total": "always",
"invoice_language": "cs",
"number_format": "{prefix}{yyyy}{nnnn}",
"reminder_days": [
3,
14
],
"show_qr": true,
"invoice_style": "plain",
"invoice_font": "auto",
"invoice_density": "normal",
"invoice_table": "auto",
"invoice_corners": "auto",
"invoice_logo_size": "m",
"invoice_logo_name": false,
"invoice_row_numbers": false,
"invoice_paid_stamp": true,
"invoice_contacts": true,
"invoice_credit": true,
"demo": true,
"statement_category": "mikro",
"submitter": {
"first_name": "Jana",
"last_name": "Ukázková",
"relation": "jednatelka"
},
"tax_profile": {
"children": [
{
"order": 1,
"first_name": "Eliška",
"last_name": "Ukázková",
"birth_number": "1855120003"
}
],
"main_activity": true,
"birth_number": "8001010006"
},
"ossz_code": "110",
"cssz_variable_symbol": "1234567890",
"jmhz_workplace": {
"municipality": "Praha",
"municipality_code": "554782",
"country": "CZ"
}
},
"has_logo": false,
"legal_form_label": "s.r.o.",
"bookkeeping_label": "Podvojné účetnictví",
"vat_status_label": "Plátce DPH – měsíčně",
"vat_payer": true,
"double_entry": true,
"role": "owner",
"can_write": true,
"can_manage": true,
"payroll_access": true,
"member_user_id": 2,
"membership_id": 3,
"ownership_offer": null
}
Dlouhé seznamy jsou v ukázce zkrácené na první položky.
PATCH Určí, kdo za firmu odpovídá
/entities/{entity_id}/responsible
- Oprávnění
- Vlastník nebo účetní
- Klíč jen pro čtení
- Nestačí, vrátí 403
READ_ONLY_KEY
Určí jednoho přijatého člena firmy s právem zápisu (vlastník, účetní, editor) jako odpovědnou osobu, nebo ji zruší (user_id null). Odpovědná osoba převezme otevřené kroky fronty, které nikdo nepřidělil ručně, a dostává nové kroky firmy automaticky; ručně přidělené kroky zůstanou. Když člen ztratí právo zápisu nebo z firmy odejde, odpovědnost zanikne.
Parametry
| Název | Kde | Typ | Povinný | Popis |
|---|---|---|---|---|
entity_id | cesta | celé číslo | ano | ID firmy. Příklad 1. |
Tělo požadavku
Formát application/json.
| Pole | Typ | Povinné | Popis |
|---|---|---|---|
user_id | celé číslo | ne | ID uživatele (member user_id z GET /entities/{entity_id}/members); null nebo prázdná hodnota odpovědnost zruší. |
Odpověď
200 application/json Nová odpovědná osoba a počet předaných kroků.
| Pole | Význam |
|---|---|
responsible | { id, name }, nebo null |
moved | Počet otevřených kroků, které přešly na novou osobu (nebo se uvolnily) |
Chyby této operace
| Stav | Kód | Kdy |
|---|---|---|
| 400 | – | user_id je pole či objekt |
| 403 | – | Volající není vlastník ani účetní, nebo je firma archivovaná (code ARCHIVED) |
| 422 | – | Uživatel není přijatým členem firmy s právem zápisu („Za firmu může odpovídat jen její přijatý člen s právem zápisu“) |
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 firmy, předá jí otevřené kroky bez ručního přidělení a do historie změn zapíše událost entity.responsible.
- Opakování
- Stejná osoba nic nepředá (moved 0); každé volání přidá do historie změn nový záznam.
Příklad
cURL
curl \
-X PATCH \
-H "X-API-Key: $SALDO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"user_id":2}' \
https://techtools.cz/ucetnictvi-api/entities/1/responsibleJavaScript
const response = await fetch('https://techtools.cz/ucetnictvi-api/entities/1/responsible', {
headers: { 'X-API-Key': process.env.SALDO_API_KEY, 'Content-Type': 'application/json' },
method: 'PATCH',
body: JSON.stringify({
"user_id": 2
})
});
const data = await response.json();{
"responsible": {
"id": 2,
"name": "ucetni_ukazka"
},
"moved": 53
}
GET Historie změn firmy
/entities/{entity_id}/events
- Oprávnění
- Každý člen firmy včetně role Jen čtení
- Klíč jen pro čtení
- Stačí
Vrátí historii změn firmy (kdo co udělal) od nejnovější, po 100 záznamech na stránku, s celkovým počtem. Podrobnosti (details) se vracejí u podání (filing.*), dokladů (document.*: číslo verze, digest a changes – pole field, label, from, to; u účetních zápisů from = zrušené a to = nové zápisy), změn nastavení (entity.updated: changes; daňový profil a logo jen jako hidden s názvy polí; locked_period, když změna prošla přes uzamčené období), zámku (entity.locked: from, to), exportů a archivů (entity.exported), vlastnictví (entity.ownership), členů (member.*) a úprav a smazání kontaktů, pracovníků, cest, opakovaných faktur a účtů (*.updated, *.deleted: changes). Akce provedená API klíčem nese api_key s jeho názvem a koncovkou. Volající bez přístupu ke mzdám dostane události pracovníků a mezd (employee.*, payroll.*) jen s obecným popisem (např. „Zaúčtována mzda“), bez details a subject_id.
Parametry
| Název | Kde | Typ | Povinný | Popis |
|---|---|---|---|---|
entity_id | cesta | celé číslo | ano | ID firmy. Příklad 1. |
page | dotaz | celé číslo | ne | Stránka po 100 záznamech; hodnota menší než 1 znamená 1. Výchozí 1. Rozsah od 1. Příklad 1. |
Odpověď
200 application/json Stránka historie.
| Pole | Význam |
|---|---|
total | Celkový počet událostí |
page | Vrácená stránka |
rows[].id | ID události |
rows[].action | Druh události, např. entity.updated, member.invited, partner.created |
rows[].subject_type | Typ dotčeného záznamu, např. Entity, Partner, Document |
rows[].subject_id | ID dotčeného záznamu |
rows[].summary | Popis (nejvýše 250 znaků) |
rows[].user | Uživatelské jméno autora |
rows[].created_at | Čas |
rows[].details | Podrobnosti u událostí uvedených v popisu, jinak chybí |
rows[].api_key | { name, hint } API klíče, kterým akce proběhla; u akce v prohlížeči chybí |
Chování
- Co změní
- Nic nezapisuje.
- Limity
- 100 záznamů na stránku.
Příklad
cURL
curl \
-H "X-API-Key: $SALDO_API_KEY" \
"https://techtools.cz/ucetnictvi-api/entities/1/events?page=1"JavaScript
const response = await fetch('https://techtools.cz/ucetnictvi-api/entities/1/events?page=1', {
headers: { 'X-API-Key': process.env.SALDO_API_KEY }
});
const data = await response.json();{
"total": 341,
"page": 1,
"rows": [
{
"id": 537,
"action": "vat_registration.created",
"subject_type": "VatRegistration",
"subject_id": 2,
"summary": "Registrace k DPH od 1. 1. 2027: Plátce DPH – čtvrtletně",
"created_at": "2026-09-28T10:00:00.000Z",
"user": "ukazka",
"api_key": {
"name": "Dokumentace API",
"hint": "…2Udf"
}
},
{
"id": 536,
"action": "vat_adjustment.created",
"subject_type": "VatAdjustment",
"subject_id": 1,
"summary": "Ruční úprava přiznání k DPH 2026-07: ř. 60 · Hodnota -800 Kč",
"created_at": "2026-09-28T10:00:00.000Z",
"user": "ukazka",
"api_key": {
"name": "Dokumentace API",
"hint": "…2Udf"
}
}
]
}
Dlouhé seznamy jsou v ukázce zkrácené na první položky.