API dokumentacija

Uvod i generiranje API ključa

Kako bi se pristupilo API sučelju potrebno je registrirati API ključ na adresi https://primosten.transparentor.org/zatrazi-api-kljuc. 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://primosten-api.transparentor.org. Svi upiti se vrše POST metodom JSON podataka.

Autentikacija

Generirani API ključ se šalje u headeru zahtjeva u obliku varijable Authorization.

Authorization: ApiKey _VAS_API_KLJUC_

Izlazni podaci

API podržava 3 vrste izlaznih podataka: JSON, XML i CSV. Parametar izlaznih podataka šalje se u headeru zahtjeva u polju Accept.


Accept: application/json
Accept: text/csv
Accept: text/xml

Polja koja se vraćaju u API-u:

Parametar	Opis polja	Tip polja
id	Oznaka	int
vat	OIB	string
destination	Ime i prezime/naziv tvrtke	string
postcode	Poštanski broj	string
city	Grad/oćina	string
occurrence	Datum knjiženja	string (ISO 8601)
amount	Iznos isplate	decimal
description	Opis isplate	string
economical	Ekonomska klasifikacija	lista string-ova
functional	Funkcijska klasifikacija - razina	lista string-ova
organisational	Organizacijska klasifikacija - razina	lista string-ova
program	Programska klasifikacija - razina	lista string-ova
comment	Komentar	string
update_date	Vrijeme posljednje izmjene	string (ISO 8601)

Metode

API podržava metodu EXPORT na endpointu /export

Metoda EXPORT

Metoda export omogućava pretragu po poljima:

Parametar	Opis polja	Tip polja
id	Oznaka	int
vat	OIB	string
destination	Ime i prezime/naziv tvrtke	string
postcode	Poštanski broj	string
city	Grad/oćina	string
occurrence	Datum knjiženja	string (ISO 8601)
amount	Iznos isplate	decimal
description	Opis isplate	string
economical	Ekonomska klasifikacija	string
functional	Funkcijska klasifikacija - razina	string
organisational	Organizacijska klasifikacija - razina	string
program	Programska klasifikacija - razina	string
row	Skup polja za Full Text Search pretragu	string

Polja dozvoljavaju pretragu koristeći operatore:

