API

API Dokumentácia

FirmAPI poskytuje REST API na prístup k slovenským firemným dátam agregovaným z viacerých oficiálnych registrov (RPO, ORSR, ZRSR) s automatickým obohatením z daňových úradov a EU VIES.

Autentifikácia

Všetky API požiadavky vyžadujú autentifikáciu pomocou API kľúča. API kľúče si môžete vytvoriť vo svojom dashboarde.

Pridajte API kľúč do hlavičky Authorization:

Authorization: Bearer YOUR_API_KEY

Alebo použite hlavičku X-API-Key:

X-API-Key: YOUR_API_KEY

Základná URL

https://api.firmapi.sk/v1

Zdroje dát

FirmAPI agreguje dáta z viacerých slovenských registrov 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
RegisterÚZ / Finančná správa	DIČ, IČ DPH, platca DPH	Denne (pri zmene)
EU VIES	Overenie platnosti IČ DPH	Na vyžiadanie (cache 7 dní)

Neaktuálne dáta a obnova na pozadí

Pre firmy zapísané v obchodnom registri (ORSR) sú podrobné dáta (spoločníci, štatutárne orgány, predmety podnikania) pravidelne obnovované z ORSR.sk.

Ak sú dáta z ORSR staršie ako 30 dní, API vráti existujúce (neaktuálne) dáta okamžite a zaradí obnovu na pozadí. Odpoveď bude obsahovať:

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 — buď orsr_data_outdated alebo orsr_data_not_available

Jednoducho zopakujte rovnakú požiadavku po čase retry_at pre získanie aktuálnych dát. Obnova na pozadí sa zvyčajne dokončí za 10 – 15 sekúnd.

{
  "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

GET /company/ico/{ico}

Získať údaje o firme podľa IČO (identifikačné číslo organizácie).

Parametre

ico

string

8-miestne identifikačné číslo organizácie

Príklad požiadavky

curl -X GET "https://api.firmapi.sk/v1/company/ico/51636549" \
     -H "Authorization: Bearer YOUR_API_KEY"

Príklad odpovede

{
  "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"
  }
}

GET /search/autocomplete

Vyhľadávanie firiem podľa názvu alebo IČO s automatickým dopĺňaním. Vracia formát kompatibilný so Select2.

Query parametre

q	string	Vyhľadávací dopyt (min 2 znaky)
limit	integer	Max. výsledkov (predvolené: 10, max: 20)

Príklad odpovede

{
  "results": [
    {"id": "51636549", "text": "Version Two s. r. o.", "ico": "51636549", "city": "Bratislava"},
    {"id": "12345678", "text": "Version s.r.o.", "ico": "12345678", "city": "Košice"}
  ],
  "pagination": {"more": false}
}

GET /company/id/{orsr_id}

Získať údaje o firme podľa interného ID z obchodného registra.

Príklad požiadavky

curl -X GET "https://api.firmapi.sk/v1/company/id/427482" \
     -H "Authorization: Bearer YOUR_API_KEY"

GET /company/{id}

Získať údaje o firme podľa interného databázového ID.

Príklad požiadavky

curl -X GET "https://api.firmapi.sk/v1/company/12345" \
     -H "Authorization: Bearer YOUR_API_KEY"

GET /search/name

Vyhľadávanie firiem podľa názvu so stránkovaním.

Query parametre

q	string	Názov firmy (min 3 znaky)
exact	integer	Presná zhoda (0 alebo 1, predvolené: 0)
limit	integer	Max. výsledkov (predvolené: 10, max: 100)
offset	integer	Offset stránkovania (predvolené: 0)

GET /search/ico

Vyhľadávanie firiem podľa čiastočného IČO.

Query parametre

q	string	Čiastočné IČO
limit	integer	Max. výsledkov (predvolené: 10, max: 100)

GET /search/advanced

Vyhľadávanie podľa viacerých polí s rôznymi filtrami.

Query parametre

name	string	Názov firmy
city	string	Mesto
legal_form	string	Právna forma

