SaldoDokumentace
Otevřít Saldo

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.

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

PoleVýznam
keys[].idID klíče
keys[].nameNázev klíče
keys[].hintKonec tokenu ve tvaru …abcd
keys[].read_onlyKlíč smí jen číst (GET a HEAD)
keys[].created_atVytvoření
keys[].last_used_atPoslední použití (s přesností na 5 minut) nebo null
keys[].revoked_atČas zrušení nebo null
keys[].activeKlíč není zrušený
keys[].entity_idFirma, na kterou je klíč omezený, nebo null (všechny firmy)
keys[].entity_nameNázev té firmy nebo null

Chyby této operace

StavKódKdy
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": "…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.

PoleTypPovinnéPopis
nametextneNázev klíče; prázdný nebo chybějící název se uloží jako „API klíč“. Nejvýše 80 znaků.
read_onlyano/neneKlíč smí jen číst. Výchozí false.
entity_idcelé čísloneOmezí 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.

PoleVýznam
tokenCelý token klíče; vrací se jen v této odpovědi
idID klíče
hintPoslední čtyři znaky tokenu ve tvaru …abcd
read_onlyKlíč smí jen číst
activetrue

Chyby této operace

StavKódKdy
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();
Odpověď 201 Created
{
  "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ázevKdeTypPovinnýPopis
idcestacelé čísloanoID 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

StavKódKdy
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();
Odpověď 200 OK
{
  "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.

PoleVýznam
idID pozvánky (členství) pro přijetí nebo odmítnutí
entity_idID firmy
entity_nameNázev firmy
legal_formPrávní forma
legal_form_labelNázev právní formy
roleNabízená role: accountant, editor nebo viewer
role_labelNázev role
invited_byUž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ázevKdeTypPovinnýPopis
idcestacelé čísloanoID 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,
  "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ázevKdeTypPovinnýPopis
idcestacelé čísloanoID 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.

PoleVýznam
codeČtyřmístný kód banky
nameNázev banky
bicBIC (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.

PoleVýznam
exportsNá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 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čí

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 }

PoleVýznam
banks[].statusNejlepší 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_providers

JavaScript

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();
Odpověď 200 OK
{
  "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ázevKdeTypPovinnýPopis
icocestatextanoIČ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 }.

PoleVýznam
foundSubjekt byl nalezen
looked_up_atČas dotazu (odpověď může být z mezipaměti)
companyNá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
suggestionNá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
sourcesKteré zdroje odpověděly: ares, res, vat_registry
warningsUpozornění (zaniklý subjekt, nedostupný zdroj)

Chyby této operace

StavKódKdy
422INVALID_ICOIČO nemá platnou kontrolní číslici
502ARES_UNAVAILABLEARES neodpovídá nebo vrátil chybu
429RATE_LIMITEDVí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": [],
    "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.

PoleVýznam
idID firmy (entity_id v dalších cestách)
nameNázev
legal_formPrávní forma a legal_form_label
bookkeepingZpůsob vedení a bookkeeping_label
vat_statusVztah k DPH a vat_status_label
locked_untilObdobí uzamčené do tohoto dne včetně, nebo null
settingsNastavení doplněné o výchozí hodnoty
has_logoFirma má logo
vat_payerPlátce DPH (měsíční nebo čtvrtletní)
double_entryVede podvojné účetnictví
roleRole volajícího: owner, accountant, editor nebo viewer
can_writeVolající smí zapisovat (u archivované firmy false)
can_manageVolající je vlastník nebo účetní
payroll_accessVolající vidí mzdy a údaje zaměstnanců (vlastník a účetní vždy, editor a viewer podle Vidí mzdy)
member_user_idID uživatele volajícího
membership_idID členství volajícího
ownership_offerNabí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/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.",
    "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.

PoleTypPovinnéPopis
entityobjektano
entity.nametextanoNázev firmy nebo jméno OSVČ; řídicí znaky se nahradí mezerou. Nejvýše 200 znaků.
entity.legal_formtextnePrávní forma. Hodnoty: osvc, sro, as, vos, ks, druzstvo, spolek, other. Výchozí sro.
entity.icotextneIČO; nečíselné znaky se odstraní a kratší číslo doplní nulami na 8 číslic. Kontrolní číslice se neověřuje.
entity.dictextneDIČ; převede se na velká písmena bez mezer a k 8–10 číslicím se doplní CZ.
entity.titletextneTitul (OSVČ).
entity.first_nametextneJméno (OSVČ).
entity.last_nametextnePříjmení (OSVČ).
entity.streettextneUlice.
entity.house_numbertextneČíslo popisné.
entity.orientation_numbertextneČíslo orientační.
entity.citytextneObec.
entity.ziptextnePSČ.
entity.countrytextneStát. Výchozí CZ.
entity.emailtextneE-mail na dokladech.
entity.phonetextneTelefon.
entity.webtextneWeb.
entity.databoxtextneID datové schránky.
entity.register_notetextneZápis v rejstříku, tiskne se na doklady.
entity.bookkeepingtextneZpů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_ratecelé čísloneVýdajový paušál v procentech; uloží se jen s bookkeeping flat_expenses. Hodnoty: 80, 60, 40, 30.
entity.vat_statustextneVztah k DPH. Hodnoty: none, monthly, quarterly, identified. Výchozí none.
entity.vat_registered_ondatumneDatum registrace k DPH.
entity.tax_office_codetextneKód finančního úřadu (číselník tax_offices z GET /codebooks).
entity.tax_office_workplacetextneKód územního pracoviště.
entity.nacetextnePřevažující činnost CZ-NACE (pro přiznání).
entity.fiscal_year_startcelé čísloneMěsíc začátku účetního období. Výchozí 1. Rozsah od 1 do 12.
entity.currencytextneÚčetní měna, tři velká písmena. Výchozí CZK.
entity.default_due_dayscelé čísloneVýchozí splatnost vydaných faktur ve dnech. Výchozí 14. Rozsah od 0 do 365.
entity.invoice_footertextnePatička dokladů.
entity.accent_colortextneBarva dokladů ve tvaru #RRGGBB.
entity.archivedano/neneFirma je archivovaná (v seznamech až na konci). Výchozí false.
entity.settingsobjektneNastavení. 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_totaltextneZaokrouhlení 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_languagetextneJazyk nových dokladů, cs nebo en (jiná hodnota vrátí 422). Výchozí cs.
entity.settings.number_formattextneMaska čí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.settings.show_qrano/neneTisknout QR Platbu. Výchozí true.
entity.settings.invoice_styletextneVzhled 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_fonttextnePísmo faktury (auto = podle vzhledu). Hodnoty: auto, inter, plex, manrope, dm, franklin, serif, lora. Výchozí auto.
entity.settings.invoice_densitytextneHustota faktury. Hodnoty: normal, compact, airy. Výchozí normal.
entity.settings.invoice_tabletextneStyl tabulky položek. Hodnoty: auto, lines, zebra, grid, minimal, headfill, headline. Výchozí auto.
entity.settings.invoice_cornerstextneRohy prvků faktury. Hodnoty: auto, sharp, round. Výchozí auto.
entity.settings.invoice_logo_sizetextneVelikost loga. Hodnoty: s, m, l. Výchozí m.
entity.settings.invoice_logo_nameano/neneTisknout název firmy vedle loga. Výchozí false.
entity.settings.invoice_row_numbersano/neneČíslovat řádky. Výchozí false.
entity.settings.invoice_paid_stampano/neneRazítko Zaplaceno na uhrazených dokladech. Výchozí true.
entity.settings.invoice_contactsano/neneTisknout kontakty firmy. Výchozí true.
entity.settings.invoice_creditano/neneTisknout odkaz na Saldo. Výchozí true.
entity.settings.statement_categorytextneKategorie účetní jednotky pro výkazy (mikro, mala, stredni, velka); výchozí mikro.
entity.settings.statement_activitytextnePředmět podnikání do záhlaví tištěných výkazů (bez něj CZ-NACE firmy).
entity.settings.statement_signatorytextneKdo podepisuje účetní závěrku (podpisový záznam na výtisku výkazů).
entity.settings.result_on_431ano/neneVý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.settings.signaturetextnePodpis na dokladech.
entity.settings.vat_coefficientčísloneKoeficient 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.settings.vat_input_accounttextneAnalytika DPH na vstupu (účet 343… z účtového rozvrhu firmy); prázdné = 343.
entity.settings.vat_output_accounttextneAnalytika DPH na výstupu (účet 343… z účtového rozvrhu firmy); prázdné = 343.
entity.settings.vat_self_assessment_entriesano/neneSamovyměř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.settings.tax_advisorano/nenePřiznání podává daňový poradce.
entity.settings.auditano/nenePovinný audit.
entity.settings.real_estateano/nenePlatí daň z nemovitých věcí (kalendář lhůt).
entity.settings.road_taxano/nenePlatí silniční daň (kalendář lhůt).
entity.settings.income_kindtextneDruh příjmů OSVČ pro výdajový paušál (crafts, trade, other, rental).
entity.settings.cssz_variable_symboltextneVariabilní symbol plateb ČSSZ.
entity.settings.ossz_codetextneKód okresní správy sociálního zabezpečení.
entity.settings.flat_tax_bandcelé číslonePásmo paušální daně.
entity.settings.reminder_dayspole (celé číslo)nePo kolika dnech po splatnosti připomínat. Výchozí [3, 14, 30].
entity.settings.jmhz_ownership_formtextneForma vlastnictví pro JMHZ.
entity.settings.jmhz_collective_agreementspole (text)neKolektivní smlouvy pro JMHZ.
entity.settings.jmhz_workplaceobjektnePracoviště pro JMHZ – municipality, municipality_code, country.
entity.settings.jmhz_disabled_quotaobjektnePovinný podíl OZP pro JMHZ – employees, disabled, share.
entity.settings.submitterobjektneOsoba podávající přiznání – first_name, last_name, phone, relation.
entity.settings.tax_representativeobjektneZmocně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.settings.tax_profileobjektneSpoleč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.settings.profileobjektneOdpově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.modulesobjektneZapnuté 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.checklistobjektneStav prvních kroků – hidden (boolean) a dismissed (pole klíčů).
bankobjektneVolitelný bankovní účet: name, number, bank_code, iban, bic, currency, opening_balance, opening_date. Založí se jen s number nebo iban.
bank.nametextneNázev účtu; výchozí „Bankovní účet“
bank.numbertextneČíslo účtu bez kódu banky
bank.bank_codetextneKód banky (4 číslice)
bank.ibantextneIBAN
bank.bictextneBIC
bank.currencytextneMěna účtu; výchozí CZK
bank.opening_balancečíslonePočáteční stav
bank.opening_datedatumneDatum 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

StavKódKdy
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,
  "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ázevKdeTypPovinnýPopis
variantdotaztextneDruh 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

StavKódKdy
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.",
  "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ázevKdeTypPovinnýPopis
idcestacelé čísloanoID firmy. Příklad 1.

Odpověď

200 application/json Firma, nastavení s výchozími hodnotami, role volajícího a logo.

PoleVýznam
logo_dataLogo jako data:image/…;base64, nebo null
settingsNastavení doplněné o výchozí hodnoty
roleRole volajícího
payroll_accessVolají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/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).",
  "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ázevKdeTypPovinnýPopis
idcestacelé čísloanoID firmy. Příklad 1.
confirm_lockeddotazano/nenetrue 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.

PoleTypPovinnéPopis
entityobjektano
entity.nametextneNázev Nejvýše 200 znaků.
entity.legal_formtextnePrávní forma Hodnoty: osvc, sro, as, vos, ks, druzstvo, spolek, other.
entity.icotextneIČO (normalizuje se na 8 číslic)
entity.dictextneDIČ
entity.titletextneTitul
entity.first_nametextneJméno
entity.last_nametextnePříjmení
entity.streettextneUlice
entity.house_numbertextneČíslo popisné
entity.orientation_numbertextneČíslo orientační
entity.citytextneObec
entity.ziptextnePSČ
entity.countrytextneStát
entity.emailtextneE-mail
entity.phonetextneTelefon
entity.webtextneWeb
entity.databoxtextneID datové schránky
entity.register_notetextneZápis v rejstříku
entity.bookkeepingtextneZpůsob vedení; jiný než double_entry jen pro osvc Hodnoty: double_entry, tax_records, flat_expenses, flat_tax.
entity.flat_expense_ratecelé čísloneVýdajový paušál; uloží se jen s flat_expenses Hodnoty: 80, 60, 40, 30.
entity.vat_statustextneVztah k DPH Hodnoty: none, monthly, quarterly, identified.
entity.vat_registered_ondatumneDatum registrace k DPH
entity.tax_office_codetextneKód finančního úřadu
entity.tax_office_workplacetextneKód územního pracoviště
entity.nacetextneCZ-NACE
entity.fiscal_year_startcelé čísloneMěsíc začátku účetního období Rozsah od 1 do 12.
entity.currencytextneÚčetní měna
entity.default_due_dayscelé čísloneVýchozí splatnost Rozsah od 0 do 365.
entity.invoice_footertextnePatička dokladů
entity.accent_colortextneBarva #RRGGBB
entity.archivedano/neneArchivovat firmu (jen pro čtení), false ji obnoví
entity.logo_datatextneLogo jako data:image/png, jpeg, webp nebo gif;base64,…; prázdný řetězec logo odstraní. Nejvýše 400000 znaků.
entity.settingsobjektneStejné 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

StavKódKdy
403–Volající není vlastník ani účetní („Nastavení smí měnit jen vlastník nebo účetní“)
403ARCHIVEDFirma 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/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,
  "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ázevKdeTypPovinnýPopis
idcestacelé čísloanoID firmy. Příklad 2.

Tělo požadavku

Formát application/json.

PoleTypPovinnéPopis
confirmtextanoPř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

StavKódKdy
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/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

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ázevKdeTypPovinnýPopis
idcestacelé čísloanoID firmy. Příklad 1.

Tělo požadavku

Formát application/json.

PoleTypPovinnéPopis
locked_untildatumnePoslední 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

StavKódKdy
403–Volající není vlastník ani účetní („Období smí uzamknout jen vlastník nebo účetní“)
403ARCHIVEDFirma 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/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,
  "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ázevKdeTypPovinnýPopis
idcestacelé čísloanoID firmy. Příklad 1.

Odpověď

200 application/json Kroky a souhrn.

PoleVýznam
items[].keyKlíč kroku: import, bank, first_invoice, received, invoice_look, recurring, bank_rules, accountant, tax_data
items[].doneKrok je splněný
items[].dismissedUživatel krok skryl
items[].titleNázev kroku
items[].textVysvětlení
items[].hrefAdresa obrazovky v aplikaci
items[].actionPopisek tlačítka
items[].iconIkona Font Awesome
donePočet splněných neskrytých kroků
totalPočet neskrytých kroků
completeVšechny neskryté kroky jsou splněné
hiddenSeznam 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": "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ázevKdeTypPovinnýPopis
idcestacelé čísloanoID firmy. Příklad 1.

Tělo požadavku

Formát application/json.

PoleTypPovinnéPopis
keytextneKrok 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.
allano/neneSkrý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

StavKódKdy
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": "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ázevKdeTypPovinnýPopis
idcestacelé čísloanoID 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": "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ázevKdeTypPovinnýPopis
entity_idcestacelé čísloanoID firmy. Příklad 1.

Odpověď

200 application/json Pole členů.

PoleVýznam
idID členství (pro změnu role a odebrání)
user_idID uživatele; u nepřijaté pozvánky podle e-mailu null
usernameUživatelské jméno; u nepřijaté pozvánky podle e-mailu null
display_nameZobrazované jméno; u nepřijaté pozvánky podle e-mailu null
emailE-mail, jen u volajícího; jinak null
invited_asE-mail, na který šla nepřijatá pozvánka podle e-mailu (jinak null); neprozradí, komu adresa patří
roleowner, accountant, editor nebo viewer
role_labelNázev role
payroll_accessČlen vidí mzdy a údaje zaměstnanců; u vlastníka a účetní vždy true
pendingPozvánka zatím nebyla přijata
accepted_atČas přijetí
invited_byKdo pozval
is_selfJde 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/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",
    "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

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ázevKdeTypPovinnýPopis
entity_idcestacelé čísloanoID firmy. Příklad 1.

Tělo požadavku

Formát application/json.

PoleTypPovinnéPopis
logintextanoUž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í.
roletextneRole; 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_accessano/neneEditor 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

StavKódKdy
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ý
429RATE_LIMITEDVí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)
422PAYROLL_ALWAYSpayroll_access false u role accountant – účetní vidí mzdy vždy
403ARCHIVEDFirma 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/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",
  "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

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ázevKdeTypPovinnýPopis
entity_idcestacelé čísloanoID firmy. Příklad 1.
idcestacelé čísloanoID členství z GET /entities/{entity_id}/members. Příklad 3.

