Účtování – Dokumentace | handelsregister.ai

Ceny podle endpointu a funkce

API účtuje v kreditech. Každý požadavek stojí základní cenu svého endpointu plus funkce, které vrátí data, a případné zvolené příplatky. Ceny jsou ve všech tarifech stejné. Tvůj tarif rozhoduje, které funkce můžeš používat.

Endpoint
Endpoint	Co	Kredity
fetch-organization	Profil firmy se základními údaji	5
fetch-organization	Funkce, viz další tabulka	1 až 80
fetch-organization	Příplatek za AI režim, i bez nalezené shody	+20
fetch-organization	Příplatek za režim v reálném čase, za každé úspěšné živé načtení	+10
fetch-person	Profil osoby, včetně rešerše na webu (od tarifu Plus)	15
fetch-person	Funkce `shareholdings`, jen když vrátí data	+5
fetch-person	Funkce `network` (Pro, Max), jen když vrátí data	+25
search-organizations	Jedna stránka výsledků, i prázdná	1
fetch-document	Jeden doručený dokument	15
signals	Jedna stránka Signals nebo jeden signál	20
signals	Katalog témat `/v1/signals/catalog`	zdarma
account, auth	Účet, zůstatek, využití, klíče, tokeny a webhook endpointy	zdarma

Funkce endpointu fetch-organization si vyžádáš jednotlivě. Každá stojí jen tehdy, když vrátí data:

Funkce
Funkce	Obsah	Kredity	Tarif
related_persons	Vedení	2	každý účet
shareholders	Společníci (Beta)	5	každý účet
shareholders_deep	Podrobní společníci	80	Max
ubos	Skuteční majitelé (UBO, Beta)	10	každý účet
shareholdings	Majetkové účasti (Beta)	5	každý účet
mergers_and_acquisitions	Fúze a akvizice (M&A, Beta)	20	každý účet
network	Síť firmy (Beta)	25	Pro, Max
publications	Historie: rejstříková oznámení	1	každý účet
financial_kpi	Finanční KPI	1	každý účet
balance_sheet_accounts	Rozvaha	3	každý účet
profit_and_loss_account	Výkaz zisku a ztráty	3	každý účet
annual_financial_statements	Roční účetní závěrky (Markdown)	5	každý účet
annual_financial_statements__html	Roční účetní závěrky (HTML)	5	každý účet
insolvency_publications	Insolvenční oznámení	5	každý účet
news	Zprávy	10	každý účet
website_content	Obsah webu · jen s AI režimem	zdarma	každý účet

Se všemi funkcemi a oběma příplatky stojí požadavek na fetch-organization nejvýše 215 kreditů. Tento rozsah je součástí tarifu Max.

Monitor stojí pevnou cenu za období 30 dní, podle intervalu kontrol. Vytvoření a první výchozí stav jsou zdarma.

Interval kontrol
Interval kontrol	Kredity za 30 dní
každý den	50
každé 3 dny	40
každých 7 dní	20
každých 30 dní	10
Každá další úspěšná kontrola v období	+2

Interval mezi těmito stupni stojí tolik jako nejbližší častější stupeň. Více v account/monitors.

Platíš jen za to, co vrátí data

Funkce bez dat nestojí nic. Pokud vrátí null nebo prázdný seznam, neplatíš za ni. To platí pro každou funkci, včetně insolvency_publications: bez insolvenčních oznámení je zdarma.

Základní cena a příplatky se řídí vlastními pravidly. Základní cenu platíš za každý doručený profil firmy. AI režim stojí i bez shody. Režim v reálném čase stojí za každé úspěšné živé načtení, i když se v rejstříku nic nezměnilo. Více v části Příplatky.

U některých funkcí záleží na konkrétním obsahu:

shareholders a shareholders_deep stojí jen tehdy, když existují aktuální záznamy. Samotná historie je zdarma.
mergers_and_acquisitions stojí jen s transakcemi, ovládacími vztahy nebo právními nástupnictvími.
network stojí jen s alespoň jednou vazbou.
news stojí, jakmile seznam obsahuje alespoň jeden článek.

fetch-organization vynechá funkci, kterou tvůj tarif nezahrnuje, a neúčtuje ji.

