Príklad - jQuery UI | API Integrácia

Kľúčové slová

API integrácia

API Integrácia - jQuery UI autocomplete

Integrácia prostredníctvom jQuery UI widgetu autocomplete vyžaduje odoslanie autentifikačného API kľúča ako POST parameter xauth. Z toho dôvodu vyžaduje miernu úpravu metódy "source" pre načítanie zdrojových dát. API kľúč ku konkrétnej aplikácii / webu nájdete po prihlásení v Nastaveniach - časť API Integrácia.

Vrátený zoznam nájdených subjektov obsahuje zakódované dáta vo formáte JSON, ktoré po zvolení položky zo zoznamu dekódujeme a nastavíme do potrebných polí. Nie je potrebné zasielať ďalšiu API požiadavku pre načítanie detailov zvoleného subjektu. Popis podporovaných API metód a parametrov pozrite tu.

Príklad #1 - jednoduchý - vyhľadanie firmy/subjektu
Príklad #2 - pokročilý - vyhľadanie firmy/subjektu
Príklad #3 - vyhľadanie firmy/subjektu podľa adresy
Príklad #4 - výber štatutára podľa firmy/subjektu
Príklad #5 - vyhľadanie štatutára vo všetkých subjektoch

Pokiaľ preferujete integráciu bez externých závislostí, môžete využiť predpripravenú knižnicu vanilla JS.

Príklad #1 - jednoduchý - vyhľadanie firmy/subjektu

Najjednoduchší variant, avšak aj najmenej flexibilný. Neumožňuje napr. ošetrenie chyby - pozrite príklad #2. Vrátená odpoveď obsahuje zakódovaný JSON reťazec s atribútmi subjektu a nevyžaduje odoslanie ďalšej API požiadavky.

Obr. 1 - Vzor výstupu - vyhľadanie firmy podľa názvu, IČO, DIČ

HTML markup:

<!-- načítame externé javascript knižnice do HTML tagu <head> - jQuery, jQueryUI -->
<script src="https://code.jquery.com/jquery-3.7.1.min.js"></script>
<script src="https://code.jquery.com/ui/1.13.2/jquery-ui.min.js"></script>

<!-- vložíme pole do HTML <body> pre zadanie hľadaného názvu subjektu -->
<input type="text" id="company-suggester1" placeholder="Vyhľadať .." class="form-control" />

JS script:

$("#company-suggester1").autocomplete({
	// nemá zmysel hľadať subjekty pre menej ako 3 písmená - výsledky sú irelevantné
	minLength: 3,

	source : function(request, response) {
		// CORS POST request
		$.post({
			url: 'https://bizdata.sk/api/v1/search-company',
			data: {
				term: request.term, // company name, DIČ or IČO
				xauth: "my-secret-key", // find authentication key in your account settings
				// optional options and search attributes - see the documentation
				// is_active: 'any', // search in active and inactive entities
				// zip: '957', // partial match supported, returns both "95701" and "95702"
				option_size: 5
			},
			dataType: "json",
			success: function(resp) {
				if (resp && resp.length) {
					// render list items, already contains label - value pairs
					response(resp);
					/* // alternatively - customize labels ie. add IČO ..
					response($.map(resp, function(item) {
						var data = $.parseJSON( item.value );
						return {
							label: item.label + " (IČO "+data.ico+")",
							value: item.value
						}
					})); */
				} else {
					// show error or message "Žiadne záznamy."
					alert(resp.errorMsg ? resp.errorMsg : "Žiadne záznamy.");
				}
			}
		});
	},

	// vypneme nastavenie "value" hodnoty, nakoľko by nastavilo zakódovaný JSON reťazec
	focus : function(event, ui) {
		event.preventDefault();
	},

	// spracovanie zvolenej položky zo zoznamu
	select : function(event, ui) {
		event.preventDefault(); // don't set the value (which is encoded JSON) ..
		$(this).val( ui.item.label ); // .. instead set the label - company name
		try{
			// dekódujeme JSON reťazec - údaje subjektu
			var data = $.parseJSON( ui.item.value );
			alert("Vybratý záznam:"
				+"\nNázov: " + data.obchodne_meno
				+"\nAdresa: "+ data.addr_street_nr +", "+ data.addr_zip +" "+ data.addr_city
				+(data.ico ? "\nIČO: " + data.ico : "")
				+(data.dic ? "\nDIČ: " + data.dic : "")
				+"\nVznik: " + data.date_vznik
				+"\nSubjekt aktívny: " + (data.is_active ? 'Áno' : 'Nie')
				+"\nTyp osoby: " + data.kod_typ_osoby
				+"\n ... "
			);
			// príp. nastavíme údaje subjektu do potrebných polí
			$("#company-name").val(data.obchodne_meno);
			$("#company-street-number").val(data.addr_street_nr);
			$("#company-zip-city").val(data.addr_zip +" "+ data.addr_city);
			$("#company-ico").val(data.ico ? data.ico : "-");
			// ... atď ...
		} catch (error) {
			alert("Neplatné JSON údaje .. \n"+error);
		}
	}
})

