API dokumentacija
Uvod i generiranje API ključa
Kako bi se pristupilo API sučelju potrebno je registrirati API ključ na adresi https://drnje.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://drnje-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 );
});