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:
OTTIENI /api-test/get/vies/euvat/PL7171642051 HTTP/1.1
Host: viesapi.eu:443
Autorizzazione: MAC id="api_key_id", ts="unix_timestamp", nonce="random_str", mac="b64_calculated_mac_value"
Agente utente: VIESAPIClient/versione_client nome_piattaforma/versione_piattaforma
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 fileAPI key
, valoretest_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).
Tutte le risposte restituite dal sito Web sono in formato 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 (sempreviesapi.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 + ':' + chiave
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, stringtest_key
).
Per l'ambiente di test, la stringa di input per la funzione Base64 sarà:
str = "id_test:chiave_test"
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:
Autorizzazione: Base 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 VIESdate
– data di esecuzione della querysource
– 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:
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),