Firmaport API Dokumentácia

REST API pre prístup k databáze 944 000+ slovenských firiem

Base URL: https://firmaport.ekonza.sk
Autentifikácia: Verejné endpointy (company-search, company-detail) fungujú bez kľúča (rate limit: 30 req/min). Pre vyšší limit použite Bearer token: Authorization: Bearer <token> (300 req/min).

Obsah

1. Vyhľadávanie firiem 2. Detail firmy 3. Autocomplete 4. Export CSV 5. Health check 6. Autentifikácia (API tokeny) 7. Rate limiting 8. Formáty odpovedí 9. Bulk Company Detail 10. Webhooks

1. Vyhľadávanie firiem

GET /api/company-search.php

Vyhľadávanie vo full-text databáze 944 000+ firiem s filtrovaním.

Parametre

Parameter	Typ	Popis
q	string	Vyhľadávací výraz (názov, IČO)
page	int	Stránka výsledkov (default: 1)
limit	int	Počet výsledkov (max 100, default: 20)
nace	string	Prefix NACE kódu (napr. "62" pre IT)
city	string	Mesto (čiastočná zhoda)
legal_form	string	Právna forma (presná zhoda)
has_dph	1\|0	Len DPH platcovia
no_debt	1\|0	Len firmy bez dlhov
sort	string	Zoradenie: name\|registered

# Príklad — IT firmy v Bratislave bez dlhov
curl "https://firmaport.ekonza.sk/api/company-search.php?nace=62&city=Bratislava&no_debt=1&limit=10"

# Odpoveď
{
  "query": "",
  "total": 873,
  "page": 1,
  "results": [
    {
      "ico": "12345678",
      "name": "ACME Software s.r.o.",
      "legal_form": "Spoločnosť s ručením obmedzeným",
      "status": "aktívny",
      "city": "Bratislava",
      "nace": "6201",
      "nace_description": "Počítačové programovanie, poradenstvo a IT",
      "ic_dph": "SK1234567890"
    }
  ]
}

2. Detail firmy

GET /api/company-detail.php?ico={ico}

Kompletný profil firmy: základné údaje, konatelia, finančné výsledky, rizikové udalosti.

# Príklad
curl "https://firmaport.ekonza.sk/api/company-detail.php?ico=35751444"

# Odpoveď obsahuje:
{
  "company": { "ico": "...", "name": "...", "legalForm": "...", "status": "...",
               "city": "...", "nace": "...", "icDph": "...", ... },
  "executives": [{ "name": "...", "role": "konateľ", "fromDate": "..." }],
  "financials": [{ "year": 2023, "revenue": 1500000, "profit": 200000 }],
  "events": { "taxDebt": false, "vszpDebt": false, "insolvency": false, "taxReliable": true },
  "jsonLd": { "@context": "https://schema.org", "@type": "Organization", ... }
}

3. Autocomplete

GET /api/autocomplete.php?q={query}

Rýchle návrhy pri písaní (min 2 znaky, max 8 výsledkov). Cache 5 minút.

curl "https://firmaport.ekonza.sk/api/autocomplete.php?q=Tesla"
→ {"suggestions": [{"ico":"...", "name":"Tesla...", "meta":"Bratislava"}]}

4. Export CSV

GET /api/export_companies.php

Export výsledkov vyhľadávania do CSV (UTF-8 BOM, oddeľovač ;). Max 5000 riadkov. Rate limit: 10 req/min.

# Export IT firiem bez dlhov
curl "https://firmaport.ekonza.sk/api/export_companies.php?nace=62&no_debt=1&limit=1000" -o firmy.csv

# Export konkrétnych IČO
curl "https://firmaport.ekonza.sk/api/export_companies.php?icos=12345678,87654321" -o export.csv

5. Health check

GET /api/health.php

Stav systému. Vracia HTTP 200 ak všetko v poriadku, 503 ak je degradovaný.

curl "https://firmaport.ekonza.sk/api/health.php"
→ {"status":"ok", "snapshot_rows":944767, "last_sync":"ok", "disk":"ok"}

6. Autentifikácia

GET /api/admin/tokens.php Vyžaduje admin

Správa API tokenov. Tokeny sa použijú v Authorization hlavičke pre vyšší rate limit.

# Vytvorenie tokenu (POST)
curl -X POST "https://firmaport.ekonza.sk/api/admin/tokens.php" \
  -H "Cookie: firmaport_sess=..." \
  -H "Content-Type: application/json" \
  -d '{"name":"Môj API token"}'
→ {"ok":true, "token":"abcd1234...", "message":"Token zobrazený len raz"}

# Použitie tokenu
curl "https://firmaport.ekonza.sk/api/company-search.php?q=Tesla" \
  -H "Authorization: Bearer abcd1234..."

7. Rate limiting

