# FirmAPI – API dokumentácia

Base URL: `https://firmapi.sk/v1`

FirmAPI poskytuje REST API pre slovenské firemné dáta a rozšírené obohatenia – daňové údaje, bankové účty, kontakty, finančné ukazovatele, účtovné závierky, insolvenciu, verejné zákazky a notifikácie cez webhook alebo email.

## Autentifikácia

Každá požiadavka vyžaduje API kľúč. Kľúč získate zadarmo po registrácii na https://firmapi.sk/registracia a spravujete ho v dashboarde na https://firmapi.sk/panel/api-kluce. Podporované sú dve rovnocenné hlavičky.

```bash
curl -H "X-API-Key: fa_your_key" "https://firmapi.sk/v1/company/ico/51636549"
```

```bash
curl -H "Authorization: Bearer fa_your_key" "https://firmapi.sk/v1/company/ico/51636549"
```

## Sandbox

Vyskúšanie API bez registrácie – 10 demo firiem s kompletnými údajmi, bez limitov, s neobmedzeným počtom volaní. Ideálne na vývoj a integračné testovanie.

Sandbox API kľúč: `fa_sandbox_test_key_firmapi_sk_2026`

| Endpoint | Popis | Auth |
|---|---|---|
| `GET /v1/sandbox/companies` | Zoznam demo firiem | Nie je potrebný |
| `GET /v1/sandbox/company/ico/{ico}` | Kompletný profil firmy so všetkými scope | Nie je potrebný |
| `GET /v1/sandbox/search/autocomplete?q=` | Vyhľadávanie v demo firmách | Sandbox kľúč |

SDK skratky pre sandbox režim: PHP `\FirmApi\Client::sandbox()`, JavaScript/TypeScript `FirmApi.sandbox()`.

## Zdroje dát

FirmAPI agreguje základné registre a doplnkové enrichment zdroje do jednej odpovede.

| Zdroj | Dáta | Frekvencia aktualizácie |
|---|---|---|
| RPO (Register právnických osôb) | Názov, IČO, sídlo, právna forma, stav | Denne |
| ORSR (Obchodný register) | Spoločníci, štatutárne orgány, predmety podnikania, základné imanie | Na vyžiadanie / mesačne |
| Daňové a finančné zdroje | DIČ, IČ DPH, platca DPH, základné finančné ukazovatele, účtovné závierky | Priebežne podľa dostupnosti zdroja |
| EU VIES | Overenie platnosti IČ DPH | Na vyžiadanie (cache 7 dní) |
| Verejné registre a vestníky | Dlžnícke zoznamy, obchodný vestník, insolvencia, verejné zmluvy a obstarávania, ÚVO, súdne rozhodnutia, sankčné zoznamy (EÚ/OFAC) a ďalšie verejné registre | Priebežne podľa dostupnosti zdroja |

## Neaktuálne dáta a obnova na pozadí

FirmAPI vracia posledné dostupné dáta okamžite a snaží sa udržiavať dáta zo zdrojov mladšie ako 10 dní. Ak sú ORSR detaily staršie ako 30 dní alebo doplnkové dáta staršie ako 10 dní, automaticky sa spustí obnova na pozadí (zvyčajne dokončená do 10 – 15 sekúnd) a odpoveď obsahuje príznaky neaktuálnosti:

- `meta.stale: true` – dáta sú neaktuálne
- `meta.retry_at` – ISO 8601 časová značka, kedy znova požiadať o aktuálne dáta
- `meta.stale_reason` – napr. `orsr_data_outdated`, `enrichment_data_outdated` alebo `orsr_and_enrichment_data_stale`

Rovnakú požiadavku zopakujte po čase `retry_at`.

```json
{
  "data": { "...": "..." },
  "meta": {
    "rpo_updated_at": "2026-02-05T06:00:00Z",
    "orsr_synced_at": "2025-12-01T14:30:00Z",
    "source": "database",
    "stale": true,
    "retry_at": "2026-02-05T12:00:15Z",
    "stale_reason": "orsr_data_outdated"
  }
}
```

## Endpointy

### Stav služby (verejné, bez API kľúča)

| Endpoint | Popis |
|---|---|
| `GET /status` | Stav API a dostupnosť služby |
| `GET /health` | Health-check pre monitoring |

### Firmy

| Endpoint | Popis |
|---|---|
| `GET /company/ico/{ico}` | Detail firmy podľa 8-miestneho IČO |
| `GET /company/id/{orsrId}` | Detail firmy podľa interného ID z Obchodného registra |
| `GET /company/{id}` | Detail firmy podľa interného databázového ID |

Query parameter `scope` (čiarkou oddelený zoznam) riadi rozsah odpovede pre `/company/*` endpointy. Bez neho sa vracajú len základné údaje (názov, adresa, stav) – najrýchlejšia odpoveď. `scope=all` vráti kompletný profil. Každý scope vyžaduje príslušnú funkciu vo vašom pláne:

