Dokumentácia
Môj účet Registrácia - vytvorenie účtu Nastavenia účtu
API Integrácia Metódy a parametre Príklad - jQuery UI Príklad - vanilla JS Príklad - server REST
O projekte Dátové registre Obchodné podmienky Ochrana súkromia Kontakt

Kľúčové slová

API metódy a parametre

Všetky API metódy vyžadujúce prístup k údajom musia odoslať požiadavky metódou POST. Metóda GET nie je podporovaná (s výnimkou metódy ping) z bezpečnostných dôvodov ako aj kvôli technickým obmedzeniam. Nasledovné URL linky (endpoints) sú dostupné prostredníctvom API rozhrania na serveri bizdata.sk.
  1. ping
  2. check-api-key
  3. search-company
  4. get-company-data
https://bizdata.sk/api/v1/ping
POST / GET
Popis:
Podporná metóda pre uľahčenie integrácie pri úvodnom spustení. Môže tiež slúžiť na overenie dostupnosti API rozhrania. Ako jediná nevyžaduje autentikačný API kľúč a akceptuje požiadavky aj metódou GET.
Parametre:
Žiadne.
Vrátená odpoveď:
  • V prípade úspechu vráti JSON obsahujúci kľúč response s aktuálnym časom servera.
    { "response":"PONG @ 2024-12-31 23:59:59" }
  • V prípade chyby vráti JSON reťazec obsahujúci kód chyby s popisom.
    { "errorMsg": "Page not found.", "errorCode": 404 }
https://bizdata.sk/api/v1/check-api-key
POST
Popis:
Podporná metóda pre overenie platnosti autentifikačného API kľúča.
Parametre:
Názov Povinný Popis
xauth áno Autentifikačný API kľúč v tvare napr. x97WeRRt65M1.. nájdete v Nastaveniach v časti API Integrácia.
Vrátená odpoveď:
  • Vráti JSON obsahujúci kľúč valid s hodnotou 1 v prípade úspechu, alebo 0 v prípade neúspechu.
    {"valid": 1, "key": "atVeY..63Mzo"}
    {"valid": 0, "key": "atVeY..63Mzo"}
  • V prípade chyby vráti JSON reťazec obsahujúci kód chyby s popisom.
    { "errorMsg": "Required parameter not found (xauth).", "errorCode": 400 }
