REST API dokumentacija

VIES API REST 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),

Klaidų kodai

Žemiau esančioje lentelėje pateikiamos visos galimos REST API ir programavimo bibliotekų grąžintos klaidos:

Klaidos kodas Klaidos pranešimas
8 Netinkamas užklausos formatas
10 Netinkamas API kelias
11 Vidinė aptarnavimo klaida
22 ES PVM mokėtojo kodas neteisingas
23 Nepavyko gauti duomenų iš VIES sistemos
26 Ši funkcija nepasiekiama šiuo metu pasirinktame plane
27 Ši funkcija nepalaiko šio paieškos režimo
33 Užklausa pateiktų duomenų negalima bandymo režimu
35 Prieigos užklausos autorizacijos nereikia
36 Paslauga laikinai neteikiama dėl suplanuotų techninių darbų
43 Nepavyko gauti einamojo mėnesio naudotojų užklausų skaičiaus
54 Neteisinga data arba laikas vartotojo kompiuteryje arba sistemoje
55 Netinkama MAC eilutės reikšmė antraštėje su užklausos kredencialais
57 Netinkama rakto reikšmė antraštėje su užklausos kredencialais
58 Pasiektas didžiausias vienu metu atliekamų užklausų skaičius šioje valstybėje narėje
59 Į paraišką valstybėje narėje neatsakoma arba ji neprieinama
101 Ryšio IP numeris nesutampa su API raktui priskirtu IP numeriu
102 API raktas užblokuotas
103 Neteisingas API raktas
104 Pasiektas maksimalus pasirinkto plano užklausų skaičius
105 Paskyra užblokuota arba ištrinta
106 Netinkamas paskyros tipas
107 Išankstinio mokėjimo sąskaita neapmokėta
108 Neteisingas API rakto ID
201 Nepavyko prisijungti prie VIES API paslaugos
202 VIES API paslaugos atsako formatas netinkamas
203 Neteisingas numerio tipas
204 NIP neteisingas
205 ES PVM mokėtojo kodas neteisingas
206 Funkcija sukūrė išimtį
207 Datos formatas netinkamas
208 Netinkamas įvesties parametras