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 a Bandymo aplinka iš interneto 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ą.

gautiVIESduomenis atsakymą

Jei užklausa apdorojama teisingai, sugeneruojamas toks atsakymas:

vies api – gautiVIESDataParsed

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 (pradinis formatas),
  • traderAddressComponent – komponentų grupavimo adreso informacija – pasirenkamasis atributas, niekada nebus grąžintas naudojant šią funkciją.
  • id – unikalus VIES sistemos sugeneruotas užklausos identifikatorius (konsultacijos numeris),
  • date – užklausos vykdymo data
  • source – duomenų šaltinis, visada: http://ec.europa.eu

gautiVIESDataParsed atsakymą

Jei užklausa apdorojama teisingai, sugeneruojamas toks atsakymas:

„Vies“ rest API duomenų išanalizuotas 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 registracijos pavadinimas (originalus formatas),
  • traderNameComponents – komponentų grupės bendrovės teisinė forma:
    • name – įmonės pavadinimas iš „traderName“ (be teisinės formos),
    • legalForm – teisinės formos pavadinimas, gautas iš „traderName“ (be įmonės pavadinimo),
    • legalFormCanonicalId – teisinės formos žodyninis identifikatorius,
    • legalFromCanonicalName – teisinės formos žodyninis pavadinimas,
  • traderCompanyType – visada grąžindavo „-“ simbolių eilutę,
  • traderAddress – įmonės adresas, kuriame įmonė įregistruota (pradinis formatas),
  • traderAddressComponent – komponentų grupės adreso duomenys:
    • country – prekybininko šalies pavadinimas jos nacionaline kalba,
    • postalCode – prekiautojo adreso pašto kodas,
    • city – prekiautojo adreso miestas,
    • street - prekiautojo adreso gatvė,
    • streetNumber – prekiautojo adreso gatvės numeris,
    • houseNumber – prekiautojo adreso namo numeris,
  • id – unikalus VIES sistemos sugeneruotas užklausos identifikatorius (konsultacijos numeris),
  • date – užklausos vykdymo data,
  • source – duomenų šaltinis, visada: http://ec.europa.eu
teisinės formos kanoninis ID teisinė forma Kanoninis pavadinimas bibliotekos sąrašo pavadinimas
0 Nežinoma NEŽINOMAS
1 Individuali įmonė IŠSKIRTINĖ NUOSAVYBĖ
2 Ribotos atsakomybės bendrovė RIBOTA_ATSAKOMYBĖS_ĮMONĖ
3 Bendroji partnerystė BENDROJI PARTNERYSTĖ
4 Akcinė bendrovė JUNGTINĖ_AKCINĖ_BENDROVĖ
5 Komanditinė ūkinė bendrija RIBOTA PARTNERYSTĖ
6 Uždaroji akcinė bendrovė PRIVATE_LIMITED_LIABILITY_COMPANY
7 Vieno nario akcinė bendrovė VIENO_NARIO_JUNGTA_AKCINĖ_BENDROVĖ
8 Paprasta ribotos atsakomybės bendrovė PAPRASTA_RIBOTA_ATSAKOMYBĖS_ĮMONĖ
9 Vieno nario ribotos atsakomybės bendrovė VIENO_NARIO_RIBOTOS_ATSAKOMYBĖS_ĮMONĖ
10 Supaprastinta akcinė bendrovė SUPAPRASTINTA_JUNGTA_AKCINĖ_BENDROVĖ
11 Maža įmonė MAŽA_ĮMONĖ
12 Uždaroji akcinė bendrovė LIMITED_JOINT_STOCK_PARTNERSHIP
13 Profesionali partnerystė PROFESIONALI PARTNERYSTĖ
14 Ribotos atsakomybės partnerystė RIBOTA_ATSAKOMYBĖS_PARTNERYSTĖ
15 Privati partnerystė PRIVATE_PARTNERSHIP
16 Ribotos atsakomybės bendrovė Komanditinė ūkinė bendrija RIBOTA_ATSAKOMYBĖS_ĮMONĖ_RIBOTA_PARTNERYSTĖ
17 Uždaroji akcinė bendrovė LIMITED_LIABILITY_COMPANY_LIMITED_JOINT_STOCK_PARTNERSHIP
18 Viešoji įstaiga VIEŠOJI_INSTITUCIJA

Svarbus atsakomybės atsisakymas!

Analizavimo funkcija naudoja išorinius AI algoritmus ir API, kad automatiškai išskirtų atributus, tokius kaip: miestas, pašto kodas, gatvė su gatvės numeriu (pastato numeris) ir namo numeris, todėl negalime garantuoti, kad 100% tinkamai veikia.

gautiVIESDataAsync atsakymą

Jei užklausa apdorojama teisingai, sugeneruojamas toks atsakymas:

VIES API gautiVIESDataAsync atsakymą

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

  • token – viesapi.eu sugeneruotas paketinis prieigos raktas (gidas), turi būti naudojamas getVIESDataAsync (po 2-3 minučių) funkcijai iškviesti, kad būtų gauti rezultatai.

gautiVIESDataAsyncResult atsakymą

Jei užklausa tvarkoma teisingai, turėtų būti sugeneruotas toks atsakymas, kuriame yra objektų sąrašas su VIES grąžintais duomenimis:

vies api getVIESDataAsyncResults

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

  • numbers – objektų masyvas su VIES grąžintais rezultatais, atitinkančiais ES PVM numerius, išsiųstus funkcijos getVIESDataAsync iškvietimo užklausoje
    • 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 (pradinis formatas),
    • id – unikalus VIES sistemos sugeneruotas užklausos identifikatorius (konsultacijos numeris),
    • date – užklausos vykdymo data
    • source – duomenų šaltinis, visada: http://ec.europa.eu
  • errors – objektų su klaidomis masyvas, kurį VIES grąžino ES PVM numerio duomenims, išsiųstiems getVIESDataAsync funkcijos iškvietimo užklausoje
    • 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,
    • error – išsami informacija apie klaidą, grąžintą dėl šio konkretaus ES PVM mokėtojo kodo
    • 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:

vies rest api klaidos atsakymas

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
62 Paketas vis dar apdorojamas, vėlai bandykite dar kartą
63 Pasiektas maksimalus paketinių užklausų skaičius. Vėliau pateikite užklausą iš naujo
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
209 Viršytas partijos dydžio apribojimas [2–99]