Documentația REST API

Introducere

API-ul furnizat de noi utilizează protocolul standard HTTP. Toate funcțiile API folosesc metoda HTTP GET. Fiecare apel de funcție necesită autorizare de interogare. Datele pentru autorizarea interogării sunt trimise în antetul HTTP.

Serviciu de productie

Este necesară înregistrarea unei entități care dorește să folosească funcționalitatea sistemului viesapi.eu. Pentru a face acest lucru, mergeți la Înregistrare pagina și completați formularul corespunzător. Condiția prealabilă pentru utilizarea sistemului viesapi.eu este acceptarea Termenii serviciului. Completarea corectă a formularului și făcând clic pe Inregistreaza-te butonul va crea un cont în sistemul viesapi.eu și va activa automat.

Când vă conectați pentru prima dată, un identificator este generat automat împreună cu cheia corespunzătoare. Identificatorul este public și nu necesită protecție, în timp ce cheia este privată și nu ar trebui să fie pusă la dispoziția terților.

Adresa serviciului de productie: https://viesapi.eu/api

Serviciu de testare

Funcționalitatea completă a tuturor bibliotecilor partajate poate fi verificată folosind partajarea Testați API-ul VIES. Prin utilizarea API-ului de testare, este posibil să verificați toate funcțiile oferite în planurile plătite fără a fi nevoie să creați un cont.

Adresa serviciului de testare: https://viesapi.eu/api-test

Definirea interfeței API

O definiție detaliată a API-ului este disponibilă într-un format compatibil OpenAPI și poate fi descărcată ca fișier YAML Aici.

API-ul este disponibil și ca interfață client Swagger UI.

Executarea interogării

Un exemplu de efectuare a unei interogări către site-ul de testare:

GET /api-test/get/vies/euvat/PL7171642051 HTTP/1.1
Gazdă: viesapi.eu:443
Autorizare: 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

Unde:

  • api_key_id – identificatorul cheii API (pe mediul de producție, valoarea identificatorului generat în timpul înregistrării, pe mediul de testare, valoarea test_id),
  • unix_timestamp – timpul curent sub forma unui număr de secunde de la așa-numitul epoca unix,
  • random_str – șir aleator, diferit pentru fiecare interogare (min. 8 caractere, max. 16 caractere),
  • b64_calculated_mac_value – HMAC calculat (folosind un API key, valoare test_key pe mediul de testare),
  • client_version – versiunea client (în bibliotecile noastre este versiunea bibliotecii noastre API, de exemplu 1.2.3),
  • platform_name – numele platformei client API (în bibliotecile noastre este numele limbajului bibliotecii, de exemplu JAVA, PHP, .NET, Python),
  • platform_version – Versiunea platformei client API (în bibliotecile noastre este versiunea mediului de bibliotecă, de exemplu 17 pentru JAVA, sau 7.4 pentru PHP).

Toate răspunsurile returnate de site-ul web sunt în format XML.

Cerere de autentificare

Specificarea metodei de autorizare utilizată: Autentificare HTTP: Autentificare acces MAC. Fiecare interogare către site-ul nostru trebuie să fie autentificată folosind această metodă. Autorizarea constă în calcularea HMAC SHA256 dintr-un șir pregătit corespunzător și trimiterea rezultatului în antetul HTTP.

Exemplu

Șirul de intrare în funcția HMAC este:
ts + '\n' + nonce + '\n' + method + '\n' + path + '\n' + host + '\n' + port + '\n\n'

Unde:

  • ts – timpul curent sub forma unui număr de secunde de la așa-numitul epoca unix, ar trebui să furnizați întotdeauna timpul curent de execuție a interogării (toleranța serverului +/- 10 min în raport cu ora curentă),
  • nonce – șir aleator, diferit pentru fiecare interogare (min. 8 caractere, max. 16 caractere),
  • method – Numele metodei HTTP (întotdeauna GET),
  • path – calea URL a interogării care urmează să fie executată,
  • host – Numele serverului API VIES (întotdeauna viesapi.eu),
  • port – Numărul portului serverului API VIES (întotdeauna 443),
  • ’\n’ – caracter newline (cod ASCII 10, 0x0A).

Pentru interogarea pentru numărul de TVA PL7171642051 trimisă serviciului de testare pe 2019-11-25 00:00:00 UTC, șirul de intrare în funcția HMAC va arăta astfel:
str = "1574640000\ndt831hs59s\nGET\n/api-test/get/vies/euvat/PL7171642051\nviesapi.eu\n443\n\n"

Fișierul șir de intrare pentru acest exemplu poate fi descărcat Aici.

Din șirul pregătit, calculăm HMAC SHA256, ca parolă HMAC o dăm API key, adică în cazul testului API, valoarea lui test_key:

HMAC_SHA256(str, "test_key") = 7776a12b958233ce60dd0f16b8d141e80472a1ee3b1e1fb136d7abe34cb59306

Funcția HMAC SHA256 returnează 32 de octeți binari (prezentați mai sus ca a hex șir pentru lizibilitate). Descărcați fișierul cu valoare binară Aici.

Valoarea binară a HMAC calculat ar trebui să fie codificată cu algoritmul Base64, obținem:

d3ahK5WCM85g3Q8WuNFB6ARyoe47Hh+xNter40y1kwY=

This value should be sent as MAC value in the header with data for authorization. Finally:

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

On Linux machine required MAC value can be calculated in one step using this command:

$ 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