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

getVIESData răspuns

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

vies api - getVIESDataParsed

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 (format original),
  • traderAddressComponent – detalii despre adresa de grupare a componentelor – atribut opțional, nu va fi returnat niciodată în această funcție.
  • id – identificatorul unic de interogare generat de sistemul VIES (Numărul de consultare),
  • date – data executării interogării
  • source – sursa de date, întotdeauna: http://ec.europa.eu

getVIESDataParsed răspuns

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

vies api - getVIESDataParsed

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 (format original),
  • traderAddressComponent – detaliile adresei grupării componentelor
    • country – numele țării comerciant în limba sa națională
    • postalCode – codul poștal al adresei comerciantului
    • city – orasul adresa comerciantului
    • street -strada adresei comerciantului
    • streetNumber – numărul stradal al adresei comerciantului
    • houseNumber – numarul locuintei adresei comerciantului
  • id – identificatorul unic de interogare generat de sistemul VIES (Numărul de consultare),
  • date – data executării interogării,
  • source – sursa de date, întotdeauna: http://ec.europa.eu

Disclaimer important!

Funcția de analiză folosește algoritmi externi AI și API-uri pentru a extrage automat atribute precum: orașul, codul poștal, strada cu numărul străzii (numărul clădirii) și numărul casei, așa că nu putem garanta funcționarea corectă a lui 100%.

getVIESDataAsync răspuns

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

Răspunsul VIES API getVIESDataAsync

Descrierea detaliată a atributelor returnate:

  • token – batch token (ghid) generat de viesapi.eu, ar trebui folosit pentru a apela funcția getVIESDataAsync (după 2-3 minute) pentru a obține rezultate.

getVIESDataAsyncResult răspuns

Dacă cererea este tratată corect, trebuie generat următorul răspuns, care să conțină o listă de obiecte cu date returnate de VIES:

vies api getVIESDataAsyncResults

Descrierea detaliată a atributelor returnate:

  • numbers – o serie de obiecte cu rezultate returnate de VIES corespunzătoare numerelor de TVA UE trimise în cererea de apelare a funcției getVIESDataAsync
    • 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 (format original),
    • id – identificatorul unic de interogare generat de sistemul VIES (Numărul de consultare),
    • date – data executării interogării
    • source – sursa de date, întotdeauna: http://ec.europa.eu
  • errors – matrice de obiecte cu erori returnate de VIES pentru datele privind numărul de TVA UE trimise în cererea de apelare a funcției getVIESDataAsync
    • 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ă,
    • error – detalii despre eroarea returnată pentru acest număr specific de TVA UE
    • 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:

Vies rest api error response

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ă
62 Lotul este încă în procesare, încercați din nou târziu
63 Numărul maxim de solicitări de lot a fost atins, vă rugăm să retrimiteți cererea mai târziu
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
209 Limita de dimensiune a lotului a fost depășită [2-99]