SaldoDokumentace
Otevřít Saldo

Reference API

Kontakty

Kontakty (odběratelé a dodavatelé) firmy: seznam, založení, úpravy a mazání, doplnění podle IČO z ARES a kontrola v registru plátců DPH a v insolvenčním rejstříku.

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

GET Kontakty firmy s obraty

/entities/{entity_id}/partners

Oprávnění
Každý člen firmy včetně role Jen čtení
Klíč jen pro čtení
Stačí

Vrátí kontakty firmy (odběratele i dodavatele) seřazené podle názvu bez ohledu na velikost písmen, nejvýše 500. Ke každému kontaktu připojí obraty: součet základu vystavených faktur a dobropisů v Kč zvlášť za prodej a za nákup a počet neuhrazených vystavených faktur, zálohových faktur a dobropisů; kontakt bez takových dokladů má stats null. Hledání q najde část názvu, IČO, DIČ, IBAN nebo čísla účtu.

Parametry

NázevKdeTypPovinnýPopis
entity_idcestacelé čísloanoID firmy. Příklad 1.
qdotaztextneHledaný text (část názvu, IČO, DIČ, IBAN nebo čísla účtu), bez ohledu na velikost písmen a diakritiku. Příklad Nordwood.

Odpověď

200 application/json Pole kontaktů.

PoleVýznam
idID kontaktu
nameNázev
icoIČO (8 číslic)
dicDIČ
streetUlice
cityObec
zipPSČ
countryStát (ISO kód)
emailE-mail
phoneTelefon
webWeb
bank_accountČíslo účtu
ibanIBAN
bicBIC
due_daysSplatnost ve dnech pro nové doklady
default_account_codeVýchozí účet pro doklady
notePoznámka
company_idPropojení s firmou v registru firem TechTools
vat_payerPlátce DPH podle poslední kontroly registru (null = neověřeno)
unreliableNespolehlivý plátce podle poslední kontroly
checked_atČas poslední kontroly v registru plátců DPH
insolventV insolvenčním rejstříku podle poslední kontroly
insolvency_noteSpisové značky a stavy řízení
insolvency_checked_atČas poslední kontroly v insolvenčním rejstříku
vies_validVýsledek poslední kontroly DIČ ve VIES (true platné, false neplatné, null neověřeno)
vies_checked_atČas poslední kontroly ve VIES
vies_nameNázev plátce podle VIES, pokud ho stát uvádí
statssales, purchases (základ v Kč) a open_documents, nebo null

Chování

Co změní
Nic nezapisuje.
Limity
Nejvýše 500 kontaktů, bez stránkování.

Příklad

cURL

curl \
  -H "X-API-Key: $SALDO_API_KEY" \
  "https://techtools.cz/ucetnictvi-api/entities/1/partners?q=Nordwood"

JavaScript

const response = await fetch('https://techtools.cz/ucetnictvi-api/entities/1/partners?q=Nordwood', {
  headers: { 'X-API-Key': process.env.SALDO_API_KEY }
});
const data = await response.json();
Odpověď 200 OK
[
  {
    "id": 1,
    "bank_account": null,
    "bic": null,
    "checked_at": null,
    "city": "Praha 10",
    "company_id": null,
    "country": "CZ",
    "created_at": "2026-09-28T10:00:00.000Z",
    "default_account_code": null,
    "dic": "CZ90000013",
    "due_days": 14,
    "email": "fakturace@example.cz",
    "iban": null,
    "ico": "90000013",
    "insolvency_checked_at": null,
    "insolvency_note": null,
    "insolvent": null,
    "name": "Nordwood Studio s.r.o.",
    "note": null,
    "phone": null,
    "street": "Korunní 1208/74",
    "unreliable": null,
    "updated_at": "2026-09-28T10:00:00.000Z",
    "vat_payer": null,
    "vies_checked_at": null,
    "vies_name": null,
    "vies_valid": null,
    "web": null,
    "zip": "10100",
    "stats": {
      "sales": 467200.0,
      "purchases": 0.0,
      "open_documents": 2
    }
  }
]

POST Založí kontakt

/entities/{entity_id}/partners

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

Založí odběratele nebo dodavatele. IČO se doplní nulami na 8 číslic a musí mít platnou kontrolní číslici, DIČ se převede na velká písmena bez mezer (k 8–10 číslicím se doplní CZ, GR na EL) a u států EU musí odpovídat jejich tvaru (CZ a 8–10 číslic, DE a 9 číslic, ATU a 8 číslic …); DIČ mimo EU se neověřuje. Stát na velká písmena. Duplicitu IČO Saldo nekontroluje. company_id se uloží jen u firmy z vlastního registru firem TechTools volajícího, jinak se tiše zahodí.

