REST API dokumentacija

VIES API REST 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
Host: viesapi.eu:443
Authorization: MAC id="api_key_id", ts="unix_timestamp", nonce="random_str", mac="b64_calculated_mac_value"
User-Agent: VIESAPIClient/client_version platform_name/platform_version
Accept: mime_type

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, ili 7.4 za PHP),
  • mime_type – Naziv tipa MIME u kojem se odgovor treba vratiti, podržana su dva tipa: text/xml i application/json, ako zahtjev ne sadrži zaglavlje Accept, XML se vraća prema zadanim postavkama.

Zahtjev za autentifikaciju

Podaci o ovlaštenju moraju biti pripremljeni u skladu s HTTP autentifikacija: MAC autentifikacija pristupa i ovo je preporučena metoda provjere autentičnosti. Također je moguće koristiti HTTP autentifikacija: Osnovna autentifikacija međutim, iz sigurnosnih razloga koristite je samo kada korištenje prve metode iz nekog razloga nije moguće.

Svaki upit na našu web stranicu mora biti autentificiran pomoću jedne od dvije dostupne metode.

Metoda 1 – HMAC (preporučeno)

Specifikacija korištene metode autorizacije: HTTP autentifikacija: MAC autentifikacija pristupa. 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=

Ovu vrijednost treba poslati kao MAC vrijednost u zaglavlju s podacima za autorizaciju. Konačno:

Authorization: MAC id="test_id", ts="1574640000", nonce="dt831hs59s", mac="d3ahK5WCM85g3Q8WuNFB6ARyoe47Hh+xNter40y1kwY="

Na Linux stroju potrebna MAC vrijednost može se izračunati u jednom koraku pomoću ove naredbe:

$ 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

Metoda 2 – Osnovna provjera autentičnosti

Specifikacija ove metode autorizacije koja se koristi: HTTP autentifikacija: Osnovna autentifikacija.

Primjer 1

Ulazni niz za funkciju Base64 je:

str = key_id + ':' + key

Gdje:

  • key_id – identifikator API ključa (u slučaju testnog okruženja, test_id niz),
  • key – API ključ (u slučaju testnog okruženja, niz test_key).

Za testno okruženje, ulazni niz za funkciju Base64 bit će:

str = "test_id:test_key"

Nakon primjene funkcije Base64 dobivamo:

Base64(str) = dGVzdF9pZDp0ZXN0X2tleQ==

Ovu vrijednost treba poslati kao osnovnu vrijednost u zaglavlju s podacima za autorizaciju. U konačnici:

Authorization: Basic dGVzdF9pZDp0ZXN0X2tleQ==

Primjer 2

Sljedeći primjer prikazuje upit koji se može pozvati u testnom okruženju iz web preglednika. Samo ga kopirajte i zalijepite u adresnu traku preglednika:

https://test_id:test_key@viesapi.eu/api-test/get/vies/euvat/PL7171642051

Gdje:

  • test_id – za provjeru autentičnosti u proizvodnji okoliš, parametar treba sadržavati važeći identifikator ključa koji se koristi za autorizaciju,
  • test_key – za provjeru autentičnosti u proizvodnji okruženju, parametar treba sadržavati valjanu vrijednost ključa koji se koristi za autorizaciju.

Identifikator ključa i ključ generira korisnik nakon što se prijavi na svoj račun na viesapi.eu portal (API keys kartica). See the dokumentacija stranicu za više informacija o ID-u i generiranju ključeva.

Odgovor

Ako se zahtjev ispravno obradi, generira se sljedeći odgovor:

Detaljan opis vraćenih atributa:

  • uid – jedinstveni identifikator upita koji generira viesapi.eu,
  • countryCode – kôd zemlje u kojoj je registrirana tvrtka povezana s EU PDV brojem navedenim u upitu,
  • vatNumber – EU PDV broj provjerene tvrtke naveden u upitu,
  • valid – odgovor VIES servisa s informacijom o trenutnom EU PDV statusu provjeravanog subjekta:
    • true – EU PDV broj naveden u upitu je valjan,
    • false – EU PDV broj naveden u upitu nije valjan,
  • traderName – trgovačko ime društva,
  • traderCompanyType – uvijek vraća niz znakova '-',
  • traderAddress – adresu tvrtke na kojoj je tvrtka registrirana,
  • id – jedinstveni identifikator upita generiran od strane VIES sustava
  • date – datum izvršenja upita
  • source – izvor podataka, uvijek: http://ec.europa.eu

Odgovor na pogrešku

U slučaju bilo kakve pogreške u vezi s obradom zahtjeva, vraća se sljedeća poruka o pogrešci:

Greška

Detaljan opis vraćenih atributa:

  • code – jedinstveni kod greške za automatsko rukovanje greškama,
  • description – ljudski presretljivi opis pogreške,
  • details – mdetaljan opis pogreške (izborno),

Kodovi grešaka

Tablica u nastavku navodi sve moguće pogreške koje vraćaju REST API-ji i programske biblioteke:

Šifra greške Poruka o pogrešci
8 Nevažeći format zahtjeva
10 Nevažeći API put
11 Interna servisna greška
22 EU PDV broj je nevažeći
23 Dohvaćanje podataka iz VIES sustava nije uspjelo
26 Ova značajka nije dostupna na trenutno odabranom planu
27 Ova funkcija ne podržava ovaj način pretraživanja
33 Upit za dane podatke nije moguć u testnom načinu
35 Nije potrebna autorizacija upita za pristup
36 Usluga je privremeno nedostupna zbog planiranih tehničkih radova
43 Nije moguće dohvatiti broj korisničkih upita za tekući mjesec
54 Netočan datum ili vrijeme na korisnikovom računalu ili sustavu
55 Nevažeća vrijednost MAC niza u zaglavlju s vjerodajnicama upita
57 Nevažeća vrijednost ključa u zaglavlju s vjerodajnicama upita
58 Dosegnut je najveći broj istodobnih upita za ovu državu članicu
59 Aplikacija u državi članici ne odgovara ili nije dostupna
101 IP broj veze ne odgovara IP broju dodijeljenom API ključu
102 API ključ je blokiran
103 Nevažeći API ključ
104 Dosegnut je maksimalan broj dostupnih upita za odabrani plan
105 Račun blokiran ili izbrisan
106 Nevažeća vrsta računa
107 Pre-paid račun nije plaćen
108 Nevažeći ID ključa API-ja
201 Povezivanje s VIES API uslugom nije uspjelo
202 Odgovor usluge VIES API ima nevažeći format
203 Nevažeća vrsta broja
204 NIP je nevažeći
205 EU PDV ID je nevažeći
206 Funkcija je generirala iznimku
207 Datum ima nevažeći format
208 Nevažeći ulazni parametar