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.
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 }
- V prípade úspechu vráti JSON obsahujúci kľúč response s aktuálnym časom servera.
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
1v prípade úspechu, alebo0v 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áti JSON obsahujúci kľúč valid s hodnotou
- 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.termnie 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ľúčmilabelavalue.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..\".. }, ... ]namenie 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) obsahuje1v prípade úspechu,0v 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_activenie V akých typoch subjektov vyhľadávať? 1- len v aktívnych subjektoch, tzn. zaniknuté sú ignorované (default)0- len v zaniknutých subjektochany- hľadať vo všetkých subjektoch (tiež prázdny reťazec)langnie Vrátený jazykový variant pre textové atribúty, príp. chybové správy. sk- slovenčina (default)en- angličtinaiconie Vyhľadanie subjektu podľa IČO (aj čiastková zhoda). dicnie Vyhľadanie subjektu podľa DIČ (aj čiastková zhoda). icdphnie Vyhľadanie subjektu podľa IČ-DPH. zipnie Vyhľadanie subjektu podľa PSČ. citynie Vyhľadanie subjektu podľa obce. streetnie Vyhľadanie subjektu podľa ulice. kod_krajnie Vyhľadanie subjektu podľa kódu kraja, napr. SK010.kod_okresnie Vyhľadanie subjektu podľa kódu okresu, napr. SK0101.kod_sidlonie Vyhľadanie subjektu podľa kódu obce (lokality), napr. SK0236543071.full_addressnie 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_sizenie Počet vrátených záznamov 1 - 30, štandardne je vrátených 10 záznamov. option_find_insidenie 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ízitaby nevrátiloobezita, ale lenZita.1- áno, hľadá zhodu aj v strede slova. Napríklad pri hľadanízitaby vrátiloobezitaajZita.option_formatnie Vráti odpoveď v požadovanom formáte. Momentálne podporuje jedinú hodnotu label-valuepre prípadnú kombináciu s parametromname. Vrátená odpoveď je formátovaná špecificky pre autocomplete javascript widgets (tzn.valueobsahuje zakódovaný JSON reťazec).option_extra_fieldnie 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 hashvrátený metódou search-company.option_extra_fieldnie 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 }
- V prípade úspechu vráti JSON obsahujúci kľúč response s výsledkom overenia, napr.
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 }
- V prípade úspechu vráti JSON s atribútmi osoby a základnými (fakturačnými) údajmi materského subjektu.
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_activeapod. - 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 }
- V prípade úspechu vráti JSON s atribútmi osoby a základnými (fakturačnými) údajmi materského subjektu.
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.1000x-rate-limit-remaining- počet zostávajúcich (nevyčerpaných) požiadaviek, napr.123