Dokumentacija REST API

Dokumentacija VIES API REST

Uvod

API, ki ga ponujamo, uporablja standardni protokol HTTP. Vse funkcije API-ja uporabljajo metodo HTTP GET. Vsak klic funkcije zahteva avtorizacijo poizvedbe. Podatki za avtorizacijo poizvedbe se pošljejo v glavi HTTP.

Produkcijska storitev

Obvezna je registracija subjekta, ki želi uporabljati funkcionalnosti sistema viesapi.eu. Če želite to narediti, pojdite na Registracija strani in izpolnite ustrezen obrazec. Predpogoj za uporabo sistema viesapi.eu je sprejem Pogoji storitve. Pravilno izpolnitev obrazca in klik na Registrirajte se Gumb ustvari račun v sistemu viesapi.eu in njegovo samodejno aktivacijo.

Ob prvi prijavi se identifikator samodejno ustvari skupaj z ustreznim ključem. Identifikator je javen in ne zahteva zaščite, ključ pa je zaseben in ne sme biti dostopen tretjim osebam.

Naslov proizvodne službe: https://viesapi.eu/api

Testna storitev

Popolno funkcionalnost vseh knjižnic v skupni rabi lahko preverite s pomočjo deljene knjižnice Test VIES API. Z uporabo testnega API-ja je mogoče preveriti vse funkcije, ki so na voljo v plačljivih paketih brez potrebe po ustvarjanju računa.

Naslov testne službe: https://viesapi.eu/api-test

Definicija vmesnika API

Podrobna definicija API-ja je na voljo v formatu, združljivem z OpenAPI, in jo lahko prenesete kot datoteko YAML tukaj.

API je na voljo tudi kot vmesnik odjemalca Uporabniški vmesnik Swagger.

Izvedba poizvedbe

Primer izdelave poizvedbe na testnem mestu:

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

Kje:

  • api_key_id – identifikator ključa API (v produkcijskem okolju vrednost identifikatorja, generiranega med registracijo, v testnem okolju vrednost test_id),
  • unix_timestamp – trenutni čas v obliki števila sekund iz ti unix epoha,
  • random_str – naključni niz, drugačen za vsako poizvedbo (najmanj 8 znakov, največ 16 znakov),
  • b64_calculated_mac_value – izračunan HMAC (z uporabo an API key, vrednost test_key v testnem okolju),
  • client_version – različica odjemalca (v naših knjižnicah je to različica naše knjižnice API, npr. 1.2.3),
  • platform_name – ime platforme odjemalca API (v naših knjižnicah je to ime jezika knjižnice, npr. JAVA, PHP, .NET, Python),
  • platform_version – različica platforme odjemalca API (v naših knjižnicah je to različica knjižničnega okolja, npr. 17 za JAVA ali 7.4 za PHP),
  • mime_type – Ime tipa MIME, v katerem mora biti vrnjen odgovor, podprti sta dve vrsti: text/xml in application/json, če zahteva ne vsebuje glave Accept, je privzeto vrnjen XML.

Zahteva za preverjanje pristnosti

Podatki o pooblastilu morajo biti pripravljeni v skladu z Preverjanje pristnosti HTTP: Preverjanje pristnosti dostopa MAC in to je priporočena metoda preverjanja pristnosti. Možna je tudi uporaba Preverjanje pristnosti HTTP: Osnovno preverjanje pristnosti vendar jo iz varnostnih razlogov uporabite le, če uporaba prve metode iz nekega razloga ni mogoča.

Vsaka poizvedba na naši spletni strani mora biti overjena z enim od dveh razpoložljivih metod.

1. način – HMAC (priporočeno)

Specifikacija uporabljene metode avtorizacije: Preverjanje pristnosti HTTP: Preverjanje pristnosti dostopa MAC. Avtorizacija je sestavljena iz izračuna HMAC SHA256 iz pravilno pripravljenega niza in pošiljanja rezultata v glavi HTTP.

Primer

Vhodni niz za funkcijo HMAC je:
ts + '\n' + nonce + '\n' + method + '\n' + path + '\n' + host + '\n' + port + '\n\n'

