# Subjekt API — Prehľad

Subjekt API je bezplatné verejné REST API pre vyhľadávanie slovenských a českých firiem. Bez registrácie, bez API kľúča. Jeden GET request vráti dostupné IČO, obchodný názov, DIČ, IČ DPH, adresu a právnu formu nájdeného subjektu. Pokrytie závisí od zdrojových registrov a ich aktuálnosti; niektoré polia môžu byť `null`.

## V1 endpointy

| Endpoint | Popis |
|---|---|
| `GET /v1/search` | Vyhľadávanie firiem podľa názvu alebo IČO |
| `GET /v1/entity/{ico}` | Kompletný detail entity vrátane zdrojových metadát |
| `GET /v1/health` | Stav API, počet entít, čas poslednej synchronizácie |

## Rýchly štart

### Vyhľadať firmu podľa názvu

```bash
curl "https://api.subjekt.sk/v1/search?q=slovnaft&country=sk&limit=5"
```

Vráti zoznam výsledkov s IČO, názvom, adresou, DIČ a IČ DPH. Ak existuje ďalšia stránka výsledkov, odpoveď obsahuje `next_cursor`.

### Získať detail firmy podľa IČO

```bash
curl "https://api.subjekt.sk/v1/entity/31322832?country=sk"
```

Vráti kompletný záznam vrátane právnej formy, dátumu vzniku, registrácie a zdrojových metadát (`source_system`, `source_country`, `source_license_class`).

### Overiť stav API

```bash
curl "https://api.subjekt.sk/v1/health"
```

Vráti počet entít v databáze, čas posledného syncu a `sync_lag_seconds` — koľko sekúnd uplynulo od poslednej synchronizácie SK dát.

## Dôležité upozornenie

> **CZ dáta sú informatívne.** České výsledky sú získavané živou proxy cez ARES (Administratívny register ekonomických subjektov). Nie sú to dáta z vlastnej databázy a nemajú charakter oficiálneho právneho výpisu. Dostupnosť závisí od ARES. Pre právne relevantné účely používajte priamo [ares.gov.cz](https://ares.gov.cz).

SK dáta pochádzajú z Registra právnických osôb (RPO) a evidencií Finančnej správy SR. RPO kontrolujeme denne a nový týždenný snapshot importujeme pri zmene; daňové identifikátory a registrácie DPH dorovnávame denne. Nová firma sa objaví po publikovaní v zdroji a úspešnom importe. Čas importu aj publikovania zdrojových dát uvádza `/v1/health` a stránka Stav.

## Integrácia do formulárov

- [Fakturačné údaje podľa IČO](./fakturacne-udaje.md) — automatické dopĺňanie firemných údajov.
- [Autocomplete názvu firmy](./autocomplete-firiem.md) — vyhľadávanie počas písania a výber správnej firmy.
- [DIČ a IČ DPH podľa IČO](./dic-ic-dph.md) — význam identifikátorov a obmedzenia overovania.

## Čo ďalej

- [GET /v1/search](./api/search.md) — parametre, stránkovanie, príklady
- [GET /v1/entity/{ico}](./api/entity.md) — všetky polia odpovede
- [Stránkovanie](./strankovanie.md) — cursor stránkovanie krok za krokom
- [SDK príklady](./sdk-priklady.md) — JavaScript, Python, PHP s error handlingom
- [Schémy odpovedí](./schemy-odpovedi.md) — kompletná tabuľka polí