Dokumentácia k API

Firemné údaje SK/CZ pre e-shopy

Dokumentácia k API

API-DATA poskytuje REST endpointy pre firemné údaje zo Slovenska (RPO) a Česka (ARES), autocomplete adries, overenie IČ DPH cez VIES a referenčné dáta ako banky a IBAN, krajiny, sviatky a menové kurzy ECB. Kľúčové datasety držíme a pravidelne synchronizujeme na vlastnom serveri, takže API nie je len jednoduchá proxy nad externými službami. Zachovávame v1 endpointy kvôli kompatibilite, no pre nové integrácie odporúčame v2.

v2 (recommended)

Preferované pre nové projekty: X-API-Key v hlavičke, konzistentný kontrakt.

v1 (legacy)

Kompatibilita pre staré integrácie: parameter k=API_KEY v URL.

Cieľ tejto stránky: aby integrátor bez zbytočných otázok vedel vyhľadať firmu → načítať detail → vyplniť checkout → voliteľne overiť VAT → pozrieť usage.

Rýchly štart (JS snippet)

Najrýchlejšia integrácia do checkoutu alebo formulára: nastavíš selektory inputov a načítaš loader skript. V produkcii používaj kľúč viazaný na doménu.

Poznámka: API kľúč v browseri nie je možné skryť - vždy je čitateľný v DevTools. Preto pre frontend používaj doménovo viazaný kľúč.

<!-- FREE kľúč: meta tag netreba. Platené plány: vlož meta do <head>. -->
<meta name="autofirmy-verification" content="META_KOD">

<script>
window.RPO_AUTOCOMPLETE_CONFIG = {
  apiKey: 'VAS_API_KEY',

  // UI
  theme: 'auto',              // 'auto' | 'light' | 'dark' | 'custom'
  dropdown: { width: 'min' }, // 'min' | 'match' | číslo (px)

  // krajina (ak máš select SK/CZ)
  countrySelect: '#CountryId',

  // firmy + VAT
  vies: 'on',

  // adresy
  addressMode: 'combined',    // 'combined' | 'split'
  address: { minChars: 3, limit: 8, debounce: 240 },

  // mapovanie inputov (CSS selektory)
  fields: {
    company: '#FirmId',
    ico:     '#INId',
    dic:     '#TINId',
    vat:     '#INVATId',

    // adresa (combined) - stále mapuj na "street"
    street:  '#AddressId',
    city:    '#CityId',
    postal:  '#PostalId'
  },

  // rohy dropdownu
  radius: { top: 0, bottom: 8 }
};
</script>

<script src="https://api-data.eu/api/js/rpo_ares_autocomplete_inc.js" defer></script>

Parametre snippetu

apiKey - API kľúč (frontend, viazaný na doménu)
countrySelect - CSS selektor selectu krajiny (SK/CZ). Ak je default -1, nastav ho na SK.
fields - mapovanie inputov (CSS selektory)
vies - on | off (overenie IČ DPH cez VIES)
addressMode - combined (ulica+cislo v 1 poli) alebo split (ulica a cislo zvlášť)
address.minChars, address.debounce, address.limit - UX vs. spotreba dopytov
theme, dropdown.width, radius - vzhľad dropdownu

Najčastejšie chyby

Zlá krajina v selecte (napr. -1) - autocomplete firiem sa nespustí.
Zlé selektory v fields - over v konzole document.querySelector(...).
Adresy: aj pri addressMode: 'combined' mapuj ulicu do fields.street (nie fullAddress).

Ako sa rátajú dopyty (API calls)

Základné pravidlo

Bežný endpoint = 1 jednotka na HTTP request, ak nie je pri endpointe uvedené inak.
Dopyty sa rátajú rovnako pre API, JS snippet aj moduly, pretože všetko ide cez API.
Limity sú hodinové. Špička / hod. je denný +50 % limit, použiteľný raz za 24 h; resetuje sa o polnoci.

Typické scenáre

Firma (v2, SK/CZ): vyhľadanie firmy je 1 HTTP dopyt / 1 jednotka z hlavného limitu; po jeho vyčerpaní stojí najviac 1 kredit (/api/v2/search_company.php). Pri detail=1 sa po výbere polia zvyčajne vyplnia bez ďalšieho dopytu. Ak chýbajú údaje, priamy detail je +1 HTTP dopyt / 1 jednotka / najviac 1 kredit (/api/v2/company.php alebo /api/v2/cz_company.php).
Firma (CZ - iba IČO): priamy detail cez /api/v2/cz_company.php = 1 dopyt.
Adresy (v2, SK/CZ): každý návrh = 1 dopyt (/api/v2/search_address.php). Po kliknutí sa už len vyplnia polia (bez ďalšieho dopytu).
VIES: každé overenie = 1 dopyt (/api/check_vat.php).

Tip: najviac dopytov vzniká pri písaní. Zvyš minChars a debounce (napr. 3-4 znaky, 250-400 ms) - menšia spotreba, stabilnejší UX.

Autentifikácia

v2: používaj hlavičku X-API-Key (bezpečnejšie, neuniká do URL logov).
v1: len kvôli kompatibilite - kľúč je v URL parametri k.

v2 (recommended)

curl -H "X-API-Key: YOUR_KEY" "https://api-data.eu/api/v2/company.php?ico=12345678&country=SK"

Výhoda: kľúč nie je v URL, znižuje riziko leakov (history, referer, logy).

v1 (legacy)

GET https://api-data.eu/api/company.php?ico=12345678&country=SK&k=YOUR_KEY

Použi iba ak máš starú integráciu, ktorú nechceš meniť.

Rate limit a doménové viazanie

Licencie majú plán s limitom (napr. requests/hour).
Niektoré licencie môžu byť viazané na doménu alebo IP (S2S).
Pri prekročení limitu API vráti chybu (typicky 429).

Základné URL

https://api-data.eu/api/v2/ (v2 - recommended)
https://api-data.eu/api/ (v1 - legacy)

Všetky ukážky nižšie sú primárne pre v2. v1 je vždy v zbalenom „Legacy” bloku na konci.

Test (konzola v dokumentácii)

Interaktívna

