Documentazione API REST

Documentazione REST dell'API VIES

introduzione

L'API da noi fornita utilizza il protocollo HTTP standard. Tutte le funzioni API utilizzano il metodo HTTP GET. Ogni chiamata di funzione richiede l'autorizzazione alla query. I dati per l'autorizzazione alla query vengono inviati nell'intestazione HTTP.

Servizio di produzione

È richiesta la registrazione di un soggetto che voglia utilizzare le funzionalità del sistema viesapi.eu. Per fare ciò, vai su Registrazione pagina e compilare l'apposito modulo. Il presupposto per l'utilizzo del sistema viesapi.eu è l'accettazione del Termini di servizio. Compilando correttamente il form e cliccando su Registrati creerà un account nel sistema viesapi.eu e la sua attivazione automatica.

Al primo accesso viene generato automaticamente un identificatore insieme alla chiave corrispondente. L'identificatore è pubblico e non richiede protezione, mentre la chiave è privata e non deve essere resa disponibile a terzi.

Indirizzo del servizio di produzione: https://viesapi.eu/api

Servizio di prova

La piena funzionalità di tutte le librerie condivise può essere verificata utilizzando la condivisione Prova l'API VIES. Utilizzando l'API di test, è possibile verificare tutte le funzioni offerte nei piani a pagamento senza la necessità di creare un account.

Indirizzo del servizio di prova: https://viesapi.eu/api-test

Definizione interfaccia API

Una definizione dettagliata dell'API è disponibile in un formato compatibile con OpenAPI e può essere scaricata come file YAML qui.

L'API è disponibile anche come interfaccia client Interfaccia utente spavalda.

Esecuzione della query

Un esempio di esecuzione di una query al sito di test:

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

