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.

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 @ 2025-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"}
  • 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 (firmy, organizácie) 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": "35Cy15w658WtRRE85_98Xb..",
	  "is_active": 1,
	  "is_likvidacia_konkurz": 0,
	  "is_debtor": 0,
	  "is_cinnost_pozastavena": 0,
	  "ico": "36629999",
	  "dic": "2021809999",
	  "icdph": "SK2021809999",
	  "icdph_par": "7a",
	  "kod_typ_osoby": "P",
	  "addr_street_nr": "Mierová 123",
	  "addr_street": "Mierová",
	  "addr_number": "123",
	  "addr_city": "Snina",
	  "addr_zip": "97499",
	  "addr_gps": "48.1517,17.1093",
	  "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 1 - vráti aktívne subjekty, tzn. zaniknuté ignoruje (default, aj pri neuvedení atribútu)
0 - vráti len zaniknuté subjekty
any - hľadať v zaniknutých aj aktívnych subjektoch (tiež prázdny reťazec)
ico nie Vyhľadanie subjektu podľa IČO (aj čiastočná zhoda).
dic nie Vyhľadanie subjektu podľa DIČ (aj čiastočná zhoda).
icdph nie Vyhľadanie subjektu podľa IČ-DPH (aj čiastočná zhoda).
zip nie Vyhľadanie subjektu podľa PSČ (aj čiastočná zhoda).
city nie Vyhľadanie subjektu podľa obce (aj čiastočná zhoda).
street nie Vyhľadanie subjektu podľa ulice (aj čiastočná zhoda).
kod_kraj nie Vyhľadanie subjektu podľa kódu kraja, napr. SK010.
kod_okres nie Vyhľadanie subjektu podľa kódu okresu, napr. SK0101.
kod_sidlo nie Vyhľadanie subjektu podľa kódu obce resp. mestskej časti, napr. SK0236543071.
full_address nie Vyhľadanie subjektu podľa adresy, napr. bratislavska, senec. Zadaná adresa musí obsahovať reťazec s uvedením ulice (môže obsahovať aj popisné číslo), obce a PSČ. Tieto tri časti adresy musia byť oddelené čiarkou a môžu byť uvedené v ľubovoľnom poradí. Nie je nutné uvádzať všetky tri časti adresy, postačí uvedenie aspoň jednej.
Rozšírené vyhľadávacie atribúty
option_size nie Počet vrátených záznamov 1 - 30, štandardne je vrátených 10 záznamov.
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_lang nie Vrátený jazykový variant pre textové atribúty, príp. chybové správy.
sk - slovenčina (default)
en - angličtina
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ú:
  • 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"
  • 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.2025"
  • kod_kraj - kód kraja, napr. "SK010" podľa číselníka
  • text_kraj - názov kraja, napr. "Bratislavský kraj" podľa číselníka
  • kod_okres - kód okresu, napr. "SK0108" podľa číselníka
  • text_okres - názov okresu, napr. "Senec" podľa číselníka
  • kod_sidlo - kód obec alebo mestskej časti, napr. "SK0106504769" podľa číselníka
  • text_sidlo - názov obce alebo mestskej časti, napr. "Rohožník" 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.2025"
  • orsr_den_vymazu - deň výmazu z Obchodného registra, napr. "31.12.2025"
  • date_last_reg_change - dátum poslednej zmeny v registri, napr. "31.12.2025"
  • company_executives - vráti zoznam osôb vo firme (konateľov, akcionárov, ..)
  • company_offices - vráti zoznam pobočiek (adresu, gps, ..)
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ú:
  • 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"
  • 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.2025"
  • kod_kraj - kód kraja, napr. "SK010" podľa číselníka
  • text_kraj - názov kraja, napr. "Bratislavský kraj" podľa číselníka
  • kod_okres - kód okresu, napr. "SK0108" podľa číselníka
  • text_okres - názov okresu, napr. "Senec" podľa číselníka
  • kod_sidlo - kód obec alebo mestskej časti, napr. "SK0106504769" podľa číselníka
  • text_sidlo - názov obce alebo mestskej časti, napr. "Rohožník" 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.2025"
  • orsr_den_vymazu - deň výmazu z Obchodného registra, napr. "31.12.2025"
  • date_last_reg_change - dátum poslednej zmeny v registri, napr. "31.12.2025"
  • company_executives - vráti zoznam osôb vo firme (konateľov, akcionárov, ..)
  • company_offices - vráti zoznam pobočiek (adresu, gps, ..)
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,
    	  is_debtor: 0,
    	  is_cinnost_pozastavena: 0,
    	  ico: "36629999",
    	  dic: "2021809999",
    	  icdph: "SK2021809999",
    	  icdph_par: "7a",
    	  kod_typ_osoby: "P",
    	  addr_street_nr: "Mierová 123",
    	  addr_street: "Mierová",
    	  addr_number: "123",
    	  addr_city: "Snina",
    	  addr_zip: "97499",
    	  addr_gps: "48.921,17.658",
    	  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: "",
    	  company_executives: [
    		{
    		  city: "Bratislava",
    		  zip: "85103",
    		  is_active: 1,
    		  is_foreigner: 0,
    		  person_name: "Ján Novák",
    		  role_code: "S",
    		  role_title: "Spoločník",
    		  role_from: "2022-11-08",
    		  role_to: "",
    		}
    	  ]
    	  "company_offices" [
    		{
    		  is_active => 1,
    		  from => "2004-03-26",
    		  to => "2014-12-31",
    		  city => "Bratislava",
    		  street => "Osuského 123",
    		  zip => "85103",
    		  gps => "48.1271,17.1258",
    		}
    	  ]
    	},
    	...
      ]
    }
  • V prípade chyby vráti JSON reťazec obsahujúci kód chyby s popisom.
    { "errorMsg": "Autentification key not found.", "errorCode": 400 }

