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 Integrácia - Server REST

Načítanie zoznamu subjektov na strane servera je v niektorých ohľadoch jednoduchšie, než implementácia prostredníctvom javascript v prehliadači. Odpadá napr. nutnosť formátovať odpoveď a nie sú potrebné žiadne externé knižnice.

Pre získanie odpovede na strane servera je potrebné zaslať autorizovanú POST požiadavku s kľúčom xauth a rovnakými vstupnými parametrami ako v prípade implementácie prostredníctvom javascriptu. Vrátená odpoveď môže byť buď vo formáte label-value (autocomplete implementácia) alebo nezakódované dáta ako pole.

Správne nastavenie parametrov v hlavičke (request headers)

Odoslanie požiadavky zo servera vyžaduje správne nastavenie parametrov v hlavičke požiadavky (request headers). POST požiadavka môže byť odoslaná dvoma spôsobmi - buď ako HTML formulár, alebo ako JSON dáta.
  1. HTML formulár
    V tomto prípade sú odosielané údaje zakódované rovnakým spôsobom ako pri odoslaní multipart HTML formulára. Do hlavičky je potrebné uviesť správny typ formátu nasledovne:
    Content-type: application/x-www-form-urlencoded
    Zároveň dáta je potrebné odoslať ako URL-encoded (napr. v PHP použite funkciu http_build_query).
  2. JSON dáta
    V tomto prípade je potrebné dáta odoslať ako zakódovaný JSON reťazec v tvare napr. {key1:"value1", key2:"value2",..}. V prípade PHP použite funkciu json_encode a do hlavičky treba nastaviť dva parametre:
    Content-type: application/json
    Accept: application/json
Pre obidve varianty pozrite vzorový príklad implementácie v PHP nižšie. Na účel testovania môžete využiť tiež voľne dostupné online služby napr. reqbin.com, restninja.io alebo aplikáciu postman.
Funkcia sendApiRequest() pre odoslanie autorizovanej požiadavky

Najprv vytvoríme všeobecnú funkciu (v PHP) pre odoslanie HTTP požiadavky na API rozhranie servera bizdata.sk. Funkcia odošle požiadavku s dodanými parametrami vyhľadávania, ku ktorým pridá niektoré povinné (napr. autentifikačný kľúč xauth). Vrátená odpoveď bude obsahovať dekódované údaje o subjektoch, osobách apod. alebo chybovú správu. 

/**
* @param array $params Request parameters ie. "term", "name", "full_address", "zip" ..
* @param string $urlService Service name ie. "search-person-by-company", defaults to "search-company"
* @return array List of matching records or "errorMsg" if error occured
*/
function sendApiRequest ( array $params, $urlService = 'search-company' )
{
	// zlúčime parametre pre odosielanú API požiadavku
	$params = [
		// povinný autentifikačný kľúč - nájdete ho v Nastaveniach účtu
		'xauth' => 'my-secret-key',
		// nepovinné parametre (atribúty) a nastavenia (options)
		// 'is_active' => 'any', // 0|1|any - hľadať v aktívnych / neaktívnych záznamoch?
		// 'option_size' => 5, // počet vrátených záznamov
		// 'option_format' => 'label-value', // ak chceme odpoveď pre autocomplete
		// 'option_extra_field' => 'text_kraj, text_velkost', // vyžiadame dodatočné polia
	] + $params;

	$options = [
		'http' => [
			'method' => 'POST', // must be uppercase, GET is not supported
			'timeout' => 5, // connect timeout
			// odoslať ako POST request
			'content' => http_build_query($params),
			'header' => [
				'Content-type: application/x-www-form-urlencoded; charset=utf-8',
			],
			// alebo odkomentujte pre odoslanie ako JSON data
			/*
			'content' => json_encode($params, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE),
			'header' => [
				'Content-type: application/json; charset=utf-8',
				'Accept: application/json',
			],
			*/
			// uncomment to show returned API error rather than PHP error
			//'ignore_errors' => true,
		],
		// pri vývoji na lokálnom serveri môže byť vhodné vypnúť kontrolu certifikátu
		'ssl' => [
			// 'verify_peer' => false,
			// 'verify_peer_name' => false,
		],
	];

	// získame odpoveď
	$errorMsg = '';
	$out = [];
	$url = "https://bizdata.sk/api/v1/".$urlService;

	try {
		$ctx = stream_context_create($options);
		$response = file_get_contents($url, false, $ctx);
	} catch (\Exception $e) {
		$errorMsg = $e->getMessage();
	}

	// spracujeme odpoveď - dekódujeme JSON reťazec
	if (!$errorMsg) {
		if ($response && ($response = json_decode($response, true))) {
			// preveríme, či server vrátil chybu, alebo platné dáta
			if (!empty($response['errorMsg'])) {
				$errorMsg = $response['errorMsg'];
			} elseif ( !empty($response[0]['value']) ) {
				// pairs label - value, ie. for autocomplete, JSON encoded in value
				foreach ( $response as $data ) {
					$out[] = json_decode($data['value'], true);
				}
			} elseif ( !empty($response['data'][0]) ) {
				// 0-based list - returned raw data are NOT JSON encoded
				foreach ( $response['data'] as $data ) {
					$out[] = is_array($data) ? $data : json_decode($data, true);
				}
			} else {
				$errorMsg = Yii::t('app', 'Žiadne záznamy.');
			}
		} elseif (false === $response) {
			$errorMsg = "Chyba spojenia.";
		} else {
			$errorMsg = "Neboli nájdené žiadne záznamy.";
		}
	}

	if ($errorMsg) {
		$out['errorMsg'] = $errorMsg;
	}

	return $out;
}
Príklad #1 - vyhľadanie firmy/subjektu podľa názvu, IČO, DIČ

