API dokumentacija

Uvod i generiranje API ključa

Kako bi se pristupilo API sučelju pootrebno je registrirati API ključ na adresi https://transparentnost.bjelovar.hr/api-pristup. Za generiranje API ključa potrebna je ispravna e-mail adresa i IP adresa (ipv4) sa koje će dolaziti zahtjevi.

Nakon što zaprimite API ključ možete krenuti sa spajanjem na API sučelje.

Spajanje na API sučelje

API sučelje nalazi se na adresi https://transparentnost.bjelovar.hr/api. Svi upiti se vrše POST metodom JSON podataka.

Autentikacija

Generirani API ključ se šalje u headeru zahtjeva u obliku varijable “api_key”.

api_key : _vas_api_kljuc_

Izlazni podaci

API podržava 3 vrste izlaznih podataka: JSON, XML i CSV. Parametar izlaznih podataka šalje se u “output” varijabli. Polja koja se vraćaju u API-u:

Parametar Opis polja Tip polja
id Oznaka int
oib OIB int (11)
name Ime i prezime/naziv tvrtke string
postcode Poštanski broj int (5)
city Grad/oćina string
date Datum isplate string (d.m.Y.)
amount Iznos isplate float
description Opis isplate string
level_1 Ekonomska klasifikacija - razina 1 string
level_2 Ekonomska klasifikacija - razina 2 string
level_3 Ekonomska klasifikacija - razina 3 string
level_4 Ekonomska klasifikacija - razina 4 string
function_level_1 Funkcijska klasifikacija - razina 1 string
function_level_2 Funkcijska klasifikacija - razina 2 string
function_level_3 Funkcijska klasifikacija - razina 3 string
function_level_4 Funkcijska klasifikacija - razina 4 string

Metode

API podržava dvije vrste upita: query i filter

Metoda QUERY

Query metoda omogućuje pretragu po ključnim riječima polja:

Parametar Opis polja Tip polja
oib OIB int (11)
name Ime i prezime/naziv tvrtke string
postcode Poštanski broj int (5)
city Grad/općina string
date Datum isplate string (d.m.Y.)
amount Iznos isplate float
description Opis isplate string
level_1 Ekonomska klasifikacija razina 1 int (1)
level_2 Ekonomska klasifikacija razina 2 int (2)
level_3 Ekonomska klasifikacija razina 3 int (3)
level_4 Ekonomska klasifikacija razina 4 int (4)
function_level_1 Funkcijska klasifikacija razina 1 int (1)
function_level_2 Funkcijska klasifikacija razina 2 int (2)
function_level_3 Funkcijska klasifikacija razina 3 int (3)
function_level_4 Funkcijska klasifikacija razina 4 int (4)

Parametri koji se šalju u JSON formatu:

Parametar Obavezan Moguće vrijednosti Zadana vrijednost
method da query  
query da alfaumerička vrijednost sa zarezima i točkama (min 2, max 50)  
sort_by ne name
city
postcode
date
amount
id
sort ne ASC
DESC
DESC
output ne json
xml
csv
json

{
	"method" : "query",
	"query" : “plin”,
	“output” : “json”
}

Metoda FILTER

Metoda query omogućuje pretragu/filtriranje (moguće viđe parametara) po sljedećim parametrima:

Filter Selektori Očekivana vrijednost
oib = (jednako) int (11)
name LIKE (kao) string (min 2, max 50)
city LIKE (kao) string (min 2, max 50)
postcode = (jednako) int (5)
date = (jednako)
< (manje)
> (veće)
<= (manje jednako)
>= (veće jednako)
string (d.m.Y.)
amount = (jednako)
< (manje)
> (veće)
<= (manje jednako)
>= (veće jednako)
float  
description LIKE (kao) string (min 2, max 50)
level_1 LIKE (kao) int (1)
level_2 LIKE (kao) int (2)
level_3 LIKE (kao) int (3)
level_4 LIKE (kao) int (4)
function_level_1 LIKE (kao) int (1)
function_level_2 LIKE (kao) int (2)
function_level_3 LIKE (kao) int (3)
function_level_4 LIKE (kao) int (4)

Parametri koji se šalju u JSON formatu:

Parametar Obavezan Moguće vrijednosti Zadana vrijednost
method da filter  
filter da array (filter, selector, query)  
sort_by ne name
city
postcode
date
amount
id
sort ne ASC
DESC
DESC
output ne json
xml
csv
json

Primjer:

{
	"method" : "filter",
    	"filter" : [
     			 {
			    "filter" : "name",
			    "selector" : "LIKE",
			    "query" : "plin"
     			 }
   		 ],
	“output” : “json”
}
{
	"method" : "filter",
    	"filter" : [
     			 {
			    "filter" : "name",
			    "selector" : "LIKE",
			    "query" : "plin"
     			 },
			{
			    "filter" : "amount",
			    "selector" : ">",
			    "query" : "100"	
			}
   		 ],
	“output” : “xml”
}

API limiti

Dnevni dozvoljeni broj upita po API ključu je 100.

Moguće greške

Status Greška
405 Nepodržani tip izlaznih podataka. Provjerite dokumentaciju.
418 Nedozvoljeni request.
401 Nedostaje API ključ. Generiajte API ključ.
401 API ključ nije ispravan ili zahtjev ne dolazi sa registrirane IP adrese uz ključ.
423 Dosegnut je dnevni limit API poziva (—tu isto ide limit iz API-a—)
400 Poslani parametri nisu u JSON formatu. Provjerite dokumentaciju.
406 Filter nije dobro strukturiran. Provjerite dokumentaciju.
406 Filter nije ispravan. Provjerite dokumentaciju.
406 Uvjet filtera nije ispravan. Provjerite dokumentaciju.
405 Uvjet filtera nije ispravan. Provjerite dokumentaciju.
400 Greška polja, npr. “OIB je obavezno polje”

Primjeri:

PHP(curl)


<?php
    $api_endpoint = "https://transparentnost.bjelovar.hr/api";
    $api_key 	  = "_vas_api_kljuc_";
	
    $data = [
    		"method"  => "query",
    		"query"   => "plin",
    		"sort_by" => "name",
    		"sort"    => "ASC",
    		"output"  => "json"
    ]; 
 
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $api_endpoint);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [ 
						"api_key: {$api_key}",
						"cache-control: no-cache"
					]);

    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 10);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode( $data ) );
	
    curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
    curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
	
    $result = curl_exec($ch);

    echo "<pre>";
    	print_r( json_decode( $result ) );
    echo "</pre>";
 
    curl_close($ch);
?>
	

JavaScript(FETCH)

{
    var api_endpoint = "https://transparentnost.bjelovar.hr/api";
    var api_key      = "_vas_api_kljuc_";

    var params = {
        "method" : "query",
        "query"  : "plin"
    };

    fetch( api_endpoint, {
        method: "POST",
        mode: "cors", 
        cache: "no-cache",
        headers: {
            "Content-Type": "application/json",
            "api_key" : api_key
        },
        redirect: "follow", 
        body: JSON.stringify( params ),
    })
    .then( response => response.json() )
    .then( ( response ) => {

        console.log( response );

    });