https://bizdata.sk/api/v1/search-person-by-company
POST
Popis:
Metóda vráti zoznam osôb (konateľov, štatutárov, akcionárov atď.) v nájdenom subjekte.
Parametre:
Rovnaké ako v prípade search-company.
Vrátená odpoveď:
  • V prípade úspechu vráti JSON s atribútmi osoby a základnými (fakturačnými) údajmi materského subjektu.
    [
    	0 => [
    		'person_name' => 'doc. Ing. Peter Novák',
    		'is_active' => 1,
    		'is_foreigner' => 0,
    		'city' => 'Bratislava',
    		'zip' => '85101',
    		'country' => '', // empty for Slovakia
    		'role_title' => 'Konateľ',
    		'role_code' => 'K',
    		'role_from' => '2014-03-26',
    		'role_to' => '',
    		'company' => [
    			'obchodne_meno' => 'Moja Firma, s.r.o.',
    			'is_active' => 1,
    			'ico' => '36624999',
    			'dic' => '2021806999',
    			'icdph' => 'SK2021806999',
    			'kod_typ_osoby' => 'P',
    			'addr_street_nr' => '29. augusta 123',
    			'addr_city' => 'Senec',
    			'addr_zip' => '92401',
    			'hlavicka' => 'Spoločnosť zapísaná v OR OÚ Senec, oddiel sro, vložka 12/S.',
    			'hlavicka_kratka' => 'OS Senec, oddiel sro, vložka 123/S.',
    		],
    	],
    	1 => [ ... ],
    	...
    ]
  • V prípade chyby vráti JSON reťazec obsahujúci kód chyby s popisom.
    { "errorMsg": "Autentification key not found.", "errorCode": 400 }

https://bizdata.sk/api/v1/search-person
POST
Popis:
Metóda vráti zoznam osôb (konateľov, štatutárov, akcionárov atď.) vo všetkých subjektoch.
Parametre:
Rovnaké ako v prípade search-company s rozdielom, že namiesto vyhľadania v zozname spoločností vyhľadá v zozname osôb - pozrite príklady. Použijú sa rovnako parametre term, name, is_active apod.
Vrátená odpoveď:
  • V prípade úspechu vráti JSON s atribútmi osoby a základnými (fakturačnými) údajmi materského subjektu.
    [
    	0 => [
    		'person_name' => 'doc. Ing. Peter Novák',
    		'is_active' => 1,
    		'is_foreigner' => 0,
    		'city' => 'Bratislava',
    		'zip' => '85101',
    		'country' => '', // empty for Slovakia
    		'role_title' => 'Konateľ',
    		'role_code' => 'K',
    		'role_from' => '2014-03-26',
    		'role_to' => '',
    		'company' => [
    			'obchodne_meno' => 'Moja Firma, s.r.o.',
    			'is_active' => 1,
    			'ico' => '36624999',
    			'dic' => '2021806999',
    			'icdph' => '',
    			'kod_typ_osoby' => 'P',
    			'addr_street_nr' => '29. augusta 123',
    			'addr_city' => 'Senec',
    			'addr_zip' => '92401',
    			'hlavicka' => 'Spoločnosť zapísaná v OR OÚ Senec, oddiel sro, vložka 12/S.',
    			'hlavicka_kratka' => 'OS Senec, oddiel sro, vložka 123/S.',
    		],
    	],
    	1 => [ ... ],
    	...
    ]
  • 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