Pre vyhľadanie subjektu je potrené odoslať v požiadavke pole term alebo name. Pole term vždy vracia odpoveď v párovom formáte label-value (value obsahuje zakódované JSON dáta, čo je vhodné pre implementáciu autocomplete zoznamov v prehliadači). Pole name vráti pôvodné nezakódované dáta - nie je potrebné ich dekódovať. 

// using field "term" automatically returns pairs label-value for autocompletes
$response = sendApiRequest(["term" => "slovnaft"]);

// use field "name" to return raw data, set "is_active=any" to search also closed entities
$response = sendApiRequest([
	"name" => "slovnaft",
	"is_active" => "any", // defaults to 1 - only search active entities
	"option_extra_field" => "text_kraj, text_velkost", // request returning additional fields
]);

Príklad odpovede: 

array (
  0 => array (
	'obchodne_meno' => 'SLOVNAFT, a.s.', // zhoda
	'hash' => 'csgYb-aW064XfGytv1D...',
	'is_active' => 1,
	'is_likvidacia_konkurz' => 0,
	'ico' => '31322832',
	'dic' => '2020372640',
	'icdph' => 'SK2020372640',
	'icdph_par' => '7',
	'kod_typ_osoby' => 'P',
	'addr_street_nr' => 'Vlčie hrdlo 1',
	'addr_street' => 'Vlčie hrdlo',
	'addr_number' => '1',
	'addr_city' => 'Bratislava',
	'addr_zip' => '82412',
	'addr_gps' => '48.1517,17.1093',
	'hlavicka' => 'Spoločnosť zapísaná v OR MS Bratislava III, oddiel sa, vložka 426/B.',
	'hlavicka_kratka' => 'MS Bratislava III, oddiel sa, vložka 426/B.',
	'orsr_sud' => 'Bratislava III',
	'orsr_oddiel' => 'sa',
	'orsr_vlozka' => '426/B',
	'zrsr_urad' => 'Bratislava',
	'zrsr_cislo_registra' => '102-12319',
	'kod_nace' => '19200',
	'text_nace' => 'Výroba rafin.ropn.prod.',
	'kod_pravna_forma' => '121',
	'text_pravna_forma' => 'Akc. spol.',
	'date_vznik' => '01.05.1992',
	'date_zanik' => '',
	'text_kraj' => 'Bratislavský kraj', // dodatocne pole
	'text_velkost' => '2000-2999 zamestnancov', // dodatocne pole
	  ),
  1 => array (
	'obchodne_meno' => 'Slovnaft Retail, s.r.o.', // zhoda
	'hash' => 'FxBQEwMI2OIbYf9xAFn...',
	'is_active' => 1,
	'is_likvidacia_konkurz' => 0,
	'ico' => '35681039',
	'dic' => '2020323261',
	'icdph' => '',
	'icdph_par' => '4a',
	'kod_typ_osoby' => 'P',
	'addr_street_nr' => 'Vlčie hrdlo 1',
	'addr_street' => 'Vlčie hrdlo',
	'addr_number' => '1',
	'addr_city' => 'Bratislava',
	'addr_zip' => '82107',
	'addr_gps' => '48.1517,17.1093',
	'hlavicka' => 'Spoločnosť zapísaná v OR MS Bratislava I, oddiel sro, vložka 10146/B.',
	'hlavicka_kratka' => 'MS Bratislava I, oddiel sro, vložka 10146/B.',
	'orsr_sud' => 'Bratislava I',
	'orsr_oddiel' => 'sro',
	'orsr_vlozka' => '10146/B',
	'zrsr_urad' => 'Bratislava',
	'zrsr_cislo_registra' => '104-20633',
	'kod_nace' => '47300',
	'text_nace' => 'Maloobch.s pohon.látkami',
	'kod_pravna_forma' => '112',
	'text_pravna_forma' => 'Spol. s r. o.',
	'date_vznik' => '19.12.1995',
	'date_zanik' => '',
	'text_kraj' => 'Bratislavský kraj', // dodatocne pole
	'text_velkost' => '1 zamestnanec', // dodatocne pole
  ),
  ...
)
Príklad #2 - vyhľadanie firmy/subjektu podľa adresy

