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
Specifica del metodo di autorizzazione utilizzato: Autenticazione HTTP: Autenticazione accesso MAC. Ogni richiesta al nostro sito Web deve essere autenticata utilizzando questo metodo. 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