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

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),
  • mime_type – MIME tipo pavadinimas, kuriuo turi būti grąžintas atsakymas, palaikomi du tipai: text/xml ir application/json, jei užklausoje nėra antraštės Priimti, XML grąžinamas pagal numatytuosius nustatymus.

Autentifikavimo prašymas

Autorizacijos duomenys turi būti parengti pagal HTTP autentifikavimas: MAC prieigos autentifikavimas ir tai yra rekomenduojamas autentifikavimo metodas. Taip pat galima naudoti HTTP autentifikavimas: pagrindinis autentifikavimas metodas, tačiau saugumo sumetimais naudokite jį tik tada, kai dėl kokių nors priežasčių neįmanoma naudoti pirmojo metodo.

Kiekviena mūsų svetainės užklausa turi būti patvirtinta vienu iš dviejų prieinamų metodų.

1 būdas – HMAC (rekomenduojama)

Naudojamo leidimo suteikimo metodo specifikacija: HTTP autentifikavimas: MAC prieigos autentifikavimas. 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=

Ši vertė turėtų būti siunčiama kaip MAC reikšmė antraštėje su duomenimis, kuriuos reikia patvirtinti. Pagaliau:

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

Linux kompiuteryje reikiamą MAC vertę galima apskaičiuoti vienu žingsniu naudojant šią komandą:

$ 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 būdas – pagrindinis autentifikavimas

Šio naudojamo leidimo metodo specifikacija: HTTP autentifikavimas: pagrindinis autentifikavimas.

1 pavyzdys

Funkcijos „Base64“ įvesties eilutė yra:

str = key_id + ':' + key

Kur:

  • key_id – API rakto identifikatorius (bandomosios aplinkos atveju, test_id eilutė),
  • key – API raktas (bandomosios aplinkos atveju eilutė test_key).

Bandymo aplinkoje Base64 funkcijos įvesties eilutė bus:

str = "test_id:test_key"

Pritaikę Base64 funkciją, gauname:

Base64(str) = dGVzdF9pZDp0ZXN0X2tleQ==

Ši vertė turėtų būti siunčiama kaip pagrindinė reikšmė antraštėje su duomenimis, kuriuos reikia patvirtinti. Galiausiai:

Authorization: Basic dGVzdF9pZDp0ZXN0X2tleQ==

2 pavyzdys

Šiame pavyzdyje parodyta užklausa, kurią galima iškviesti bandomojoje aplinkoje iš žiniatinklio naršyklės. Tiesiog nukopijuokite ir įklijuokite jį į naršyklės adreso juostą:

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

Kur:

  • test_id – autentifikuoti gamyboje aplinką, parametre turi būti galiojantis rakto identifikatorius, naudojamas autorizacijai,
  • test_key – autentifikuoti gamyboje aplinkoje, parametre turi būti galiojanti autorizacijai naudojamo rakto reikšmė.

Rakto identifikatorių ir raktą sugeneruoja vartotojas, prisijungęs prie savo paskyros viesapi.eu portalas (API keys skirtukas). See dokumentacija puslapis, kuriame rasite daugiau informacijos apie ID ir raktų generavimą.

Atsakymas

Jei užklausa apdorojama teisingai, sugeneruojamas toks atsakymas:

Išsamus grąžintų atributų aprašymas:

  • uid – unikalus užklausos identifikatorius, sugeneruotas viesapi.eu,
  • countryCode – šalies kodas, kurioje registruota įmonė, susijusi su užklausoje nurodytu ES PVM mokėtojo numeriu,
  • vatNumber – užklausoje nurodytas patikrintos įmonės ES PVM mokėtojo kodas,
  • valid – VIES tarnybos atsakymas, informuojantis apie esamą tikrinamo subjekto ES PVM statusą:
    • true – galioja užklausoje nurodytas ES PVM mokėtojo kodas,
    • false – užklausoje pateiktas ES PVM mokėtojo kodas negalioja,
  • traderName - įmonės prekės pavadinimas,
  • traderCompanyType – visada grąžindavo „-“ simbolių eilutę,
  • traderAddress – įmonės adresas, kuriame įmonė įregistruota,
  • id – unikalus VIES sistemos sugeneruotas užklausos identifikatorius
  • date – užklausos vykdymo data
  • source – duomenų šaltinis, visada: http://ec.europa.eu

Klaidos atsakymas

Įvykus bet kokiai klaidai, susijusiai su užklausos tvarkymu, grąžinamas toks klaidos pranešimas:

Klaida

Išsamus grąžintų atributų aprašymas:

  • code – unikalus klaidos kodas automatiniam klaidų apdorojimui,
  • description – žmogaus perimamas klaidos aprašymas,
  • details – mišsamus klaidos aprašymas (neprivaloma),