Vyhľadanie firmy je tiež možné podľa adresy odoslaním špeciálne určeného poľa full_address. Pole 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í - napr. Strážovská 1201, Bánovce alebo Bratislava, 85102. Nie je nutné uvádzať všetky tri časti adresy, postačí uvedenie aspoň jednej časti. 

// using field "term" automatically returns pairs label-value for autocompletes
$response = sendApiRequest(["full_address" => "Bratislavska 12, senec"]);

Príklad odpovede: 

array (
  0 =>
  array (
	'obchodne_meno' => 'Občianske združenie ArtGuardia',
	'hash' => 'px83ibEGzguJM0qagT....',
	'is_active' => 1,
	'is_likvidacia_konkurz' => 0,
	'ico' => '56767331',
	'dic' => '',
	'icdph' => '',
	'icdph_par' => '',
	'kod_typ_osoby' => 'P',
	'addr_street_nr' => 'Bratislavská 1209/47', // zhoda adresy
	'addr_street' => 'Bratislavská', // zhoda adresy
	'addr_number' => '1209/47', // zhoda adresy
	'addr_city' => 'Senec',  // zhoda adresy
	'addr_zip' => '90301',
	'addr_gps' => '',
	'hlavicka' => '',
	'hlavicka_kratka' => '',
	'orsr_sud' => '',
	'orsr_oddiel' => '',
	'orsr_vlozka' => '',
	'zrsr_urad' => '',
	'zrsr_cislo_registra' => '',
	'kod_nace' => '94992',
	'text_nace' => 'Čin.záujmových org.',
	'kod_pravna_forma' => '701',
	'text_pravna_forma' => 'Združenie (zväz,spolok)',
	'date_vznik' => '31.01.2025',
	'date_zanik' => '',
  ),
  1 =>
  array (
	'obchodne_meno' => 'Dom Seniorov n.o.',
	'hash' => 'ZMht9xQXNcWHpof1ja...',
	'is_active' => 1,
	'is_likvidacia_konkurz' => 0,
	'ico' => '45732191',
	'dic' => '2022964108',
	'icdph' => '',
	'icdph_par' => '',
	'kod_typ_osoby' => 'P',
	'addr_street_nr' => 'Bratislavská 1219/67',  // zhoda adresy
	'addr_street' => 'Bratislavská',  // zhoda adresy
	'addr_number' => '1219/67',  // zhoda adresy
	'addr_city' => 'Senec',  // zhoda adresy
	'addr_zip' => '90301',
	'addr_gps' => '',
	'hlavicka' => '',
	'hlavicka_kratka' => '',
	'orsr_sud' => '',
	'orsr_oddiel' => '',
	'orsr_vlozka' => '',
	'zrsr_urad' => '',
	'zrsr_cislo_registra' => '',
	'kod_nace' => '87300',
	'text_nace' => 'Starost.o staršie os.',
	'kod_pravna_forma' => '120',
	'text_pravna_forma' => 'Nezisk.org.poskyt.všeob.prosp.služby',
	'date_vznik' => '08.02.2010',
	'date_zanik' => '',
  ),
)
Príklad #3 - vyhľadanie štatutára podľa firmy/subjektu

Pre vyhľadanie osôb požadovanej spoločnosti (organizácie) slúži API metóda search-person-by-company, ktorej odošleme meno a priezvisko osoby. Metóda vráti zoznam všetkých osôb (môžu byť aj právnické osoby) s uvedením ich poslednej funkcie (napr. štatutár, spoločník, konateľ, akcionár, ..) a základné detaily materskej spoločnosti. 

$response = sendApiRequest(["name" => "aaa"], "search-person-by-company");

// výber subjektu môžeme zúžiť napr. pridaním PSČ (aj čiastkového), kódu okresu, kraja apod.
$response = sendApiRequest(["name" => "peter", "zip" => "851"], "search-person-by-company");

Príklad odpovede: 

