REST API 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
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 (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).

Visas vietnes sniegtās atbildes ir XML formātā.

Autentifikācijas pieprasījums

Izmantotās autorizācijas metodes specifikācija: HTTP autentifikācija: MAC piekļuves autentifikācija. Katrs mūsu vietnes vaicājums ir jāautentificē, izmantojot šo metodi. 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