Príklad #2 - pokročilý - vyhľadanie firmy/subjektu

Pokročilejšia alternatíva - umožňuje napr. ošetrenie užívateľského vstupu, zobrazenie chyby, vloženie spinner loadera (koliesko) a zobrazenie IČO aj DIČ subjektu. Atribút value zvolenej položky obsahuje zakódovaný JSON reťazec s atribútmi subjektu a nevyžaduje odoslanie ďalšej API požiadavky.

Obr. 2 - Vzor výstupu - vyhľadanie firmy podľa názvu, IČO, DIČ

HTML markup:

<!-- načítame externé knižnice do HTML <head> - jQuery, jQueryUI a CSS štýly -->
<script src="https://code.jquery.com/jquery-3.7.1.min.js"></script>
<script src="https://code.jquery.com/ui/1.13.2/jquery-ui.min.js"></script>
<link href="https://code.jquery.com/ui/1.13.1/themes/smoothness/jquery-ui.css" rel="stylesheet">

<!-- vložíme HTML kód do elementu <body> pre zadanie hľadaného názvu subjektu -->
<div class="my-3 offset-2 col-8" id="wrapper-suggester2">
	<input type="text" id="suggester2" class="form-control" placeholder="Vyhľadať ..">
	<div id="suggester2-message" class="py-2"></div>
</div>

CSS:

/* modify original jQuery CSS - remove border, set BG color .. */
#wrapper-suggester2 .ui-state-active,
#wrapper-suggester2 .ui-widget-content .ui-state-active
{
	border: 0;
	background-color: #ffa5006e;
	transition: background-color 100ms linear;
	margin: 0;
}

#wrapper-suggester2 .ui-widget.ui-widget-content
{
	border-radius: 4px;
	box-shadow: rgba(0, 0, 0, 0.35) 0px 5px 15px;
}

/* položka v zozname */
.item-wrapper {
	display: block;
	border-bottom: 1px solid orange;
	padding: 0;
	margin: 0;
	clear: both;
	overflow: hidden;
	font-size: 14px;
}

/* nazov subjektu */
.item-left {
	float: left;
	display: inline-block;
	width: 47%;
	padding: 5px;
	margin: 0;
	overflow: hidden;
}

/* IČO, DIČ */
.item-right {
	float: right;
	display: inline-block;
	width: 53%;
	text-align: right;
	padding: 5px;
	margin: 0;
	white-space: nowrap;
}

JS script:

