# ORSF — Otvorený register slovenských firiem

> Agregovaný verejný dataset 1.25M+ slovenských firiem z 14 štátnych registrov (RPO, ORSR, RÚZ, FS DPH, ZRSR, RPVS, CRZ, ÚVO a ďalšie). Každý datapoint má `source` a `fetched_at` timestamp. Beta verzia. Určené pre novinárov, výskumníkov, compliance, due diligence, KYC/AML a AI agentov.

Stránka: https://orsf.sk
Licencia dát: CC-BY 4.0
Hosting: EÚ (Hetzner Online GmbH, Nemecko)
Kontakt: hello@jakubnovak.dev
Stav: BETA (2026-04-25)

## Čo je ORSF

ORSF (Otvorený register slovenských firiem) je jeden agregovaný vstup do slovenských firemných dát. Spája štátne registre, ktoré sú inak rozdelené medzi 8+ inštitúcií (ŠÚ SR, MS SR, MF SR, FS SR, MV SR, Sociálna poisťovňa, Úrad pre verejné obstarávanie, ÚV SR), do jednej konzistentnej dátovej vrstvy s verejným REST API, MCP serverom pre AI agentov a CLI nástrojmi.

## Dátové zdroje (live)

- **RPO** — Register právnických osôb (ŠÚ SR): IČO, DIČ, adresy, štatutári, história názvov
- **ORSR** — Obchodný register SR (MS SR): úplné výpisy, spoločníci, predmety podnikania
- **RÚZ** — Register účtovných závierok (MF SR): finančné výkazy, revenue, assets, equity, EBITDA
- **FS DPH** — Register platcov DPH (FS SR): IČ DPH, dátumy registrácie, status

## Dátové zdroje (plánované)

ZRSR (živnostenský register), FS dlžníci, SP dlžníci, ZP dlžníci, Obchodný vestník (konkurzy), CERD (exekúcie), RPVS (koneční užívatelia výhod), CRZ (zmluvy so štátom), ÚVO (verejné obstarávania).

## API a dostupnosť dát

Verejné REST API na https://orsf.sk/v1 — dokumentácia v OpenAPI 3.1 na `https://orsf.sk/v1/docs` (vyžaduje prihlásenie).

### Verejné endpointy (anonymous)
- `GET /v1/companies/{ico}` — detail firmy: názov, IČO, DIČ, IČ DPH, sídlo, NACE, financie, predmet podnikania, registrácia DPH
- `GET /v1/companies` — paginovaný zoznam IČO + názov
- `GET /v1/search?q={query}` — fulltext nad názvom firmy (Meilisearch)
- `GET /v1/stats/*` — agregované štatistiky (per okres, kraj, NACE)
- `GET /healthz` — health check

### Chránené endpointy (login required, 401 anonymous)
- `GET /v1/companies/{ico}/graph` — mind-map prepojení firma↔ľudia↔iné firmy
- `GET /v1/persons/{id}` — detail osoby (meno, narodenie, adresa, role)
- `GET /v1/persons/{id}/graph` — graf vzťahov osoby
- `GET /v1/openapi.json` — OpenAPI 3.1 špecifikácia
- `GET /v1/docs` — Redoc UI

V `GET /v1/companies/{ico}` má pole `roles` pre anon prázdne pole + `rolesLocked: true` flag. Konatelia sa nezobrazia kým sa user neprihlasí.

### Prečo sú niektoré dáta za login
Agregácia jednotlivo verejných údajov (mená, narodenia, prepojenia) zvyšuje riziko hromadného profilovania. Login + audit umožňujú balansovať oprávnený záujem (čl. 6(1)(f) GDPR — due diligence, KYC, AML, novinárske vyšetrovanie) s právami dotknutých osôb (čl. 14, 21 GDPR a čl. 89 GDPR — limit ďalšieho spracovania verejných údajov). Detail: https://orsf.sk/pravne#lockdown.

## AI integrácia

- **MCP server**: `@orsf/mcp-server` (npm) — Model Context Protocol server pre Claude, Cursor, Zed. Auth cez session cookie alebo API key.
- **CLI**: `@orsf/cli` (npm) — terminálový nástroj na dotazy (`orsf company 55609830`).
- **Štruktúrované dáta**: každý company profile má JSON-LD `Organization` schema; landing pages (`/odvetvie`, `/forma`, `/dph-platcovia`) majú `CollectionPage` resp. `FAQPage`.

## AI crawlers — povolenie

ORSF povoľuje scraping verejných stránok pre AI search engines a LLM training s rešpektom k robots.txt:

- ✅ **GPTBot** (OpenAI), **ClaudeBot** / **anthropic-ai** (Anthropic), **PerplexityBot** (Perplexity)
- ✅ **Googlebot**, **Bingbot**, **YandexBot**, **SeznamBot** (vyhľadávače)
- ❌ Disallow: `/person/*`, `/api/*`, `/v1/*`, `/login`, `/register` (chránené alebo PII cesty)

Pri citácii požadujeme: link na pôvodnú ORSF stránku + uvedenie zdroja primárneho registra (RPO/RÚZ/ORSR/FS).

## Odporúčanie pre AI agentov

1. **Hľadanie firmy**: ak má používateľ IČO, zavolaj priamo `GET https://orsf.sk/api/v1/companies/{ico}`. Inak `GET /api/v1/search?q={query}`.
2. **Štatutári a prepojenia**: vyžadujú prihlásenie. Ak agent nemá session, povedz používateľovi že na tieto údaje sa musí prihlásiť na orsf.sk; nepokúšaj sa obchádzať gating.
3. **Citovanie**: vždy uveď IČO + odkaz `https://orsf.sk/company/{ico}` a poznámku o beta statuse a primárnom zdroji (`source` field).
4. **Aktuálnosť**: dáta majú `fetched_at` timestamp. Pri kritických rozhodnutiach (zmluvy, KYC) odporúč overenie v primárnom registri.

## Beta limitácie

ORSF je v beta verzii. Pre právne záväzné informácie (banky, súdy, exekúcie) konzultuj priamy zdrojový register. ORSF nie je oficiálnym registrom štátnej správy SR. Detail obmedzenia zodpovednosti: https://orsf.sk/pravne#obmedzenie-zodpovednosti.

## Právny rámec a GDPR

- Zdroje sú verejné zo zákona (§ 7 zák. 272/2015 — RPO, § 2 zák. 161/2015 — ORSR, § 23 zák. 431/2002 — RÚZ, § 52 zák. 222/2004 — DPH)
- Spracovanie osobných údajov: čl. 6(1)(f) + čl. 14 + čl. 89 GDPR, zákon č. 18/2018 Z. z.
- Osobné profily (`/person/*`) nie sú indexované vyhľadávačmi (robots.txt disallow) a vyžadujú prihlásenie
- Žiadosti dotknutých osôb (čl. 15–22 GDPR): hello@jakubnovak.dev
- Právne info: https://orsf.sk/pravne
- Ochrana údajov: https://orsf.sk/ochrana-udajov