U Vyhledávání a export, dokumentů a Signals platíš za samotný požadavek: jednu stránku výsledků, jeden dokument, jednu stránku Signals. Hledání bez výsledků a prázdná stránka Signals se účtují také.

Neúspěšný nebo odmítnutý požadavek nestojí nic, viz Chyby.

Příplatky za AI režim a režim v reálném čase

fetch-organization má dva příplatky, které zapínáš pro každý požadavek zvlášť.

AI režim (ai_search=on-default, +20 kreditů) najde firmu i z nepřesného vstupu a hledá na webu. Účtuje se, jakmile rešerše proběhla, i když nenajde žádnou firmu nebo zdroj dat ohlásí chybu. Jen když API požadavek ukončí s 408, neúčtuje se.

Režim v reálném čase (realtime_mode=handelsregister-default, +10 kreditů) načte zapsané osoby živě z Handelsregister (obchodní rejstřík). Příplatek účtujeme, když živé načtení uspěje, bez ohledu na to, co vrátí. Pak má _realtime_mode.status hodnotu success.

Jakákoli jiná hodnota tam znamená, že živé načtení selhalo. Pak dostaneš uložená data a platíš za zbytek požadavku, bez příplatku za režim v reálném čase. Pokud požadavek trvá příliš dlouho, API odpoví 408 a nic neúčtuje.

1{2  "name": "Hetzner Online GmbH",3  "_realtime_mode": {4    "mode": "handelsregister-default",5    "status": "success"6  },7  "meta": {8    "request_credit_cost": 15,9    "credits_remaining": 14510  }11}

200 · Ukázková odpověď pro základní údaje v režimu v reálném čase: základní cena plus příplatek

Náklady v odpovědi

Každá odpověď ti řekne, kolik stála. V odpovědích JSON je to v meta, u dokumentů v headerech.

Kde
Kde	Význam
meta.request_credit_cost	Kolik tento požadavek stál. U opakování s idempotency klíčem a téměř všech chyb je to `0`.
meta.credits_remaining	Tvůj zůstatek po požadavku.
X-Credits-Charged	signals a doručený dokument: kolik požadavek stál, jako header.
X-Credits-Remaining	Doručený dokument: tvůj zůstatek po požadavku, jako header.

1{2  "name": "Hetzner Online GmbH",3  "meta": {4    "request_credit_cost": 5,5    "credits_remaining": 1456  }7}

200 · Konec ukázkové odpovědi z fetch-organization

Odmítnutí při autentizaci (401, 403) a nad limit (429) obvykle přicházejí bez meta. Nikdy nic nestojí.

Každé zaúčtování najdeš v Účet › Využití a přes API na GET /v1/account/usage/transactions, viz account.

Nedostatek kreditů

Než API požadavek zpracuje, zkontroluje, zda tvůj zůstatek pokryje nejvyšší možné náklady: základní cenu, všechny požadované funkce a příplatky. Pokud ne, API odpoví 402 a nic neúčtuje.

Odpověď ukazuje toto maximum v meta.request_credit_cost a tvůj zůstatek v meta.credits_remaining. Později zaúčtovaná částka bývá často nižší, protože funkce bez dat nic nestojí.

Příklad: základní údaje s AI režimem a funkcí ubos potřebují předem 35 kreditů. Pokud ubos nevrátí data, požadavek stojí 25 kreditů.

signals odpovídá ve formátu Problem Details s kódem INSUFFICIENT_CREDITS.

Předplatné kreditů a dobití kreditů

Každý nový účet dostane 150 startovních kreditů. Platí 30 dní.

S předplatným kreditů (Plus, Pro, Max nebo Enterprise) dostáváš kredity každý měsíc. Platí do konce zúčtovacího období. Pokud změníš tarif, nevyčerpané měsíční kredity si převedeš do nového období. Od tarifu Plus můžeš používat fetch-person; Pro a Max odemykají další data.

Dobití kreditů kupuješ jednorázově, navíc. Bez předplatného kreditů platí 30 dní. Dokud běží předplatné kreditů, nepropadá ani dobití kreditů, ani startovní kredity.

Svůj zůstatek a co kdy propadá, vidíš v Účet › Kredity a přes API na GET /v1/account/credits.

Všechny tarify a ceny najdeš na stránce s ceníkem.