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:

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