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 anAPI key, vrijednosttest_keyna 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/xmliapplication/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 (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=
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_idniz),key– API ključ (u slučaju testnog okruženja, niztest_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 a Testno okruženje 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.
getVIESData 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 (izvorni format),traderAddressComponent– detalji adrese grupiranja komponenti – izborni atribut, nikada neće biti vraćen u ovoj funkciji.id– jedinstveni identifikator upita koji generira VIES sustav (Consultation Number),date– datum izvršenja upitasource– izvor podataka, uvijek: http://ec.europa.eu
getVIESDataParsed 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– naziv tvrtke (originalni format),traderNameComponents– pravni oblik tvrtke koja je dio grupiranja komponenti:name– naziv tvrtke iz traderName (bez pravnog oblika),legalForm– naziv pravnog oblika preuzet iz naziva trgovca (bez naziva tvrtke),legalFormCanonicalId– rječnički identifikator pravnog oblika,legalFromCanonicalName– naziv pravnog oblika iz rječnika,
traderCompanyType– uvijek vraća niz znakova '-',traderAddress– adresu tvrtke na kojoj je tvrtka registrirana (izvorni format),traderAddressComponent– detalji adrese grupiranja komponenti:country– naziv zemlje trgovca na njezinom nacionalnom jeziku,postalCode– poštanski broj adrese trgovca,city– grad u kojem se nalazi adresa trgovca,street- ulica na kojoj se nalazi adresa trgovca,streetNumber– kućni broj adrese trgovca,houseNumber– kućni broj adrese trgovca,
id– jedinstveni identifikator upita koji generira VIES sustav (Consultation Number),date– datum izvršenja upita,source– izvor podataka, uvijek: http://ec.europa.eu
legalFormCanonicalId |
legalFormCanonicalName |
| 0 | NEPOZNATO |
| 1 | SAMOSTALNO VLASNIŠTVO |
| 2 | DRUŠTVO S OGRANIČENOM ODGOVORNOŠĆU |
| 3 | OPĆE PARTNERSTVO |
| 4 | DIONIČKO DRUŠTVO |
| 5 | OGRANIČENO PARTNERSTVO |
| 6 | PRIVATNO_DRUŠTVO_S_OGRANIČENOM_ODGOVORNOŠĆU |
| 7 | DIONIČKO DRUŠTVO S JEDNIM ČLANOM |
| 8 | SIMPLE_LIMITED_LIABILITY_COMPANY |
| 9 | DRUŠTVO S OGRANIČENOM ODGOVORNOŠĆU S JEDNIM ČLANOM |
| 10 | POJEDNOSTAVLJENO_DIONIČKO_DRUŠTVO |
| 11 | MALA_TVRTKA |
| 12 | DIONIČKO PARTNERSTVO S OGRANIČENOM DOPRIVREDOM |
| 13 | PROFESIONALNO PARTNERSTVO |
| 14 | PARTNERSTVO S OGRANIČENOM ODGOVORNOŠĆU |
| 15 | PRIVATNO_PARTNERSTVO |
| 16 | DRUŠTVO_S_OGRANIČENOM_ODGOVORNOŠĆU_S_OGRANIČENOM_ODGOVORNOŠĆU |
| 17 | DRUŠTVO_S_OGRANIČENOM_ODGOVORNOŠĆU_S_OGRANIČENOM_ODGOVORNOŠĆU_DIONIČKO_PARTNERSTVO |
| 18 | JAVNA_INSTITUCIJA |
Važno odricanje od odgovornosti!
Funkcija raščlambe koristi vanjske AI algoritme i API-je za automatsko izdvajanje atributa kao što su: grad, poštanski broj, ulica s brojem ulice (broj zgrade) i kućni broj, tako da ne možemo jamčiti ispravan rad 100%.
getVIESDataAsync odgovor
Ako se zahtjev ispravno obradi, generira se sljedeći odgovor:
Detaljan opis vraćenih atributa:
token– paketni token (guid) koji je generirao viesapi.eu, trebao bi se koristiti za pozivanje funkcije getVIESDataAsync (nakon 2-3 minute) za dobivanje rezultata.
getVIESDataAsyncResult odgovor
Ako se zahtjev ispravno obradi, trebao bi se generirati sljedeći odgovor koji sadrži popis objekata s podacima koje vraća VIES:
Detaljan opis vraćenih atributa:
numbers– niz objekata s rezultatima koje vraća VIES koji odgovaraju EU PDV brojevima poslanim u zahtjevu za poziv funkcije getVIESDataAsyncuid– 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 (izvorni format),id– jedinstveni identifikator upita koji generira VIES sustav (Consultation Number),date– datum izvršenja upitasource– izvor podataka, uvijek: http://ec.europa.eu
errors– niz objekata s pogreškama koje vraća VIES za podatke EU PDV broja poslane u zahtjevu za poziv funkcije getVIESDataAsyncuid– 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,error– pojedinosti o pogrešci vraćenoj za ovaj specifični EU PDV brojdate– datum izvršenja upitasource– 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:
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 |
| 62 | Serija se još obrađuje, pokušajte ponovo kasnije |
| 63 | Dosegnut je maksimalan broj skupnih zahtjeva, molimo vas da ponovo pošaljete svoj zahtjev kasnije |
| 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 |
| 209 | Ograničenje veličine serije premašeno [2-99] |