Testovanie endpointov priamo v prehliadači. Poznámka: API kľúč v browseri nie je možné „skryť” - vždy je čitateľný v DevTools (Network / Headers). Pre JavaScript integrácie preto používaj kľúč určený do frontendu: viazaný na doménu.

Jedna konzola pre všetky endpointy

Rýchle testy v konzole

Tieto tlačidlá otvoria modal a predvyberú konkrétny endpoint s ukážkovými parametrami.

v2 - Company detail (SK/CZ index)

GET

Endpoint: /api/v2/company.php
Vyhľadá detail firmy podľa ico. Podpora country=SK|CZ (default SK).

Query parametre

ico - IČO (číslice)
country - SK|CZ (default SK)
detail - prázdne/off = rýchly detail, 1 = normalizovaný RPO/ARES detail, full = aj raw záznam

Auth: X-API-Key hlavička.

Príklady

curl -H "X-API-Key: YOUR_KEY" "https://api-data.eu/api/v2/company.php?ico=12345678&country=SK"

curl -H "X-API-Key: YOUR_KEY" "https://api-data.eu/api/v2/company.php?ico=36562939&country=SK&detail=1"

curl -H "X-API-Key: YOUR_KEY" "https://api-data.eu/api/v2/company.php?ico=27082440&country=CZ&detail=1"

Rozšírený detail sa ukladá do lokálnej cache company_registry_detail. Prvý request môže dotiahnuť RPO/ARES upstream, ďalšie requesty idú z našej DB. Vyhľadávanie v Meili sa tým nemení.

Odpoveď

v2 odpoveď používa data + meta.

{
  "ok": true,
  "data": {
    "organization_id": 1234567,
    "ico": "12345678",
    "name": "Príkladná firma, s.r.o.",
    "dic": "1234567890",
    "ic_dph": "SK1234567890",
    "street": "Hlavná",
    "reg_number": 123,
    "building_number": "123",
    "address1": "Hlavná 123",
    "postal_code": "811 01",
    "city": "Bratislava",
    "country": "Slovenská republika",
    "country_iso": "SK",
    "legal_form": null,
    "main_activity": null,
    "registry_detail": {
      "available": true,
      "cache_hit": true,
      "source": "rpo",
      "source_updated_at": "2025-07-07",
      "normalized": {
        "country_iso": "SK",
        "ico": "36562939",
        "name": "Alza.sk s. r. o.",
        "legal_form": {
          "value": "Spoločnosť s ručením obmedzeným",
          "code": "112"
        },
        "activities": []
      }
    }
  },
  "meta": {
    "version": "2",
    "request_id": "optional",
    "country_iso": "SK",
    "time_ms": 12,
    "source": "db"
  }
}

JS fetch

fetch('https://api-data.eu/api/v2/company.php?ico=36562939&country=SK', {
  headers: { 'X-API-Key': 'YOUR_KEY' }
}).then(r => r.json()).then(console.log);

PHP cURL

$ch = curl_init('https://api-data.eu/api/v2/company.php?ico=36562939&country=SK');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_TIMEOUT => 5,
  CURLOPT_HTTPHEADER => ['X-API-Key: YOUR_KEY', 'Accept: application/json'],
]);
$json = curl_exec($ch);
echo $json;

Python requests

import requests
r = requests.get(
  'https://api-data.eu/api/v2/company.php',
  params={'ico':'36562939','country':'SK'},
  headers={'X-API-Key':'YOUR_KEY'}
)
print(r.json())

Test - company

{}

v2 - CZ Company detail

GET

Nové integrácie používajú jednotný endpoint /api/v2/company.php?ico=27082440&country=CZ&detail=1. /api/v2/cz_company.php ostáva ako kompatibilný alias.

Endpoint: /api/v2/cz_company.php
Dočasne napojené na ARES. Polia sú normalizované do rovnakého formátu ako SK company.

CZ zdroj je zatiaľ ARES. Keď prejdeš na interný index, endpoint ostane rovnaký a formát odpovede zachováme.

Query parametre

ico - IČO (CZ) (číslice)

Auth: X-API-Key hlavička.

Príklad

curl -H "X-API-Key: YOUR_KEY" "https://api-data.eu/api/v2/company.php?ico=27082440&country=CZ&detail=1"

curl -H "X-API-Key: YOUR_KEY" "https://api-data.eu/api/v2/company.php?ico=27082440&country=CZ&detail=full"

Test - cz_company

{}

v2 - Company search

GET

Endpoint: /api/v2/search_company.php
Vyhľadáva firmy podľa názvu.

Query parametre

q - dotaz (min. 2 znaky)
country - SK|CZ|'' (mix) (optional)
limit - 1..50 (optional)

Príklad

curl -H "X-API-Key: YOUR_KEY" "https://api-data.eu/api/v2/search_company.php?q=alza"

Autocomplete ukážka

Rovnaký JS helper ako v hero deme na úvodnej stránke. Začni písať názov firmy a vyber návrh z dropdownu.

Názov firmy autocomplete

Krajina

IČO

DIČ

IČ DPH

Adresa

Mesto

PSČ

{
  "ok": true,
  "results": [
    {
      "organization_id": 100001,
      "ico": "12345678",
      "name": "TEST FIRMA 1.",
      "city": "Bratislava",
      "postal_code": "811 01",
      "country_iso": "SK"
    }
  ],
  "meta": {
    "country": "MIX",
    "processingTimeMs": 2,
    "estimatedTotalHits": 123
  }
}

JS fetch

fetch('https://api-data.eu/api/v2/search_company.php?q=alza', {
  headers: { 'X-API-Key': 'YOUR_KEY' }
}).then(r => r.json()).then(console.log);

PHP cURL

$ch = curl_init('https://api-data.eu/api/v2/search_company.php?q=alza');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_TIMEOUT => 5,
  CURLOPT_HTTPHEADER => ['X-API-Key: YOUR_KEY'],
]);
echo curl_exec($ch);

Python requests

import requests
r = requests.get(
  'https://api-data.eu/api/v2/search_company.php',
  params={'q':'alza'},
  headers={'X-API-Key':'YOUR_KEY'}
)
print(r.json())