Parametry

NázevKdeTypPovinnýPopis
entity_idcestacelé čísloanoID firmy. Příklad 1.

Tělo požadavku

Formát application/json.

PoleTypPovinnéPopis
partnerobjektano
partner.nametextanoNázev nebo jméno Nejvýše 200 znaků.
partner.icotextneIČO; nečíselné znaky se odstraní a doplní se nulami na 8 číslic
partner.dictextneDIČ ve tvaru dvou písmen státu a 2–12 znaků
partner.streettextneUlice a číslo
partner.citytextneObec
partner.ziptextnePSČ
partner.countrytextneStát, dvoupísmenný kód Výchozí CZ.
partner.emailtextneE-mail
partner.phonetextneTelefon
partner.webtextneWeb
partner.bank_accounttextneČíslo účtu ve tvaru předčíslí-číslo/kód banky (tvar se neověřuje)
partner.ibantextneIBAN
partner.bictextneBIC
partner.due_dayscelé čísloneSplatnost ve dnech pro nové doklady Rozsah od 0 do 365.
partner.default_account_codetextneVýchozí účet pro řádky dokladů
partner.notetextnePoznámka
partner.company_idcelé čísloneID firmy z registru firem TechTools volajícího

Odpověď

201 application/json Založený kontakt ve stejném tvaru jako v seznamu (stats null).

Chyby této operace

StavKódKdy
422–IČO bez platné kontrolní číslice: „IČO … nemá platnou kontrolní číslici – zkontrolujte ho, nebo ho nechte prázdné“
422–DIČ neodpovídá tvaru svého státu EU: „DIČ … nemá platný tvar“

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

Chování

Co změní
Vytvoří kontakt. Do historie změn zapíše událost partner.created.
Opakování
Každé volání založí nový kontakt, i se stejným IČO.

Příklad

cURL

curl \
  -X POST \
  -H "X-API-Key: $SALDO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"partner":{"name":"Kavárna Modrý pták s.r.o.","ico":"90000102","dic":"CZ90000102","street":"Jugoslávská 12","city":"Praha 2","zip":"12000","country":"CZ","email":"ucetni@modry-ptak.example","due_days":14}}' \
  https://techtools.cz/ucetnictvi-api/entities/1/partners

JavaScript

const response = await fetch('https://techtools.cz/ucetnictvi-api/entities/1/partners', {
  headers: { 'X-API-Key': process.env.SALDO_API_KEY, 'Content-Type': 'application/json' },
  method: 'POST',
  body: JSON.stringify({
    "partner": {
      "name": "Kavárna Modrý pták s.r.o.",
      "ico": "90000102",
      "dic": "CZ90000102",
      "street": "Jugoslávská 12",
      "city": "Praha 2",
      "zip": "12000",
      "country": "CZ",
      "email": "ucetni@modry-ptak.example",
      "due_days": 14
    }
  })
});
const data = await response.json();
Odpověď 201 Created
{
  "id": 29,
  "bank_account": null,
  "bic": null,
  "checked_at": null,
  "city": "Praha 2",
  "company_id": null,
  "country": "CZ",
  "created_at": "2026-09-28T10:00:00.000Z",
  "default_account_code": null,
  "dic": "CZ90000102",
  "due_days": 14,
  "email": "ucetni@modry-ptak.example",
  "iban": null,
  "ico": "90000102",
  "insolvency_checked_at": null,
  "insolvency_note": null,
  "insolvent": null,
  "name": "Kavárna Modrý pták s.r.o.",
  "note": null,
  "phone": null,
  "street": "Jugoslávská 12",
  "unreliable": null,
  "updated_at": "2026-09-28T10:00:00.000Z",
  "vat_payer": null,
  "vies_checked_at": null,
  "vies_name": null,
  "vies_valid": null,
  "web": null,
  "zip": "12000",
  "stats": null
}

GET Detail kontaktu s posledními doklady

/entities/{entity_id}/partners/{id}

Oprávnění
Každý člen firmy včetně role Jen čtení
Klíč jen pro čtení
Stačí

Vrátí kontakt s obraty a posledními 100 doklady firmy s tímto kontaktem (od nejnovějšího data vystavení) ve zkráceném tvaru jako v seznamu dokladů.

Parametry

