REST API dokumentācija

VIES API REST dokumentācija

Ievads

Mūsu nodrošinātā API izmanto standarta HTTP protokolu. Visas API funkcijas izmanto HTTP GET metodi. Katrai funkcijas izsaukšanai ir nepieciešama vaicājuma autorizācija. Dati vaicājuma autorizācijai tiek nosūtīti HTTP galvenē.

Ražošanas serviss

Nepieciešama subjekta reģistrācija, kas vēlas izmantot sistēmas viesapi.eu funkcionalitāti. Lai to izdarītu, dodieties uz Reģistrācija lapu un aizpildiet atbilstošo veidlapu. Viesapi.eu sistēmas lietošanas priekšnoteikums ir akcepts Pakalpojuma noteikumi. Pareizi aizpildot veidlapu un noklikšķinot uz Reģistrēties pogu izveidos kontu viesapi.eu sistēmā un tā automātisku aktivizāciju.

Piesakoties pirmo reizi, kopā ar atbilstošo atslēgu automātiski tiek ģenerēts identifikators. Identifikators ir publisks un tam nav nepieciešama aizsardzība, savukārt atslēga ir privāta, un to nevajadzētu darīt pieejamu trešajām personām.

Ražošanas dienesta adrese: https://viesapi.eu/api

Testa serviss

Visu koplietoto bibliotēku pilnu funkcionalitāti var pārbaudīt, izmantojot koplietoto Pārbaudiet VIES API. Izmantojot testa API, iespējams pārbaudīt visas maksas plānos piedāvātās funkcijas bez nepieciešamības izveidot kontu.

Testa servisa adrese: https://viesapi.eu/api-test

API saskarnes definīcija

Detalizēta API definīcija ir pieejama ar OpenAPI saderīgā formātā, un to var lejupielādēt kā YAML failu šeit.

API ir pieejama arī kā klienta saskarne Swagger UI.

Vaicājuma izpilde

Piemērs vaicājuma veikšanai testa vietnei:

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 atslēgas identifikators (ražošanas vidē reģistrācijas laikā ģenerētā identifikatora vērtība, testa vidē test_id vērtība),
  • unix_timestamp – pašreizējais laiks sekunžu skaita veidā no tā sauktā unix laikmets,
  • random_str – nejauša virkne, katram vaicājumam atšķirīga (min. 8 rakstzīmes, ne vairāk kā 16 rakstzīmes),
  • b64_calculated_mac_value - aprēķinātais HMAC (izmantojot API key, vērtība test_key testa vidē),
  • client_version – klienta versija (mūsu bibliotēkās tā ir mūsu API bibliotēkas versija, piemēram, 1.2.3),
  • platform_name – API klienta platformas nosaukums (mūsu bibliotēkās tas ir bibliotēkas valodas nosaukums, piemēram, JAVA, PHP, .NET, Python),
  • platform_version – API klienta platformas versija (mūsu bibliotēkās tā ir bibliotēkas vides versija, piemēram, 17 JAVA vai 7.4 PHP),
  • mime_type – MIME tipa nosaukums, kurā jāatgriež atbilde, tiek atbalstīti divi veidi: text/xml un application/json, ja pieprasījums nesatur Accept galvenes, XML tiek atgriezts pēc noklusējuma.

Autentifikācijas pieprasījums

Autorizācijas dati jāsagatavo saskaņā ar HTTP autentifikācija: MAC piekļuves autentifikācija un šī ir ieteicamā autentifikācijas metode. Ir iespējams arī izmantot HTTP autentifikācija: pamata autentifikācija metodi, tomēr drošības apsvērumu dēļ, lūdzu, izmantojiet to tikai tad, ja pirmās metodes izmantošana kādu iemeslu dēļ nav iespējama.

Katrs vaicājums mūsu tīmekļa vietnē ir jāautentificē, izmantojot vienu no divām pieejamām metodēm.

1. metode — HMAC (ieteicams)

Izmantotās autorizācijas metodes specifikācija: HTTP autentifikācija: MAC piekļuves autentifikācija. Autorizācija sastāv no HMAC SHA256 aprēķināšanas no pareizi sagatavotas virknes un rezultāta nosūtīšanas HTTP galvenē.

