Documentazione API REST

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

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