Tělo požadavku

Formát application/json.

PoleTypPovinnéPopis
roletextneNová 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_accessano/neneEditor 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

StavKódKdy
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)
422PAYROLL_ALWAYSpayroll_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/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",
  "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ázevKdeTypPovinnýPopis
entity_idcestacelé čísloanoID firmy. Příklad 1.
idcestacelé čísloanoID členství z GET /entities/{entity_id}/members. Příklad 3.

Odpověď

204 Bez obsahu.

Chyby této operace

StavKódKdy
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ů

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ázevKdeTypPovinnýPopis
entity_idcestacelé čísloanoID firmy. Příklad 1.
idcestacelé čísloanoID přijatého členství z GET /entities/{entity_id}/members. Příklad 3.

Tělo požadavku

Formát application/json.

PoleTypPovinnéPopis
modetextanotransfer = předání vlastnictví, co_owner = druhý vlastník se stejnými právy. Hodnoty: transfer, co_owner.
keep_roletextneJen u transfer – role, kterou si dosavadní vlastník po předání ponechá; none = firmu opustí. Hodnoty: accountant, editor, viewer, none. Výchozí accountant.
confirmtextneJen 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

StavKódKdy
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/ownership

JavaScript

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();
Odpověď 200 OK
{
  "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ázevKdeTypPovinnýPopis
entity_idcestacelé čísloanoID firmy. Příklad 1.
idcestacelé čísloanoID č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

StavKódKdy
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/ownership

JavaScript

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();
Odpověď 200 OK
{
  "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ázevKdeTypPovinnýPopis
entity_idcestacelé čísloanoID firmy. Příklad 1.
idcestacelé čísloanoID 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

StavKódKdy
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/accept

JavaScript

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();
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).",
  "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ázevKdeTypPovinnýPopis
entity_idcestacelé čísloanoID firmy. Příklad 1.

Tělo požadavku

Formát application/json.

PoleTypPovinnéPopis
user_idcelé čísloneID 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ů.

PoleVýznam
responsible{ id, name }, nebo null
movedPočet otevřených kroků, které přešly na novou osobu (nebo se uvolnily)

Chyby této operace

StavKódKdy
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/responsible

JavaScript

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();
Odpověď 200 OK
{
  "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ázevKdeTypPovinnýPopis
entity_idcestacelé čísloanoID firmy. Příklad 1.
pagedotazcelé čísloneStrá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.

PoleVýznam
totalCelkový počet událostí
pageVrácená stránka
rows[].idID události
rows[].actionDruh události, např. entity.updated, member.invited, partner.created
rows[].subject_typeTyp dotčeného záznamu, např. Entity, Partner, Document
rows[].subject_idID dotčeného záznamu
rows[].summaryPopis (nejvýše 250 znaků)
rows[].userUživatelské jméno autora
rows[].created_atČas
rows[].detailsPodrobnosti 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();
Odpověď 200 OK
{
  "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.