NázevKdeTypPovinnýPopis
entity_idcestacelé čísloanoID firmy. Příklad 1.
idcestacelé čísloanoID kontaktu. Příklad 1.

Odpověď

200 application/json Kontakt jako v seznamu a pole documents.

PoleVýznam
statssales, purchases a open_documents, nebo null
documentsNejvýše 100 dokladů: id, kind, status, number, data, měna, částky, stav úhrady a další údaje přehledu

Chování

Co změní
Nic nezapisuje.
Limity
Nejvýše 100 dokladů.

Příklad

cURL

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

JavaScript

const response = await fetch('https://techtools.cz/ucetnictvi-api/entities/1/partners/1', {
  headers: { 'X-API-Key': process.env.SALDO_API_KEY }
});
const data = await response.json();
Odpověď 200 OK
{
  "id": 1,
  "bank_account": null,
  "bic": null,
  "checked_at": null,
  "city": "Praha 10",
  "company_id": null,
  "country": "CZ",
  "created_at": "2026-09-28T10:00:00.000Z",
  "default_account_code": null,
  "dic": "CZ90000013",
  "due_days": 14,
  "email": "fakturace@example.cz",
  "iban": null,
  "ico": "90000013",
  "insolvency_checked_at": null,
  "insolvency_note": null,
  "insolvent": null,
  "name": "Nordwood Studio s.r.o.",
  "note": null,
  "phone": null,
  "street": "Korunní 1208/74",
  "unreliable": null,
  "updated_at": "2026-09-28T10:00:00.000Z",
  "vat_payer": null,
  "vies_checked_at": null,
  "vies_name": null,
  "vies_valid": null,
  "web": null,
  "zip": "10100",
  "stats": {
    "sales": 467200.0,
    "purchases": 0.0,
    "open_documents": 2
  },
  "documents": [
    {
      "id": 132,
      "kind": "invoice_out",
      "kind_label": "Faktura vydaná",
      "status": "draft",
      "number": null,
      "variable_symbol": null,
      "original_number": null,
      "partner_id": 1,
      "partner_name": "Nordwood Studio s.r.o.",
      "partner_ico": "90000013",
      "issue_date": "2026-09-28",
      "taxable_date": "2026-09-28",
      "due_date": "2026-10-12",
      "currency": "CZK",
      "total_net": 19800.0,
      "total_vat": 4158.0,
      "total_payable": 23958.0,
      "total_gross_czk": 23958.0,
      "paid_amount": 0.0,
      "remaining": 23958.0,
      "payment_state": "na",
      "days_overdue": 0,
      "description": "Návrh úvodní stránky",
      "vat_mode": "domestic",
      "source": "manual",
      "tags": null,
      "related_document_id": null,
      "reminders_sent": 0,
      "outcome": null,
      "attachments_count": 0,
      "approval_state": null,
      "created_by_id": 1,
      "created_by_name": "ukazka"
    },
    {
      "id": 129,
      "kind": "invoice_out",
      "kind_label": "Faktura vydaná",
      "status": "issued",
      "number": "FV20260025",
      "variable_symbol": "20260025",
      "original_number": null,
      "partner_id": 1,
      "partner_name": "Nordwood Studio s.r.o.",
      "partner_ico": "90000013",
      "issue_date": "2026-09-28",
      "taxable_date": "2026-09-28",
      "due_date": "2026-10-12",
      "currency": "CZK",
      "total_net": 19800.0,
      "total_vat": 4158.0,
      "total_payable": 23958.0,
      "total_gross_czk": 23958.0,
      "paid_amount": 0.0,
      "remaining": 23958.0,
      "payment_state": "unpaid",
      "days_overdue": 0,
      "description": "Správa webu – září",
      "vat_mode": "domestic",
      "source": "manual",
      "tags": null,
      "related_document_id": null,
      "reminders_sent": 0,
      "outcome": null,
      "attachments_count": 0,
      "approval_state": null,
      "created_by_id": 1,
      "created_by_name": "ukazka"
    }
  ]
}

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

PATCH Změní kontakt

/entities/{entity_id}/partners/{id}

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

Změní údaje kontaktu; pole, jejich úpravy a kontrola IČO a DIČ jsou stejné jako při založení (kontroluje se jen změněné IČO nebo DIČ, starý kontakt jde upravit i s neplatným). Vystavené doklady si ponechávají údaje kontaktu z doby vystavení, koncepty převezmou nové. Když má firma zapnuté schvalování přijatých výdajů, přepočítá schválené přijaté faktury, pokladní výdaje a dobropisy tohoto dodavatele: změna názvu, IČO nebo účtu pro platbu u nich zruší schválení, případně je rovnou schválí znovu, smí-li je volající schválit.