array (
  0 =>
  array (
	'person_name' => 'doc. Ing. Jaroslav Ďaďo',
	'is_active' => 1,
	'is_foreigner' => 0,
	'city' => 'Banská Bystrica',
	'zip' => '',
	'country' => '',
	'role_title' => 'Vedúci prevádzky',
	'role_code' => 'VP',
	'role_from' => '2004-03-26',
	'role_to' => '',
	'company' =>
	array (
	  'obchodne_meno' => 'AAA Experts, s.r.o.', // zhoda
	  'is_active' => 1,
	  'ico' => '36624811',
	  'dic' => '2021806798',
	  'icdph' => '',
	  'kod_typ_osoby' => 'P',
	  'addr_street_nr' => '29.augusta 31',
	  'addr_city' => 'Banská Bystrica',
	  'addr_zip' => '97401',
	  'hlavicka' => 'Spoločnosť zapísaná v OR OÚ Banská Bystrica, oddiel sro, vložka 9069/S.',
	  'hlavicka_kratka' => 'OS Banská Bystrica, oddiel sro, vložka 9069/S.',
	),
  ),
  1 =>
  array (
	'person_name' => 'Dipl. Ing. Igor Harach',
	'is_active' => 1,
	'is_foreigner' => 0,
	'city' => 'Banská Bystrica',
	'zip' => '',
	'country' => '',
	'role_title' => 'Spoločník',
	'role_code' => 'S',
	'role_from' => '2004-03-26',
	'role_to' => '',
	'company' =>
	array (
	  'obchodne_meno' => 'AAA Experts, s.r.o.', // zhoda
	  'is_active' => 1,
	  'ico' => '36624811',
	  'dic' => '2021806798',
	  'icdph' => '',
	  'kod_typ_osoby' => 'P',
	  'addr_street_nr' => '29.augusta 31',
	  'addr_city' => 'Banská Bystrica',
	  'addr_zip' => '97401',
	  'hlavicka' => 'Spoločnosť zapísaná v OR OÚ Banská Bystrica, oddiel sro, vložka 9069/S.',
	  'hlavicka_kratka' => 'OS Banská Bystrica, oddiel sro, vložka 9069/S.',
	),
  ),
  ...
)
Príklad #4 - vyhľadanie štatutára (osoby) vo všetkých subjektoch

Pre vyhľadanie osoby vo všetkých subjektoch slúži metóda search-person. 

$response = sendApiRequest(["name" => "peter"], "search-person");

// výber subjektu môžeme zúžiť napr. pridaním PSČ (aj čiastkového), kódu okresu, kraja apod.
$response = sendApiRequest(["name" => "peter", "zip" => "85103"], "search-person");

Príklad odpovede: 

array (
  0 =>
  array (
	'person_name' => 'Dipl. Ing. Peter Petržela', // zhoda
	'is_active' => 1,
	'is_foreigner' => 0,
	'city' => 'Diviaky nad Nitricou',
	'zip' => '97225',
	'country' => '',
	'company' =>
	array (
	  'obchodne_meno' => 'AKA-EXPORT-IMPORT, s.r.o.',
	  'is_active' => 1,
	  'ico' => '36256544',
	  'dic' => '2021756220',
	  'icdph' => '',
	  'kod_typ_osoby' => 'P',
	  'addr_street_nr' => 'Dobrá Voda 15',
	  'addr_city' => 'Dobrá Voda',
	  'addr_zip' => '91954',
	  'hlavicka' => 'Spoločnosť zapísaná v OR OS Trnava, oddiel sro, vložka 14385/T.',
	  'hlavicka_kratka' => 'OS Trnava, oddiel sro, vložka 14385/T.',
	),
  ),
  1 =>
  array (
	'person_name' => 'Ing. Peter Obertík', // zhoda
	'is_active' => 1,
	'is_foreigner' => 0,
	'city' => 'Bojnice',
	'zip' => '97201',
	'country' => '',
	'company' =>
	array (
	  'obchodne_meno' => 'UBYFO-ÚDRŽBA VÝŤAHOV s.r.o.',
	  'is_active' => 1,
	  'ico' => '36627674',
	  'dic' => '2021850435',
	  'icdph' => '',
	  'kod_typ_osoby' => 'P',
	  'addr_street_nr' => 'Športová 32',
	  'addr_city' => 'Prievidza',
	  'addr_zip' => '97101',
	  'hlavicka' => 'Spoločnosť zapísaná v OR OS Trenčín, oddiel sro, vložka 18129/R.',
	  'hlavicka_kratka' => 'OS Trenčín, oddiel sro, vložka 18129/R.',
	),
  ),
  ...
)