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
Raidījums: viesapi.eu:443
Autorizācija: MAC id="api_key_id", ts="unix_timestamp", nonce="random_str", mac="b64_calculated_mac_value"
Lietotāja aģents: VIESAPIClient/client_version platformas_nosaukums/platformas_versija
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 (izmantojotAPI key
, vērtībatest_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).
Visas vietnes sniegtās atbildes ir XML formātā.
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ērviesapi.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 = atslēgas_id + ':' + taustiņš
Kur:
key_id
– API atslēgas identifikators (testa vides gadījumā,test_id
virkne),key
– API atslēga (testa vides gadījumā virknetest_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ā:
Autorizācija: pamata 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ēmadate
- vaicājuma izpildes datumssource
— 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:
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),