Parametry

NázevKdeTypPovinnýPopis
entity_idcestacelé čísloanoID firmy. Příklad 1.
idcestacelé čísloanoID kontaktu. Příklad 1.

Tělo požadavku

Formát application/json.

PoleTypPovinnéPopis
partnerobjektano
partner.nametextneNázev nebo jméno Nejvýše 200 znaků.
partner.icotextneIČO
partner.dictextneDIČ
partner.streettextneUlice a číslo
partner.citytextneObec
partner.ziptextnePSČ
partner.countrytextneStát, dvoupísmenný kód
partner.emailtextneE-mail
partner.phonetextneTelefon
partner.webtextneWeb
partner.bank_accounttextneČíslo účtu
partner.ibantextneIBAN
partner.bictextneBIC
partner.due_dayscelé čísloneSplatnost ve dnech Rozsah od 0 do 365.
partner.default_account_codetextneVýchozí účet
partner.notetextnePoznámka
partner.company_idcelé čísloneID firmy z vlastního registru firem TechTools; cizí ID se ignoruje

Odpověď

200 application/json Uložený kontakt (stats null).

Chyby této operace

StavKódKdy
422–Změněné IČO nebo DIČ je neplatné (jako createPartner)

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

Chování

Co změní
Uloží kontakt; když se něco změnilo, zapíše do historie změn událost partner.updated s původními a novými hodnotami (details.changes). Při zapnutém schvalování může schváleným přijatým výdajům tohoto dodavatele zrušit schválení (událost document.approval_changed) nebo je znovu schválit.
Opakování
Stejný požadavek vede ke stejnému stavu.

Příklad

cURL

curl \
  -X PATCH \
  -H "X-API-Key: $SALDO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"partner":{"email":"fakturace@nordwood.example","due_days":21}}' \
  https://techtools.cz/ucetnictvi-api/entities/1/partners/1

JavaScript

const response = await fetch('https://techtools.cz/ucetnictvi-api/entities/1/partners/1', {
  headers: { 'X-API-Key': process.env.SALDO_API_KEY, 'Content-Type': 'application/json' },
  method: 'PATCH',
  body: JSON.stringify({
    "partner": {
      "email": "fakturace@nordwood.example",
      "due_days": 21
    }
  })
});
const data = await response.json();
Odpověď 200 OK
{
  "email": "fakturace@nordwood.example",
  "due_days": 21,
  "name": "Nordwood Studio s.r.o.",
  "ico": "90000013",
  "dic": "CZ90000013",
  "country": "CZ",
  "id": 1,
  "bank_account": null,
  "bic": null,
  "checked_at": null,
  "city": "Praha 10",
  "company_id": null,
  "created_at": "2026-09-28T10:00:00.000Z",
  "default_account_code": null,
  "iban": null,
  "insolvency_checked_at": null,
  "insolvency_note": null,
  "insolvent": null,
  "note": null,
  "phone": null,
  "street": "Korunní 1208/74",
  "unreliable": null,
  "updated_at": "2026-09-28T10:00:00.000Z",
  "vat_payer": null,
  "vies_checked_at": null,
  "vies_name": null,
  "vies_valid": null,
  "web": null,
  "zip": "10100",
  "stats": null
}

DELETE Smaže kontakt bez dokladů

/entities/{entity_id}/partners/{id}

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

Smaže kontakt, který nemá žádný doklad (ani koncept).

Parametry

NázevKdeTypPovinnýPopis
entity_idcestacelé čísloanoID firmy. Příklad 1.
idcestacelé čísloanoID kontaktu. Příklad 24.

Odpověď

204 Bez obsahu.

Chyby této operace

StavKódKdy
422–Kontakt má doklady („Kontakt má doklady – nelze ho smazat“)

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

Chování

Co změní
Smaže kontakt. Do historie změn zapíše událost partner.deleted s jeho údaji (details.changes).
Opakování
Druhé volání vrátí 404.

Příklad

Potřebuje kontakt bez dokladů.

cURL

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

JavaScript

const response = await fetch('https://techtools.cz/ucetnictvi-api/entities/1/partners/24', {
  headers: { 'X-API-Key': process.env.SALDO_API_KEY },
  method: 'DELETE'
});
const data = await response.json();
Odpověď 204 No Content
soubor, 0 bajtů

GET Údaje subjektu z ARES pro nový kontakt