`tax, bank_accounts, contacts, financials, debtor_status, financial_statements, insolvency, execution_authorizations, rpvs, nbs, tax_reliability, erased_vat, commercial_bulletin, public_contracts, procurement, trade_license_activities, reges, contracting_authority, debarred, uvo_references, crp_projects, ted_tenders, gleif, sanctions, social_enterprise, replik_administrator, sbs, transport_licence, utility_licence, fs_imports, illegal_employment, court_decisions, employer_headcount, soi_travel_agency, svps_establishments`

```bash
curl -H "Authorization: Bearer fa_your_key" \
  "https://firmapi.sk/v1/company/ico/51636549?scope=tax,financials,debtor_status"
```

```json
{
  "data": {
    "ico": "51636549",
    "name": "Version Two s. r. o.",
    "legal_form": "Spoločnosť s ručením obmedzeným",
    "legal_form_code": "112",
    "address": {"street": "Hlavná 1", "city": "Bratislava", "postal_code": "81101", "country": "Slovensko"},
    "established_date": "2018-05-15",
    "terminated_date": null,
    "source_register": "Obchodný register",
    "status": "active",
    "orsr_id": "427482",
    "registration_date": "2018-05-15",
    "business_activities": "Počítačové služby...",
    "registered_capital": "5 000 EUR",
    "shareholders": [{"name": "John Doe", "address": "Bratislava", "share_amount": "5000 EUR", "share_percentage": "100%"}],
    "statutory_body": [{"name": "John Doe", "role": "konateľ", "address": "Bratislava"}]
  },
  "meta": {"rpo_updated_at": "2026-02-05T06:00:00Z", "orsr_synced_at": "2026-01-20T14:30:00Z", "source": "database"}
}
```

### Vyhľadávanie

| Endpoint | Parametre | Popis |
|---|---|---|
| `GET /search/autocomplete?q=` | `q` (min. 2 znaky), `limit` (predvolené 10, max. 20) | Autocomplete pre Select2/typeahead – vracia `{id, text, ico, city}` |
| `GET /search/name?q=` | `q` (min. 3 znaky), `exact` (0 alebo 1, predvolené 0), `limit` (predvolené 10, max. 100), `offset` (predvolené 0) | Vyhľadávanie podľa názvu so stránkovaním |
| `GET /search/ico?q=` | `q` (čiastočné IČO), `limit` (predvolené 10, max. 100) | Vyhľadávanie podľa čiastočného IČO |
| `GET /search/advanced` | `name`, `city`, `legal_form` | Vyhľadávanie podľa viacerých polí s rôznymi filtrami |

```json
{
  "results": [
    {"id": "51636549", "text": "Version Two s. r. o.", "ico": "51636549", "city": "Bratislava"}
  ],
  "pagination": {"more": false}
}
```

### Batch (vyžaduje plán Starter a vyšší)

| Endpoint | Popis |
|---|---|
| `POST /batch/ico` | Hromadné načítanie firiem podľa zoznamu IČO – telo `{"icos": ["51636549", "..."]}` |
| `POST /batch/names` | Hromadné vyhľadávanie podľa zoznamu názvov – telo `{"names": ["Version Two s. r. o.", "..."]}` |
| `GET /batch/{batchId}/status` | Stav spracovania hromadnej operácie |
| `GET /batch/{batchId}/results` | Výsledky hromadnej operácie (po obmedzenom čase expirujú) |

```json
{
  "data": {
    "51636549": {"found": true, "data": {"...": "..."}},
    "87654321": {"found": false, "data": null}
  },
  "meta": {"total": 2, "found": 1, "not_found": 1}
}
```

### Účet

| Endpoint | Popis |
|---|---|
| `GET /account/usage` | Štatistiky využitia za aktuálne obdobie |
| `GET /account/quota` | Zostávajúca kvóta za aktuálne fakturačné obdobie |
| `GET /account/history?days=` | História využitia; `days` predvolené 30, max. 365 |
| `POST /account/thresholds` | Nastavenie prahov upozornení na spotrebu kreditov |

### Notifikácie (webhooky a email)

| Endpoint | Popis |
|---|---|
| `GET /notifications` | Zoznam aktívnych a historických notifikačných subscription záznamov |
| `POST /notifications` | Vytvorenie alebo aktualizácia odberu zmien pre konkrétne IČO (webhook, email alebo oboje) |
| `DELETE /notifications/{ico}` | Odstránenie subscription pre dané IČO |
| `GET /notifications/{subscriptionId}/deliveries` | História doručení pre danú subscription (kanál, stav, počet pokusov) |
| `GET /notifications/history/{ico}` | História zistených zmien pre dané IČO |
| `POST /notifications/test` | Testovacie doručenie – overí cieľ bez vytvorenia trvalej subscription |

```json
{
  "ico": "51636549",
  "webhook_url": "https://example.com/firmapi/webhook",
  "notification_emails": ["ops@example.com", "alerts@example.com"],
  "events": ["updated"]
}
```

## Formát odpovede a dátový model

Firemné endpointy vracajú JSON objekt s poľami `data` a `meta`. Objekt `data` obsahuje dostupné firemné údaje rozdelené do kategórií:

- **Základné informácie** (RPO) – `ico`, `name`, `legal_form`, `legal_form_code`, `address` (street, city, postal_code, country), `status` (active/terminated/deleted), `established_date`, `terminated_date`, `source_register`.
- **Daňové informácie** (`tax`) – `dic`, `ic_dph`, `is_vat_payer`, `vies_valid`, `vies_verified_at`.
- **Detaily z ORSR** (len firmy zapísané v Obchodnom registri) – `orsr_id`, `shareholders` (name, address, share_amount, share_percentage, is_company, ico), `statutory_body` (name, role, address, acting_method), `business_activities`, `registered_capital`, `registration_date`.
- **Kontakty, účty a financie** (voliteľné, podľa plánu) – `bank_accounts` (IBAN, banka, publikovaný účet), `contacts` (emaily, telefóny, weby podľa typu), `financials` (rok, tržby, zisk, aktíva, počet zamestnancov).
- **Rizikové a compliance dáta** – `debtor_status`, `financial_statements` (latest, available_years), `insolvency`, `commercial_bulletin`, `public_contracts_summary`, `procurement_summary`.
- **Meta polia** – `rpo_updated_at`, `orsr_synced_at`, `enriched_at`, `source` (database/cache/live), `cached`, `stale`, `retry_at`, `stale_reason`.

## Webhooky – detaily

Nastavenie prebieha v dashboarde alebo cez `POST /notifications`. Každá webhook subscription dostane unikátny HMAC tajný kľúč na overenie podpisu.

Typ udalosti: `company.updated` – vyvolaná pri zmene existujúcich firemných dát (napr. zmena adresy, noví spoločníci, zmena stavu). Doručenie prebieha cez nakonfigurovaný `webhook_url`, pole `notification_emails`, alebo oboje.

Štruktúra payloadu:

```json
{
  "event": "company.updated",
  "timestamp": "2026-02-05T12:00:00Z",
  "data": {
    "ico": "51636549",
    "change_type": "updated",
    "field": "address",
    "old_value": "Hlavná 1, 81101 Bratislava",
    "new_value": "Mlynské nivy 5, 82109 Bratislava",
    "detected_at": "2026-02-05T06:15:00Z",
    "company": {"name": "Version Two s. r. o.", "legal_form": "Spoločnosť s ručením obmedzeným", "city": "Bratislava", "status": "active"},
    "tax_info": {"dic": "2120776680", "ic_dph": "SK2120776680", "is_vat_payer": true}
  }
}
```

Email notifikácie nesú rovnaký význam udalosti, doručujú sa ako čitateľné upozornenie bez HMAC hlavičiek.

Hlavičky webhook požiadavky:

- `X-Webhook-Signature` – HMAC-SHA256 podpis tela požiadavky pomocou vášho webhook tajného kľúča
- `X-Webhook-Event` – typ udalosti (napr. `company.updated`)
- `X-Webhook-Delivery-Id` – unikátny identifikátor doručenia pre idempotentnosť

Overenie podpisu (PHP):

```php
$signature = $request->header('X-Webhook-Signature');
$payload = $request->getContent();
$expected = hash_hmac('sha256', $payload, $webhookSecret);

if (hash_equals($expected, $signature)) {
    // podpis je platný
}
```

Ak webhook endpoint vráti iný než 2xx stavový kód, FirmAPI zopakuje doručenie s exponenciálnym odstupom. História doručení je dostupná cez `GET /notifications/{subscriptionId}/deliveries`. Email notifikácie sa evidujú v tom istom delivery logu s kanálom `email`.

## Limity požiadaviek

Limity závisia od vášho predplatného. Každá odpoveď obsahuje hlavičky:

- `X-RateLimit-Limit-Minute` – povolené požiadavky za minútu
- `X-RateLimit-Remaining-Minute` – zostávajúce požiadavky v tejto minúte
- `X-RateLimit-Limit-Daily` – povolené požiadavky za deň
- `X-RateLimit-Remaining-Daily` – zostávajúce požiadavky dnes

## Chyby

Všetky chyby vracajú JSON objekt s poľami `error` a `message`.

| Kód | Chyba | Popis |
|---|---|---|
| 401 | `unauthorized` | Neplatný alebo chýbajúci API kľúč |
| 402 | `credits_exhausted` | Kredity vyčerpané – doplňte kredity alebo povoľte overage |
| 403 | `forbidden` | Funkcia nie je dostupná vo vašom pláne |
| 404 | `not_found` | Firma sa nenašla |
| 422 | `validation_error` | Neplatné parametre požiadavky |
| 429 | `rate_limit_exceeded` | Príliš veľa požiadaviek |
| 503 | `service_unavailable` | Služba je dočasne nedostupná |

---

Kompletná interaktívna dokumentácia s príkladmi kódu: https://firmapi.sk/dokumentacia · Príklady použitia: https://firmapi.sk/priklady-pouzitia.md · Cenník: https://firmapi.sk/cennik.md · Zdroje dát: https://firmapi.sk/ake-data-poskytujeme.md