Kje:

  • ts – trenutni čas v obliki števila sekund iz ti unix epoha, morate vedno navesti trenutni čas izvajanja poizvedbe (toleranca strežnika +/- 10 min glede na trenutni čas),
  • nonce – naključni niz, drugačen za vsako poizvedbo (najmanj 8 znakov, največ 16 znakov),
  • method – ime metode HTTP (vedno GET),
  • path – URL pot poizvedbe, ki naj se izvede,
  • host – Ime strežnika VIES API (vedno viesapi.eu),
  • port – številka vrat strežnika VIES API (vedno 443),
  • ’\n’ – znak za novo vrstico (ASCII koda 10, 0x0A).

Za poizvedbo za številko DDV PL7171642051, poslano testni storitvi dne 2019-11-25 00:00:00 UTC, bo vhodni niz v funkcijo HMAC videti takole:
str = "1574640000\ndt831hs59s\nGET\n/api-test/get/vies/euvat/PL7171642051\nviesapi.eu\n443\n\n"

Datoteko vhodnega niza za ta primer lahko prenesete tukaj.

Iz pripravljenega niza izračunamo HMAC SHA256 kot geslo HMAC, ki ga podamo API key, tj. v primeru testnega API-ja vrednost test_key:

HMAC_SHA256(str, "test_key") = 7776a12b958233ce60dd0f16b8d141e80472a1ee3b1e1fb136d7abe34cb59306

Funkcija HMAC SHA256 vrne 32 binarnih bajtov (prikazano zgoraj kot a hex niz za berljivost). Prenesite datoteko z binarno vrednostjo tukaj.

Binarno vrednost izračunanega HMAC je treba kodirati z algoritmom Base64, dobimo:

d3ahK5WCM85g3Q8WuNFB6ARyoe47Hh+xNter40y1kwY=

To vrednost je treba poslati kot vrednost MAC v glavi s podatki za avtorizacijo. Končno:

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

V stroju Linux je zahtevano vrednost MAC mogoče izračunati v enem koraku s tem ukazom:

$ 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

2. način – Osnovna avtentikacija

Specifikacija uporabljene metode avtorizacije: Preverjanje pristnosti HTTP: Osnovno preverjanje pristnosti.

Primer 1

Vhodni niz za funkcijo Base64 je:

str = key_id + ':' + key

Kje:

  • key_id – identifikator ključa API (v primeru testnega okolja, test_id vrvica),
  • key – API ključ (v primeru testnega okolja niz test_key).

Za preskusno okolje bo vhodni niz za funkcijo Base64:

str = "test_id:test_key"

Po uporabi funkcije Base64 dobimo:

Base64(str) = dGVzdF9pZDp0ZXN0X2tleQ==

To vrednost je treba poslati kot osnovno vrednost v glavi s podatki za avtorizacijo. Končno:

Authorization: Basic dGVzdF9pZDp0ZXN0X2tleQ==

Primer 2

Naslednji primer prikazuje poizvedbo, ki jo je mogoče priklicati v a Testno okolje iz spletnega brskalnika. Samo kopirajte in prilepite v naslovno vrstico brskalnika:

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

Kje:

  • test_id – za avtentikacijo v produkciji okolju, mora parameter vsebovati veljaven identifikator ključa, ki se uporablja za avtorizacijo,
  • test_key – za avtentikacijo v produkciji okolje, mora parameter vsebovati veljavno vrednost ključa, uporabljenega za avtorizacijo.

Identifikator ključa in ključ generira uporabnik po prijavi v svoj račun na viesapi.eu portal (API keys zavihek). See dokumentacijo stran za več informacij o ustvarjanju ID-ja in ključa.

getVIESData odgovor

Če je zahteva obravnavana pravilno, se ustvari naslednji odgovor:

vies api - getVIESDataParsed

