Kontakty

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

V příručce

Vydané faktury › Odběratel

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

Odpověď

200 application/json Pole kontaktů.

Chování

Co změní

Nic nezapisuje.

Limity

Nejvýše 500 kontaktů, bez stránkování.

Příklad

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

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

[
  {
    "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,
    "web": null,
    "zip": "10100",
    "stats": {
      "sales": 447400.0,
      "purchases": 0.0,
      "open_documents": 1
    }
  }
]

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

V příručce

Vydané faktury › Odběratel

Založí odběratele nebo dodavatele. IČO se doplní nulami na 8 číslic, DIČ převede na velká písmena bez mezer (k 8–10 číslicím se doplní CZ), 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

Tělo požadavku

Formát application/json.

Odpověď

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

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 \
  -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

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

{
  "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,
  "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

Odpověď

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

Chování

Co změní

Nic nezapisuje.

Limity

Nejvýše 100 dokladů.

Příklad

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

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

{
  "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,
  "web": null,
  "zip": "10100",
  "stats": {
    "sales": 447400.0,
    "purchases": 0.0,
    "open_documents": 1
  },
  "documents": [
    {
      "id": 145,
      "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
    },
    {
      "id": 143,
      "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
    }
  ]
}

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 a jejich úpravy jsou stejné jako při založení. 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

Tělo požadavku

Formát application/json.

Odpověď

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

Chování

Co změní

Uloží kontakt; samotná změna kontaktu se do historie změn nezapisuje. 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 \
  -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

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

{
  "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,
  "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

Odpověď

204 Bez obsahu.

Chyby této operace

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

Chování

Co změní

Smaže kontakt. Do historie změn nezapisuje.

Opakování

Druhé volání vrátí 404.

Příklad

Potřebuje kontakt bez dokladů.

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

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

soubor, 0 bajtů

GET Údaje subjektu z ARES pro nový kontakt

/entities/{entity_id}/partners/lookup

Oprávnění

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

Pravidlo

Stačí přihlášení nebo API klíč. Členství ve firmě z cesty se neověřuje, entity_id nemusí patřit volajícímu.

Klíč jen pro čtení

Stačí

V příručce

Vydané faktury › Odběratel

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í 502 s chybou „Neplatné IČO“.

Parametry

Odpověď

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

Chyby této operace

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

Chování

Co změní

Nic nezapisuje. Volá ARES dvakrát (údaje subjektu a stav DPH).

Limity

Časový limit dotazu do ARES je 8 s. Vlastní omezení počtu dotazů ani mezipaměť tato cesta nemá.

Příklad

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

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

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

{
  "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, dostane oba příznaky prázdné, ale čas kontroly se mu uloží.

Parametry

Odpověď

200 application/json Souhrn kontroly.

Chyby této operace

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

Chování

Co změní

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 \
  -X POST \
  -H "X-API-Key: $SALDO_API_KEY" \
  https://techtools.cz/ucetnictvi-api/entities/1/partners/vat_registry_all

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

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

Odpověď

200 application/json Souhrn várky.

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 \
  -X POST \
  -H "X-API-Key: $SALDO_API_KEY" \
  https://techtools.cz/ucetnictvi-api/entities/1/partners/insolvency_all

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

{
  "checked": 12,
  "remaining": 1,
  "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). Protože jde o GET, projde i s API klíčem jen pro čtení a výsledek ke kontaktu uloží.

Klíč jen pro čtení

Stačí

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. Kvůli chybě v kódu teď vrací 500, kdykoli registr DIČ ve své odpovědi uvede; výsledek se ke kontaktu přesto uloží.

Parametry

Odpověď

200 application/json Zamýšlený tvar je { status, account, account_published }. Skutečně se 200 vrátí jen tehdy, když registr DIČ neuvede, a to bez klíče status.

Chyby této operace

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

Chování

Co změní

Uloží ke kontaktu vat_payer, unreliable a checked_at. Do historie změn nezapisuje. Volá registr plátců DPH.

Opakování

Každé volání ověří DIČ znovu.

Příklad

Ukázka odpovědi chybí: operace teď při nalezeném DIČ končí chybou 500 (chyba aplikace), takže skutečnou odpověď nešlo zaznamenat. Stav plátce se přitom u kontaktu uloží.

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

Odpověď

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

Chyby této operace

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

Chování

Co změní

Uloží 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 \
  -X POST \
  -H "X-API-Key: $SALDO_API_KEY" \
  "https://techtools.cz/ucetnictvi-api/entities/1/partners/1/insolvency?refresh=true"

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

{
  "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,
    "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í.