Piemērs

HMAC funkcijas ievades virkne ir:
ts + '\n' + nonce + '\n' + method + '\n' + path + '\n' + host + '\n' + port + '\n\n'

Kur:

  • ts – pašreizējais laiks sekunžu skaita veidā no tā sauktā unix laikmets, vienmēr ir jānorāda pašreizējais vaicājuma izpildes laiks (servera pielaide +/- 10 min attiecībā pret pašreizējo laiku),
  • nonce – nejauša virkne, katram vaicājumam atšķirīga (min. 8 rakstzīmes, ne vairāk kā 16 rakstzīmes),
  • method - HTTP metodes nosaukums (vienmēr GET),
  • path - izpildāmā vaicājuma URL ceļš,
  • host - VIES API servera nosaukums (vienmēr viesapi.eu),
  • port - VIES API servera porta numurs (vienmēr 443),
  • ’\n’ – jaunrindas rakstzīme (ASCII kods 10, 0x0A).

Vaicājumam par PVN numuru PL7171642051, kas nosūtīts testa dienestam 2019-11-25 00:00:00 UTC, HMAC funkcijas ievades virkne izskatīsies šādi:
str = "1574640000\ndt831hs59s\nGET\n/api-test/get/vies/euvat/PL7171642051\nviesapi.eu\n443\n\n"

Šī piemēra ievades virknes failu var lejupielādēt šeit.

No sagatavotās virknes mēs aprēķinām HMAC SHA256, kā HMAC paroli mēs piešķiram API key, ti, testa API gadījumā vērtība test_key:

HMAC_SHA256(str, "test_key") = 7776a12b958233ce60dd0f16b8d141e80472a1ee3b1e1fb136d7abe34cb59306

Funkcija HMAC SHA256 atgriež 32 bināros baitus (iepriekš parādīts kā a hex virkne lasāmībai). Lejupielādēt failu ar bināro vērtību šeit.

Aprēķinātā HMAC binārā vērtība jākodē ar Base64 algoritmu, mēs iegūstam:

d3ahK5WCM85g3Q8WuNFB6ARyoe47Hh+xNter40y1kwY=

Šī vērtība ir jānosūta kā MAC vērtība galvenē ar datiem autorizācijai. Visbeidzot:

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

Linux mašīnā nepieciešamo MAC vērtību var aprēķināt vienā solī, izmantojot šo komandu:

$ 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. metode – pamata autentifikācija

Šīs izmantotās autorizācijas metodes specifikācija: HTTP autentifikācija: pamata autentifikācija.

1. piemērs

Funkcijas Base64 ievades virkne ir:

str = key_id + ':' + key

Kur:

  • key_id – API atslēgas identifikators (testa vides gadījumā, test_id virkne),
  • key – API atslēga (testa vides gadījumā virkne test_key).

Testa vidē Base64 funkcijas ievades virkne būs:

str = "test_id:test_key"

Pēc funkcijas Base64 lietošanas mēs iegūstam:

Base64(str) = dGVzdF9pZDp0ZXN0X2tleQ==

Šī vērtība ir jānosūta kā pamata vērtība galvenē ar datiem autorizācijai. Galu galā:

Authorization: Basic dGVzdF9pZDp0ZXN0X2tleQ==

2. piemērs

Nākamajā piemērā ir parādīts vaicājums, ko var izsaukt testa vidē no tīmekļa pārlūkprogrammas. Vienkārši nokopējiet un ielīmējiet to pārlūkprogrammas adreses joslā:

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

Kur:

  • test_id – autentificēties iestudējumā vidi, parametram ir jāietver derīgs atslēgas identifikators, ko izmanto autorizācijai,
  • test_key – autentificēties iestudējumā vidē, parametram ir jāietver derīga autorizācijai izmantotās atslēgas vērtība.

Atslēgas identifikatoru un atslēgu ģenerē lietotājs pēc pieteikšanās savā kontā vietnē viesapi.eu portāls (API keys cilne). See dokumentācija lapā, lai iegūtu papildinformāciju par ID un atslēgu ģenerēšanu.