Test - search

{}

v2 - Address search (SK/CZ)

GET

Endpoint: /api/v2/search_address.php
Vyhľadáva adresy pre autocomplete (ulica + číslo + obec + PSČ). Výstup je pripravený na priamy render do dropdownu.

Odporúčanie pre UX: volaj endpoint až od 3 znakov a debounce 200-350 ms.

Query parametre

q - dotaz (min. 3 znaky)
country - SK|CZ (default SK)
limit - 1..20 (default 8)
numberMode - auto | orientation | registry (default auto)
Rieši prípady, keď používateľ napíše iba jedno číslo (napr. Horská 7): orientation preferuje orientačné číslo, registry preferuje súpisné / č.p.

Auth: X-API-Key hlavička.

Príklad

curl -H "X-API-Key: YOUR_KEY" "https://api-data.eu/api/v2/search_address.php?q=Horska%201776/7&country=SK"

SK: supisne + orientacne
CZ: do polí mapujeme cp → supisne a co (+ suffix) → orientacne.

Odpoveď

Vráti pole data.results s pripraveným label (bez duplicít typu „Martin, Martin”). Polia ber ako stabilné API kontrakty; interné ID vráť/ulož iba ako „opaque”.

{
  "ok": true,
  "data": {
    "results": [
      {
        "id": "SK:123456",
        "country_iso": "SK",
        "label": "Horská 1776/7, Martin 036 01",
        "street": "Horská",
        "supisne": "1776",
        "orientacne": "7",
        "psc": "036 01",
        "municipality": "Martin",
        "part": null,
        "district": "Martin",
        "region": "Žilinský kraj",
        "lat": 49.066,
        "lon": 18.923
      }
    ]
  },
  "meta": {
    "country": "SK",
    "q": "Horska 1776/7",
    "count": 1,
    "limit": 8,
    "source": "meili",
    "cache": "miss",
    "time_ms": 3,
    "extra": {
      "country": "SK",
      "index": "addresses_sk",
      "numberMode": "auto",
      "pass": "sk_orient+fallback_fulltext"
    }
  }
}

JS fetch

fetch('https://api-data.eu/api/v2/search_address.php?q=Horska%201776/7&country=SK', {
  headers: { 'X-API-Key': 'YOUR_KEY' }
}).then(r => r.json()).then(console.log);

PHP cURL

$ch = curl_init('https://api-data.eu/api/v2/search_address.php?q=Horska%201776/7&country=SK');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_TIMEOUT => 5,
  CURLOPT_HTTPHEADER => ['X-API-Key: YOUR_KEY'],
]);
echo curl_exec($ch);

Python requests

import requests
r = requests.get(
  'https://api-data.eu/api/v2/search_address.php',
  params={'q':'Horska 1776/7','country':'SK'},
  headers={'X-API-Key':'YOUR_KEY'}
)
print(r.json())

Chyby špecifické pre tento endpoint

400 - query_too_short (q < 3 znaky)
502 - meili_unavailable (dočasný problém so search backendom)

Test - search_address

{}

v2 - VAT check (VIES)

GET

Endpoint: /api/v2/check_vat.php
Overí platnosť IČ DPH cez VIES (EU). VIES môže občas odpovedať pomalšie alebo dočasne zlyhať.

Query parametre

country alebo cc - ISO krajina (napr. SK, CZ)
vat - VAT číslo (bez prefixu)

Príklad

curl -H "X-API-Key: YOUR_KEY" "https://api-data.eu/api/v2/check_vat.php?cc=SK&vat=SK4020121402"

{
  "ok": true,
  "data": {
    "valid": true,
    "name": "COMPANY NAME (as returned by VIES)",
    "address": "ADDRESS (as returned by VIES)",
    "countryCode": "SK",
    "vatNumber": "SK4020121402"
  },
  "meta": {
    "version": "2",
    "request_id": "optional",
    "time_ms": 140,
    "source": "vies"
  }
}

Test - check_vat

{}

v2 - Počasie SHMÚ

GET

Endpointy pre aktuálne merania zo staníc SHMÚ, rýchle agregácie, výstrahy CAP a ALADIN predpoveď z predpočítaného cache. Bundle endpoint je optimalizovaný pre Home Assistant a ľahké dashboardy. Auth: X-API-Key alebo verejný IP režim pre weather endpointy.

Verejný režim: weather endpointy môžu fungovať bez API kľúča s limitom 100 dopytov/hodinu/IP. S API kľúčom sa použijú štandardné licenčné limity a allowances.

Default odpovede su kompaktne: bez SHMU raw payloadu, bez expirovanych vystrah a bez celeho ALADIN katalogu v bundle. Debug data sa daju zapnut iba cielene cez raw=1 alebo detail=1 na endpointoch, ktore to podporuju. Pri ALADIN-e znamena forecast_hour predpovedny krok od startu modeloveho behu, nie hodinu dna; presny cas je v valid_at.

Endpoint	Parametre	Použitie
/api/v2/weather/bundle.php	ind, include?, minutes?, hours?, ttl?, alerts_limit?	Jeden kompaktný JSON pre Home Assistant: aktuálne dáta, agregácia, výstrahy a ALADIN stav.
/api/v2/weather/stations.php	q?, refresh?	Zoznam staníc s ID, názvom a GPS súradnicami.
/api/v2/weather/current.php	ind, raw?, detail?	Aktuálne meranie stanice z AWS 1-min dát. Raw SHMÚ polia sú vypnuté, ak si ich nevyžiadaš.
/api/v2/weather/aggregate.php	ind, minutes?, step?, max_files?	Agregácia teploty, vlhkosti, tlaku, vetra a zrážok za interval.
/api/v2/weather/alerts.php	days?, limit?, include_expired?	Aktívne a budúce SHMÚ výstrahy vo formáte odvodenom z CAP XML.
/api/v2/weather/aladin.php	ind?, hours?, detail?, raw?	ALADIN katalóg alebo predpočítaná bodová predpoveď pre stanicu. Kompaktné pole používa forecast_hour a valid_at.
/api/v2/weather/homeassistant.php	ind, name?, minutes?, hours?, alerts_limit?	Generovanie Home Assistant YAML senzora cez rýchly bundle endpoint.