Limity sú sliding-window (60 sekúnd):

Endpoint	Anonymný	S Bearer tokenom
company-search.php	30 req/min	300 req/min
company-detail.php	30 req/min	300 req/min
export_companies.php	10 req/min	10 req/min
autocomplete.php	60 req/min	60 req/min
companies_bulk.php	10 req/min (max 10 IČO)	50 req/min (max 50 IČO)

Pri prekročení limitu: HTTP 429 Too Many Requests. Hlavičky: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

8. Formáty a chyby

Všetky JSON odpovede sú UTF-8, Content-Type: application/json.

HTTP kód	Popis
200	OK — úspešná odpoveď
302	Redirect — vyžaduje prihlásenie
400	Bad Request — chýbajúci alebo neplatný parameter
404	Not Found — firma neexistuje
429	Too Many Requests — rate limit prekročený
500	Internal Server Error
503	Service Degraded — health check zlyhal

Tip: Vždy kontrolujte HTTP status kód. Pole ok: true/false je len informačné.

9. Bulk Company Detail

POST /api/companies_bulk.php

Načítaj detail pre viacero firiem naraz. Max 10 firiem (anon) / 50 firiem (s Bearer tokenom).

curl -X POST "https://firmaport.ekonza.sk/api/companies_bulk.php" \
  -H "Content-Type: application/json" \
  -d '{"icos":["35751444","00001805"]}'

# GET variant:
curl "https://firmaport.ekonza.sk/api/companies_bulk.php?icos=35751444,00001805"

# Odpoveď:
{
  "ok": true,
  "requested": 2,
  "found": 2,
  "not_found": [],
  "companies": {
    "35751444": { "ico":"...", "name":"...", "events":{...}, "executives":[...] }
  }
}

10. Webhooks

Webhooky umožňujú prijímať real-time HTTP notifikácie pri zmene sledovanej firmy. Vyžaduje prihlásenie (session cookie).

GET /api/crm/webhooks.php

Zoznam všetkých webhookov prihláseného používateľa.

curl "https://firmaport.ekonza.sk/api/crm/webhooks.php" \
  -H "Cookie: firmaport_sess=..."

# Odpoveď
{
  "ok": true,
  "webhooks": [
    {
      "id": 1,
      "name": "Môj webhook",
      "url": "https://example.com/hook",
      "events": "[\"company_change\"]",
      "active": 1,
      "success_count": 5,
      "fail_count": 0,
      "last_triggered_at": "2026-05-07T10:00:00+02:00"
    }
  ]
}

POST /api/crm/webhooks.php

Registruj nový webhook. Secret pre HMAC-SHA256 podpis je voliteľný — ak nie je zadaný, vygeneruje sa automaticky.

JSON body

Parameter	Typ	Popis
name	string	Názov webhooку (povinné)
url	string	Cieľová URL (povinné, musí byť platná URL)
events	array	Typy udalostí: `company_change`, `insolvency`, `new_debt`, `status_change` (default: `["company_change"]`)
secret	string	HMAC secret pre overenie podpisu (voliteľné)

curl -X POST "https://firmaport.ekonza.sk/api/crm/webhooks.php" \
  -H "Cookie: firmaport_sess=..." \
  -H "Content-Type: application/json" \
  -d '{"name":"Môj hook","url":"https://example.com/fp-hook","events":["new_debt","insolvency"]}'

# Odpoveď
{"ok": true, "webhook_id": 1, "message": "Webhook zaregistrovaný"}

DELETE /api/crm/webhooks.php?id={id}

Deaktivuj webhook (soft delete — záznamy delivery ostávajú).

curl -X DELETE "https://firmaport.ekonza.sk/api/crm/webhooks.php?id=1" \
  -H "Cookie: firmaport_sess=..."
→ {"ok": true}

PAYLOAD Formát doručeného webhook payloadu

Každý webhook POST obsahuje JSON s podpisom v hlavičke X-Firmaport-Signature.

# HTTP POST na tvoju URL
POST https://example.com/fp-hook
Content-Type: application/json
X-Firmaport-Event: new_debt
X-Firmaport-Signature: sha256=abc123...
X-Firmaport-Webhook-ID: 1

{
  "event": "new_debt",
  "timestamp": "2026-05-07T10:00:00+02:00",
  "webhook_id": 1,
  "data": {
    "ico": "35751444",
    "company_name": "ACME s.r.o.",
    "change_type": "new_debt",
    "old_value": "0",
    "new_value": "1",
    "user_id": 42
  }
}

# Overenie HMAC podpisu (PHP)
$valid = hash_equals(
    'sha256=' . hash_hmac('sha256', $rawBody, $yourSecret),
    $_SERVER['HTTP_X_FIRMAPORT_SIGNATURE']
);

Firmaport API | firmaport.ekonza.sk | Stav: health check