POST /batch/ico Vyžaduje plán Starter+

Hromadné vyhľadanie viacerých firiem podľa IČO. Vyžaduje plán Starter alebo vyšší.

Telo požiadavky

{
  "icos": ["51636549", "12345678", "87654321"]
}

Príklad odpovede

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

POST /batch/names Vyžaduje plán Starter+

Hromadné vyhľadanie viacerých firiem podľa názvu. Vyžaduje plán Starter alebo vyšší.

Telo požiadavky

{
  "names": ["Version Two s. r. o.", "Example Company"]
}

GET /account/usage

Získať štatistiky využitia za aktuálne obdobie.

GET /account/quota

Získať zostávajúcu kvótu za aktuálne fakturačné obdobie.

GET /account/history

Získať históriu využitia za zadané obdobie.

Query parametre

days

integer

Počet dní na zobrazenie (predvolené: 30, max: 365)

Formát odpovede a dátový model

Firemné endpointy vracajú JSON objekt s poľami data a meta. Objekt data obsahuje všetky dostupné firemné údaje rozdelené do nasledujúcich kategórií.

Základné informácie

Základné firemné dáta z 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

Daňové identifikátory a stav DPH: dic (DIČ), ic_dph (IČ DPH), is_vat_payer, vies_valid (výsledok overenia cez EU VIES), vies_verified_at.

Detaily z ORSR

Podrobné dáta z obchodného registra (len pre firmy zapísané v ORSR): 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.

Meta polia

Metadáta odpovede: rpo_updated_at (posledná synchronizácia RPO), orsr_synced_at (posledné načítanie z ORSR), source (database alebo cache), stale (boolean, či sú dáta z ORSR neaktuálne), retry_at (kedy znova požiadať o aktuálne dáta), stale_reason.

Webhooky

Webhooky vám umožňujú prijímať notifikácie v reálnom čase, keď sa zmenia firemné dáta vo FirmAPI. Namiesto opakovaného dotazovania API môžete nakonfigurovať URL adresu, ktorá bude prijímať HTTP POST požiadavky pri každej relevantnej udalosti.

Nastavenie

Nakonfigurujte endpoint pre webhooky v dashboarde. Každá registrácia dostane unikátny HMAC tajný kľúč na overenie podpisu.

Typy udalostí

company.updated — Vyvolaná pri zmene existujúcich firemných dát (napr. zmena adresy, noví spoločníci, zmena stavu)
company.created — Vyvolaná pri pridaní novej firmy do databázy

Štruktúra payloadu

Každá webhook požiadavka obsahuje JSON payload s typom udalosti, časovou značkou a dátami dotknutej firmy.

{
  "event": "company.updated",
  "timestamp": "2026-02-05T12:00:00Z",
  "data": {
    "ico": "51636549",
    "name": "Version Two s. r. o.",
    "changes": ["address", "shareholders"]
  }
}

Hlavičky

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

Každá webhook požiadavka je podpísaná pomocou HMAC-SHA256. Overte podpis, aby ste sa uistili, že požiadavka je autentická a nebola pozmenená.

// PHP verification example
$signature = $request->header('X-Webhook-Signature');
$payload = $request->getContent();
$expected = hash_hmac('sha256', $payload, $webhookSecret);

if (hash_equals($expected, $signature)) {
    // Signature is valid
}

Správanie pri opakovaní

Ak váš endpoint vráti iný ako 2xx stavový kód, FirmAPI zopakuje doručenie s exponenciálnym odstupom: po 5 minútach, 30 minútach, 2 hodinách a 12 hodinách. Po 10 po sebe idúcich zlyhaniach sa webhook registrácia automaticky deaktivuje.

Limity požiadaviek

Limity požiadaviek závisia od vášho predplatného. Nasledujúce hlavičky sú súčasťou každej odpovede:

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.

Stavový kód	Chyba	Popis
401	unauthorized	Neplatný alebo chýbajúci API kľúč
403	forbidden	Funkcia nie je dostupná vo vašom pláne
404	not_found	Firma nebola nájdená
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á