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 @ 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"}
  • 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,
	  "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 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)
lang nie Vrátený jazykový variant pre textové atribúty, príp. chybové správy.
sk - slovenčina (default)
en - angličtina
ico nie Vyhľadanie subjektu podľa IČO (aj čiastková zhoda).
dic nie Vyhľadanie subjektu podľa DIČ (aj čiastková zhoda).
icdph nie Vyhľadanie subjektu podľa IČ-DPH.
zip nie Vyhľadanie subjektu podľa PSČ.
city nie Vyhľadanie subjektu podľa obce.
street nie Vyhľadanie subjektu podľa ulice.
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 (lokality), 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.
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_format nie Vráti odpoveď v požadovanom formáte. Momentálne podporuje jedinú hodnotu label-value pre prípadnú kombináciu s parametrom name. Vrátená odpoveď je formátovaná špecificky pre autocomplete javascript widgets (tzn. value obsahuje zakódovaný JSON reťazec).
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".
  • company_executives - vráti zoznam osôb vo firme (konateľov, akcionárov, ..)
  • company_offices - vráti zoznam pobočiek
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".
  • company_executives - vráti zoznam osôb vo firme (konateľov, akcionárov, ..)
  • company_offices - vráti zoznam pobočiek
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",
    	  "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",
    	  "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 }
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' => '',
    			'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