Parametar	Operator	Opis	Primjer
vat	=	jednako	vat = '75494420706'
vat	IN	sadržan u listi	vat IN [ '75494420706', '97202814929’]
destination	CONTAINS	sadržan u listi	destination CONTAINS 'plaća'
destination	ICONTAINS	sadrži string – case insensitive	destination ICONTAINS 'Trošak'
postcode	=	jednakost	postcode = '10000'
postcode	=	jednakost	postcode = '10000'
location	CONTAINS	sadrži string	location CONTAINS 'Zagreb'
location	ICONTAINS	sadrži stringcase insensitive	location ICONTAINS omisalj'
occurrence	=	jednako	occurrence = '2020-01-31'
occurrence	<	manje	occurrence < '2020-01-31'
occurrence	>	veće	occurrence > '2020-01-31'
occurrence	<=	manje ili jednako	occurrence <= '2020-01-31'
occurrence	>=	veće ili jednako	occurrence >= '2020-01-31'
occurrence	BETWEEN	u rasponu	occurrence BETWEEN '2020-01-01' AND '2020-01-31'
amount	=	jednako	amount = 3141.59
amount	<	manje	amount < 3141.59
amount	>	veće	amount > 3141.59
amount	<=	manje ili jednako	amount <= 3141.59
amount	>=	veće ili jednako	amount >= 3141.59
amount	BETWEEN	u rasponu	amount BETWEEN 100 AND 1000.11
description	CONTAINS	sadrži string	description CONTAINS 'Bonus'
description	ICONTAINS	sadrži string insensitive	description ICONTAINS
economical	STARTSWITH	započinje sa string-om	economical STARTSWITH '38'
functional	STARTSWITH	započinje sa string-om	functional STARTSWITH '01'
organisational	STARTSWITH	započinje sastring-om	organisational STARTSWITH '1'
program	STARTSWITH	započinje sa string-om	program STARTSWITH '14'
row	FTSEARCH	FTS pretraga	row FTSEARCH 'troškovi'

Operatore je moguće kombinirati koristeći logičke operacije i zagrade:

Operator	Opis	Primjer
NOT	negacija	NOT vat = '75494420706'
AND	logičko I	amount >= 5000 AND description CONTAINS 'Bonus'
OR	logičko ILI	amount >= 5000 OR program STARTSWITH '14'
()	zagrade	NOT ( postcode = '10000' AND economical STARTSWITH '38' )

Prioritet operatora je redom NOT, AND pa OR.

Sortiranje rezultata moguće je po poljima:

Parametar	Opis polja	Primjer
vat	OIB	vat ASC
destination	Ime i prezime/naziv tvrtke	destination ASC
postcode	Poštanski broj	postcode DESC
location	Grad/oćina	location ASC
occurrence	Datum knjiženja	occurrence DESC
amount	Iznos isplate	amount DESC

S prethodno navedenim operatorima moguće je sastaviti upit za pretragu sljedećeg oblika:


SELECT ALL DATA 
[ WHERE  _logički_uvijet_ ]
[ ORDER BY _sort_rezultata_ ]

Pri tome su WHERE dio i ORDER BY dio opcionalni.

Primjer:

Primjer upita (sve stavke u kojoj se spominje trošak nastale u siječnju 2020., sortirano po gradovima i padajućem iznosu isplate)


SELECT ALL DATA
WHERE row FTSEARCH 'trošak'
AND occurrence BETWEEN '2020-01-01' AND '2020-01-31'
ORDER BY location ASC, amount DESC

Napomene

Sve ključne riječi i operatori su „case sensitive“.

Content type za slanje upita je: text/plain;charset=utf-8

API limiti

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

Moguće greške

Status	Greška
406	Nepodržani tip izlaznih podataka. Provjerite dokumentaciju.
401	Nedostaje API ključ. Generiajte API ključ.
403	API ključ nije ispravan ili zahtjev ne dolazi sa registrirane IP adrese uz ključ.
429	Dosegnut je dnevni limit API poziva (—tu isto ide limit iz API-a—)
400	Upit nije ispravan, provjerite dokumentaciju.

Primjeri:

CURL


curl \
  -X POST \
  -H "Authorization: ApiKey _vas_api_kljuc_" \
  -H "Content-Type: text/plain;charset=utf-8" \
  -H "Accept: application/json" \
  --data "SELECT ALL DATA
WHERE row FTSEARCH 'trošak'
AND occurrence BETWEEN '2020-01-01' AND '2020-01-31'
ORDER BY location ASC, amount DESC " \
 https://omisalj-api.transparentor.org/export

PHP(curl)


<php
    $api_endpoint = "https://omisalj-api.transparentor.org/export";
    $api_key      = "_vas_api_kljuc_";
    
    $data = <<<EOD
      SELECT ALL DATA
WHERE row FTSEARCH 'trošak'
AND occurrence BETWEEN '2020-01-01' AND '2020-01-31'
ORDER BY location ASC, amount DESC
EOD; 
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $api_endpoint);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [ 
                        "Content-Type: text/plain;charset=utf-8",
                        "Authorization: ApiKey {$api_key}",
                        "cache-control: no-cache",
                        "Accept: application/json"
                    ]);

    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 10);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $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://omisalj-api.transparentor.org/export";
    var api_key      = "_vas_api_kljuc_";

    fetch( api_endpoint, {
        method: "POST",
        mode: "cors", 
        cache: "no-cache",
        headers: {
            "Content-Type: text/plain;charset=utf-8",
        "Accept: application/json",
            "Authorization: ApiKey {$api_key}"
        },
        redirect: "follow", 
        body: JSON.stringify( params ),
    })
    .then( response => response.json() )
    .then( ( response ) => {

        console.log( response );

    });