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,
  • getVIESDataParsedfunzione 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 getVIESDataAsync
  • getAccountStatus – 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.

// 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:

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:

// 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 query
  • source – 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:

// 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)
  • traderAddressComponentdettagli dell'indirizzo del raggruppamento dei componenti
    • country – nome del paese del commerciante nella sua lingua nazionale
    • postalCode – codice postale dell'indirizzo del commerciante
    • city – città in cui ha sede il commerciante
    • street -via dell'indirizzo del commerciante
    • streetNumber – numero civico dell'indirizzo del commerciante
    • houseNumber – numero civico dell'indirizzo del commerciante
  • id – identificativo univoco della query generato dal sistema VIES (Numero di Consultazione)
  • date – data di esecuzione della query
  • source – 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:

// 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!

  1. 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.
  2. 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:

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

// 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:

  1. Scarica il Libreria .NET archiviare e decomprimerlo su un disco locale in qualsiasi posizione.
  2. Vai alla directory con i file di libreria decompressi e trova il file com-register.bat file.
  3. Seleziona il com-register.bat file con il mouse e selezionare il Run 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:

  1. Registrati il viesapiLibrary.dll biblioteca come COM oggetto su Windows.
  2. Avvia l'applicazione Excel. Seleziona il DEVELOPER scheda sulla barra multifunzione e quindi fare clic su Visual Basic pulsante.
  3. Nel Visual Basic for Application finestra, seleziona Tools poi References dal menu. Nel Available References elenca, trova e seleziona VIESAPI Service Client for .NET Framework (C#). Conferma la tua selezione con il OK pulsante.
  4. Dal Insert menu, scegli Module e incollare il codice della funzione presentato negli esempi per Visual Basic nella nuova finestra.
  5. Infine, valori appropriati di w per viesapi.ID e viesapi.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