$("#suggester2").autocomplete({
	// nemá zmysel hľadať subjekty pre menej ako 3 písmená - výsledky sú irelevantné
	minLength: 3,

	// (msec) požiadavku odošleme až keď užívateľ ukončil písanie (throttling)
	delay : 500,

	// responsivita - zabezpečíme posun zoznamu pri zmene veľkosti okna
	appendTo : "#wrapper-suggester2",

	// centrujeme mierne posunuté doľava a nadol
	position : {
		my : "left+2 top+5"
	},

	// načítanie zoznamu subjektov prostredníctvom funkcie
	source : function(request, response){

		var msg = $("#suggester2-message"),
			me = this.element,
			err = '';

		// ak zostalo z predošlej požiadavky koliesko/loader, odstránime ho
		$(".spinner-border").remove();

		// kontrola vstupu od užívateľa, musí byť 3 - 20 znakov
		request.term = request.term.replace(/[ ]+$/g, ' '); // flatten whitespaces
		if (!$.trim(request.term)) {
			err = 'Zadajte názov firmy alebo meno podnikateľa.';
		} else if(request.term.length < 3) {
			err = 'Príliš krátky názov, zadajte aspoň 3 znaky.';
		} else if(request.term.length > 20) {
			err = 'Príliš dlhý názov, zadajte najviac 20 znakov.';
		}

		if (err) {
			me.autocomplete('close');
			msg.html('<div class="alert alert-danger">'+err+'</div>');
			return;
		}

		// spinner - koliesko
		$('<span class="spinner-border text-muted" '
			+'style="position:absolute;right:20px;top:2px;"></span>').insertAfter(me);

		// načítame zoznam subjektov
		$.post({
			url: "https://bizdata.sk/api/v1/search-company",
			data: {
				xauth: "my-secret-key",
				term: request.term // company name, DIČ or IČO
				// additional options and search attributes - see the documentation
				// is_active: 'any',
				// zip: '957', // partial match supported, returns both "95701" and "95702"
				// city: 'Bánovce',
				// option_size: 3,
				// option_extra_field: 'text_druh_vlastnictva, orsr_den_zapisu'
			},
			complete: function() {
				$(".spinner-border").remove();
			},
			success: function (resp) {
				if (resp && resp.length && resp[0]['label'] != undefined) {
					// clear previous error
					msg.html("");
					// render list items or return resp, which already contains labels + values
					response($.map(resp, function(item) {
						// here we can parse JSON and customize labels
						return {
							label: item.label,
							value: item.value
						}
					}));
				} else {
					// chyba ošetrená a vrátená serverom
					var e = resp.errorMsg ? resp.errorMsg : "Žiadne záznamy.";
					msg.hide().html('<div class="alert alert-danger">'+e+'</div>').fadeIn();
					me.autocomplete('close');
				}
			},
			error: function(xhr) {
				// typicky chyba spojenia alebo neošetrená chyba
				var txt = 'Chyba spojenia.';
				if(xhr && xhr.responseJSON && xhr.responseJSON.errorMsg != undefined){
					txt = 'Chyba! ' + xhr.responseJSON.errorMsg;
				}
				msg.html('<div class="alert alert-danger">'+txt+'</div>');
				me.autocomplete('close');
			}
		})
	},

	create : function() {
		// vlastné formátovanie zoznamu subjektov s IČO, DIČ
		$(this).data('ui-autocomplete')._renderItem = function( ul, item ) {
			var data = $.parseJSON( item.value ),
				name = item.label.substring(0, 22);
			// zvýrazníme text
			name = String($.trim(name))
					.replace(new RegExp($.trim(this.term), "gi"), "<b>$&</b>");
			if(data.dic){
				data.dic = String($.trim(data.dic))
					.replace(new RegExp($.trim(this.term), "gi"), "<b>$&</b>");
			}
			if(data.ico){
				data.ico = String($.trim(data.ico))
					.replace(new RegExp($.trim(this.term), "gi"), "<b>$&</b>");
			}
			// vložíme záznam s IČO, DIČ ..
			return $( "<li class='item-wrapper'>"
					  +"<div class='item-left'>"
						+ name + (item.label.length > 22 ? ".." : "")
					  +"</div>"
					  +"<div class='item-right'>"
						+(data.dic ? " &nbsp; DIČ: "+data.dic : "")
						+(data.ico ? " &nbsp; IČO: "+data.ico : "")
					  +"</div>"
					+"</li>" ).appendTo( ul );
		};
	},

	// vypneme nastavenie "value" hodnoty, nakoľko by nastavilo nezmyselný JSON reťazec
	focus : function(event, ui) {
		event.preventDefault();
	},

	// spracovanie zvolenej položky zo zoznamu
	select : function(event, ui) {
		event.preventDefault();
		$(this).val( ui.item.label );
		try{
			// dekódujeme JSON reťazec - údaje subjektu
			var data = $.parseJSON( ui.item.value );
			if (data) {
				var txt = "<div class='jumbotron p-3 mb-0'><u>Vybratý záznam:</u>"
					+"<br>Názov: <b>" + data.obchodne_meno + "</b>"
					+"<br>Adresa: " + data.addr_street_nr +", "
									+ data.addr_zip +" "+ data.addr_city
					+(data.ico ? "<br>IČO: " + data.ico : "")
					+(data.dic ? "<br>DIČ: " + data.dic : "")
					+"<br>Vznik: " + data.date_vznik
					+"<br>Typ osoby: " + data.kod_typ_osoby
					+"<br>Subjekt aktívny: " + (data.is_active ? 'Áno' : 'Nie')
					+"<br> ... </div>";

				$("#suggester2-message").html(txt);

				// príp. nastavíme údaje subjektu do potrebných polí
				$("#company-name").val(data.obchodne_meno);
				$("#company-street-number").val(data.addr_street_nr);
				$("#company-zip-city").val(data.addr_zip +" "+ data.addr_city);
				$("#company-ico").val(data.ico ? data.ico : "-");
				// ... atď ...
			}
		} catch (error) {
			alert("Neplatné JSON údaje .. \n"+error);
		}
	}
});

