Api-data.eu – Firemné údaje pre e-shopy a portály

Firemné údaje SK/CZ pre e-shopy

Dokumentácia k API

API-DATA poskytuje REST endpointy na dopĺňanie firemných údajov zo Slovenska (RPO), Česka (ARES - dočasne) a overenie IČ DPH v EÚ cez VIES. 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

1 dopyt = 1 HTTP request na API endpoint (v1 aj v2).
Dopyty sa rátajú rovnako pre API, JS snippet aj moduly (všetko ide cez API).
Limity sú hodinové. „Špička / hod.“ je krátkodobý burst limit pre peak.

Typické scenáre

Firma (v2, SK/CZ): každý návrh = 1 dopyt (/api/v2/search_company.php). Pri detail=1 sa po výbere polia zvyčajne vyplnia bez ďalšieho dopytu; iba ak chýbajú údaje, dotiahne sa detail = +1 dopyt (/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)

Interactive

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.

API kľúč (v2)

Použiť demo kľúč

X-API-Key

Odporúčanie: pre produkciu používaj vlastný kľúč viazaný na doménu (a pri S2S podpis). Demo kľúč je verejný a limitovaný.

Rýchle testy

Tieto tlačidlá presunú stránku na konkrétny endpoint a spustia test priamo tam (výstup uvidíš hneď pri sekcii).

v2 - Company detail (SK/CZ index)

GET

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

Query parametre

ico - IČO (číslice), alebo
name - názov (min 3 znaky)
country - SK|CZ (default SK)

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?name=alza&country=SK"

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

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/cz_company.php?ico=27082440"

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"

{
  "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 - License stats (usage bez loginu)

GET

Endpoint: /api/v2/license_stats.php
Informácie o programe, hourly limite a usage okne.

Príklad

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

{
  "ok": true,
  "data": {
    "license": {
      "id": 123,
      "program": "Starter",
      "program_code": "starter",
      "key_type": "standard",
      "hourly_limit": 1000,
      "valid_until": "2026-03-01 12:00:00"
    },
    "usage": {
      "window_start": "2026-02-08 14:00:00",
      "used": 12,
      "remaining": 988
    }
  },
  "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

{}

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

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