REST API dokumentacija

Įvadas

Mūsų teikiama API naudoja standartinį HTTP protokolą. Visos API funkcijos naudoja HTTP GET metodą. Kiekvienam funkcijos iškvietimui reikalingas užklausos leidimas. Duomenys užklausos autorizacijai siunčiami HTTP antraštėje.

Gamybos paslauga

Būtina užsiregistruoti subjektą, kuris nori naudotis viesapi.eu sistemos funkcionalumu. Norėdami tai padaryti, eikite į Registracija puslapį ir užpildykite atitinkamą formą. Būtina sąlyga norint naudotis viesapi.eu sistema yra sutikimas su Paslaugų teikimo sąlygos. Teisingai užpildę formą ir spustelėdami Registruotis mygtukas sukurs paskyrą viesapi.eu sistemoje ir jos automatinį aktyvavimą.

Prisijungiant pirmą kartą kartu su atitinkamu raktu automatiškai sugeneruojamas identifikatorius. Identifikatorius yra viešas ir jam nereikia apsaugos, o raktas yra privatus ir neturėtų būti prieinamas trečiosioms šalims.

Gamybos tarnybos adresas: https://viesapi.eu/api

Bandymo paslauga

Visą visų bendrinamų bibliotekų funkcionalumą galima patikrinti naudojant bendrinamą Išbandykite VIES API. Naudojantis testine API, galima patikrinti visas mokamuose planuose siūlomas funkcijas nereikia susikurti paskyros.

Bandymo paslaugos adresas: https://viesapi.eu/api-test

API sąsajos apibrėžimas

Išsamų API apibrėžimą galima rasti su OpenAPI suderinamu formatu ir jį galima atsisiųsti kaip YAML failą čia.

API taip pat galima kaip kliento sąsają Swagger vartotojo sąsaja.

Užklausos vykdymas

Pavyzdys, kaip pateikti užklausą bandomojoje svetainėje:

GET /api-test/get/vies/euvat/PL7171642051 HTTP/1.1
Laidos vedėjas: viesapi.eu:443
Autorizacija: MAC id="api_key_id", ts="unix_timestamp", nonce="random_str", mac="b64_calculated_mac_value"
Vartotojo agentas: VIESAPIClient/client_version platform_name/platform_version

Kur:

  • api_key_id – API rakto identifikatorius (gamybinėje aplinkoje registracijos metu sugeneruoto identifikatoriaus reikšmė, bandomojoje aplinkoje test_id vertė),
  • unix_timestamp – dabartinis laikas sekundžių skaičiumi nuo vadinamojo unix epocha,
  • random_str – atsitiktinė eilutė, skirtinga kiekvienai užklausai (mažiausiai 8 simboliai, ne daugiau kaip 16 simbolių),
  • b64_calculated_mac_value – apskaičiuotas HMAC (naudojant API key, vertė test_key bandymo aplinkoje),
  • client_version – kliento versija (mūsų bibliotekose tai yra mūsų API bibliotekos versija, pvz., 1.2.3),
  • platform_name – API kliento platformos pavadinimas (mūsų bibliotekose tai yra bibliotekos kalbos pavadinimas, pvz., JAVA, PHP, .NET, Python),
  • platform_version – API kliento platformos versija (mūsų bibliotekose tai bibliotekos aplinkos versija, pvz. 17 JAVA arba 7.4 PHP).

Visi svetainės pateikti atsakymai yra XML formatu.

Autentifikavimo prašymas

Naudojamo leidimo suteikimo metodo specifikacija: HTTP autentifikavimas: MAC prieigos autentifikavimas. Kiekviena mūsų svetainės užklausa turi būti patvirtinta naudojant šį metodą. Autorizacija susideda iš HMAC SHA256 apskaičiavimo iš tinkamai paruoštos eilutės ir rezultato siuntimo HTTP antraštėje.

Pavyzdys

HMAC funkcijos įvesties eilutė yra:
ts + '\n' + nonce + '\n' + method + '\n' + path + '\n' + host + '\n' + port + '\n\n'

Kur:

  • ts – dabartinis laikas sekundžių skaičiumi nuo vadinamojo unix epocha, visada turėtumėte pateikti esamą užklausos vykdymo laiką (serverio tolerancija +/- 10 min., palyginti su dabartiniu laiku),
  • nonce – atsitiktinė eilutė, skirtinga kiekvienai užklausai (mažiausiai 8 simboliai, ne daugiau kaip 16 simbolių),
  • method – HTTP metodo pavadinimas (visada GET),
  • path – vykdomos užklausos URL kelias,
  • host – VIES API serverio pavadinimas (visada viesapi.eu),
  • port – VIES API serverio prievado numeris (visada 443),
  • ’\n’ – naujos eilutės simbolis (ASCII kodas 10, 0x0A).

Užklausos dėl PVM numerio PL7171642051, išsiųstos testavimo tarnybai 2019-11-25 00:00:00 UTC, HMAC funkcijos įvesties eilutė atrodys taip:
str = "1574640000\ndt831hs59s\nGET\n/api-test/get/vies/euvat/PL7171642051\nviesapi.eu\n443\n\n"

Šio pavyzdžio įvesties eilutės failą galima atsisiųsti čia.

Iš paruoštos eilutės apskaičiuojame HMAC SHA256, kaip HMAC slaptažodį suteikiame API key, ty bandomosios API atveju vertė test_key:

HMAC_SHA256(str, "test_key") = 7776a12b958233ce60dd0f16b8d141e80472a1ee3b1e1fb136d7abe34cb59306

Funkcija HMAC SHA256 grąžina 32 dvejetainius baitus (parodyta aukščiau kaip a hex skaitomumo eilutę). Atsisiųsti failą su dvejetaine verte čia.

Apskaičiuoto HMAC dvejetainė reikšmė turėtų būti užkoduota Base64 algoritmu, gauname:

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