Príklad #3 - vyhľadanie firmy/subjektu podľa adresy

Vyhľadanie firmy je tiež možné podľa adresy odoslaním špeciálne parsované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.

Pre vrátenie odpovede priamo vo formáte optimizovanom pre jQuery autocomplete je potrebné tiež nastaviť option_format na hodnotu label-value. (nastavenie nie je potrebné pri odoslaní poľa term - ktoré však v tomto prípade neodosielame).

Obr. 3 - Vzor výstupu - vyhľadanie firmy podľa adresy

HTML markup:

<!-- načítame externé javascript knižnice do HTML tagu <head> - jQuery, jQueryUI -->
<script src="https://code.jquery.com/jquery-3.7.1.min.js"></script>
<script src="https://code.jquery.com/ui/1.13.2/jquery-ui.min.js"></script>

<!-- vložíme pole do HTML <body> pre zadanie hľadaného názvu subjektu -->
<input type="text" id="suggester3" placeholder=" Ulica, obec, PSČ .." class="form-control" />

JS script:

$("#suggester3").autocomplete({
	// nemá zmysel hľadať subjekty pre menej ako 3 písmená - výsledky sú irelevantné
	minLength: 3,

	source : function(request, response) {
		// CORS POST request
		$.post({
			url: 'https://bizdata.sk/api/v1/search-company',
			data: {
				xauth: "my-secret-key",
				full_address: request.term, // napr. "Pekná cesta, Bratislava"
				// is_active: 'any', // hľadať v aktívnych / neaktívnych / všetkých subjektoch
				option_format: 'label-value', // enforce returning pairs label - value
				option_size: 5
			},
			dataType: "json",
			success: function(resp) {
				if (resp && resp.length) {
					// render list items
					response($.map(resp, function(item) {
						var data = $.parseJSON( item.value );
						return {
							value: item.value,
							// customize labels - add full address
							label: item.label + " (" + data.addr_street_nr
									+", "+ data.addr_zip +" "+ data.addr_city +")"
						}
					}));
				} else {
					// show error or message "No records." into some element ID="msg-sample-3"
					$("#msg-sample-3").finish().hide()
						.html(resp.errorMsg ? resp.errorMsg : "Žiadne záznamy.").fadeIn();
					// enforce closing previous list
					response({});
				}
			}
		});
	},

	// vypneme nastavenie "value" hodnoty, nakoľko by nastavilo nezmyselný JSON reťazec
	focus : function(event, ui) {
		event.preventDefault();
	},

	// spracovanie zvolenej položky zo zoznamu
	select : function(event, ui) {
		event.preventDefault(); // don't set the value (which is JSON hash)
		try{
			// dekódujeme JSON reťazec a zobrazíme údaje subjektu
			var data = $.parseJSON( ui.item.value );
			$("#msg-sample-3").hide().html(
				"<div class='g-color-black jumbotron p-2'>"
				+"Názov: <b>" + data.obchodne_meno + "</b>"
				+"<br>Obec: <b>"+ data.addr_city+"</b>"
				+"<br>Ulica: <b>"+ data.addr_street_nr +"</b>"
				+"<br>PSČ: <b>"+ data.addr_zip +"</b>"
				+(data.ico ? "<br>IČO: " + data.ico : "")
				+(data.dic ? "<br>DIČ: " + data.dic : "")
				+"<br>Vznik: " + data.date_vznik
				+"<br>Subjekt aktívny: " + (data.is_active ? 'Áno' : 'Nie')
				+"<br>Typ osoby: " + data.kod_typ_osoby
				+"<br>...atď. </div>"
			).fadeIn();
		} catch (error) {
			alert("Neplatné JSON údaje .. \n"+error);
		}
	}
})