Dove:

  • api_key_id – Identificatore chiave API (sull'ambiente di produzione, il valore dell'identificatore generato in fase di registrazione, sull'ambiente di test, il valore di test_id),
  • unix_timestamp – l'ora corrente sotto forma di un numero di secondi dal cosiddetto epoca unix,
  • random_str – stringa casuale, diversa per ogni query (min. 8 caratteri, max. 16 caratteri),
  • b64_calculated_mac_value – HMAC calcolato (utilizzando un file API key, valore test_key sull'ambiente di prova),
  • client_version – versione client (nelle nostre librerie è la versione della nostra libreria API, es. 1.2.3),
  • platform_name – il nome della piattaforma client API (nelle nostre librerie è il nome del linguaggio della libreria, es. JAVA, PHP, .NET, Python),
  • platform_version – Versione della piattaforma client API (nelle nostre librerie è la versione dell'ambiente della libreria, ad esempio 17 per JAVA, o 7.4 per PHP),
  • mime_type – Nome del tipo MIME in cui deve essere restituita la risposta, sono supportati due tipi: text/xml e application/json, se la richiesta non contiene l'intestazione Accept, per impostazione predefinita viene restituito XML.

Richiesta di autenticazione

I dati di autorizzazione devono essere preparati in conformità con Autenticazione HTTP: Autenticazione accesso MAC e questo è il metodo di autenticazione consigliato. È anche possibile utilizzare il Autenticazione HTTP: autenticazione di base metodo, tuttavia per motivi di sicurezza, utilizzalo solo quando l'utilizzo del primo metodo non è possibile per qualche motivo.

Ogni query al nostro sito Web deve essere autenticata utilizzando uno dei due metodi disponibili.

Metodo 1 – HMAC (consigliato)

Specifica del metodo di autorizzazione utilizzato: Autenticazione HTTP: Autenticazione accesso MAC. L'autorizzazione consiste nel calcolare l'HMAC SHA256 da una stringa opportunamente preparata e inviare il risultato nell'intestazione HTTP.

Esempio

La stringa di input per la funzione HMAC è:
ts + '\n' + nonce + '\n' + method + '\n' + path + '\n' + host + '\n' + port + '\n\n'

Dove:

  • ts – l'ora corrente sotto forma di un numero di secondi dal cosiddetto epoca unix, dovresti sempre fornire il tempo di esecuzione della query corrente (tolleranza del server +/- 10 min rispetto all'ora corrente),
  • nonce – stringa casuale, diversa per ogni query (min. 8 caratteri, max. 16 caratteri),
  • method – Nome del metodo HTTP (sempre GET),
  • path – Percorso URL della query da eseguire,
  • host – Nome del server VIES API (sempre viesapi.eu),
  • port – Numero di porta del server VIES API (sempre 443),
  • ’\n’ – carattere di nuova riga (codice ASCII 10, 0x0A).

Per la query per il numero di partita IVA PL7171642051 inviata al servizio di test il 25-11-2019 00:00:00 UTC, la stringa di input per la funzione HMAC sarà simile a questa:
str = "1574640000\ndt831hs59s\nGET\n/api-test/get/vies/euvat/PL7171642051\nviesapi.eu\n443\n\n"

È possibile scaricare il file della stringa di input per questo esempio qui.

Dalla stringa preparata, calcoliamo HMAC SHA256, come password HMAC diamo il API key, ovvero nel caso dell'API di test, il valore di test_key:

HMAC_SHA256(str, "test_key") = 7776a12b958233ce60dd0f16b8d141e80472a1ee3b1e1fb136d7abe34cb59306

La funzione HMAC SHA256 restituisce 32 byte binari (mostrati sopra come a hex stringa per leggibilità). Scarica il file con valore binario qui.

Il valore binario dell'HMAC calcolato dovrebbe essere codificato con l'algoritmo Base64, otteniamo:

d3ahK5WCM85g3Q8WuNFB6ARyoe47Hh+xNter40y1kwY=

Questo valore deve essere inviato come valore MAC nell'intestazione con i dati per l'autorizzazione. Finalmente:

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

Sulla macchina Linux il valore MAC richiesto può essere calcolato in un solo passaggio utilizzando questo comando:

$ 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

Metodo 2 – Autenticazione di base

Specifica di questo metodo di autorizzazione utilizzato: Autenticazione HTTP: autenticazione di base.

Esempio 1

La stringa di input per la funzione Base64 è:

str = key_id + ':' + key

Dove:

  • key_id – Identificatore della chiave API (nel caso di un ambiente di test, test_id corda),
  • key – API key (nel caso di un ambiente di test, string test_key).

Per l'ambiente di test, la stringa di input per la funzione Base64 sarà:

str = "test_id:test_key"

Dopo aver applicato la funzione Base64, otteniamo:

Base64(str) = dGVzdF9pZDp0ZXN0X2tleQ==

Questo valore deve essere inviato come valore di base nell'intestazione con i dati per l'autorizzazione. In definitiva:

Authorization: Basic dGVzdF9pZDp0ZXN0X2tleQ==

Esempio 2

L'esempio seguente mostra una query che può essere richiamata in un ambiente di test da un Web browser. Basta copiarlo e incollarlo nella barra degli indirizzi del browser:

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

Dove:

  • test_id – per autenticare in una produzione ambiente, il parametro deve contenere un identificatore di chiave valido utilizzato per l'autorizzazione,
  • test_key – per autenticare in una produzione environment, il parametro deve contenere un valore valido della chiave utilizzata per l'autorizzazione.

L'identificatore della chiave e la chiave vengono generati dall'utente dopo aver effettuato l'accesso al proprio account su viesapi.eu portale (API keys scheda). Sehi il documentazione pagina per ulteriori informazioni su ID e generazione di chiavi.

Risposta

Se la richiesta viene gestita correttamente, viene generata la seguente risposta:

Descrizione dettagliata degli attributi restituiti:

  • uid – identificatore di query univoco generato da viesapi.eu,
  • countryCode – codice paese in cui è registrata la società associata alla partita IVA UE fornita nella richiesta,
  • vatNumber – Partita IVA UE della società verificata fornita nella richiesta,
  • valid – risposta dal servizio VIES, che informa sullo stato attuale dell'IVA UE dell'entità controllata:
    • true – il numero di partita IVA UE fornito nella richiesta è valido,
    • false – il numero di partita IVA UE fornito nella richiesta non è valido,
  • traderName – nome commerciale dell'azienda,
  • traderCompanyType – restituiva sempre una stringa di caratteri '-',
  • traderAddress – indirizzo della società in cui è registrata la società,
  • id – identificatore univoco della query generato dal sistema VIES
  • date – data di esecuzione della query
  • source – fonte dati, sempre: http://ec.europa.eu

Risposta di errore

In caso di qualsiasi errore relativo alla gestione della richiesta, viene restituito il seguente messaggio di errore:

Errore

Descrizione dettagliata degli attributi restituiti:

  • code – codice di errore univoco per la gestione automatica degli errori,
  • description – descrizione dell'errore intercettabile dall'uomo,
  • details - Mo descrizione dettagliata dell'errore (facoltativo),

Codici di errore

Nella tabella seguente sono elencati tutti i possibili errori restituiti dalle API REST e dalle librerie di programmazione:

Codice di errore Messaggio di errore
8 Formato di richiesta non valido
10 Percorso API non valido
11 Errore di servizio interno
22 Il numero di partita IVA UE non è valido
23 Impossibile ottenere i dati dal sistema VIES
26 Questa funzionalità non è disponibile sul piano attualmente selezionato
27 Questa funzione non supporta questa modalità di ricerca
33 La query dei dati forniti non è possibile nella modalità di test
35 Nessuna autorizzazione di query di accesso richiesta
36 Il servizio è temporaneamente non disponibile a causa di lavori tecnici programmati
43 Non è stato possibile recuperare il numero di query degli utenti per il mese corrente
54 Data o ora non corrette sul computer o sul sistema dell'utente
55 Valore stringa MAC non valido nell'intestazione con credenziali di query
57 Valore chiave non valido nell'intestazione con credenziali di query
58 È stato raggiunto il numero massimo di query contemporanee per questo Stato membro
59 La domanda presso lo Stato membro non risponde o non è disponibile
101 Il numero IP della connessione non corrisponde al numero IP assegnato alla chiave API
102 La chiave API è bloccata
103 Chiave API non valida
104 È stato raggiunto il numero massimo di query disponibili per il piano selezionato
105 Account bloccato o eliminato
106 Tipo di account non valido
107 Il conto prepagato non è stato pagato
108 ID chiave API non valido
201 Impossibile connettersi al servizio API VIES
202 La risposta del servizio API VIES ha un formato non valido
203 Tipo di numero non valido
204 NIP non è valido
205 La partita IVA UE non è valida
206 La funzione ha generato un'eccezione
207 La data ha un formato non valido
208 Parametro di input non valido