Príklady

curl "https://api-data.eu/api/v2/weather/bundle.php?ind=11800&minutes=60&hours=24&ttl=900&alerts_limit=8&include=current,alerts,aladin"

curl -H "X-API-Key: YOUR_KEY" "https://api-data.eu/api/v2/weather/current.php?ind=11800"

Konfigurátor pre Home Assistant

Pre pohodlné poskladanie URL, YAML konfigurácie a výber stanice použi samostatný konfigurátor počasia.

Otvoriť konfigurátor

{
  "ok": true,
  "data": {
    "station": {
      "station_id": 11800,
      "name": "Banská Bystrica",
      "lat": 48.735,
      "lon": 19.145
    },
    "current": {
      "temperature_c": 18.7,
      "humidity_pct": 62,
      "pressure_hpa": 1014.2,
      "wind_speed_ms": 2.1,
      "observed_at_utc": "2026-05-31T10:15:00Z"
    },
    "alerts": {
      "alerts_count": 0,
      "alerts": []
    },
    "partial_errors": {
      "aggregate": {
        "code": "SECTION_UNAVAILABLE",
        "message": "No recent samples found for station"
      }
    }
  },
  "meta": {
    "version": "2",
    "request_id": "optional",
    "source": "shmu_aws1min,shmu_cap_alerts",
    "freshness": "partial",
    "bundle_cache": "hit",
    "ttl": 900,
    "time_ms": 2
  }
}

Cache a rýchlosť

Bundle používa vlastnú cache podľa parametrov a vie vrátiť stale odpoveď, aby Home Assistant nečakal na upstream.

ALADIN

SHMÚ publikuje ALADIN ako GRIB. JSON predpoveď sa má predpočítavať workerom a endpoint potom číta hotový cache.

Partial odpovede

Ak jedna sekcia nie je dostupná, bundle stále vráti použiteľný JSON a problém uvedie v partial_errors.

v2 - License stats (usage bez loginu)

GET

Endpoint: /api/v2/license_stats.php
Informácie o pláne, globálnom hodinovom limite, dennej špičke a použití jednotlivých endpointov bez prihlásenia do účtu.

Predvolený režim detail=compact vracia súhrn a iba endpointy použité v aktuálnej hodine. Parameter detail=full pridá všetky endpointové free limity plánu vrátane nulového použitia. Každý objekt v items má vlastný free_limit a remaining_free; nejde o spoločný pool. http_requests počíta volania voči RPH, kým used počíta účtovacie jednotky endpointu; jedno volanie môže mať viac jednotiek. Globálne usage.used nezahŕňa requesty pokryté vlastným free limitom endpointu.

Parameter	Hodnoty	Predvolené	Význam
detail	compact \| full	compact	compact vráti použité endpointy; full všetky nakonfigurované endpointové scope.

Príklad

curl -H "X-API-Key: YOUR_KEY" "https://api-data.eu/api/v2/license_stats.php"

curl -H "X-API-Key: YOUR_KEY" "https://api-data.eu/api/v2/license_stats.php?detail=full"

Ukážková odpoveď – dátumy, časy a počítadlá sú ilustračné. Živé hodnoty podľa aktuálnej hodiny vráti test endpointu nižšie.

{
  "ok": true,
  "data": {
    "license": {
      "id": 123,
      "program": "Starter",
      "program_code": "starter",
      "key_type": "standard",
      "base_hourly_limit": 50,
      "hourly_limit": 50,
      "hourly_override": {
        "active": false,
        "limit": null,
        "valid_until": null
      },
      "valid_until": "2027-03-01 12:00:00"
    },
    "usage": {
      "window_start": "2026-07-01 14:00:00",
      "used": 12,
      "remaining": 38,
      "excludes_endpoint_free": true,
      "reset_at": "2026-07-01T15:00:00+02:00"
    },
    "peak": {
      "enabled": true,
      "status": "available",
      "plan_limit": 75,
      "limit": 75,
      "remaining": 63,
      "reason": null,
      "available_today": true,
      "active": false,
      "claimed_hour": null,
      "reset_at": "2026-07-02T00:00:00+02:00"
    },
    "endpoint_usage": {
      "available": true,
      "detail": "compact",
      "allowance_model": "per_endpoint",
      "window_start": "2026-07-01 14:00:00",
      "reset_at": "2026-07-01T15:00:00+02:00",
      "shared_pool": false,
      "totals": {
        "http_requests": 8,
        "http_requests_complete": true,
        "used_units": 8,
        "known_scopes": 47,
        "free_allowance_scopes": 47,
        "active_scopes": 1
      },
      "items": [
        {
          "endpoint": "iban_validate",
          "country": "global",
          "api_version": "v2",
          "http_requests": 8,
          "http_requests_complete": true,
          "main_plan_requests": 0,
          "endpoint_free_requests": 8,
          "used": 8,
          "free_limit": 15,
          "remaining_free": 7,
          "free_used": 8,
          "charged_requests": 0,
          "charged_credits": 0,
          "credit_cost": 1
        }
      ]
    }
  },
  "meta": {
    "version": "2",
    "request_id": "optional",
    "time_ms": 4
  }
}

JS fetch

fetch('https://api-data.eu/api/v2/license_stats.php', {
  headers: { 'X-API-Key': 'YOUR_KEY' }
}).then(r => r.json()).then(console.log);

PHP cURL

$ch = curl_init('https://api-data.eu/api/v2/license_stats.php');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_TIMEOUT => 5,
  CURLOPT_HTTPHEADER => ['X-API-Key: YOUR_KEY'],
]);
echo curl_exec($ch);

Python requests

import requests
r = requests.get(
  'https://api-data.eu/api/v2/license_stats.php',
  headers={'X-API-Key':'YOUR_KEY'}
)
print(r.json())

Test - license_stats

{}

v2 - IBAN validácia a parsovanie

GET

Endpointy pre kontrolu IBAN, rozklad na komponenty a zostavenie IBAN zo základných bankových údajov. Auth: X-API-Key hlavička.

