Uvod
API koji nudimo koristi standardni HTTP protokol. Sve API funkcije koriste HTTP GET metodu. Svaki poziv funkcije zahtijeva autorizaciju upita. Podaci za autorizaciju upita šalju se u HTTP zaglavlju.
Usluga proizvodnje
Potrebna je registracija subjekta koji želi koristiti funkcionalnosti sustava viesapi.eu. Da biste to učinili, idite na Registracija stranicu i ispunite odgovarajući obrazac. Preduvjet za korištenje sustava viesapi.eu je prihvaćanje Uvjeti pružanja usluge. Ispravno ispunjavanje obrasca i klik na Registar gumb kreirat će račun u sustavu viesapi.eu i njegovu automatsku aktivaciju.
Prilikom prve prijave automatski se generira identifikator zajedno s odgovarajućim ključem. Identifikator je javan i ne zahtijeva zaštitu, dok je ključ privatan i ne smije biti dostupan trećim stranama.
Adresa proizvodne službe: https://viesapi.eu/api
Test servis
Potpuna funkcionalnost svih dijeljenih knjižnica može se provjeriti korištenjem dijeljenih knjižnica Testirajte VIES API. Korištenjem testnog API-ja moguće je provjeriti sve funkcije koje se nude u plaćenim planovima bez potrebe za kreiranjem računa.
Adresa službe za testiranje: https://viesapi.eu/api-test
Definicija API sučelja
Detaljna definicija API-ja dostupna je u OpenAPI kompatibilnom formatu i može se preuzeti kao YAML datoteka ovdje.
API je također dostupan kao klijentsko sučelje Swagger korisničko sučelje.
Izvršenje upita
Primjer postavljanja upita testnom mjestu:
GET /api-test/get/vies/euvat/PL7171642051 HTTP/1.1
Voditelj: viesapi.eu:443
Autorizacija: MAC id="api_key_id", ts="unix_timestamp", nonce="random_str", mac="b64_calculated_mac_value"
Korisnički agent: VIESAPIClient/client_version naziv_platforme/verzija_platforme
Gdje:
api_key_id
– API ključ identifikator (na produkcijskom okruženju vrijednost identifikatora generiranog tijekom registracije, na testnom okruženju vrijednost test_id),unix_timestamp
– trenutno vrijeme u obliku broja sekundi iz tzv unix epoha,random_str
– nasumični niz, različit za svaki upit (min. 8 znakova, maks. 16 znakova),b64_calculated_mac_value
– izračunati HMAC (koristeći anAPI key
, vrijednosttest_key
na testnom okruženju),client_version
– verzija klijenta (u našim knjižnicama to je verzija naše API knjižnice, npr. 1.2.3),platform_name
– naziv platforme API klijenta (u našim knjižnicama to je naziv jezika knjižnice, npr. JAVA, PHP, .NET, Python),platform_version
– Verzija platforme API klijenta (u našim knjižnicama to je verzija okruženja knjižnice, npr. 17 za JAVA, odnosno 7.4 za PHP).
Svi odgovori koje vraća web stranica su u XML formatu.
Zahtjev za autentifikaciju
Specifikacija korištene metode autorizacije: HTTP autentifikacija: MAC autentifikacija pristupa. Svaki upit na našu web stranicu mora biti ovjeren ovom metodom. Autorizacija se sastoji u izračunavanju HMAC SHA256 iz ispravno pripremljenog niza i slanju rezultata u HTTP zaglavlju.
Primjer
Ulazni niz u funkciju HMAC je:
ts + '\n' + nonce + '\n' + method + '\n' + path + '\n' + host + '\n' + port + '\n\n'
Gdje:
ts
– trenutno vrijeme u obliku broja sekundi iz tzv unix epoha, uvijek trebate navesti trenutno vrijeme izvršenja upita (tolerancija poslužitelja +/- 10 min u odnosu na trenutno vrijeme),nonce
– nasumični niz, različit za svaki upit (min. 8 znakova, maks. 16 znakova),method
– naziv HTTP metode (uvijek GET),path
– URL put upita koji treba izvršiti,host
– VIES API naziv poslužitelja (uvijekviesapi.eu
),port
– broj porta VIES API poslužitelja (uvijek 443),’\n’
– znak novog retka (ASCII kod 10, 0x0A).
Za upit za PDV broj PL7171642051 poslan testnoj službi 2019-11-25 00:00:00 UTC, ulazni niz u funkciju HMAC izgledat će ovako:
str = "1574640000\ndt831hs59s\nGET\n/api-test/get/vies/euvat/PL7171642051\nviesapi.eu\n443\n\n"
Datoteka ulaznog niza za ovaj primjer može se preuzeti ovdje.
Iz pripremljenog niza izračunavamo HMAC SHA256, kao HMAC lozinku koju dajemo API key
, tj. u slučaju testnog API-ja, vrijednost od test_key
:
HMAC_SHA256(str, "test_key") = 7776a12b958233ce60dd0f16b8d141e80472a1ee3b1e1fb136d7abe34cb59306
Funkcija HMAC SHA256 vraća 32 binarna bajta (prikazano gore kao a hex
niz za čitljivost). Preuzmite datoteku s binarnom vrijednošću ovdje.
Binarnu vrijednost izračunatog HMAC-a treba kodirati algoritmom Base64, dobivamo:
d3ahK5WCM85g3Q8WuNFB6ARyoe47Hh+xNter40y1kwY=
This value should be sent as MAC value in the header with data for authorization. Finally:
Authorization: MAC id="test_id", ts="1574640000", nonce="dt831hs59s", mac="d3ahK5WCM85g3Q8WuNFB6ARyoe47Hh+xNter40y1kwY="
On Linux machine required MAC value can be calculated in one step using this command:
$ echo -e -n "1574640000\ndt831hs59s\nGET\n/api-test/get/vies/euvat/PL7171642051\nviesapi.eu\n443\n\n" | openssl dgst -sha256 -hmac "test_key" -binary | openssl enc -base64