Bibliotecas de programación VIES

Las bibliotecas de programación le permiten buscar datos de empresarios en función del número de IVA de la UE ingresado. Actualmente, las bibliotecas API están disponibles para los siguientes lenguajes de programación:

.NET (C#, Visual Basic)
Java
JavaScript (Node.js)
PHP
Pitón
C/C++

La API proporciona las siguientes características:

getVIESData – función para confirmar la actividad del número de IVA de la UE asignado por cualquiera de los Estados miembros de la Unión Europea,
getVIESDataParsed – función para confirmar la actividad del número de IVA de la UE asignado por cualquiera de los Estados miembros de la Unión Europea y devolver la dirección del comerciante analizada,
getVIESDataAsync – función asincrónica que, a partir del lote enviado de números de IVA, permite obtener el estado actual del IVA de la UE y los datos del comerciante.
getVIESDataAsyncResult – la función le permite recuperar resultados por lotes según el token devuelto por la función getVIESDataAsync
getAccountStatus – función para recuperar información actualizada sobre la cuenta de usuario.

Integración

Todas las bibliotecas con códigos fuente están disponibles para su descarga en el Descargar página. Además, el código fuente de las bibliotecas también está disponible en nuestro repositorio oficial en Github.

La forma de integrar la biblioteca depende del lenguaje de programación seleccionado. Para aquellos lenguajes que soporten la gestión de bibliotecas en base a un repositorio central, es posible utilizarlo.

C#
C/C++
Java
JavaScript
PHP
Pitón
básico visual

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

Autenticación

Para realizar la autenticación correcta, los valores correctos de la id y key los parámetros deben proporcionarse durante la construcción del objeto del cliente. los id El parámetro debe contener un identificador de clave válido utilizado para la autorización. los key El parámetro debe contener un valor válido de la clave utilizada para la autorización. El identificador de clave y la clave son generados por el usuario después de iniciar sesión en su cuenta en el viesapi.eu portal. El proceso de generación de claves e identificadores se ha detallado anteriormente.

El siguiente ejemplo ilustra cómo usar las funciones de la biblioteca:

C#
C/C++
Java
JavaScript
PHP
Pitón
básico visual

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"

Atención! La hora actual de la computadora del cliente se usa durante el proceso de autenticación. Por lo tanto, en caso de problemas de autenticación al intentar conectarse al sistema viesapi.eu, primero asegúrese de que la computadora o servidor desde el que se establece la conexión tenga la hora y la zona horaria correctas. Puede encontrar más información sobre el método utilizado por el sistema viesapi.eu para autenticar las consultas. aquí.

Comprobación de los números de IVA de la UE

El número de IVA de la UE se confirma llamando al getVIESData función, cuyo parámetro es el número de IVA de la UE que queremos verificar. La función permite la verificación de los números de IVA de la UE emitidos por todos los estados miembros de la Unión Europea.

El siguiente ejemplo ilustra cómo se utilizan las funciones en las bibliotecas:

C#
C/C++
Java
JavaScript
PHP
Pitón
básico visual

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

Descripción detallada de los atributos devueltos:

uid – identificador de consulta único generado por viesapi.eu,
countryCode – código de país en el que está registrada la empresa asociada con el número de IVA de la UE proporcionado en la consulta,
vatNumber – Número de IVA de la UE de la empresa verificada proporcionada en la consulta,
valid – respuesta del servicio VIES, informando sobre el estado actual del IVA de la UE de la entidad verificada:
- true – el número de IVA de la UE proporcionado en la consulta es válido,
- false – el número de IVA de la UE proporcionado en la consulta no es válido,
traderName – nombre comercial de la empresa,
traderCompanyType – siempre devolvía una cadena de caracteres '-',
traderAddress – dirección de la empresa donde está registrada la empresa,
id – identificador único de consulta generado por el sistema VIES (Número de Consulta)
date – fecha de ejecución de la consulta
source – fuente de datos, siempre: http://ec.europa.eu

Comprobación de los números de IVA de la UE con la dirección del comerciante analizada

También puede confirmar el número de IVA de la UE llamando al getVIESDataParsed Función cuyo parámetro es el número de IVA de la UE que queremos verificar. Al llamar a esta función, además de información sobre la condición de contribuyente del IVA, también se recibe la dirección del comerciante analizada.

Nota! Debido a la falta de datos devueltos por VIES para los comerciantes de Alemania y España, la función no... No volver una dirección de comerciante analizada (traderAddressComponent) para estos países.

Descargo de responsabilidad importante

La función de análisis utiliza algoritmos de IA y API externas para extraer automáticamente atributos como: ciudad, código postal, calle con número de calle (número de edificio) y número de casa, por lo que no podemos garantizar su correcto funcionamiento.

El siguiente ejemplo ilustra cómo se utilizan las funciones en las bibliotecas:

C#
C/C++
Java
JavaScript
PHP
Pitón
básico visual

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

Descripción detallada de los atributos devueltos:

uid – identificador de consulta único generado por viesapi.eu,
countryCode – código de país en el que está registrada la empresa asociada con el número de IVA de la UE proporcionado en la consulta,
vatNumber – Número de IVA de la UE de la empresa verificada proporcionada en la consulta,
valid – respuesta del servicio VIES, informando sobre el estado actual del IVA de la UE de la entidad verificada:
- true – el número de IVA de la UE proporcionado en la consulta es válido,
- false – el número de IVA de la UE proporcionado en la consulta no es válido,
traderName – nombre comercial de la empresa,
traderCompanyType – siempre devolvía una cadena de caracteres '-',
traderAddress – dirección de la empresa donde está registrada la empresa (formato original)
traderAddressComponent – Detalles de la dirección de agrupación de componentes
- country – nombre del país del comerciante en su idioma nacional
- postalCode – código postal de la dirección del comerciante
- city – ciudad del domicilio del comerciante
- street -Calle del domicilio del comerciante
- streetNumber – número de la calle del domicilio del comerciante
- houseNumber – número de la casa donde se encuentra la dirección del comerciante
id – identificador único de consulta generado por el sistema VIES (Número de Consulta)
date – fecha de ejecución de la consulta
source – fuente de datos, siempre: http://ec.europa.eu

Comprobación por lotes (asincrónica) de números de IVA de la UE

getVIESDataAsync – función asincrónica que, a partir del lote enviado de números de IVA, permite obtener el estado actual del IVA de la UE y los datos del comerciante.
Como parámetro, proporcione una matriz de cadenas que contenga los números de IVA de la UE para los que se debe verificar el estado de contribuyente del IVA de la UE y se deben descargar los datos del lector.

El número mínimo de números de IVA de la UE enviados es 2 y el máximo es 99.

Una función llamada correctamente devuelve un token, necesario para recuperar los resultados de la solicitud. El siguiente ejemplo ilustra cómo se usan las funciones en las bibliotecas:

C#
C/C++
Java
JavaScript
PHP
Pitón
básico visual

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

Debido a la naturaleza asincrónica de la función, los resultados se pueden obtener en aproximadamente 2-3 minutos. No importa si se enviaron 2 o 99 números de IVA de la UE en la solicitud.

Si al menos un número de IVA de la UE pasado en la solicitud tiene un formato incorrecto, el sistema devuelve un error “El número de IVA no es válido”.

Para recuperar los resultados de la solicitud enviada, llame al getVIESDataAsyncResult función, que proporciona el valor del token como parámetro de entrada.

Nota importante!

La función se preparó como solución alternativa al error devuelto por el sistema VIES: “The maximum number of concurrent requests has been reached" (MS_MAX_CONCURRENT_REQ). Recomendamos usarlo al enviar solicitudes de Alemania (DE) y Francia (FR), que devolvió el error mencionado anteriormente.
Hasta que se complete el proceso de verificación de todos los números de IVA de la UE enviados en la solicitud, todos los intentos posteriores serán rechazados y se corregirá el error.The maximum number of batch request has been reached, please re-submit your request later“.

getVIESDataAsyncResult– la función le permite recuperar resultados por lotes en función del token devuelto por el getVIESDataAsync función.

El siguiente ejemplo ilustra cómo se utilizan las funciones en las bibliotecas:

C#
C/C++
Java
JavaScript
PHP
Pitón
básico visual

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

Para cada número de IVA de la UE que se pasa en la llamada por lotes, los atributos son consistentes con la respuesta a la getVIESData Se devuelven las funciones.

Recuperación de información sobre el estado de la cuenta del usuario

La función le permite descargar toda la información básica sobre la cuenta de usuario, que se muestra después de iniciar sesión en la cuenta en el portal viesapi.eu. La función también devuelve información sobre el número máximo de consultas disponibles en el plan seleccionado (por ejemplo, 5.000 para el plan Business) y el número total de todas las consultas realizadas en el mes actual en la cuenta del usuario.

Atención! Llamar a la función no no aumentar el número de consultas realizadas.

El siguiente ejemplo ilustra cómo utilizar las funciones de la biblioteca.

C#
C/C++
Java
JavaScript
PHP
Pitón
básico visual

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

Registro de una biblioteca .NET como un objeto COM

los viesapiLibrary.dll biblioteca se puede registrar en el sistema de Windows como el llamado COM objeto. Luego, se puede hacer referencia a las funciones de la biblioteca desde muchos lenguajes de programación diferentes y aplicaciones listas para usar, incl. Microsoft Excel, Access, SQL Server, Dynamics o Visual FoxPro.

Para registrar una biblioteca como un objeto COM, siga estos pasos:

Descargar el biblioteca .NET archívelo y descomprímalo en un disco local en cualquier ubicación.
Vaya al directorio con archivos de biblioteca desempaquetados y busque el com-register.bat expediente.
Selecciona el com-register.bat archivo con el ratón y seleccione el Run as administrator comando del menú contextual.

Uso de la biblioteca .NET en MS Excel

Las funciones de la biblioteca viesapiLibrary.dll se pueden utilizar en la aplicación MS Excel para escribir sus propias funciones y procedimientos en el Visual Basic idioma. Para hacerlo posible, es necesario:

Registro la viesapiLibrary.dll biblioteca como un COM objeto en Windows.
Inicie la aplicación Excel. Selecciona el DEVELOPER pestaña en la cinta y luego haga clic en el Visual Basic botón.
En el Visual Basic for Application ventana, seleccione Tools y entonces References del menú. En el Available References enumerar, buscar y seleccionar VIESAPI Service Client for .NET Framework (C#). Confirme su selección con el OK botón.
Desde el Insert menú, elige Module y pegue el código de función presentado en los ejemplos para Visual Basic en la nueva ventana.
Finalmente, los valores apropiados de w para viesapi.ID y viesapi.Key debe establecerse. El método para obtener la clave y la clave de acceso se describe en el capítulo Generación del identificador y clave de acceso

Bibliotecas de programación VIES (.net, java, php, python, javascript, c/c++)

Bibliotecas de programación VIES

Integración

Autenticación

Comprobación de los números de IVA de la UE

Comprobación de los números de IVA de la UE con la dirección del comerciante analizada

Comprobación por lotes (asincrónica) de números de IVA de la UE

Recuperación de información sobre el estado de la cuenta del usuario

Registro de una biblioteca .NET como un objeto COM

Uso de la biblioteca .NET en MS Excel