Endpoint	Parametre	Použitie
/api/v2/iban_validate.php	iban	Formát, krajina, dĺžka a MOD-97 checksum.
/api/v2/iban_parse.php	iban	Rozklad IBAN + informácia o banke.
/api/v2/iban_build.php	country, bank, account, branch?	Zostavenie IBAN z lokálnych komponentov.
/api/v2/sepa_countries.php	country?, eu_only?	Zoznam SEPA krajín a ich platobné atribúty.

Príklady

curl -H "X-API-Key: YOUR_KEY" "https://api-data.eu/api/v2/iban_validate.php?iban=SK3112000000198742637541"

curl -H "X-API-Key: YOUR_KEY" "https://api-data.eu/api/v2/iban_parse.php?iban=SK3112000000198742637541"

Interaktívny editor

Vyber IBAN endpoint v spoločnej konzole, prepíš IBAN alebo bankové komponenty a spusti request s demo kľúčom.

v2 - Bankový register

GET

Endpoint	Parametre	Použitie
/api/v2/banks.php	country	Zoznam bánk pre krajinu.
/api/v2/banks_by_code.php	country, code	Banka podľa národného bankového kódu.
/api/v2/banks_by_bic.php	bic	Banka podľa BIC/SWIFT kódu.

Bankové dáta sú vhodné pre validáciu platobných formulárov, párovanie BIC a dopĺňanie názvu banky podľa kódu. Odpovede obsahujú coverage.status (full, partial, demo), aby klient vedel rozlíšiť plný register od obmedzeného pokrytia.

v2 - Sviatky a pracovné dni

GET

Kalendár podporuje sviatky, detail dátumu a výpočty pracovných dní. Slovenské sviatky reflektujú legislatívne zmeny pre roky 2025-2026.

Endpoint	Parametre	Použitie
/api/v2/calendar/holidays.php	country, year, region?	Sviatky krajiny v danom roku.
/api/v2/calendar/holiday.php	country, date	Detail konkrétneho dátumu.
/api/v2/calendar/is_business_day.php	country, date	Či je dátum pracovný deň.
/api/v2/calendar/business_days_add.php	country, date, days	Pridá N pracovných dní.
/api/v2/calendar/business_days_subtract.php	country, date, days	Odoberie N pracovných dní.
/api/v2/calendar/business_days_between.php	country, from, to	Počet pracovných dní v intervale.
/api/v2/calendar/business_days_next.php	country, date	Najbližší pracovný deň po dátume.
/api/v2/calendar/business_days_previous.php	country, date	Predchádzajúci pracovný deň.
/api/v2/calendar/countries.php	-	Podporované krajiny.

Pre výpočty pracovných dní používaj vždy rovnakú krajinu a dátumy vo formáte YYYY-MM-DD.

v2 - FX kurzy ECB

GET

Endpoint	Parametre	Použitie
/api/v2/fx/latest.php	base?, symbols?	Aktuálne kurzy z ECB cache.
/api/v2/fx/historical.php	date, base?, symbols?	Kurzy pre dátum s fallbackom na posledný dostupný deň.
/api/v2/fx/range.php	from, to, base?, symbol	Časový rad kurzov, max 731 dní.
/api/v2/fx/convert.php	amount, from, to, date?	Konverzia sumy cez EUR cross-rate.

ECB publikuje kurzy v pracovné dni. Historické volania pri sviatku alebo víkende vrátia najbližší dostupný kurz podľa endpointu.

v2 - Krajiny a skupiny

GET

Endpoint	Parametre	Použitie
/api/v2/countries.php	q?, region?, currency?, is_eu?	Zoznam krajín s filtrami.
/api/v2/countries/country.php	iso2 alebo country	Detail krajiny podľa ISO2.
/api/v2/countries/neighbours.php	iso2 alebo country	Susedné krajiny.
/api/v2/countries/groups.php	group	Skupiny eu, eea, schengen, sepa, eurozone, nato.
/api/v2/countries/groups/eu.php	-	Skratka pre EU krajiny.
/api/v2/countries/groups/schengen.php	-	Skratka pre Schengen.
/api/v2/countries/groups/sepa.php	-	Skratka pre SEPA.

Krajiny používaj na číselníky, validáciu ISO kódov, meny, skupiny krajín a susedné krajiny pri logistike.

v2 - Graf prepojení firiem a osôb

GET

Endpoint: /api/v2/company_graph.php
Pre zadané IČO vráti sieť konateľov, spoločníkov a ich ďalších firiem do zvolenej hĺbky. Vhodné na due diligence, KYC a mapovanie vlastníckych štruktúr. Zatiaľ len SK (RPO).

Po vyčerpaní endpointového free limitu a hlavného limitu: company_graph = 5 kreditových jednotiek, search_company = 1, priamy detail firmy = 1 a doplnkové endpointy v tejto skupine zvyčajne 1. Základné hodinové sadzby plánov: Free 10/h, Mini 25/h (+38/h), Starter 50/h (+75/h), Standard 120/h (+180/h), Pro 300/h (+450/h), Business 800/h (+1200/h), Enterprise 2000/h (+3000/h). Hodnota v zátvorke je denná špička, dostupná raz za 24 h a resetovaná o polnoci.

Query parametre

ico - 8-miestne IČO firmy (alebo person)
person - person_key osoby ako koreň grafu
depth - hĺbka 1-4 (default 2)
historical - 0|1, zahrnúť historické väzby
max_nodes - strop uzlov (default 60)
company_graph_path.php - hľadanie cesty medzi dvoma firmami/osobami, účtuje sa ako company_graph

Auth: X-API-Key hlavička.

Príklad

curl -H "X-API-Key: YOUR_KEY" "https://api-data.eu/api/v2/company_graph.php?ico=51865467&depth=2"

Odpoveď