/entities/{entity_id}/partners/lookup

Oprávnění
Každý člen firmy včetně role Jen čtení
Klíč jen pro čtení
Stačí

Načte subjekt podle IČO z ARES (název, DIČ, právní forma, adresa) a zjistí, zda je podle ARES plátcem DPH. Nic neukládá. Neznámé IČO není chyba: vrátí 200 s found: false a code NOT_FOUND. IČO se nedoplňuje nulami, musí mít přesně 8 číslic; jinak (i když chybí) vrátí 422 s kódem INVALID_ICO („IČO má 8 číslic“).

Parametry

NázevKdeTypPovinnýPopis
entity_idcestacelé čísloanoID firmy, jejímž jste přijatým členem; jinak 404. Příklad 1.
icodotaztextanoIČO; nečíselné znaky se odstraní a zbýt musí přesně 8 číslic. Příklad 99999994.

Odpověď

200 application/json Údaje subjektu s found: true, nebo { ico, found: false, code: NOT_FOUND, error }.

PoleVýznam
icoIČO
nameObchodní firma nebo jméno
dicDIČ z ARES
legal_formKód právní formy ARES
company_typesro nebo as, u jiných forem null
addressAdresa sídla jedním řádkem
streetUlice s čísly
cityObec
zipPSČ
foundSubjekt byl nalezen
vatÚdaje z ARES včetně vat_payer, legal_form_name a founded, nebo null, když druhý dotaz selže

Chyby této operace

StavKódKdy
422–IČO nemá přesně 8 číslic nebo chybí (INVALID_ICO, „IČO má 8 číslic“)
502–ARES neodpovídá nebo vrátil chybu
429–Víc než 40 hledání za minutu (code RATE_LIMITED)

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 dvakrát (údaje subjektu a stav DPH).
Limity
Časový limit dotazu do ARES je 8 s. Nejvýš 40 hledání za minutu na uživatele, společně s GET /lookup/{ico}.

Příklad

ARES je v příkladu nahrazený testovacími daty.

cURL

curl \
  -H "X-API-Key: $SALDO_API_KEY" \
  "https://techtools.cz/ucetnictvi-api/entities/1/partners/lookup?ico=99999994"

JavaScript

const response = await fetch('https://techtools.cz/ucetnictvi-api/entities/1/partners/lookup?ico=99999994', {
  headers: { 'X-API-Key': process.env.SALDO_API_KEY }
});
const data = await response.json();
Odpověď 200 OK
{
  "ico": "99999994",
  "name": "Ukázková firma s.r.o.",
  "dic": "CZ99999994",
  "legal_form": "112",
  "company_type": "sro",
  "address": "Na Příkopě 859/22, 11000 Praha",
  "street": "Na Příkopě 859/22",
  "city": "Praha",
  "zip": "11000",
  "found": true,
  "vat": {
    "ico": "99999994",
    "name": "Ukázková firma s.r.o.",
    "dic": "CZ99999994",
    "legal_form": "112",
    "company_type": "sro",
    "address": "Na Příkopě 859/22, 11000 Praha",
    "street": "Na Příkopě 859/22",
    "city": "Praha",
    "zip": "11000",
    "vat_payer": true,
    "legal_form_name": "Společnost s ručením omezeným",
    "founded": "2019-03-01"
  }
}

Odpověď externí služby (ARES) je v ukázce nahrazená smyšlenými údaji ve formátu, který služba vrací.

POST Ověří všechna česká DIČ v registru plátců DPH

/entities/{entity_id}/partners/vat_registry_all

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

Ověří v registru plátců DPH Ministerstva financí všechny kontakty firmy s DIČ začínajícím CZ a u každého uloží, zda je plátcem a zda je nespolehlivý plátce. Vrátí počet ověřených a seznam nespolehlivých. Kontakt, kterého registr v odpovědi neuvede, není plátce DPH (vat_payer i unreliable false) a čas kontroly se mu uloží.

Parametry

NázevKdeTypPovinnýPopis
entity_idcestacelé čísloanoID firmy. Příklad 1.

Odpověď

200 application/json Souhrn kontroly.

PoleVýznam
checkedPočet ověřených kontaktů s českým DIČ
unreliablePočet nespolehlivých plátců
partnersNespolehliví plátci: id, name, dic

Chyby této operace

StavKódKdy
502–Registr plátců DPH je nedostupný nebo vrátil chybu

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

Chování