Podroben opis vrnjenih atributov:

  • uid – edinstven identifikator poizvedbe, ki ga ustvari viesapi.eu,
  • countryCode – kodo države, v kateri je registrirano podjetje, povezano z EU DDV številko, navedeno v povpraševanju,
  • vatNumber – številko EU za DDV preverjenega podjetja, navedeno v povpraševanju,
  • valid – odgovor storitve VIES, ki obvešča o trenutnem EU DDV statusu preverjanega subjekta:
    • true – številka EU za DDV, navedena v povpraševanju, je veljavna,
    • false – številka EU za DDV, navedena v povpraševanju, ni veljavna,
  • traderName – firmo podjetja,
  • traderCompanyType – vedno vrne niz znakov '-',
  • traderAddress – naslov podjetja, kjer je podjetje registrirano (izvirna oblika),
  • traderAddressComponent – podrobnosti naslova združevanja komponent – izbirni atribut, ta funkcija ne bo nikoli vrnjena.
  • id – enolični identifikator poizvedbe, ki ga generira sistem VIES (Consultation Number),
  • date – datum izvedbe poizvedbe
  • source – vir podatkov, vedno: http://ec.europa.eu

getVIESDataParsed odgovor

Če je zahteva obravnavana pravilno, se ustvari naslednji odgovor:

vies api - getVIESDataParsed

Podroben opis vrnjenih atributov:

  • uid – edinstven identifikator poizvedbe, ki ga ustvari viesapi.eu,
  • countryCode – kodo države, v kateri je registrirano podjetje, povezano z EU DDV številko, navedeno v povpraševanju,
  • vatNumber – številko EU za DDV preverjenega podjetja, navedeno v povpraševanju,
  • valid – odgovor storitve VIES, ki obvešča o trenutnem EU DDV statusu preverjanega subjekta:
    • true – številka EU za DDV, navedena v povpraševanju, je veljavna,
    • false – številka EU za DDV, navedena v povpraševanju, ni veljavna,
  • traderName – firmo podjetja,
  • traderCompanyType – vedno vrne niz znakov '-',
  • traderAddress – naslov podjetja, kjer je podjetje registrirano (izvirna oblika),
  • traderAddressComponent – podrobnosti o naslovu združevanja komponent
    • country – ime države trgovca v njenem nacionalnem jeziku
    • postalCode – poštno številko naslova trgovca
    • city – mesto naslova trgovca
    • street -ulica naslova trgovca
    • streetNumber – hišna številka naslova trgovca
    • houseNumber – hišna številka naslova trgovca
  • id – enolični identifikator poizvedbe, ki ga generira sistem VIES (Consultation Number),
  • date – datum izvedbe poizvedbe,
  • source – vir podatkov, vedno: http://ec.europa.eu

Pomembna izjava o omejitvi odgovornosti!

Funkcija razčlenjevanja uporablja zunanje algoritme umetne inteligence in API-je za samodejno ekstrahiranje atributov, kot so: mesto, poštna številka, ulica s številko ulice (številka stavbe) in hišna številka, zato ne moremo zagotoviti njenega pravilnega delovanja 100%.

getVIESDataAsync odgovor

Če je zahteva obravnavana pravilno, se ustvari naslednji odgovor:

Odgovor VIES API getVIESDataAsync

Podroben opis vrnjenih atributov:

  • token – paketni žeton (guid), ki ga ustvari viesapi.eu, je treba uporabiti za klic funkcije getVIESDataAsync (po 2-3 minutah), da dobite rezultate.

getVIESDataAsyncResult odgovor

Če je zahteva pravilno obravnavana, mora biti ustvarjen naslednji odgovor, ki vsebuje seznam objektov s podatki, ki jih vrne VIES:

vies api getVIESDataAsyncResults