{
  "ok": true,
  "data": {
    "root": { "id": "c:51865467", "type": "company", "ico": "51865467", "name": "Stredoslovenská energetika, a. s." },
    "depth": 2,
    "include_historical": false,
    "nodes": [
      { "id": "c:51865467", "type": "company", "label": "Stredoslovenská energetika, a. s.", "ico": "51865467", "is_root": true },
      { "id": "p:jan-novak-bratislava", "type": "person", "label": "Ján Novák", "municipality": "Bratislava" }
    ],
    "edges": [
      { "id": "e:123", "source": "p:jan-novak-bratislava", "target": "c:51865467",
        "role": "konatel", "valid_from": "2019-01-01", "valid_to": null, "active": true }
    ],
    "stats": { "nodes": 2, "edges": 1, "companies": 1, "persons": 1, "truncated": false }
  },
  "meta": { "version": "2", "country_iso": "SK", "source": "rpo", "time_ms": 38 }
}

Ochrana osobných údajov: verejný demo režim a plán Freemium vracajú osoby anonymizovane (Fyzicka osoba #N, municipality: null). Celé mená sú dostupné až s plateným plánom, ktorý má povolené reveal_persons.

v2 - Vyhľadávanie osôb v grafe

GET

Endpoint: /api/v2/graph_search.php
Našepkávač osôb podľa mena. Vráti person_key, ktorý použijete ako person parameter v grafe.

Query parametre

q - meno osoby (min. 2 znaky)

Odpoveď

{ "ok": true, "data": { "persons": [
  { "person_key": "jan-novak-bratislava",
    "label": "Ján Novák", "municipality": "Bratislava" }
] } }

v2 - Cesta medzi firmami a osobami

GET

Endpoint: /api/v2/company_graph_path.php
Nájde najkratšiu cestu medzi dvoma firmami alebo osobami v grafe. Účtuje sa rovnakými pravidlami ako company_graph, teda 5 jednotiek po vyčerpaní free limitu.

Query parametre

from_ico alebo from_person - zdroj
to_ico alebo to_person - cieľ
contracts - 0|1, zahrnúť zmluvné väzby
historical - 0|1, zahrnúť historické väzby

Príklad

curl -H "X-API-Key: YOUR_KEY" "https://api-data.eu/api/v2/company_graph_path.php?from_ico=45503249&to_ico=36426989"

v2 - Detailné dáta firmy (report)

GET

Doplnkové endpointy k firme. Všetky berú ico (8-miestne) a hlavičku X-API-Key, vracajú { ok, data, meta }. Po vyčerpaní free allowance sa účtujú podľa jednotiek endpointu. Väčšina doplnkových endpointov má cenu 1 jednotka.

Endpoint	Parametre navyše	Vracia (data)	Zdroj	Jednotky
/api/v2/company_finance.php	-	years[]: year, revenue, profit, assets, equity	RÚZ	1
/api/v2/company_risk.php	-	score (0-10), level, factors[], financials	odvodené	1
/api/v2/company_risk_signals.php	-	signals[] s first/last/resolved a score_relation, history[], summary, sources[], scoring	FS + existujúce registre	1
/api/v2/company_risk_network.php	depth, limit, max_nodes, historical	own, network.score, connections[]: cez koho a prečo	RPO graf + riziko	3
/api/v2/company_timeline.php	-	items[]: date, type, title, detail	RPO + RÚZ	1
/api/v2/company_contracts.php	page, limit, sort(date\|price\|counterparty), dir, counterparty, q	contracts[], summary	CRZ	1
/api/v2/company_tenders.php	page, limit, sort(date\|amount), dir	tenders[], summary	ITMS	1
/api/v2/company_subsidies.php	page, limit, sort(date\|amount), dir	subsidies[]: projekt, NFP, vlastné zdroje, ITMS/CRZ odkazy; summary	ITMS + CRZ	1
/api/v2/company_irregularities.php	page, limit, sort(date\|amount), dir	irregularities[], summary	ITMS	1
/api/v2/company_debts.php	history?	debts[]: amount, first_seen_on, last_seen_on, resolved_on, active; history[] pri history=1	SP + VšZP + Dôvera	1
/api/v2/company_ov.php	page, limit, dir	events[], summary	Obch. vestník	1
/api/v2/company_fs.php	-	vat, tax_periods[], corporate_tax_periods[], vat_special_schemes[], tax_incentives[], regulated_levies[]	Fin. správa	1

Dotácie - projektová suma a NFP

Pole amount je celková zazmluvnená suma projektu (amount_type=total_contracted_project). nfp_amount je schválený nenávratný finančný príspevok a own_resources_amount sú schválené vlastné zdroje. Tieto sumy preto nemusia byť rovnaké. Staršie pole url zostáva kvôli kompatibilite odkazom na zmluvu; nové polia project_url a contract_url význam odkazov rozlišujú explicitne. source_api_url smeruje na oficiálny strojovo čitateľný ITMS Open Data záznam a stav je pravidelne synchronizovaný z tohto zdroja.

{ "amount": 1910164.85, "amount_type": "total_contracted_project",
  "currency": "EUR", "nfp_amount": 1146098.91,
  "own_resources_amount": 764065.94,
  "project_url": "https://www.itms2014.sk/projekt?id=...",
  "contract_url": "https://www.crz.gov.sk/zmluva/.../" }

Dlhy - aktuálny stav a história

company_debts vracia v debts[] aktuálne evidované dlhy voči Sociálnej poisťovni, VšZP a Dôvere. Každý záznam obsahuje obdobie sledovania: first_seen_on, last_seen_on, resolved_on a active. Parameter history=1 pridá aj history[] s aktívnymi aj ukončenými obdobiami zo snapshotov SP a VšZP. Dôvera sa overuje priamo podľa firemného IČO a výsledok sa bezpečne cacheuje na 12 hodín; neposkytuje historický export. Stav overenia je v meta.dovera_lookup. Bez history=1 ostáva odpoveď ľahká a rýchla.

Request

curl -H "X-API-Key: YOUR_KEY" "https://api-data.eu/api/v2/company_debts.php?ico=31813861&history=1"

Odpoveď - skrátené

{ "ok": true, "data": {
  "ico": "31813861",
  "debts": [{
    "source": "socpoist",
    "amount": 167075367.78,
    "first_seen_on": "2026-06-15",
    "last_seen_on": "2026-06-15",
    "resolved_on": null,
    "active": true
  }],
  "summary": {
    "count": 1,
    "total_value": 167075367.78,
    "history_count": 1,
    "resolved_count": 0
  },
  "history": [ ... ]
} }

Finančná správa - daňový profil a obdobia

company_fs vracia existujúce polia vat a tax_periods[] a navyše corporate_tax_periods[] s vyrubenou daňou, dodatočne vyrubenou daňou a daňovou stratou a vat_special_schemes[] s osobitným režimom DPH. Pole tax_incentives[] pridáva odpočty na výskum a vývoj, investície, podporu športu a oslobodenia príjmov. Pole regulated_levies[] obsahuje zverejnené odvody regulovaných osôb. Pri DPH obdobiach môže byť navyše normalizované obdobie, dátum snapshotu a označenie zdroja.

Daňové sumy a profil DPH nie sú automaticky rizikové signály. Odpoveď preto obsahuje classification.risk_score_effect = none a model rizikového skóre v1 zostáva nezmenený.

curl -H "X-API-Key: YOUR_KEY" "https://api-data.eu/api/v2/company_fs.php?ico=54307945"

Dáta sú z oficiálnych CC0 exportov Finančnej správy. Ak export uvádza iba DIČ, záznam sa k firme pripája cez aktuálne DIČ evidované pri jej IČO.

Príklad - rizikové skóre

company_risk hodnotí vlastné dáta firmy. company_risk_network vracia celkové sieťové skóre: vlastnú firmu plus najvyššie riziko v okolí grafu, cez koho sú rizikové firmy napojené a stručné vysvetlenie. Pôvodné vlastné skóre je stále samostatne v data.own.

Request

curl -H "X-API-Key: YOUR_KEY" "https://api-data.eu/api/v2/company_risk.php?ico=51865467"

Odpoveď

{ "ok": true, "data": {
  "ico": "51865467", "name": "SLOVNAFT, a.s.",
  "score": 2, "level": "low",
  "factors": [ ... ],
  "financials": { "year": 2024, "revenue": 0, "profit": 0, "equity": 0 }
} }

Sieťové riziko - request

curl -H "X-API-Key: YOUR_KEY" "https://api-data.eu/api/v2/company_risk_network.php?ico=36426989&depth=2&limit=8&max_nodes=120"

Sieťové riziko - odpoveď

{ "ok": true, "data": {
  "own": { "score": 9, "level": "critical" },
  "network": {
    "score": 9,
    "level": "critical",
    "related_score": 3,
    "related_weighted_score": 2,
    "own_included": true,
    "own_signal": { "score": 9, "level": "critical" },
    "connections": [
      {
        "name": "SCHIPRO MT, s. r. o.",
        "score": 3,
        "relation": "Konateľ",
        "via": ["Fyzicka osoba #9176"],
        "factors": ["loss_2025"]
      }
    ]
  }
} }

v2 - Novozapísané firmy a živnosti

GET

Endpoint: /api/v2/companies_new.php
Denný feed nových zápisov z registra s filtrami a stránkovaním.

Query parametre

days - 1-31 (default 7)
form - all | sro | zivnost | as
q - názov alebo mesto
act - predmet podnikania (min. 3 znaky)
page, limit - stránkovanie (limit max 50)

Odpoveď

{ "ok": true, "data": {
  "items": [ {
    "ico": "12345678", "name": "Nová firma s.r.o.",
    "legal_form": "...", "established": "2026-06-10",
    "city": "Košice", "activities": ["..."], "activities_count": 5
  } ],
  "total": 142
}, "meta": { "page": 1, "pages": 8, "time_ms": 6 } }

v2 - Watchlist / monitoring

GET / POST

Endpoint: /api/v2/watchlist.php
Sledované firmy a osoby viazané na licenciu API kľúča. Počet položiek je obmedzený plánom (FREEMIUM 3 … ENTERPRISE 500).

História zmien: /api/v2/watchlist_events.php. Bez nových parametrov vracia pôvodný zoznam udalostí. Voliteľné filtre a zoskupenie sú iba rozšírením existujúcej odpovede.

Akcia	Metóda	Parametre	Popis
list	GET	-	Zoznam sledovaných položiek.
add	POST	ico \| person_key, label?, freq	Pridá položku (freq: daily\|weekly\|off).
remove	POST	ico \| person_key	Odstráni položku.
status	GET	ico \| person_key	Či už je subjekt sledovaný.

Parameter udalostí	Hodnoty	Popis
ico	6-8 číslic	Zmeny jednej sledovanej firmy.
days	1-3650	Obdobie histórie, predvolene 90 dní.
category	finance\|people\|address\|status\|other	Filter typu zmeny.
sort	newest\|smart	Inteligentné poradie uprednostní neprečítané a závažné zmeny.
grouped	0\|1	Zbalí dávku historických závierok do jednej udalosti.
group	subject	Súhrn udalostí po sledovaných firmách a osobách.
unread	0\|1	Len neprečítané udalosti.
page, limit	limit 1-500	Stránkovanie výsledku.

Detail jednej firmy so zoskupenými zmenami

curl -H "X-API-Key: YOUR_KEY" \
  "https://api-data.eu/api/v2/watchlist_events.php?ico=51865467&days=365&grouped=1&sort=smart"

total_count zachováva počet zdrojových udalostí; display_count udáva počet po zoskupení.

Pridať do watchlistu

curl -X POST -H "X-API-Key: YOUR_KEY" \
  -d "action=add&ico=51865467&freq=daily" \
  "https://api-data.eu/api/v2/watchlist.php"

Chyby špecifické

429 - WATCHLIST_FULL (dosiahnutý limit plánu)
400 - MISSING_SUBJECT (chýba ico aj person_key)

PHP config (recommended)

Helper pre v2 (header auth). Pridal som aj fallback na v1 len pre legacy prípady.

<?php
// api_config.php
const API_KEY  = 'TU_VLOŽ_SVOJ_API_KĽÚČ';
const API_V2   = 'https://api-data.eu/api/v2/';
const API_V1   = 'https://api-data.eu/api/';

function api_get_v2(string $endpoint, array $params = []): array {
  $url = API_V2 . ltrim($endpoint, '/');
  if ($params) $url .= '?' . http_build_query($params);

  $ch = curl_init($url);
  curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 5,
    CURLOPT_HTTPHEADER => [
      'X-API-Key: ' . API_KEY,
      'Accept: application/json'
    ],
  ]);

  $resp = curl_exec($ch);
  $http = ($resp === false) ? 0 : (int)curl_getinfo($ch, CURLINFO_HTTP_CODE);
  $err  = ($resp === false) ? curl_error($ch) : null;
  curl_close($ch);

  if ($resp === false) return ['ok'=>false,'error'=>'http_error','msg'=>$err];
  $data = json_decode($resp, true);
  if (!is_array($data)) return ['ok'=>false,'error'=>'bad_json','http'=>$http,'raw'=>$resp];
  $data['_http'] = $http;
  return $data;
}

