# Schémy 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](./chyby-a-kody.md).