Podroben opis vrnjenih atributov:

  • numbers – niz predmetov z rezultati, ki jih vrne VIES in ustrezajo številkam za DDV EU, poslanim v zahtevi za klic funkcije getVIESDataAsync
    • uid – edinstven identifikator poizvedbe, ki ga ustvari viesapi.eu,
    • countryCode – kodo države, v kateri je registrirano podjetje, povezano z EU DDV številko, navedeno v povpraševanju,
    • vatNumber – številko EU za DDV preverjenega podjetja, navedeno v povpraševanju,
    • valid – odgovor storitve VIES, ki obvešča o trenutnem EU DDV statusu preverjanega subjekta:
      • true – številka EU za DDV, navedena v povpraševanju, je veljavna,
      • false – številka EU za DDV, navedena v povpraševanju, ni veljavna,
    • traderName – firmo podjetja,
    • traderCompanyType – vedno vrne niz znakov '-',
    • traderAddress – naslov podjetja, kjer je podjetje registrirano (izvirna oblika),
    • id – enolični identifikator poizvedbe, ki ga generira sistem VIES (Consultation Number),
    • date – datum izvedbe poizvedbe
    • source – vir podatkov, vedno: http://ec.europa.eu
  • errors – matrika objektov z napakami, ki jih vrne VIES za podatke o številki za DDV EU, poslane v zahtevi za klic funkcije getVIESDataAsync
    • uid – edinstven identifikator poizvedbe, ki ga ustvari viesapi.eu,
    • countryCode – kodo države, v kateri je registrirano podjetje, povezano z EU DDV številko, navedeno v povpraševanju,
    • vatNumber – številko EU za DDV preverjenega podjetja, navedeno v povpraševanju,
    • error – podrobnosti o napaki, vrnjeni za to specifično številko za DDV v EU
    • date – datum izvedbe poizvedbe
    • source – vir podatkov, vedno: http://ec.europa.eu

Odgovor na napako

V primeru kakršne koli napake, povezane z obravnavanjem zahteve, se vrne naslednje sporočilo o napaki:

odgovor na napako vies rest api

Podroben opis vrnjenih atributov:

  • code – edinstvena koda napake za samodejno obravnavanje napak,
  • description – opis napake, ki jo človek prestreže,
  • details – mali podroben opis napake (neobvezno),

Kode napak

V spodnji tabeli so navedene vse možne napake, ki jih vrnejo API-ji REST in programske knjižnice:

Koda napake Sporočilo o napaki
8 Neveljavna oblika zahteve
10 Neveljavna pot API-ja
11 Notranja servisna napaka
22 Številka EU za DDV je neveljavna
23 Podatkov iz sistema VIES ni bilo mogoče pridobiti
26 Ta funkcija ni na voljo v trenutno izbranem paketu
27 Ta funkcija ne podpira tega načina iskanja
33 Poizvedovanje po danih podatkih v testnem načinu ni mogoče
35 Pooblastilo za poizvedbo o dostopu ni potrebno
36 Storitev začasno ni na voljo zaradi načrtovanih tehničnih del
43 Števila uporabniških poizvedb za trenutni mesec ni bilo mogoče pridobiti
54 Napačen datum ali ura na uporabnikovem računalniku ali sistemu
55 Neveljavna vrednost niza MAC v glavi s poverilnicami poizvedbe
57 Neveljavna vrednost ključa v glavi s poverilnicami poizvedbe
58 Največje število sočasnih poizvedb za to državo članico je bilo doseženo
59 Aplikacija v državi članici ne odgovarja ali ni na voljo
62 Paket je še v obdelavi, poskusite znova pozno
63 Doseženo je bilo največje število paketnih zahtev, prosimo, da svojo zahtevo znova oddate pozneje
101 Številka IP povezave se ne ujema s številko IP, dodeljeno ključu API
102 Ključ API je blokiran
103 Neveljaven ključ API-ja
104 Največje število razpoložljivih poizvedb za izbrani načrt je bilo doseženo
105 Račun blokiran ali izbrisan
106 Neveljavna vrsta računa
107 Predplačniški račun ni bil plačan
108 Neveljaven ID ključa API
201 Povezava s storitvijo VIES API ni uspela
202 Odgovor storitve VIES API ima neveljavno obliko
203 Neveljavna vrsta številke
204 NIP ni veljaven
205 EU ID za DDV je neveljavna
206 Funkcija je ustvarila izjemo
207 Datum ima neveljavno obliko
208 Neveljaven vnosni parameter
209 Omejitev velikosti serije je presežena [2-99]