Co změní
U každého kontaktu s českým DIČ uloží vat_payer, unreliable a checked_at. Do historie změn zapíše událost partner.vat_checked, i když firma žádný takový kontakt nemá. Volá registr plátců DPH.
Limity
Bez omezení počtu kontaktů; registr se volá po 100 DIČ, každý dotaz s limitem 8 s na spojení a 20 s na odpověď.
Opakování
Každé volání ověří kontakty znovu a přidá do historie změn nový záznam.

Příklad

Registr plátců DPH je v příkladu nahrazený testovacími daty.

cURL

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

JavaScript

const response = await fetch('https://techtools.cz/ucetnictvi-api/entities/1/partners/vat_registry_all', {
  headers: { 'X-API-Key': process.env.SALDO_API_KEY },
  method: 'POST'
});
const data = await response.json();
Odpověď 200 OK
{
  "checked": 9,
  "unreliable": 0,
  "partners": []
}

Odpověď externí služby (registr plátců DPH) je v ukázce nahrazená smyšlenými údaji ve formátu, který služba vrací.

POST Ověří další várku kontaktů v insolvenčním rejstříku

/entities/{entity_id}/partners/insolvency_all

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

Ověří v insolvenčním rejstříku (ISIR) nejvýše 15 kontaktů s IČO, které nebyly ověřené posledních 24 hodin: nejdřív ty s neuhrazenými doklady, pak ty nejdéle neověřené. Odpověď rejstříku se pro každé IČO drží 12 hodin v mezipaměti. Kontakt s neplatným IČO se jen označí jako ověřený. První chyba rejstříku várku ukončí a její text je v poli error, odpověď má přesto stav 200. Opakovaným voláním se ověří další kontakty.

Parametry

NázevKdeTypPovinnýPopis
entity_idcestacelé čísloanoID firmy. Příklad 1.

Odpověď

200 application/json Souhrn várky.

PoleVýznam
checkedPočet ověřených kontaktů
invalidPočet kontaktů s neplatným IČO, které várka jen označila jako ověřené
remainingKolik kontaktů zbývá ověřit
errorChyba rejstříku, která várku ukončila, nebo null
insolventOvěřené kontakty v insolvenci: id, name, note

Chování

Co změní
U ověřených kontaktů uloží insolvent, insolvency_note (spisové značky a stavy, nejvýše 250 znaků) a insolvency_checked_at; u kontaktů s neplatným IČO jen insolvency_checked_at. Když ověří aspoň jeden kontakt, zapíše do historie změn událost partner.isir_checked. Volá ISIR.
Limity
15 kontaktů na volání. Dotazy do ISIR server rozkládá (asi 45 za minutu a 2 500 za den); na volné místo čeká nejvýše 10 s, jinak várku ukončí s chybou v poli error. Časový limit dotazu 5 s na spojení a 15 s na odpověď.
Opakování
Každé volání pokračuje dalšími kontakty, dokud remaining neklesne na 0.

Příklad

Insolvenční rejstřík je v příkladu nahrazený testovacími daty.

cURL

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

JavaScript

const response = await fetch('https://techtools.cz/ucetnictvi-api/entities/1/partners/insolvency_all', {
  headers: { 'X-API-Key': process.env.SALDO_API_KEY },
  method: 'POST'
});
const data = await response.json();
Odpověď 200 OK
{
  "checked": 13,
  "invalid": 0,
  "remaining": 0,
  "error": null,
  "insolvent": []
}

Odpověď externí služby (insolvenční rejstřík) je v ukázce nahrazená smyšlenými údaji ve formátu, který služba vrací.

GET Ověří DIČ kontaktu v registru plátců DPH

/entities/{entity_id}/partners/{id}/vat_registry

Oprávnění
Vlastník, účetní nebo editor
Pravidlo
Vyžaduje právo zápisu (vlastník, účetní, editor). Přestože jde o GET, API klíč jen pro čtení dostane 403 READ_ONLY_KEY, protože volání ukládá výsledek ke kontaktu.
Klíč jen pro čtení
Nestačí, vrátí 403 READ_ONLY_KEY

Ověří DIČ jednoho kontaktu v registru plátců DPH Ministerstva financí, uloží výsledek ke kontaktu a vrátí stav plátce a to, zda je účet kontaktu (číslo účtu, jinak IBAN) mezi účty zveřejněnými v registru. Přestože jde o GET, zapisuje, a proto vyžaduje právo zápisu.

Parametry

NázevKdeTypPovinnýPopis
entity_idcestacelé čísloanoID firmy. Příklad 1.
idcestacelé čísloanoID kontaktu. Příklad 1.

Odpověď