Atbilde

Ja pieprasījums tiek apstrādāts pareizi, tiek ģenerēta šāda atbilde:

Detalizēts atgriezto atribūtu apraksts:

  • uid – unikāls vaicājuma identifikators, ko ģenerē viesapi.eu,
  • countryCode – valsts kods, kurā reģistrēts uzņēmums, kas saistīts ar aptaujā norādīto ES PVN maksātāja numuru,
  • vatNumber – vaicājumā norādītā pārbaudītā uzņēmuma ES PVN maksātāja numurs,
  • valid – atbilde no VIES dienesta, informējot par pārbaudāmās vienības pašreizējo ES PVN statusu:
    • true – pieprasījumā norādītais ES PVN maksātāja numurs ir derīgs,
    • false – pieprasījumā norādītais ES PVN maksātāja numurs nav derīgs,
  • traderName - uzņēmuma tirdzniecības nosaukums,
  • traderCompanyType - vienmēr atgrieza "-" rakstzīmju virkni,
  • traderAddress - uzņēmuma adrese, kurā uzņēmums reģistrēts,
  • id – unikāls vaicājuma identifikators, ko ģenerē VIES sistēma
  • date - vaicājuma izpildes datums
  • source — datu avots, vienmēr: http://ec.europa.eu

Kļūdas atbilde

Ja rodas kļūda, kas saistīta ar pieprasījuma apstrādi, tiek atgriezts šāds kļūdas ziņojums:

Kļūda

Detalizēts atgriezto atribūtu apraksts:

  • code - unikāls kļūdas kods automātiskai kļūdu apstrādei,
  • description – cilvēka pārtverams kļūdas apraksts,
  • details – mdetalizēts kļūdas apraksts (pēc izvēles),

Kļūdu kodi

Tālāk esošajā tabulā ir uzskaitītas visas iespējamās kļūdas, ko atgriež REST API un programmēšanas bibliotēkas.

Kļūdas kods Kļūdas ziņojums
8 Nederīgs pieprasījuma formāts
10 Nederīgs API ceļš
11 Iekšējā pakalpojuma kļūda
22 ES PVN numurs nav derīgs
23 Neizdevās iegūt datus no VIES sistēmas
26 Šī funkcija pašlaik atlasītajā plānā nav pieejama
27 Šī funkcija neatbalsta šo meklēšanas režīmu
33 Doto datu vaicāšana testa režīmā nav iespējama
35 Nav nepieciešama piekļuves vaicājuma autorizācija
36 Pakalpojums īslaicīgi nav pieejams plānoto tehnisko darbu dēļ
43 Pašreizējā mēneša lietotāju vaicājumu skaitu nevarēja izgūt
54 Nepareizs datums vai laiks lietotāja datorā vai sistēmā
55 Nederīga MAC virknes vērtība galvenē ar vaicājuma akreditācijas datiem
57 Nederīga atslēgas vērtība galvenē ar vaicājuma akreditācijas datiem
58 Ir sasniegts maksimālais vienlaicīgo vaicājumu skaits šai dalībvalstij
59 Dalībvalsts pieteikums neatbild vai nav pieejams
101 Savienojuma IP numurs neatbilst API atslēgai piešķirtajam IP numuram
102 API atslēga ir bloķēta
103 Nederīga API atslēga
104 Ir sasniegts atlasītajam plānam pieejamais maksimālais vaicājumu skaits
105 Konts ir bloķēts vai izdzēsts
106 Nederīgs konta veids
107 Priekšapmaksas konts nav apmaksāts
108 Nederīgs API atslēgas ID
201 Neizdevās izveidot savienojumu ar VIES API pakalpojumu
202 VIES API pakalpojuma atbildei ir nederīgs formāts
203 Nederīgs numura veids
204 NIP nav derīgs
205 ES PVN ID nav derīgs
206 Funkcija radīja izņēmumu
207 Datumam ir nederīgs formāts
208 Nederīgs ievades parametrs