Librerie di programmazione VIES
Le biblioteche di programmazione consentono di cercare i dati degli imprenditori in base al numero di partita IVA UE inserito. Attualmente, le librerie API sono disponibili per i seguenti linguaggi di programmazione:
- .NET (C#, Visual Basic)
- Giava
- JavaScript (Node.js)
- PHP
- Pitone
- C/C++
L'API fornisce le seguenti funzionalità:
getVIESData
– funzione per confermare l'attività della partita IVA UE assegnata da uno qualsiasi degli Stati membri dell'Unione Europea,getVIESDataParsed
– funzione per confermare l'attività del numero di partita IVA UE assegnato da uno qualsiasi degli Stati membri dell'Unione Europea e restituire l'indirizzo del commerciante analizzato,getVIESDataAsync
– funzione asincrona che, in base al lotto di numeri IVA inviati, consente di ottenere lo stato attuale dell’IVA UE e i dati del commerciante.getVIESDataAsyncResult
– la funzione consente di recuperare i risultati batch in base al token restituito dalla funzione getVIESDataAsyncgetAccountStatus
– funzione per recuperare informazioni aggiornate sull’account utente.
Integrazione
Tutte le librerie con i codici sorgente sono disponibili per il download su Scarica pagina. Inoltre, il codice sorgente per le librerie è disponibile anche nel nostro repository ufficiale su Github.
La modalità di integrazione della libreria dipende dal linguaggio di programmazione selezionato. Per quei linguaggi che supportano la gestione delle librerie basata su un repository centrale, è possibile utilizzarlo.
- C#
- C/C++
- Giava
- JavaScript
- PHP
- Pitone
- Visual Basic
// NuGet Gallery
// https://www.nuget.org/packages/VIESAPI.VIESAPIClient
PM> Install-Package VIESAPI.VIESAPIClient
// No central repository support
// Maven
// https://viesapi.eu/maven/
<repository>
<id>viesapi</id>
<url>https://viesapi.eu/maven/releases</url>
</repository>
<dependency>
<groupId>eu.viesapi</groupId>
<artifactId>viesapi-client</artifactId>
<version>1.2.6</version>
</dependency>
// NPM
// https://www.npmjs.com/package/viesapi-client
npm install viesapi-client
// Packagist (Composer)
// https://packagist.org/packages/viesapi/client
composer require viesapi/client
# No central repository support
pip install viesapi-python-client-1.2.6.zip
' No central repository support
Autenticazione
Al fine di eseguire la corretta autenticazione, i valori corretti del id
e key
i parametri devono essere forniti durante la costruzione dell'oggetto client. Il id
il parametro deve contenere un identificatore di chiave valido utilizzato per l'autorizzazione. Il key
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. Il processo di generazione delle chiavi e degli identificatori è stato dettagliato in precedenza.
L'esempio seguente illustra come utilizzare le funzioni della libreria:
- C#
- C/C++
- Giava
- JavaScript
- PHP
- Pitone
- Visual Basic
using viesapiLibrary.dll;
// Create the service client object
// id - a string representing the API key identifier
// key - a string representing the API key
VIESAPIClient viesapi = new VIESAPIClient("id", "key");
#include "viesapi.h"
// Create the service client object
// id - a string representing the API key identifier
// key - a string representing the API key
VIESAPIClient* viesapi = NULL;
viesapi_new_prod(&viesapi, "id", "key");
import pl.viesapi.client.*;
// Create the service client object
// id - a string representing the API key identifier
// key - a string representing the API key
VIESAPIClient viesapi = new VIESAPIClient("id", "key");
var VIESAPI = require('viesapiclient');
// Create the service client object
// id - a string representing the API key identifier
// key - a string representing the API key
var viesapi = new VIESAPI.VIESAPIClient('id', 'key');
require_once 'VIESAPI/VIESAPIClient.php';
\VIESAPI\VIESAPIClient::registerAutoloader();
// Create the service client object
// id - a string representing the API key identifier
// key - a string representing the API key
$viesapi = new \VIESAPI\VIESAPIClient('id', 'key');
from viesapi import *
from pprint import pprint
// Create the service client object
// id - a string representing the API key identifier
// key - a string representing the API key
viesapi = VIESAPIClient('id', 'key')
' Create the service client object
' id - a string representing the API key identifier
' key - a string representing the API key
Dim viesapi As New VIESAPIClient
viesapi.URL = "https://www.viesapi.eu/api"
viesapi.Id = "id"
viesapi.Key = "key"
Attenzione! L'ora corrente del computer del client viene utilizzata durante il processo di autenticazione. Pertanto, in caso di problemi di autenticazione durante il tentativo di connessione al sistema viesapi.eu, assicurarsi innanzitutto che il computer o il server da cui viene stabilita la connessione abbia l'ora e il fuso orario correnti corretti. Ulteriori informazioni sul metodo utilizzato dal sistema viesapi.eu per autenticare le richieste sono disponibili qui.
Controllo delle partite IVA UE
La partita IVA UE viene confermata chiamando il getVIESData
funzione, il cui parametro è la partita IVA UE che si vuole verificare. La funzione consente la verifica delle partite IVA UE rilasciate da tutti gli stati membri dell'Unione Europea.
L'esempio seguente illustra come vengono utilizzate le funzioni nelle librerie:
- C#
- C/C++
- Giava
- JavaScript
- PHP
- Pitone
- Visual Basic
// A call to a method that returns data from a VIES system
VIESData vies = viesapi.GetVIESData("PL1234567890");
if (vies != null) {
Console.WriteLine(vies);
}
else {
Console.WriteLine("Error: " + viesapi.LastError + " (code: " + viesapi.LastErrorCode + ")");
}
// A call to a method that returns data from a VIES system
VIESData* vies = viesapi_get_vies_data(viesapi, "PL1234567890");
if (vies != NULL) {
printf("Kraj: %s\n", vies->CountryCode);
printf("VAT ID: %s\n", vies->VATNumber);
printf("Aktywny: %d\n", vies->Valid);
}
else {
printf("Error: %s (code: %d)\n", viesapi_get_last_err(viesapi), viesapi_get_last_err_code(viesapi));
}
// A call to a method that returns data from a VIES system
VIESData vies = viesapi.getVIESData("PL1234567890");
if (vies != null) {
System.out.println(vies);
}
else {
System.out.println("Error: " + viesapi.getLastError() + " (code: " + viesapi.getLastErrorCode() + ")");
}
// A call to a method that returns data from a VIES system
viesapi.getVIESData('PL1234567890').then((vies) => {
console.log(vies.toString());
}).catch((e) => {
console.log(e.message);
});
// A call to a method that returns data from a VIES system
$vies = $viesapi->get_vies_data('PL1234567890');
if ($vies) {
print_r($vies);
}
else {
echo '<p>Error: ' . $viesapi->get_last_error() . '</p>';
}
# A call to a method that returns data from a VIES system
vies = viesapi.get_vies_data('PL1234567890')
if vies:
pprint(vars(vies))
else:
print('Error: ' + viesapi.get_last_error() + ' (code: ' + str(viesapi.get_last_error_code()) + ')')
' A call to a method that returns data from a VIES system
Dim vies As VIESData
Set vies = viesapi.GetVIESData("PL1234567890")
If vies Is Nothing Then
Console.WriteLine("Error: {0}", viesapi.LastError)
Else
Console.WriteLine(vies.ToString())
End If
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
– identificativo univoco della query generato dal sistema VIES (Numero di Consultazione)date
– data di esecuzione della querysource
– fonte dati, sempre: http://ec.europa.eu
Controllo dei numeri IVA UE con l'indirizzo del commerciante analizzato
Puoi anche confermare il numero di partita IVA UE chiamando il getVIESDataParsed
funzione, il cui parametro è il numero di partita IVA UE che vogliamo verificare. Chiamando questa funzione, oltre alle informazioni sullo stato di contribuente IVA, si riceve anche l'indirizzo del commerciante analizzato.
Nota! A causa della mancanza di dati restituiti dal VIES per i commercianti di Germania e Spagna, la funzione non non tornare un indirizzo del commerciante analizzato (traderAddressComponent
) per questi paesi.
Dichiarazione di non responsabilità importante
La funzione di analisi utilizza algoritmi di intelligenza artificiale esterni e API per estrarre automaticamente attributi quali: città, codice postale, via con numero civico (numero civico) e numero civico, pertanto non possiamo garantire il suo corretto funzionamento 100%.
L'esempio seguente illustra come vengono utilizzate le funzioni nelle librerie:
- C#
- C/C++
- Giava
- JavaScript
- PHP
- Pitone
- Visual Basic
// A call to a method that returns data from a VIES system
VIESData vies = viesapi.GetVIESDataParsed("PL1234567890");
if (vies != null) {
Console.WriteLine(vies);
}
else {
Console.WriteLine("Error: " + viesapi.LastError + " (code: " + viesapi.LastErrorCode + ")");
}
// A call to a method that returns data from a VIES system
VIESData* vies = viesapi_get_vies_data_parsed(viesapi, "PL1234567890");
if (vies != NULL) {
printf("Kraj: %s\n", vies->CountryCode);
printf("VAT ID: %s\n", vies->VATNumber);
printf("Aktywny: %d\n", vies->Valid);
}
else {
printf("Error: %s (code: %d)\n", viesapi_get_last_err(viesapi), viesapi_get_last_err_code(viesapi));
}
// A call to a method that returns data from a VIES system
VIESData vies = viesapi.getVIESDataParsed("PL1234567890");
if (vies != null) {
System.out.println(vies);
}
else {
System.out.println("Error: " + viesapi.getLastError() + " (code: " + viesapi.getLastErrorCode() + ")");
}
// A call to a method that returns data from a VIES system
viesapi.getVIESDataParsed('PL1234567890').then((vies) => {
console.log(vies.toString());
}).catch((e) => {
console.log(e.message);
});
// A call to a method that returns data from a VIES system
$vies = $viesapi->get_vies_data_parsed('PL1234567890');
if ($vies) {
print_r($vies);
}
else {
echo '<p>Error: ' . $viesapi->get_last_error() . '</p>';
}
# A call to a method that returns data from a VIES system
vies = viesapi.get_vies_data_parsed('PL1234567890')
if vies:
pprint(vars(vies))
else:
print('Error: ' + viesapi.get_last_error() + ' (code: ' + str(viesapi.get_last_error_code()) + ')')
' A call to a method that returns data from a VIES system
Dim vies As VIESData
Set vies = viesapi.GetVIESDataParsed("PL1234567890")
If vies Is Nothing Then
Console.WriteLine("Error: {0}", viesapi.LastError)
Else
Console.WriteLine(vies.ToString())
End If
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à presso cui è registrata (formato originale)traderAddressComponent
– dettagli dell'indirizzo del raggruppamento dei componenticountry
– nome del paese del commerciante nella sua lingua nazionalepostalCode
– codice postale dell'indirizzo del commerciantecity
– città in cui ha sede il commerciantestreet
-via dell'indirizzo del commerciantestreetNumber
– numero civico dell'indirizzo del commerciantehouseNumber
– numero civico dell'indirizzo del commerciante
id
– identificativo univoco della query generato dal sistema VIES (Numero di Consultazione)date
– data di esecuzione della querysource
– fonte dati, sempre: http://ec.europa.eu
Controllo batch (asincrono) dei numeri IVA UE
getVIESDataAsync
– funzione asincrona che, in base al lotto di numeri IVA inviati, consente di ottenere lo stato attuale dell’IVA UE e i dati del commerciante.
Come parametro, fornire una matrice di stringhe contenente i numeri di partita IVA UE per i quali verificare lo stato di contribuente IVA UE e scaricare i dati del commerciante.
Il numero minimo di numeri di partita IVA UE inviati è 2, quello massimo è 99.
Una funzione chiamata correttamente restituisce un token, necessario per recuperare i risultati della richiesta. Il seguente esempio illustra come le funzioni vengono utilizzate nelle librerie:
- C#
- C/C++
- Giava
- JavaScript
- PHP
- Pitone
- Visual Basic
// Upload batch of VAT numbers and get their current VAT statuses and traders data
List numbers = new List {
"PL1234567890,
"DK64839576",
"CZ8475630234"
};
string token = viesapi.GetVIESDataAsync(numbers);
if (token != null) {
Console.WriteLine("Batch token: " + token);
} else {
Console.WriteLine("Error: " + viesapi.LastError + " (code: " + viesapi.LastErrorCode + ")");
}
// Upload batch of VAT numbers and get their current VAT statuses and traders data
char* numbers[] = {
"PL1234567890,
"DK64839576",
"CZ8475630234"
};
token = viesapi_get_vies_data_async(viesapi, numbers, 3);
if (token != NULL) {
printf("Batch token: %s\n", token);
} else {
printf("Error: %s (code: %d)\n", viesapi_get_last_err(viesapi), viesapi_get_last_err_code(viesapi));
}
// Upload batch of VAT numbers and get their current VAT statuses and traders data
List numbers = new ArrayList<>();
numbers.add("PL1234567890");
numbers.add("DK64839576");
numbers.add("CZ8475630234");
String token = viesapi.getVIESDataAsync(numbers);
if (token != null) {
System.out.println("Batch token: " + token);
} else {
System.out.println("Error: " + viesapi.getLastError() + " (code: " + viesapi.getLastErrorCode() + ")");
}
// Upload batch of VAT numbers and get their current VAT statuses and traders data
const numbers = [
'PL1234567890',
'DK64839576',
'CZ8475630234'
];
viesapi.getVIESDataAsync(numbers).then((token) => {
console.log('Batch token: ' + token);
}).catch((e) => {
console.log(e.message);
});
// Upload batch of VAT numbers and get their current VAT statuses and traders data
$numbers = array(
'PL1234567890',
'DK64839576',
'CZ7710043187'
);
$token = $viesapi->get_vies_data_async($numbers);
if ($token) {
echo '<pre>Batch token: ' . $token . '</pre>';
} else {
echo '<p>Error: ' . $viesapi->get_last_error() . ' (code: ' . $viesapi->get_last_error_code() . ')</p>';
}
# Upload batch of VAT numbers and get their current VAT statuses and traders data
numbers = [
'PL1234567890',
'DK64839576',
'CZ7710043187'
]
token = viesapi.get_vies_data_async(numbers)
if token:
print('Batch token: ' + token)
else:
print('Error: ' + viesapi.get_last_error() + ' (code: ' + str(viesapi.get_last_error_code()) + ')')
' Not supported yet
Grazie alla natura asincrona della funzione, i risultati possono essere recuperati dopo circa 2-3 minuti. Non importa se nella richiesta sono stati inviati 2 o 99 numeri IVA UE.
Se almeno un numero di partita IVA UE trasmesso nella richiesta ha un formato errato, il sistema restituisce l'errore "Il numero di partita IVA non è valido".
Per recuperare i risultati della richiesta inviata, chiamare getVIESDataAsyncResult
funzione, fornendo il valore del token come parametro di input.
Nota importante!
- La funzione è stata preparata come soluzione alternativa all'errore restituito dal sistema VIES: "
The maximum number of concurrent requests has been reached
” (MS_MAX_CONCURRENT_REQ
). Si consiglia di utilizzarlo quando si inviano richieste di Germania (DE)) E Francia (FR), che ha restituito l'errore sopra menzionato. - Finché non sarà completato il processo di verifica di tutti i numeri IVA UE inviati nella richiesta, tutti i tentativi successivi verranno respinti e l'errore verrà corretto "
The maximum number of batch request has been reached, please re-submit your request later
“.
getVIESDataAsyncResult
– la funzione consente di recuperare i risultati batch in base al token restituito dal getVIESDataAsync
funzione.
L'esempio seguente illustra come vengono utilizzate le funzioni nelle librerie:
- C#
- C/C++
- Giava
- JavaScript
- PHP
- Pitone
- Visual Basic
// Check batch result and download data (at production it usually takes 2-3 min for result to be ready)
BatchResult result;
while ((result = viesapi.GetVIESDataAsyncResult(token)) == null) {
if (viesapi.LastErrorCode != Error.BATCH_PROCESSING) {
Console.WriteLine("Error: " + viesapi.LastError + " (code: " + viesapi.LastErrorCode + ")");
return;
}
Console.WriteLine("Batch is still processing, waiting...");
Thread.Sleep(30000);
}
// Batch result is ready
Console.WriteLine(result);
// Check batch result and download data (at production it usually takes 2-3 min for result to be ready)
while ((result = viesapi_get_vies_data_async_result(viesapi, token)) == NULL) {
if (viesapi_get_last_err_code(viesapi) != VIESAPI_ERR_BATCH_PROCESSING) {
printf("Error: %s (code: %d)\n", viesapi_get_last_err(viesapi), viesapi_get_last_err_code(viesapi));
return;
}
printf("Batch is still processing, waiting...\n");
Sleep(30000);
}
// Batch result is ready
for (i = 0; i < result->NumbersCount; i++) {
printf("Country: %s\n", result->Numbers[i]->CountryCode);
printf("VAT ID: %s\n", result->Numbers[i]->VATNumber);
printf("Is valid: %d\n", result->Numbers[i]->Valid);
printf("\n");
}
for (i = 0; i < result->ErrorsCount; i++) {
printf("Country: %s\n", result->Errors[i]->CountryCode);
printf("VAT ID: %s\n", result->Errors[i]->VATNumber);
printf("Error: %s\n", result->Errors[i]->Error);
printf("\n");
}
// Check batch result and download data (at production it usually takes 2-3 min for result to be ready)
BatchResult result;
while ((result = viesapi.getVIESDataAsyncResult(token)) == null) {
if (viesapi.getLastErrorCode() != eu.viesapi.client.Error.BATCH_PROCESSING) {
System.out.println("Error: " + viesapi.getLastError() + " (code: " + viesapi.getLastErrorCode() + ")");
return;
}
System.out.println("Batch is still processing, waiting...");
Thread.sleep(30000);
}
// Batch result is ready
System.out.println(result);
// Check batch result and download data (at production it usually takes 2-3 min for result to be ready)
const looper = setInterval(() => {
viesapi.getVIESDataAsyncResult(token).then((result) => {
// Batch result is ready
console.log(result);
clearInterval(looper);
}).catch((e) => {
console.log(e.message);
});
}, 30000);
// Check batch result and download data (at production it usually takes 2-3 min for result to be ready)
while (($result = $viesapi->get_vies_data_async_result($token)) === false) {
if ($viesapi->get_last_error_code() !== \VIESAPI\Error::BATCH_PROCESSING) {
echo '<p>Error: ' . $viesapi->get_last_error() . ' (code: ' . $viesapi->get_last_error_code() . ')</p>';
die();
}
echo '<p>Batch is still processing, waiting...</p>';
sleep(30);
}
// Batch result is ready
echo '<pre>' . print_r($result, true) . '</pre>';
# Upload batch of VAT numbers and get their current VAT statuses and traders data
numbers = [
'PL1234567890',
'DK64839576',
'CZ7710043187'
]
token = viesapi.get_vies_data_async(numbers)
if token:
print('Batch token: ' + token)
else:
print('Error: ' + viesapi.get_last_error() + ' (code: ' + str(viesapi.get_last_error_code()) + ')')
' Not supported yet
Per ogni numero di partita IVA UE trasmesso nella chiamata batch, attributi coerenti con la risposta al getVIESData
vengono restituite le funzioni.
Recupero di informazioni sullo stato dell'account dell'utente
La funzione consente di scaricare tutte le informazioni di base sull'account utente, che vengono visualizzate dopo aver effettuato l'accesso all'account sul portale viesapi.eu. La funzione restituisce anche informazioni sul numero massimo di richieste disponibili nell'ambito del piano selezionato (es. 5.000 per il piano Business) e il numero totale di tutte le richieste effettuate nel mese corrente sull'account dell'utente.
Attenzione! Chiamare la funzione lo fa non aumentare il numero di interrogazioni effettuate.
L'esempio seguente illustra come utilizzare le funzioni della libreria.
- C#
- C/C++
- Giava
- JavaScript
- PHP
- Pitone
- Visual Basic
// Get current account status
AccountStatus account = viesapi.GetAccountStatus();
if (account != null) {
Console.WriteLine(account);
}
else {
Console.WriteLine("Error: " + viesapi.LastError);
}
// Get current account status
AccountStatus* account = viesapi_get_account_status(viesapi);
if (account != NULL) {
printf("Plan name: %s\n", account->BillingPlanName);
printf("Price: %.2f\n", account->SubscriptionPrice);
printf("Number of queries: %d\n", account->TotalCount);
}
else {
printf("Error: %s\n", viesapi_get_last_err(viesapi));
}
// Get current account status
AccountStatus account = viesapi.getAccountStatus();
if (account != null) {
System.out.println(account);
}
else {
System.err.println("Error: " + viesapi.getLastError());
}
// Get current account status
viesapi.getAccountStatus().then((account) => {
console.log(account.toString());
}).catch((e) => {
console.log(e.message);
});
// Get current account status
$account = $viesapi->get_account_status();
if ($account) {
echo '<p>' . print_r($account, true) . '</p>';
}
else {
echo '<p>Error: ' . $viesapi->get_last_error() . '</p>';
}
# Get current account status
account = viesapi.get_account_status()
if account:
pprint(vars(account))
else:
print u'Error: ' + viesapi.get_last_error()
'Get current account status
Dim account As AccountStatus
Set account = viesapi.GetAccountStatus()
If account Is Nothing Then
Console.WriteLine("Error: {0}", viesapi.LastError)
Else
Console.WriteLine(account.ToString())
End If
Registrazione di una libreria .NET come oggetto COM
Il viesapiLibrary.dll
la libreria può essere registrata nel sistema Windows come il cosiddetto COM
oggetto. Quindi è possibile fare riferimento alle funzioni della libreria da molti diversi linguaggi di programmazione e applicazioni già pronte, incl. Microsoft Excel, Access, SQL Server, Dynamics o Visual FoxPro.
Per registrare una libreria come oggetto COM, attenersi alla seguente procedura:
- Scarica il Libreria .NET archiviare e decomprimerlo su un disco locale in qualsiasi posizione.
- Vai alla directory con i file di libreria decompressi e trova il file
com-register.bat
file. - Seleziona il
com-register.bat
file con il mouse e selezionare ilRun as administrator
comando dal menu contestuale.
Utilizzo della libreria .NET in MS Excel
Le funzioni della libreria viesapiLibrary.dll possono essere utilizzate nell'applicazione MS Excel per scrivere le proprie funzioni e procedure nel Visual Basic
linguaggio. Per renderlo possibile è necessario:
- Registrati il
viesapiLibrary.dll
biblioteca comeCOM
oggetto suWindows
. - Avvia l'applicazione Excel. Seleziona il
DEVELOPER
scheda sulla barra multifunzione e quindi fare clic suVisual Basic
pulsante. - Nel
Visual Basic for Application
finestra, selezionaTools
poiReferences
dal menu. NelAvailable References
elenca, trova e selezionaVIESAPI Service Client for .NET Framework (C#)
. Conferma la tua selezione con ilOK
pulsante. - Dal
Insert
menu, scegliModule
e incollare il codice della funzione presentato negli esempi per Visual Basic nella nuova finestra. - Infine, valori appropriati di w per
viesapi.ID
eviesapi.Key
dovrebbe essere impostato. Il metodo per ottenere la chiave e la chiave di accesso è descritto nel capitolo Generazione dell'identificatore e della chiave di accesso