Príklad #4 - výber štatutára podľa firmy/subjektu

Vyhľadanie štatutárov spoločnosti umožňuje metóda search-person-by-company. Vrátený zoznam obsahuje meno štatutára (resp. SZČO) a názov spoločnosti. Nasledujúci príklad umožňuje nastavenie štatutára napr. ako adresáta listovej zásielky.

Obr. 4 - Vzor výstupu - vloženie mena štatutára zvoleného subjektu

HTML markup:

<!-- načítame externé javascript knižnice do HTML tagu <head> - jQuery, jQueryUI -->
<script src="https://code.jquery.com/jquery-3.7.1.min.js"></script>
<script src="https://code.jquery.com/ui/1.13.2/jquery-ui.min.js"></script>

<!-- vložíme pole do HTML <body> pre zadanie hľadaného názvu subjektu -->
<input type="text" id="suggester4" placeholder=" Názov firmy, IČO .." class="form-control" />

JS script:

$("#suggester4").autocomplete({
	// nemá zmysel hľadať subjekty pre menej ako 3 písmená - výsledky sú velmi nepresné
	minLength: 3,

	source : function(request, response) {
		// CORS POST request
		$.post({
			url: 'https://bizdata.sk/api/v1/search-person-by-company',
			data: {
				xauth: "my-secret-key",
				term: request.term,
				// is_active: 'any', // hľadať v aktívnych / neaktívnych / všetkých subjektoch
				option_size: 5 // vrátený počet záznamov 1-100, default 10
			},
			dataType: "json",
			success: function(resp) {
				if (resp && resp.length) {
					// render list items
					response($.map(resp, function(item) {
						var person = $.parseJSON( item.value ),
							company = person.company,
							role = person.role_title.toLowerCase();
						// label already contains representative name, customize if needed
						return {
							value: item.value, // encoded JSON data or set other attribute
							label: item.label + " ("
								+ ( company.obchodne_meno == item.label ?
									"IČO " + company.ico + (role ? ", " + role : '')
								: (role ? role + ", " : '')
									+ company.obchodne_meno + ", IČO " + company.ico
								) + ")"
						}
					}));
				} else {
					// show error or message "No records." into some element ID="msg-sample-3"
					$("#msg-sample-4").finish().hide()
						.html(resp.errorMsg ? resp.errorMsg : "Žiadne záznamy.").fadeIn();
					// enforce closing previous list
					response({});
				}
			}
		});
	},

	// vypneme nastavenie "value" hodnoty, nakoľko by nastavilo nezmyselný JSON reťazec
	focus : function(event, ui) {
		event.preventDefault();
	},

	// spracovanie zvolenej položky zo zoznamu
	select : function(event, ui) {
		event.preventDefault(); // don't set the value (which is JSON hash)
		try{
			// dekódujeme JSON reťazec a zobrazíme meno zvoleného štatutára a adresu firmy
			var person = $.parseJSON( ui.item.value ),
				company = person.company;

			$("#msg-sample-4").hide().html(
				"<div class='g-color-black jumbotron p-2'>"
				+ "Adresované na:"
				+ "<br><b>"+ person.person_name +"</b>"
				//+"<br>" + person.role_title // looks unusual :-)
				+"<hr class='my-1 col-8'>"
				+"<b>"+ company.obchodne_meno +"</b>"
				+"<br>"+ company.addr_street_nr
				+"<br>"+ company.addr_zip +" "+ company.addr_city
				+"</div>"
			).fadeIn();

		} catch (error) {
			alert("Neplatné JSON údaje .. \n"+error);
		}
	}
})

Príklad #5 - vyhľadanie štatutára vo všetkých subjektoch

