API

API Dokumentácia

FirmAPI poskytuje REST API pre slovenské firemné dáta a rozšírené obohatenia vrátane daňových údajov, bankových účtov, kontaktov, finančných ukazovateľov, účtovných závierok, insolvencie, verejných zákaziek a notifikácií cez webhook alebo email.

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 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	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 načítané zo zdrojov mladšie ako 10 dní. Ak sú ORSR dáta alebo doplnkové dáta staršie, automaticky spúšťa obnovu na pozadí.

Ak sú ORSR detaily staršie ako 30 dní alebo dáta načítané z doplnkových zdrojov staršie ako 10 dní, odpoveď bude obsahovať 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. Obnova na pozadí sa zvyčajne dokončí do 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

Query parametre

scope

string

Čiarkou oddelený zoznam obohatení, ktoré sa majú zahrnúť. Vynechajte pre základné údaje (najrýchlejšie).

Dostupné scopy

Štandardne endpointy pre firmy vracajú len základné údaje (názov, adresa, stav). Použite parameter scope na zahrnutie doplnkových obohatení. Každý scope vyžaduje príslušnú funkciu vo vašom pláne.

tax, bank_accounts, contacts, financials, debtor_status, financial_statements, insolvency, commercial_bulletin, public_contracts, procurement

Príklad požiadavky


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


curl -X GET "https://api.firmapi.sk/v1/company/ico/51636549?scope=tax,financials,debtor_status" \
     -H "Authorization: Bearer YOUR_API_KEY"


curl -X GET "https://api.firmapi.sk/v1/company/ico/51636549?scope=all" \
     -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)

GET /notifications

Zoznam vašich aktívnych a historických notifikačných subscription záznamov.

POST /notifications

Vytvoriť alebo aktualizovať odber zmien pre konkrétne IČO. Môžete nastaviť webhook URL, email alebo oboje.

Telo požiadavky

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

DELETE /notifications/{ico}

Odstrániť subscription pre konkrétne IČO.

GET /notifications/{subscriptionId}/deliveries

Zobraziť posledné doručenia pre konkrétnu subscription vrátane kanála, stavu a počtu pokusov.

GET /notifications/history/{ico}

Získať históriu zistených zmien pre konkrétne IČO.

POST /notifications/test

Overiť konfiguráciu cieľa pre webhook alebo email bez vytvárania trvalej subscription.

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

Sekcia tax obsahuje daňové identifikátory a stav DPH: dic, ic_dph, is_vat_payer, vies_valid, 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.

Kontakty, účty a financie

Voliteľné enrichment sekcie 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

Rozšírené enrichment dáta môžu obsahovať debtor_status, financial_statements (latest, available_years), insolvency, commercial_bulletin, public_contracts_summary a procurement_summary.

Meta polia

Metadáta odpovede: rpo_updated_at, orsr_synced_at, enriched_at, source (database, cache alebo live), cached, stale, retry_at a stale_reason.

Notifikácie: webhooky a email

FirmAPI podporuje notifikácie pri zmenách firemných dát cez webhook URL aj email. Pre jedno IČO môžete nastaviť jednu alebo obe destinácie a spravovať ich cez API aj dashboard.

Nastavenie

Nastavenie notifikácií vykonáte v dashboarde alebo cez endpoint POST /notifications. Pri webhookoch každá subscription 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)
Doručenie prebieha cez nakonfigurovaný webhook_url, notification_email alebo oboje.

Štruktúra payloadu

Webhook payload obsahuje typ udalosti, časovú značku, zmenené pole s pôvodnou a novou hodnotou a stručné firemné údaje. Email notifikácie používajú rovnaký význam udalosti, ale doručujú sa ako čitateľné upozornenie bez HMAC hlavičiek.

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

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 webhook endpoint vráti iný ako 2xx stavový kód, FirmAPI zopakuje doručenie s exponenciálnym odstupom. História doručení je dostupná cez <code>GET /notifications/{subscriptionId}/deliveries</code>. Email notifikácie sa evidujú v rovnakom delivery logu s kanálom <code>email</code>.

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á