REST API dokumentacija

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 an API key, vrijednost test_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 (uvijek viesapi.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