V prípade, ak je potrebné vyhľadať osobu vo firme, ktorej názov nepoznáte, môžete využiť metódu search-person. Táto vráti zoznam všetkých nájdených osôb (tzn. štatutárov, konateľov, akcionárov apod.) vo všetkých subjektoch.

Obr. 5 - Vzor výstupu - vyhľadanie štatutára vo všetkých subjektoch

HTML markup:

<!-- načítame externé javascript knižnice do HTML tagu <head> - jQuery, jQueryUI -->
<script src="https://code.jquery.com/jquery-3.7.1.min.js"></script>
<script src="https://code.jquery.com/ui/1.13.2/jquery-ui.min.js"></script>

<!-- vložíme pole do HTML <body> pre zadanie hľadaného názvu subjektu -->
<input type="text" id="suggester5" placeholder=" Priezvisko a meno osoby .." class="form-control" />

JS script:

$("#suggester5").autocomplete({
	// nemá zmysel hľadať subjekty pre menej ako 3 písmená - výsledky sú velmi nepresné
	minLength: 3,

	source : function(request, response) {
		// CORS POST request
		$.post({
			url: 'https://bizdata.sk/api/v1/search-person',
			data: {
				xauth: "my-secret-key",
				term: request.term,
				// is_active: 'any',
				option_size: 5
			},
			dataType: "json",
			success: function(resp) {
				if (resp && resp.length) {
					// render list items
					response($.map(resp, function(item) {
						var person = $.parseJSON( item.value ),
							company = person.company,
							// zistime, ci meno osoby obsahuje skratku spoločnosti napr. "s.r.o."
							isJurist = /(\ba\. ?s\.|\bk\.s\.|\bs\. ?r\. ?o\.|\bspol\. ?s ?r\. ?o\.|\bv\. ?o\. ?s\.|\bs ?\.p\.|GmbH)/i.test(person.person_name);

						// label already contains representative name, customize if needed
						return {
							value: item.value, // encoded JSON data
							label: item.label.substring(0,40) + (item.label.length > 40 ? '..' : '')
								  // ie. "John Doe" pobytom v Bratislava vo firme My company, s.r.o., IČO 12345678
								+ ( person.city ? " "+(isJurist ? "sídlom" : "bytom")+" " + person.city + ", " : "" )
								+ ( company.obchodne_meno == item.label ? " IČO "+company.ico
								  : " vo firme "+company.obchodne_meno.substring(0,25)
									+ (company.obchodne_meno.length > 25 ? '..' : '') + ", IČO "+company.ico+", "+company.addr_city )
						}
					}));
				} else {
					// show error or message "No records." into some element ID="msg-sample-3"
					$("#msg-sample-5").finish().hide()
						.html(resp.errorMsg ? resp.errorMsg : "Žiadne záznamy.").fadeIn();
					// enforce closing previous list
					response({});
				}
			}
		});
	},

	// vypneme nastavenie "value" hodnoty, nakoľko by nastavilo nezmyselný JSON reťazec
	focus : function(event, ui) {
		event.preventDefault();
	},

	// spracovanie zvolenej položky zo zoznamu
	select : function(event, ui) {
		event.preventDefault(); // don't set the value (which is JSON hash)
		try{
			// dekódujeme JSON reťazec a zobrazíme meno zvoleného štatutára a adresu firmy
			var person = $.parseJSON( ui.item.value ),
				company = person.company;

			$("#msg-sample-5").hide().html(
				  "<div class='g-color-black jumbotron p-2'>"
				+ "Adresované na:"
				+ "<br><b>"+ person.person_name +"</b>"
				+ "<hr class='my-1 col-8'>"
				+ "<b>"+ company.obchodne_meno +"</b>"
				+ "<br>"+ company.addr_street_nr
				+ "<br>"+ company.addr_zip +" "+ company.addr_city
				+ "</div>"
			).fadeIn();

		} catch (error) {
			alert("Neplatné JSON údaje .. \n"+error);
		}
	}
})

« Metódy a parametre Príklad - vanilla JS »

Kľúčové slová

API Integrácia - jQuery UI autocomplete

bizdata.sk

Linky

Akceptované platby

Kontakt