200 application/json { status, account, account_published }; status je null, když registr DIČ nezná.

PoleVýznam
statusStav z registru: dic, found, kind, payer, unreliable, tax_office, name, since, accounts
accountÚčet kontaktu, který se porovnával
account_publishedÚčet je mezi zveřejněnými účty plátce

Chyby této operace

StavKódKdy
403–API klíč jen pro čtení (READ_ONLY_KEY)
422–Kontakt nemá DIČ začínající CZ („Kontakt nemá české DIČ“)
502–Registr plátců DPH je nedostupný nebo vrátil chybu

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

Chování

Co změní
Uloží ke kontaktu vat_payer, unreliable a checked_at (DIČ, které registr nezná, není plátce). Do historie změn nezapisuje. Volá registr plátců DPH.
Opakování
Každé volání ověří DIČ znovu.

Příklad

Registr plátců DPH odpovídá synteticky ve svém formátu.

cURL

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

JavaScript

const response = await fetch('https://techtools.cz/ucetnictvi-api/entities/1/partners/1/vat_registry', {
  headers: { 'X-API-Key': process.env.SALDO_API_KEY }
});
const data = await response.json();
Odpověď 200 OK
{
  "status": {
    "dic": "CZ90000013",
    "found": true,
    "kind": "PLATCE_DPH",
    "payer": true,
    "unreliable": false,
    "tax_office": "451",
    "name": "Nordwood Studio s.r.o.",
    "since": null,
    "accounts": [
      "9000001329/0800"
    ]
  },
  "account": null,
  "account_published": false
}

Odpověď externí služby (registr plátců DPH) je v ukázce nahrazená smyšlenými údaji ve formátu, který služba vrací.

POST Ověří DIČ kontaktu ve VIES a výsledek uloží jako doklad

/entities/{entity_id}/partners/{id}/vies

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

Ověří DIČ kontaktu s kódem státu EU (např. DE123456789; GR se posílá jako EL) v systému VIES Evropské komise a výsledek s datem uloží ke kontaktu (vies_valid, vies_name, vies_checked_at) a do historie změn (událost partner.vies_checked s odpovědí VIES). Souhrnné hlášení pak upozorní na odběratele s neplatným nebo neověřeným DIČ a editor se před vystavením dodání do EU zeptá, když je DIČ neplatné (osvobození § 64 ZDPH vyžaduje platné DIČ pořizovatele).

Parametry

NázevKdeTypPovinnýPopis
entity_idcestacelé čísloanoID účetní jednotky Příklad 12.
idcestacelé čísloanoID kontaktu Příklad 7.

Odpověď

200 application/json Odpověď VIES a uložený kontakt.

PoleVýznam
validDIČ je ve VIES platné
nameNázev podle VIES, pokud ho stát uvádí
addressAdresa podle VIES, pokud ji stát uvádí
request_dateDatum dotazu podle VIES
partnerKontakt (tvar jako GET …/partners/{id}) s vies_valid, vies_name a vies_checked_at

Chyby této operace

StavKódKdy
422–Kontakt nemá DIČ s kódem státu EU, nebo ho VIES odmítl jako chybně zadané
502–VIES nebo registr členského státu neodpovídá („Registr VIES teď neodpovídá …“)

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

Chování

Co změní
Uloží ke kontaktu výsledek kontroly a zapíše událost partner.vies_checked. Volá VIES.
Opakování
Každé volání ověří DIČ znovu a výsledek přepíše.

Příklad

cURL

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

JavaScript

const response = await fetch('https://techtools.cz/ucetnictvi-api/entities/1/partners/5/vies', {
  headers: { 'X-API-Key': process.env.SALDO_API_KEY },
  method: 'POST'
});
const data = await response.json();
Odpověď 200 OK
{
  "valid": true,
  "name": "HAFENLICHT GMBH",
  "address": "Hafenstraße 18, 20457 Hamburg",
  "request_date": "2026-09-28+02:00",
  "partner": {
    "id": 5,
    "bank_account": null,
    "bic": null,
    "checked_at": null,
    "city": "Hamburg",
    "company_id": null,
    "country": "DE",
    "created_at": "2026-09-28T10:00:00.000Z",
    "default_account_code": null,
    "dic": "DE912345678",
    "due_days": 30,
    "email": "fakturace@example.cz",
    "iban": null,
    "ico": null,
    "insolvency_checked_at": null,
    "insolvency_note": null,
    "insolvent": null,
    "name": "Hafenlicht GmbH",
    "note": null,
    "phone": null,
    "street": "Hafenstraße 18",
    "unreliable": null,
    "updated_at": "2026-09-28T10:00:00.000Z",
    "vat_payer": null,
    "vies_checked_at": "2026-09-28T10:00:00.000Z",
    "vies_name": "HAFENLICHT GMBH",
    "vies_valid": true,
    "web": null,
    "zip": "20457",
    "stats": null
  }
}

