Schémy JSON odpovedí

Táto stránka popisuje štruktúru všetkých objektov vrátených API. Každý endpoint vracia buď dátový objekt, alebo chybový objekt vo formáte ErrorResponse.

SearchResponse

Odpoveď GET /v1/search.

Pole	Typ	Nullable	Popis
`results`	SearchResult[]	nie	Výsledky na tejto stránke, najviac `limit`
`count`	integer	nie	Počet výsledkov na tejto stránke, nie celkový počet zhôd
`country`	string	nie	Požadovaný filter: `"sk"`, `"cz"` alebo `"both"`
`ms`	integer	nie	Čas spracovania v milisekundách
`next_cursor`	string	áno	Cursor pre ďalšiu stránku; `null`, ak ďalšia stránka neexistuje
`truncated`	boolean	nie	`true` na poslednej stránke, ak zhôd je viac ako 250. Spresnite dopyt.
`warnings`	object[]	nie	Upozornenia, že niektorý požadovaný zdroj nevrátil nič zo známeho dôvodu a výsledky sú neúplné. Prázdne pole, ak odpovedali všetky zdroje. Každá položka má `code` a `message`.

Jediný kód v warnings je zatiaľ cz_query_too_broad: ARES odmieta vyhľadávanie podľa názvu, ak má dopyt viac ako 1 000 zhôd (napríklad milan). Pri country=both API vráti SK výsledky s týmto upozornením, pri country=cz vráti 400 s details.reason = "cz_query_too_broad". Riešením je presnejší dopyt.

SearchResult

Jeden výsledok zo zoznamu results pri volaní GET /v1/search.

Pole	Typ	Nullable	Popis
`ico`	string	nie	Identifikačné číslo organizácie (8 číslic)
`name`	string	nie	Obchodný názov firmy
`address`	Address	nie	Sídlo firmy (pozri tabuľku Address nižšie)
`legal_form`	string	áno	Právna forma v textovom formáte (napr. "Akciová spoločnosť")
`dic`	string	áno	Daňové identifikačné číslo
`ic_dph`	string	áno	Identifikačné číslo pre DPH (napr. "SK7120001713")
`established`	string	áno	Dátum vzniku vo formáte ISO 8601 (napr. "1992-01-01")
`registration`	Registration	áno	Zápis do registra (pozri tabuľku Registration nižšie)

Entity

Odpoveď GET /v1/entity/{ico}. Obsahuje všetky polia SearchResult a navyše:

Pole	Typ	Nullable	Popis
`legal_form_code`	string	áno	Kód právnej formy z registra (iba SK; pri CZ je null)
`terminated`	string	áno	Dátum zániku (ISO 8601); null ak je firma aktívna
`source`	string	nie	Zdroj záznamu (`"subjekt.sk"` pre SK, `"ares_proxy"` pre CZ)
`updated_at`	string	áno	SK dátum zmeny poľa v databáze; CZ dátum aktualizácie v ARES. Nie čas kontroly zdroja.
`source_country`	string	nie	Krajina zdroja: `"sk"` alebo `"cz"`
`source_system`	string	nie	Zdroj základného záznamu: `"rpo"` (SK) alebo `"ares"` (CZ)
`source_license_class`	string	nie	Licencia zdrojových dát: `"cc_by_4_0"` (RPO) alebo `"ares_terms"` (ARES)
`dic_source_system`	string	áno	Zdroj DIČ: `fs`, `ruz`, `ares` alebo null
`source_terms_url`	string	nie	URL podmienok používania zdrojových dát

Address

Štruktúra sídla firmy. Nachádza sa vo všetkých odpovediach (search aj entity).

Pole	Typ	Nullable	Popis
`street`	string	áno	Ulica (bez čísla). Vo výsledkoch vyhľadávania je pri fyzických osobách – podnikateľoch vždy `null` spolu s `building_no`; celú adresu vráti detail `/v1/entity/{ico}`.
`building_no`	string	áno	Číslo budovy / súpisné číslo
`city`	string	áno	Mesto
`zip`	string	áno	PSČ
`country`	string	nie	Kód krajiny veľkými písmenami (napr. `"SK"`, `"CZ"`)

Registration

Záznam o zápise firmy do obchodného alebo iného registra.

Pole	Typ	Nullable	Popis
`office`	string	áno	Registrový súd alebo úrad (napr. "Mestský súd Bratislava III")
`number`	string	áno	Číslo zápisu v registri (napr. "Sa/426/B")

ErrorResponse

Vracia sa pri všetkých chybových stavoch (4xx, 5xx).

Pole	Typ	Nullable	Popis
`code`	string	nie	Strojovo čitateľný kód chyby (napr. `"invalid_request"`, `"not_found"`)
`message`	string	nie	Ľudsky čitateľný popis chyby v angličtine
`request_id`	string	nie	Unikátne ID requestu pre debugovanie (UUID formát)
`details`	objekt	—	Iba pri niektorých chybách, napríklad `{ "reason": "managed" }` pri `429`; inak pole chýba

Kompletný zoznam chybových kódov a odporúčaní na riešenie nájdete na stránke Chyby a kódy.