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 testnem okolju 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.

Odziv

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

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,
  • id – enolični identifikator poizvedbe, ki ga ustvari sistem VIES
  • 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:

Napaka

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
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