Vrátená odpoveď:
Príklad implementácie v jQuery: 
$.post({ // DO NOT USE $.get({..})
	url : "https://bizdata.sk/api/v1/check-api-key",
	data : {
		xauth: "a5rUY08-Mj4.."
	},
	success : function(response) {
		// debugger // optionally set breakpoint e.g. in Chrome debugger
		// console.log(response) // or send response directly to console
		if (response.valid != undefined) {
			alert("Kľúč je "+(response.valid ? "platný" : "neplatný")+".");
		} else {
			alert("Chyba! "+(response.errorMsg ? response.errorMsg : "Neznáma chyba."));
		}
	}
});
https://bizdata.sk/api/v1/search-company
POST
Popis:
Hlavná metóda pre vyhľadanie subjektu zadaním jeho obchodného názvu, mena, IČO alebo DIČ. Vrátená odpoveď už obsahuje v odpovedi všetky atribúty nájdených subjektov (ako JSON reťazec). Nie je preto potrebné odoslať žiadnu ďalšiu požiadavku pre načítanie údajov o subjekte. Zbytočne by sa vyčerpal zvyšujúci limit požiadaviek. Stačí dekódovať JSON reťazec zvoleného subjektu a dekódované atribúty nastaviť do príslušných polí, resp. ďalej s nimi manipulovať. Vrátená odpoveď obsahuje v hlavičke taktiež informáciu o zvyšujúcom limite požiadaviek.
Parametre:
Názov Povinný Popis
xauth áno Autentifikačný API kľúč v tvare napr. x97WeRRt65M1.. nájdete v Nastaveniach v časti API Integrácia.
term nie 1) Názov, IČO alebo DIČ hľadaného subjektu. 1) Parameter je povinný, pokiaľ nie je použitý parameter name. Vrátená odpoveď je špecificky formátovaná pre použitie v javascript knižnici jQuery autocomplete - tzn. obsahuje pole s kľúčmi label a value.
Príklad odpovede:
[
 {
  "label": "AAA Experts, s.r.o.",
  "value": ""{\"obchodne_meno\":\"AAA Experts, sro.\",\"hash\":\"35Cw..\"..
 },
 {
  "label": "AAA Audit, s. r. o.",
  "value": ""{\"obchodne_meno\":\"AAA Audit, s.r.o.\",\"hash\":\"3ww-w..\"..
 },
 ...
]
name nie 1) Názov, IČO alebo DIČ hľadaného subjektu. 1) Parameter je povinný, pokiaľ nie je použitý parameter term. Vrátená odpoveď je vo formáte JSON s atribútmi:
success - (int) obsahuje 1 v prípade úspechu, 0 v prípade chyby.
cntTotal - (int) celkový počet nájdených záznamov.
pattern - (string) pôvodný hľadaný výraz.
data - (array) zoznam vrátených subjektov s detailným výpisom základných atribútov.
Príklad odpovede:
{
  "success": 1,
  "pattern": "aaa",
  "cntTotal": 67,
  "data": [
	{
	  "obchodne_meno": "AAA Company, s.r.o.",
	  "hash": "35Cy15w..",
	  "is_active": 1,
	  "is_likvidacia_konkurz": 0,
	  "ico": "36629999",
	  "dic": "2021809999",
	  "kod_typ_osoby": "P",
	  "addr_street_nr": "Mierová 123",
	  "addr_street": "Mierová",
	  "addr_number": "123",
	  "addr_city": "Snina",
	  "addr_zip": "97499",
	  "hlavicka": "Spoločnosť zapísaná v OÚ Snina, odd. sro, vložka 123/S.",
	  "hlavicka_kratka": "OS Snina, oddiel sro, vložka 1234/S.",
	  "orsr_sud": "Snina",
	  "orsr_oddiel": "sro",
	  "orsr_vlozka": "1234/S",
	  "zrsr_urad": "Snina",
	  "zrsr_cislo_registra": "678-99999",
	  "kod_nace": "69100",
	  "text_nace": "Právne činnosti",
	  "kod_pravna_forma": "112",
	  "text_pravna_forma": "Spol. s r. o.",
	  "date_vznik": "26.03.2008",
	  "date_zanik": ""
	},
	{
	  "obchodne_meno": "AAA Autocamp, s.r.o.",
	  "hash": "R1-8QWqw..",
	  ...
	},
  ...
]
is_active nie V akých typoch subjektov vyhľadávať?
1 - len v aktívnych subjektoch, tzn. zaniknuté sú ignorované (default)
0 - len v zaniknutých subjektoch
any - hľadať vo všetkých subjektoch (tiež prázdny reťazec)
option_size nie Počet vrátených záznamov 1 - 30, štandardne je vrátených 10 záznamov.
lang nie Vrátený jazykový variant pre textové atribúty, príp. chybové správy.
sk - slovenčina (default)
en - angličtina
option_find_inside nie Pokúsi sa vyhľadať zhodu aj v strede reťazca.
0 - nie, tzn. hľadá zhodu od začiatku slova (default). Napríklad pri hľadaní zita by nevrátilo obezita, ale len Zita.
1 - áno, hľadá zhodu aj v strede slova. Napríklad pri hľadaní zita by vrátilo obezita aj Zita.
option_extra_field nie Zoznam dodatočných atribútov oddelených čiarkou, ktoré nie sú vrátené v štandardnej odpovedi a je potrebné si tieto polia explicitne vyžiadať. Podporované sú:
  • text_nace_full - neskrátený popis predmetu činnosti, napr. "Ostatné pomocné obchodné činnosti" namiesto skráteného "Ost.pomoc.obch.činnosti" - číselník NACE.
  • likvidacia_konkurz_since - dátum vstupu do likvidácie alebo konkurzu, napr. "31.12.2024".
  • obchodne_meno_highlight - zvýrazený hľadaný reťazec, napr. pre hľadaný výraz "jan" vráti "<b class="hilight">Ján</b> Holub".
  • kod_okres - kód okresu, napr. "SK0108" podľa číselníka.
  • text_okres - názov okresu, napr. "Senec" podľa číselníka.
  • kod_kraj - kód kraja, napr. "SK010" podľa číselníka.
  • text_kraj - názov kraja, napr. "Bratislavský kraj" podľa číselníka.
  • kod_velkost - kód veľkosti organizácie, napr. "12" podľa číselníka.
  • text_velkost - text veľkosti organizácie, napr. "50-99 zamestnancov" podľa číselníka.
  • kod_druh_vlastnictva - kód druhu vlastníctva 0-9, napr. "2" podľa číselníka.
  • text_druh_vlastnictva - text druhu vlastníctva, napr. "Štátne" podľa číselníka.
  • orsr_den_zapisu - deň zápisu do Obchodného registra, napr. "31.01.2024".
  • orsr_den_vymazu - deň výmazu z Obchodného registra, napr. "31.12.2024".
Odpoveď v prípade chyby:
V prípade chyby vráti JSON reťazec obsahujúci kód chyby s popisom - napr.
{ "errorMsg": "Invalid authentication key.", "errorCode": 403 }
https://bizdata.sk/api/v1/get-company-data
POST
Popis:
Metóda pre načítanie údajov o konkrétnom subjekte. V hlavičke vráti zostávajúci počet požiadaviek v platnom období.
Dôležité: Túto metódu nie je potrebné volať po volaní metódy search-company, nakoľko vrátená odpoveď už obsahuje atribúty nájdených subjektov (JSON reťazec). Jej volaním by došlo ku rýchlejšiemu vyčerpaniu požiadaviek.
Parametre:
Názov Povinný Popis
xauth áno Autentifikačný API kľúč v tvare napr. x97WeRRt65M1.. nájdete v Nastaveniach v časti API Integrácia.
hash áno Identifikátor subjektu - parameter hash vrátený metódou search-company.
option_extra_field nie Zoznam dodatočných atribútov oddelených čiarkou, ktoré nie sú vrátené v štandardnej odpovedi a je potrebné si tieto polia explicitne vyžiadať. Podporované sú:
  • text_nace_full - neskrátený popis predmetu činnosti, napr. "Ostatné pomocné obchodné činnosti" namiesto skráteného "Ost.pomoc.obch.činnosti" - číselník NACE.
  • likvidacia_konkurz_since - dátum vstupu do likvidácie alebo konkurzu, napr. "31.12.2024".
  • obchodne_meno_highlight - zvýrazený hľadaný reťazec, napr. pre hľadaný výraz "jan" vráti "<b class="hilight">Ján</b> Holub".
  • kod_okres - kód okresu, napr. "SK0108" podľa číselníka.
  • text_okres - názov okresu, napr. "Senec" podľa číselníka.
  • kod_kraj - kód kraja, napr. "SK010" podľa číselníka.
  • text_kraj - názov kraja, napr. "Bratislavský kraj" podľa číselníka.
  • kod_velkost - kód veľkosti organizácie, napr. "12" podľa číselníka.
  • text_velkost - text veľkosti organizácie, napr. "50-99 zamestnancov" podľa číselníka.
  • kod_druh_vlastnictva - kód druhu vlastníctva 0-9, napr. "2" podľa číselníka.
  • text_druh_vlastnictva - text druhu vlastníctva, napr. "Štátne" podľa číselníka.
  • orsr_den_zapisu - deň zápisu do Obchodného registra, napr. "31.01.2024".
  • orsr_den_vymazu - deň výmazu z Obchodného registra, napr. "31.12.2024".
Vrátená odpoveď:
  • V prípade úspechu vráti JSON obsahujúci kľúč response s výsledkom overenia, napr. 
    {
  "success": 1,
  "data": [
	{
	  "obchodne_meno": "AAA Company, s.r.o.",
	  "hash": "35Cy15w..",
	  "is_active": 1,
	  "is_likvidacia_konkurz": 0,
	  "ico": "36629999",
	  "dic": "2021809999",
	  "kod_typ_osoby": "P",
	  "addr_street_nr": "Mierová 123",
	  "addr_street": "Mierová",
	  "addr_number": "123",
	  "addr_city": "Snina",
	  "addr_zip": "97499",
	  "hlavicka": "Spoločnosť zapísaná v OÚ Snina, oddiel sro, vložka 1234/S.",
	  "hlavicka_kratka": "OS Snina, oddiel sro, vložka 1234/S.",
	  "orsr_sud": "Snina",
	  "orsr_oddiel": "sro",
	  "orsr_vlozka": "1234/S",
	  "zrsr_urad": "Snina",
	  "zrsr_cislo_registra": "678-99999",
	  "kod_nace": "69100",
	  "text_nace": "Právne činnosti",
	  "kod_pravna_forma": "112",
	  "text_pravna_forma": "Spol. s r. o.",
	  "date_vznik": "26.03.2008",
	  "date_zanik": ""
	},
]
  • V prípade chyby vráti JSON reťazec obsahujúci kód chyby s popisom.
    { "errorMsg": "Autentification key not found.", "errorCode": 400 }
Zistenie zostávajúceho limitu API požiadaviek
Volanie metód search-company a get-company-data vráti v hlavičke odpovede informáciu o zvyšujúcom, resp. spotrebovanom limite požiadaviek pre danú doménu v dvoch parametroch:
  • x-rate-limit-max - maximálny počet požiadaviek v platnom období, napr. 1000
  • x-rate-limit-remaining - počet zostávajúcich (nevyčerpaných) požiadaviek, napr. 123