/**
 * v1 legacy helper (kľúč v URL).
 * Použi iba ak potrebuješ kompatibilitu so starým kódom.
 */
function api_get_v1(string $file, array $params = []): array {
  $params['k'] = API_KEY;
  $url = API_V1 . ltrim($file, '/');
  $url .= '?' . http_build_query($params);

  $json = @file_get_contents($url);
  if ($json === false) return ['ok'=>false,'error'=>'http_error'];
  $data = json_decode($json, true);
  return is_array($data) ? $data : ['ok'=>false,'error'=>'bad_json','raw'=>$json];
}

JavaScript (fetch) - typický flow

1) search → 2) vyber IČO → 3) company detail → 4) vyplň form.

// JS fetch flow (v2)
const API_KEY = 'YOUR_KEY';
const BASE = 'https://api-data.eu/api/v2/';

async function apiGet(path, params = {}) {
  const url = new URL(BASE + path);
  Object.entries(params).forEach(([k,v]) => url.searchParams.set(k, v));
  const r = await fetch(url.toString(), { headers: { 'X-API-Key': API_KEY } });
  const data = await r.json();
  if (!data || data.ok !== true) throw data;
  return data;
}

async function searchAndPick(query) {
  const res = await apiGet('search_company.php', { q: query });
  const first = (res.results || [])[0];
  if (!first) return null;
  return first.ico;
}

