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.

24 operací · vygenerováno z OpenAPI · ukázky zaznamenané na smyšlené firmě

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ý

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();

Odpověď 200 OK

{
  "keys": [
    {
      "id": 1,
      "name": "Dokumentace API",
      "hint": "…Xejd",
      "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
    },
    {
      "id": 3,
      "name": "Starý skript",
      "hint": "…Whpi",
      "read_only": true,
      "created_at": "2026-09-28T10:00:00.000Z",
      "last_used_at": null,
      "revoked_at": null,
      "active": true
    }
  ]
}

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. Klíč jen pro čtení odmítne každý požadavek kromě GET a HEAD. Token se posílá v hlavičce X-API-Key nebo jako Authorization: Bearer.

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

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íčů“)
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();

Odpověď 201 Created

{
  "id": 4,
  "name": "Účetní agent",
  "hint": "…zRas",
  "read_only": true,
  "created_at": "2026-09-28T10:00:00.000Z",
  "last_used_at": null,
  "revoked_at": null,
  "active": true,
  "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 přepíše čas zrušení na čas posledního volání.

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();

Odpověď 200 OK

{
  "id": 3,
  "name": "Starý skript",
  "hint": "…Whpi",
  "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
}

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/invitations

JavaScript

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

Odpověď 200 OK

[
  {
    "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/accept

JavaScript

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();

Odpověď 200 OK

{
  "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,
  "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,
  "member_user_id": 1
}

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/5

JavaScript

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();

Odpověď 204 No Content

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/banks

JavaScript

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();

Odpověď 200 OK

[
  {
    "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_formats

JavaScript

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();

Odpověď 200 OK

{
  "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 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)
`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/99999994

JavaScript

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();

Odpověď 200 OK

{
  "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": []
  },
  "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
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.

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
`can_manage`	Volající je vlastník nebo účetní
`member_user_id`	ID uživatele volajícího

Chování

Co změní: Nic nezapisuje.

Příklad

cURL

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

JavaScript

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

Odpověď 200 OK

[
  {
    "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.",
    "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,
    "member_user_id": 1
  },
  {
    "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).",
    "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,
    "member_user_id": 1
  }
]

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.name`	text	ano	Název firmy nebo jméno OSVČ; řídicí znaky se nahradí mezerou. Nejvýše 200 znaků.
`entity.legal_form`	text	ne	Právní forma. Hodnoty: `osvc`, `sro`, `as`, `vos`, `ks`, `druzstvo`, `spolek`, `other`. Výchozí `sro`.
`entity.ico`	text	ne	IČO; nečíselné znaky se odstraní a kratší číslo doplní nulami na 8 číslic. Kontrolní číslice se neověřuje.
`entity.dic`	text	ne	DIČ; převede se na velká písmena bez mezer a k 8–10 číslicím se doplní CZ.
`entity.title`	text	ne	Titul (OSVČ).
`entity.first_name`	text	ne	Jméno (OSVČ).
`entity.last_name`	text	ne	Příjmení (OSVČ).
`entity.street`	text	ne	Ulice.
`entity.house_number`	text	ne	Číslo popisné.
`entity.orientation_number`	text	ne	Číslo orientační.
`entity.city`	text	ne	Obec.
`entity.zip`	text	ne	PSČ.
`entity.country`	text	ne	Stát. Výchozí `CZ`.
`entity.email`	text	ne	E-mail na dokladech.
`entity.phone`	text	ne	Telefon.
`entity.web`	text	ne	Web.
`entity.databox`	text	ne	ID datové schránky.
`entity.register_note`	text	ne	Zápis v rejstříku, tiskne se na doklady.
`entity.bookkeeping`	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.flat_expense_rate`	celé číslo	ne	Výdajový paušál v procentech; uloží se jen s bookkeeping flat_expenses. Hodnoty: `80`, `60`, `40`, `30`.
`entity.vat_status`	text	ne	Vztah k DPH. Hodnoty: `none`, `monthly`, `quarterly`, `identified`. Výchozí `none`.
`entity.vat_registered_on`	datum	ne	Datum registrace k DPH.
`entity.tax_office_code`	text	ne	Kód finančního úřadu (číselník tax_offices z GET /codebooks).
`entity.tax_office_workplace`	text	ne	Kód územního pracoviště.
`entity.nace`	text	ne	Převažující činnost CZ-NACE (pro přiznání).
`entity.fiscal_year_start`	celé číslo	ne	Měsíc začátku účetního období. Výchozí `1`. Rozsah od 1 do 12.
`entity.currency`	text	ne	Účetní měna, tři velká písmena. Výchozí `CZK`.
`entity.default_due_days`	celé číslo	ne	Výchozí splatnost vydaných faktur ve dnech. Výchozí `14`. Rozsah od 0 do 365.
`entity.invoice_footer`	text	ne	Patička dokladů.
`entity.accent_color`	text	ne	Barva dokladů ve tvaru #RRGGBB.
`entity.archived`	ano/ne	ne	Firma je archivovaná (v seznamech až na konci). Výchozí `false`.
`entity.settings`	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.settings.round_total`	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.settings.invoice_language`	text	ne	Jazyk nových dokladů; doklady přijmou jen cs nebo en. Výchozí `cs`.
`entity.settings.number_format`	text	ne	Maska čísla dokladu se značkami {prefix}, {yyyy}, {yy}, {mm} a {n…} (počet n = počet číslic pořadí). Výchozí `{prefix}{yyyy}{nnnn}`.
`entity.settings.show_qr`	ano/ne	ne	Tisknout QR Platbu. Výchozí `true`.
`entity.settings.invoice_style`	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.settings.invoice_font`	text	ne	Písmo faktury (auto = podle vzhledu). Hodnoty: `auto`, `inter`, `plex`, `manrope`, `dm`, `franklin`, `serif`, `lora`. Výchozí `auto`.
`entity.settings.invoice_density`	text	ne	Hustota faktury. Hodnoty: `normal`, `compact`, `airy`. Výchozí `normal`.
`entity.settings.invoice_table`	text	ne	Styl tabulky položek. Hodnoty: `auto`, `lines`, `zebra`, `grid`, `minimal`, `headfill`, `headline`. Výchozí `auto`.
`entity.settings.invoice_corners`	text	ne	Rohy prvků faktury. Hodnoty: `auto`, `sharp`, `round`. Výchozí `auto`.
`entity.settings.invoice_logo_size`	text	ne	Velikost loga. Hodnoty: `s`, `m`, `l`. Výchozí `m`.
`entity.settings.invoice_logo_name`	ano/ne	ne	Tisknout název firmy vedle loga. Výchozí `false`.
`entity.settings.invoice_row_numbers`	ano/ne	ne	Číslovat řádky. Výchozí `false`.
`entity.settings.invoice_paid_stamp`	ano/ne	ne	Razítko Zaplaceno na uhrazených dokladech. Výchozí `true`.
`entity.settings.invoice_contacts`	ano/ne	ne	Tisknout kontakty firmy. Výchozí `true`.
`entity.settings.invoice_credit`	ano/ne	ne	Tisknout odkaz na Saldo. Výchozí `true`.
`entity.settings.statement_category`	text	ne	Kategorie účetní jednotky pro výkazy (mikro, mala, stredni, velka); výchozí mikro.
`entity.settings.signature`	text	ne	Podpis na dokladech.
`entity.settings.vat_coefficient`	číslo	ne	Koeficient krácení nároku na odpočet DPH.
`entity.settings.tax_advisor`	ano/ne	ne	Přiznání podává daňový poradce.
`entity.settings.audit`	ano/ne	ne	Povinný audit.
`entity.settings.real_estate`	ano/ne	ne	Platí daň z nemovitých věcí (kalendář lhůt).
`entity.settings.road_tax`	ano/ne	ne	Platí silniční daň (kalendář lhůt).
`entity.settings.income_kind`	text	ne	Druh příjmů OSVČ pro výdajový paušál (crafts, trade, other, rental).
`entity.settings.cssz_variable_symbol`	text	ne	Variabilní symbol plateb ČSSZ.
`entity.settings.ossz_code`	text	ne	Kód okresní správy sociálního zabezpečení.
`entity.settings.flat_tax_band`	celé číslo	ne	Pásmo paušální daně.
`entity.settings.reminder_days`	pole (celé číslo)	ne	Po kolika dnech po splatnosti připomínat. Výchozí `[3, 14, 30]`.
`entity.settings.jmhz_ownership_form`	text	ne	Forma vlastnictví pro JMHZ.
`entity.settings.jmhz_collective_agreements`	pole (text)	ne	Kolektivní smlouvy pro JMHZ.
`entity.settings.jmhz_workplace`	objekt	ne	Pracoviště pro JMHZ – municipality, municipality_code, country.
`entity.settings.jmhz_disabled_quota`	objekt	ne	Povinný podíl OZP pro JMHZ – employees, disabled, share.
`entity.settings.submitter`	objekt	ne	Osoba podávající přiznání – first_name, last_name, phone, relation.
`entity.settings.corporate_profile`	objekt	ne	Údaje pro daň právnické osoby – loss_carryforward, gifts, paid_advances, last_known_tax.
`entity.settings.tax_profile`	objekt	ne	Daňový profil OSVČ (měsíce činnosti, hlavní činnost, manžel(ka), děti, invalidita, rodné číslo, OSSZ, zdravotní pojišťovna, odpočty, zálohy, způsob vrácení přeplatku a další údaje pro přiznání a přehledy).
`entity.settings.profile`	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.settings.modules`	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.settings.checklist`	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.name`	text	ne	Název účtu; výchozí „Bankovní účet“
`bank.number`	text	ne	Číslo účtu bez kódu banky
`bank.bank_code`	text	ne	Kód banky (4 číslice)
`bank.iban`	text	ne	IBAN
`bank.bic`	text	ne	BIC
`bank.currency`	text	ne	Měna účtu; výchozí CZK
`bank.opening_balance`	číslo	ne	Počáteční stav
`bank.opening_date`	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/entities

JavaScript

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();

Odpověď 201 Created

{
  "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,
  "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,
  "member_user_id": 1
}

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();

Odpověď 201 Created

{
  "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.",
  "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,
  "member_user_id": 1
}

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

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

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

JavaScript

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();

Odpověď 200 OK

{
  "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).",
  "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,
  "member_user_id": 1,
  "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
V příručce: Daně a pojistné › Doplnit chybějící údaje pro platby; Daně a pojistné › Vyplnit údaje pro daňové přiznání

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, corporate_profile, jmhz_*) se nahradí celý. 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ě.

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
`entity`	objekt	ano
`entity.name`	text	ne	Název Nejvýše 200 znaků.
`entity.legal_form`	text	ne	Právní forma Hodnoty: `osvc`, `sro`, `as`, `vos`, `ks`, `druzstvo`, `spolek`, `other`.
`entity.ico`	text	ne	IČO (normalizuje se na 8 číslic)
`entity.dic`	text	ne	DIČ
`entity.title`	text	ne	Titul
`entity.first_name`	text	ne	Jméno
`entity.last_name`	text	ne	Příjmení
`entity.street`	text	ne	Ulice
`entity.house_number`	text	ne	Číslo popisné
`entity.orientation_number`	text	ne	Číslo orientační
`entity.city`	text	ne	Obec
`entity.zip`	text	ne	PSČ
`entity.country`	text	ne	Stát
`entity.email`	text	ne	E-mail
`entity.phone`	text	ne	Telefon
`entity.web`	text	ne	Web
`entity.databox`	text	ne	ID datové schránky
`entity.register_note`	text	ne	Zápis v rejstříku
`entity.bookkeeping`	text	ne	Způsob vedení; jiný než double_entry jen pro osvc Hodnoty: `double_entry`, `tax_records`, `flat_expenses`, `flat_tax`.
`entity.flat_expense_rate`	celé číslo	ne	Výdajový paušál; uloží se jen s flat_expenses Hodnoty: `80`, `60`, `40`, `30`.
`entity.vat_status`	text	ne	Vztah k DPH Hodnoty: `none`, `monthly`, `quarterly`, `identified`.
`entity.vat_registered_on`	datum	ne	Datum registrace k DPH
`entity.tax_office_code`	text	ne	Kód finančního úřadu
`entity.tax_office_workplace`	text	ne	Kód územního pracoviště
`entity.nace`	text	ne	CZ-NACE
`entity.fiscal_year_start`	celé číslo	ne	Měsíc začátku účetního období Rozsah od 1 do 12.
`entity.currency`	text	ne	Účetní měna
`entity.default_due_days`	celé číslo	ne	Výchozí splatnost Rozsah od 0 do 365.
`entity.invoice_footer`	text	ne	Patička dokladů
`entity.accent_color`	text	ne	Barva #RRGGBB
`entity.archived`	ano/ne	ne	Archivovat firmu
`entity.logo_data`	text	ne	Logo jako data:image/png, jpeg, webp nebo gif;base64,…; prázdný řetězec logo odstraní. Nejvýše 400000 znaků.
`entity.settings`	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í“)
422	–	Právnická osoba s jiným vedením než double_entry
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

Společné chyby všech operací (přihlášení, oprávnění, limity) popisuje Chyby a limity.

Chování

Co změní: Uloží firmu. Do historie změn zapíše událost entity.updated, i když se nic nezměnilo.
Opakování: Stejný požadavek vede ke stejnému stavu; 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 '{"entity":{"accent_color":"#0f766e","settings":{"invoice_style":"technical","invoice_font":"plex","invoice_row_numbers":true}}}' \
  https://techtools.cz/ucetnictvi-api/entities/1

JavaScript

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();

Odpověď 200 OK

{
  "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,
  "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,
  "email": "demo@example.cz",
  "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).",
  "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": "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,
  "member_user_id": 1,
  "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. Pro potvrzení je nutné poslat přesný název firmy. Firmu, u jejíchž podání jsou uložené doručenky nebo jiné důkazní soubory, touto cestou smazat nelze. Na tom, zda jde o ukázkovou firmu, nezáleží.

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á důkazní soubory k podáním (doručenky); smazat ji tímto postupem nelze

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í, žá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/2

JavaScript

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();

Odpověď 204 No Content

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
V příručce: Měsíční a roční kontrola › Uzamknout období; Měsíční a roční kontrola › Odemknout období nebo posunout zámek

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 vrátí 400, číslo nebo jiná hodnota než řetězec skončí chybou 500.

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í“)

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).
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/lock

JavaScript

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();

Odpověď 200 OK

{
  "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,
  "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,
  "email": "demo@example.cz",
  "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).",
  "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,
  "member_user_id": 1
}

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_started

JavaScript

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();

Odpověď 200 OK

{
  "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": "Fio posílá pohyby samo – stačí vložit token jen pro čtení.",
      "href": "#/banka",
      "action": "Připojit Fio",
      "icon": "fa-building-columns",
      "dismissed": false
    }
  ],
  "done": 6,
  "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/dismiss

JavaScript

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();

Odpověď 200 OK

{
  "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": "Fio posílá pohyby samo – stačí vložit token jen pro čtení.",
      "href": "#/banka",
      "action": "Připojit Fio",
      "icon": "fa-building-columns",
      "dismissed": false
    }
  ],
  "done": 5,
  "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/dismiss

JavaScript

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();

Odpověď 200 OK

{
  "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": "Fio posílá pohyby samo – stačí vložit token jen pro čtení.",
      "href": "#/banka",
      "action": "Připojit Fio",
      "icon": "fa-building-columns",
      "dismissed": false
    }
  ],
  "done": 6,
  "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
`username`	Uživatelské jméno
`display_name`	Zobrazované jméno
`email`	E-mail, jen u volajícího; jinak null
`role`	owner, accountant, editor nebo viewer
`role_label`	Název role
`pending`	Pozvánka zatím nebyla přijata
`accepted_at`	Čas přijetí
`invited_by`	Kdo pozval
`is_self`	Jde o volajícího

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/members

JavaScript

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();

Odpověď 200 OK

[
  {
    "id": 1,
    "user_id": 1,
    "username": "ukazka",
    "display_name": null,
    "email": "ukazka@example.cz",
    "role": "owner",
    "role_label": "Vlastník",
    "pending": false,
    "accepted_at": "2026-09-28T10:00:00.000Z",
    "invited_by": null,
    "is_self": true
  },
  {
    "id": 3,
    "user_id": 2,
    "username": "ucetni_ukazka",
    "display_name": null,
    "email": null,
    "role": "accountant",
    "role_label": "Účetní",
    "pending": false,
    "accepted_at": "2026-09-28T10:00:00.000Z",
    "invited_by": null,
    "is_self": false
  }
]

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

Pozve existující účet TechTools podle uživatelského jména nebo e-mailu účtu (bez ohledu na velikost písmen, jen celá hodnota). 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; neznámá nebo chybějící role znamená viewer. Odpověď nikdy neobsahuje e-mail pozvaného.

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 účtu (hodnota se zavináčem); mezery okolo se ignorují.
`role`	text	ne	Role; jiná hodnota včetně owner znamená viewer. Hodnoty: `accountant`, `editor`, `viewer`. Výchozí `viewer`.

Odpověď

201 application/json Nové členství ve stejném tvaru jako v GET /entities/{entity_id}/members, s pending: true.

Chyby této operace

Stav	Kód	Kdy
404	–	Na TechTools není účet s tímto uživatelským jménem ani e-mailem
422	–	Uživatel už je členem firmy nebo je pozvaný

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 vrátí 422.

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/members

JavaScript

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();

Odpověď 201 Created

{
  "id": 6,
  "user_id": 3,
  "username": "kolegyne_ukazka",
  "display_name": null,
  "email": null,
  "role": "editor",
  "role_label": "Editor",
  "pending": true,
  "accepted_at": null,
  "invited_by": "ukazka",
  "is_self": false
}

PATCH Změní roli člena nebo pozvánky

/entities/{entity_id}/members/{id}

Oprávnění: Vlastník nebo účetní
Klíč jen pro čtení: Nestačí, vrátí 403 READ_ONLY_KEY

Změní roli člena nebo čekající pozvánky. Roli vlastníka změnit nelze a nikoho nelze povýšit na vlastníka. Neznámá nebo chybějící role znamená viewer. Účetní může změnit i vlastní roli, a tím přijít o správu firmy; vlastník svou roli změnit nemůže (jeho členství má roli owner).

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; jiná hodnota znamená viewer. Hodnoty: `accountant`, `editor`, `viewer`. Výchozí `viewer`.

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ří vlastníkovi („Roli vlastníka nelze změnit“)

Společné chyby všech operací (přihlášení, oprávnění, limity) popisuje Chyby a limity.

Chování

Co změní: Uloží roli. Do historie změn zapíše událost member.updated.
Opakování: Stejná role vede ke stejnému stavu; 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 '{"role":"editor"}' \
  https://techtools.cz/ucetnictvi-api/entities/1/members/3

JavaScript

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();

Odpověď 200 OK

{
  "id": 3,
  "user_id": 2,
  "username": "ucetni_ukazka",
  "display_name": null,
  "email": null,
  "role": "editor",
  "role_label": "Editor",
  "pending": false,
  "accepted_at": "2026-09-28T10:00:00.000Z",
  "invited_by": null,
  "is_self": false
}

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.

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/3

JavaScript

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();

Odpověď 204 No Content

soubor, 0 bajtů

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í jen u událostí podání (action začínající filing.).

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, jen u událostí filing.*

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();

Odpověď 200 OK

{
  "total": 333,
  "page": 1,
  "rows": [
    {
      "id": 572,
      "action": "filing.evidence_attached",
      "subject_type": "Filing",
      "subject_id": 1,
      "summary": "DPH 2026-08: přiložen potvrzeni-podani.pdf",
      "created_at": "2026-09-28T10:00:00.000Z",
      "user": "ukazka"
    },
    {
      "id": 571,
      "action": "filing.created",
      "subject_type": "Filing",
      "subject_id": 2,
      "summary": "Připraveno KH za 2026-08",
      "created_at": "2026-09-28T10:00:00.000Z",
      "user": "ukazka"
    }
  ]
}

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