Odpověď externí služby (VIES (Evropská komise)) je v ukázce nahrazená smyšlenými údaji ve formátu, který služba vrací.

POST Ověří kontakt v insolvenčním rejstříku

/entities/{entity_id}/partners/{id}/insolvency

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

Ověří IČO kontaktu v insolvenčním rejstříku (ISIR) a vrátí probíhající řízení, ve kterých je kontakt dlužníkem (nejvýše 50), s odkazem na detail řízení. Výsledek uloží ke kontaktu. Odpověď rejstříku se pro IČO drží 12 hodin v mezipaměti; refresh vynutí nový dotaz.

Parametry

NázevKdeTypPovinnýPopis
entity_idcestacelé čísloanoID firmy. Příklad 1.
idcestacelé čísloanoID kontaktu. Příklad 1.
refreshdotazano/neneNepoužít výsledek z mezipaměti a zeptat se rejstříku znovu. Výchozí false. Příklad true.

Odpověď

200 application/json Výsledek kontroly a uložený kontakt.

PoleVýznam
icoOvěřené IČO
insolventKontakt je v probíhajícím insolvenčním řízení
proceedingsŘízení: file_mark, court, state, state_label, started_on, ended_on, url
checked_atČas dotazu do rejstříku (při výsledku z mezipaměti starší)
partnerKontakt po uložení výsledku

Chyby této operace

StavKódKdy
422–Kontakt nemá IČO („Kontakt nemá IČO“)
422–IČO kontaktu nemá platnou kontrolní číslici
502–ISIR je nedostupný, odmítl dotaz, vrátil nečitelnou odpověď nebo byl překročen limit dotazů

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

Chování

Co změní
Uloží ke kontaktu insolvent, insolvency_note (nejvýše 250 znaků) a insolvency_checked_at. Do historie změn nezapisuje. Volá ISIR, pokud výsledek není v mezipaměti nebo je zadán refresh.
Limity
Mezipaměť 12 hodin na IČO. Dotazy do ISIR server rozkládá (asi 45 za minutu a 2 500 za den) a na volné místo čeká nejvýše 10 s, jinak vrátí 502.
Opakování
Bez refresh vrací 12 hodin stejný výsledek z mezipaměti; čas kontroly u kontaktu se přesto přepíše.

Příklad

Insolvenční rejstřík je v příkladu nahrazený testovacími daty.

cURL

curl \
  -X POST \
  -H "X-API-Key: $SALDO_API_KEY" \
  "https://techtools.cz/ucetnictvi-api/entities/1/partners/1/insolvency?refresh=true"

JavaScript

const response = await fetch('https://techtools.cz/ucetnictvi-api/entities/1/partners/1/insolvency?refresh=true', {
  headers: { 'X-API-Key': process.env.SALDO_API_KEY },
  method: 'POST'
});
const data = await response.json();
Odpověď 200 OK
{
  "ico": "90000013",
  "insolvent": false,
  "proceedings": [],
  "checked_at": "2026-09-28T10:00:00.000Z",
  "partner": {
    "id": 1,
    "bank_account": null,
    "bic": null,
    "checked_at": null,
    "city": "Praha 10",
    "company_id": null,
    "country": "CZ",
    "created_at": "2026-09-28T10:00:00.000Z",
    "default_account_code": null,
    "dic": "CZ90000013",
    "due_days": 14,
    "email": "fakturace@example.cz",
    "iban": null,
    "ico": "90000013",
    "insolvency_checked_at": "2026-09-28T10:00:00.000Z",
    "insolvency_note": null,
    "insolvent": false,
    "name": "Nordwood Studio s.r.o.",
    "note": null,
    "phone": null,
    "street": "Korunní 1208/74",
    "unreliable": null,
    "updated_at": "2026-09-28T10:00:00.000Z",
    "vat_payer": null,
    "vies_checked_at": null,
    "vies_name": null,
    "vies_valid": null,
    "web": null,
    "zip": "10100",
    "stats": null
  }
}

Odpověď externí služby (insolvenční rejstřík) je v ukázce nahrazená smyšlenými údaji ve formátu, který služba vrací.