Documentația REST API

Documentația VIES API REST

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
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

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),
  • mime_type – Numele tipului MIME în care trebuie returnat răspunsul, sunt acceptate două tipuri: text/xml și application/json, dacă cererea nu conține antetul Accept, XML este returnat implicit.

Cerere de autentificare

Datele de autorizare trebuie pregătite în conformitate cu Autentificare HTTP: Autentificare acces MAC și aceasta este metoda de autentificare recomandată. De asemenea, este posibil să utilizați Autentificare HTTP: Autentificare de bază Cu toate acestea, din motive de securitate, vă rugăm să o utilizați numai atunci când utilizarea primei metode nu este posibilă dintr-un motiv oarecare.

Fiecare interogare către site-ul nostru trebuie să fie autentificată folosind una dintre cele două metode disponibile.

Metoda 1 – HMAC (recomandat)

Specificarea metodei de autorizare utilizată: Autentificare HTTP: Autentificare acces MAC. 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=

Această valoare ar trebui trimisă ca valoare MAC în antet cu date pentru autorizare. In cele din urma:

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

Pe mașina Linux, valoarea MAC necesară poate fi calculată într-un singur pas folosind această comandă:

$ 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

Metoda 2 – Autentificarea de bază

Specificarea acestei metode de autorizare utilizată: Autentificare HTTP: Autentificare de bază.

Exemplul 1

Șirul de intrare în funcția Base64 este:

str = key_id + ':' + key

Unde:

  • key_id – identificatorul cheii API (în cazul unui mediu de testare, test_id şir),
  • key – cheie API (în cazul unui mediu de testare, șir test_key).

Pentru mediul de testare, șirul de intrare pentru funcția Base64 va fi:

str = "test_id:test_key"

După aplicarea funcției Base64, obținem:

Base64(str) = dGVzdF9pZDp0ZXN0X2tleQ==

Această valoare trebuie trimisă ca valoare de bază în antet cu date pentru autorizare. Pana la urma:

Authorization: Basic dGVzdF9pZDp0ZXN0X2tleQ==

Exemplul 2

Următorul exemplu arată o interogare care poate fi invocată într-un mediu de testare dintr-un browser web. Doar copiați și inserați-l în bara de adrese a browserului:

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

Unde:

  • test_id – a se autentifica într-o producție mediu inconjurator, parametrul ar trebui să conțină un identificator de cheie valid utilizat pentru autorizare,
  • test_key – a se autentifica într-o producție mediu, parametrul ar trebui să conțină o valoare validă a cheii utilizate pentru autorizare.

Identificatorul cheii și cheia sunt generate de utilizator după conectarea la contul său de pe viesapi.eu portal (API keys fila). See the documentație pagina pentru mai multe informații despre ID-ul și generarea cheilor.

Raspuns

Dacă cererea este tratată corect, se generează următorul răspuns:

Descrierea detaliată a atributelor returnate:

  • uid – identificatorul unic de interogare generat de viesapi.eu,
  • countryCode – codul țării în care este înregistrată societatea asociată cu numărul de TVA UE furnizat în anchetă,
  • vatNumber – Numărul de TVA UE al companiei verificate furnizat în anchetă,
  • valid – răspuns din partea serviciului VIES, care informează cu privire la statutul actual de TVA UE al entității verificate:
    • true – numărul de TVA al UE furnizat în cerere este valabil,
    • false – numărul de TVA al UE furnizat în cerere nu este valid,
  • traderName – denumirea comercială a companiei,
  • traderCompanyType – a returnat întotdeauna un șir de caractere „-”,
  • traderAddress – adresa firmei la care este înregistrată societatea,
  • id – identificatorul unic de interogare generat de sistemul VIES
  • date – data executării interogării
  • source – sursa de date, întotdeauna: http://ec.europa.eu

Răspuns de eroare

În cazul oricărei erori legate de tratarea cererii, este returnat următorul mesaj de eroare:

Eroare

Descrierea detaliată a atributelor returnate:

  • code – cod unic de eroare pentru tratarea automată a erorilor,
  • description – descrierea erorilor interceptabile de om,
  • details – msau descrierea detaliată a erorii (opțional),

Coduri de eroare

Tabelul de mai jos listează toate erorile posibile returnate de API-urile REST și bibliotecile de programare:

Cod de eroare Mesaj de eroare
8 Format de solicitare nevalid
10 Cale API nevalidă
11 Eroare de serviciu intern
22 Numărul de TVA al UE este invalid
23 Nu s-au putut obține date din sistemul VIES
26 Această funcție nu este disponibilă în planul selectat în prezent
27 Această funcție nu acceptă acest mod de căutare
33 Interogarea datelor date nu este posibilă în modul de testare
35 Nu este necesară autorizarea de interogare de acces
36 Serviciul este temporar indisponibil din cauza lucrărilor tehnice programate
43 Numărul de interogări ale utilizatorilor pentru luna curentă nu a putut fi preluat
54 Data sau ora incorectă pe computerul sau sistemul utilizatorului
55 Valoarea șirului MAC nevalidă în antet cu acreditările de interogare
57 Valoare cheie nevalidă în antetul cu acreditările de interogare
58 Numărul maxim de interogări simultane pentru acest stat membru a fost atins
59 Cererea din statul membru nu răspunde sau nu este disponibilă
101 Numărul IP al conexiunii nu se potrivește cu numărul IP alocat cheii API
102 Cheia API este blocată
103 Cheie API nevalidă
104 Numărul maxim de interogări disponibile pentru planul selectat a fost atins
105 Cont blocat sau șters
106 Tip de cont nevalid
107 Contul preplătit nu a fost plătit
108 ID cheie API nevalid
201 Nu s-a putut conecta la serviciul API VIES
202 Răspunsul serviciului API VIES are un format nevalid
203 Tip de număr nevalid
204 NIP este invalid
205 ID de TVA UE este nevalid
206 Funcția a generat o excepție
207 Data are un format nevalid
208 Parametru de intrare nevalid