async function fillCompany(ico) {
  const res = await apiGet('company.php', { ico, country: 'SK' });
  const c = res.data;
  console.log('NAME', c.name);
  console.log('ICO', c.ico);
  console.log('DIC', c.dic);
  console.log('VAT', c.ic_dph);
  console.log('ADDR', c.address1, c.city, c.postal_code);
}

(async () => {
  const ico = await searchAndPick('alza');
  if (ico) await fillCompany(ico);
})();

PHP (cURL) - typický flow

<?php
require __DIR__ . '/api_config.php';

// 1) search
$s = api_get_v2('search_company.php', ['q' => 'alza']);
if (empty($s['ok'])) die('Search error: ' . ($s['error']['code'] ?? $s['error'] ?? 'unknown'));

$first = $s['results'][0] ?? null;
if (!$first) die('No results');

$ico = $first['ico'];

// 2) detail
$d = api_get_v2('company.php', ['ico' => $ico, 'country' => 'SK']);
if (empty($d['ok'])) die('Detail error: ' . ($d['error']['code'] ?? $d['error'] ?? 'unknown'));

$c = $d['data'];
echo "Name: {$c['name']}\n";
echo "ICO: {$c['ico']}\n";
echo "DIC: " . ($c['dic'] ?? '') . "\n";
echo "VAT: " . ($c['ic_dph'] ?? '') . "\n";
echo "Address: {$c['address1']}, {$c['city']}, {$c['postal_code']}\n";

Python (requests) - typický flow

import requests

API_KEY = "YOUR_KEY"
BASE = "https://api-data.eu/api/v2/"

def api_get(path, params=None):
    r = requests.get(BASE + path, params=params or {}, headers={"X-API-Key": API_KEY}, timeout=5)
    data = r.json()
    if not data.get("ok"):
        raise Exception(data)
    return data

s = api_get("search_company.php", {"q": "alza"})
ico = s["results"][0]["ico"]

d = api_get("company.php", {"ico": ico, "country": "SK"})
c = d["data"]

print(c["name"], c["ico"], c.get("dic"), c.get("ic_dph"))

Chyby

v2 odporúčanie: používať error.code + HTTP status (400/401/403/404/429/5xx).

MISSING_INPUT - chýba parameter
INVALID_* - neplatný formát
NOT_FOUND - firma neexistuje
UPSTREAM_* - problém upstream (ARES/VIES)
RATE_LIMITED - rate limit

Poznámky

Pre nové integrácie používaj v2 endpointy a header X-API-Key.
Frontend kľúč nikdy nie je úplne skrytý, preto pri browser integráciách používaj doménovo viazaný kľúč.
Weather endpointy môžu mať verejný IP limit bez kľúča; s API kľúčom sa použijú licenčné limity.

Changelog

v2: odporúčaný header auth (X-API-Key), v1 zachovaný kvôli kompatibilite.
license_stats: endpoint pre zistenie plánu a usage bez loginu.

Legacy v1 (kompatibilita)

v1 endpointy sú zachované, ale pre nové integrácie ich nepoužívaj. Dôvod: kľúč v URL k= sa môže logovať a leakovať.

Ak máš starý modul/implementáciu, nechaj v1. Ak tvoríš niečo nové, choď rovno v2.

v1 - Company detail

GET

Endpoint: /api/company.php

GET https://api-data.eu/api/company.php?ico=12345678&country=SK&k=YOUR_KEY

v1 - CZ Company detail

GET

Endpoint: /api/cz_company.php

GET https://api-data.eu/api/cz_company.php?ico=27082440&k=YOUR_KEY

v1 - Company search

GET

Endpoint: /api/search_company.php

GET https://api-data.eu/api/search_company.php?q=alza&k=YOUR_KEY

v1 - VAT check (VIES)

GET

Endpoint: /api/check_vat.php

GET https://api-data.eu/api/check_vat.php?country=SK&vat=SK4020121402&k=YOUR_KEY

v1 - License stats

GET

Endpoint: /api/license_stats.php

GET https://api-data.eu/api/license_stats.php?k=YOUR_KEY