Dokumentacija REST API

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
Gostitelj: viesapi.eu:443
Avtorizacija: MAC id="api_key_id", ts="unix_timestamp", nonce="random_str", mac="b64_calculated_mac_value"
Uporabniški agent: VIESAPIClient/client_version ime_platforme/različica_platforme

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

Vsi odgovori, ki jih vrne spletno mesto, so v formatu XML.

Zahteva za preverjanje pristnosti

Specifikacija uporabljene metode avtorizacije: Preverjanje pristnosti HTTP: Preverjanje pristnosti dostopa MAC. Vsaka poizvedba na naši spletni strani mora biti overjena s to metodo. 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=

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