Bibliotecas de programação VIES

As bibliotecas de programação permitem pesquisar dados de empreendedores com base no número de IVA da UE inserido. Atualmente, as bibliotecas de API estão disponíveis para as seguintes linguagens de programação:

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

A API fornece os seguintes recursos:

getVIESData – função para confirmar a atividade do número de IVA da UE atribuído por qualquer um dos Estados-Membros da União Europeia,
getVIESDataParsed – função para confirmar a atividade do número de IVA da UE atribuído por qualquer um dos Estados-Membros da União Europeia e retornar o endereço do comerciante analisado,
getVIESDataAsync – função assíncrona que, com base no lote enviado de números de IVA, permite obter o status atual do IVA da UE e os dados do comerciante.
getVIESDataAsyncResult – a função permite que você recupere resultados em lote com base no token retornado pela função getVIESDataAsync
getAccountStatus – função para recuperar informações atualizadas sobre a conta do usuário.

Integração

Todas as bibliotecas com códigos-fonte estão disponíveis para download no site Download página. Além disso, o código fonte das bibliotecas também está disponível em nosso repositório oficial em Github.

A forma de integração da biblioteca depende da linguagem de programação selecionada. Para as linguagens que suportam o gerenciamento de bibliotecas com base em um repositório central, é possível usá-lo.

C#
C/C++
Java
JavaScript
PHP
Pitão
Visual básico

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

Autenticação

Para realizar a autenticação correta, os valores corretos do id e key parâmetros devem ser fornecidos durante a construção do objeto cliente. o id O parâmetro deve conter um identificador de chave válido usado para autorização. o key O parâmetro deve conter um valor válido da chave usada para autorização. O identificador de chave e a chave são gerados pelo usuário após fazer login em sua conta no viesapi.eu portal. O processo de geração das chaves e identificadores foi detalhado acima.

O exemplo a seguir ilustra como usar as funções da biblioteca:

C#
C/C++
Java
JavaScript
PHP
Pitão
Visual básico

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"

Atenção! A hora atual do computador do cliente é usada durante o processo de autenticação. Portanto, em caso de problemas de autenticação ao tentar se conectar ao sistema viesapi.eu, primeiro certifique-se de que o computador ou servidor a partir do qual a conexão é estabelecida tenha a hora e o fuso horário atuais corretos. Mais informações sobre o método usado pelo sistema viesapi.eu para autenticar consultas podem ser encontradas aqui.

Verificando os números de IVA da UE

O número de IVA da UE é confirmado ligando para o getVIESData função, cujo parâmetro é o número de IVA da UE que queremos verificar. A função permite a verificação de números de IVA da UE emitidos por todos os estados membros da União Europeia.

O exemplo a seguir ilustra como as funções são usadas em bibliotecas:

C#
C/C++
Java
JavaScript
PHP
Pitão
Visual básico

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

Descrição detalhada dos atributos retornados:

uid – identificador de consulta exclusivo gerado por viesapi.eu,
countryCode – código do país em que a empresa associada ao número de IVA da UE fornecido na consulta está registrada,
vatNumber – Número de IVA da UE da empresa verificada fornecida no inquérito,
valid – resposta do serviço VIES, informando sobre o atual status de IVA da UE da entidade verificada:
- true – o número de IVA da UE fornecido no inquérito é válido,
- false – o número de IVA da UE fornecido no inquérito não é válido,
traderName – nome comercial da empresa,
traderCompanyType – sempre retornou uma string de caracteres '-',
traderAddress – endereço da empresa onde a empresa está registrada,
id – identificador de consulta único gerado pelo sistema VIES (Número de Consulta)
date – data de execução da consulta
source – fonte de dados, sempre: http://ec.europa.eu

Verificação de números de IVA da UE com endereço de comerciante analisado

Você também pode confirmar o número de IVA da UE ligando para getVIESDataParsed function, cujo parâmetro é o número de IVA da UE que queremos verificar. Ao chamar esta função, além de informações sobre o status do contribuinte de IVA, você também recebe o endereço do comerciante analisado.

Observação! Devido à falta de dados retornados pelo VIES para comerciantes da Alemanha e Espanha, a função não não retornar um endereço de comerciante analisado (traderAddressComponent) para esses países.

Isenção de responsabilidade importante

A função de análise usa algoritmos de IA externos e APIs para extrair automaticamente atributos como: cidade, código postal, rua com número da rua (número do prédio) e número da casa, portanto não podemos garantir sua operação correta 100%.

O exemplo a seguir ilustra como as funções são usadas em bibliotecas:

C#
C/C++
Java
JavaScript
PHP
Pitão
Visual básico

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

Descrição detalhada dos atributos retornados:

uid – identificador de consulta exclusivo gerado por viesapi.eu,
countryCode – código do país em que a empresa associada ao número de IVA da UE fornecido na consulta está registrada,
vatNumber – Número de IVA da UE da empresa verificada fornecida no inquérito,
valid – resposta do serviço VIES, informando sobre o atual status de IVA da UE da entidade verificada:
- true – o número de IVA da UE fornecido no inquérito é válido,
- false – o número de IVA da UE fornecido no inquérito não é válido,
traderName – nome comercial da empresa,
traderCompanyType – sempre retornou uma string de caracteres '-',
traderAddress – endereço da empresa onde a empresa está registrada (formato original)
traderAddressComponent – detalhes do endereço do agrupamento de componentes
- country – nome do país do comerciante na sua língua nacional
- postalCode – código postal do endereço do comerciante
- city – cidade do endereço do comerciante
- street - rua do endereço do comerciante
- streetNumber – número da rua do endereço do comerciante
- houseNumber – número da casa do endereço do comerciante
id – identificador de consulta único gerado pelo sistema VIES (Número de Consulta)
date – data de execução da consulta
source – fonte de dados, sempre: http://ec.europa.eu

Verificação em lote (assíncrona) de números de IVA da UE

getVIESDataAsync – função assíncrona que, com base no lote enviado de números de IVA, permite obter o status atual do IVA da UE e os dados do comerciante.
Como parâmetro, forneça uma matriz de strings contendo números de IVA da UE para os quais o status de contribuinte de IVA da UE deve ser verificado e os dados do contribuinte devem ser baixados.

O número mínimo de números de IVA da UE enviados é 2 e o máximo é 99.

Uma função chamada corretamente retorna um token, que é necessário para recuperar os resultados da solicitação. O exemplo a seguir ilustra como as funções são usadas em bibliotecas:

C#
C/C++
Java
JavaScript
PHP
Pitão
Visual básico

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

Devido à natureza assíncrona da função, os resultados podem ser recuperados após cerca de 2-3 minutos. Não importa se 2 ou 99 números de IVA da UE foram enviados na solicitação.

Se pelo menos um número de IVA da UE transmitido na solicitação tiver um formato incorreto, o sistema retornará um erro “O número de IVA é inválido”.

Para recuperar os resultados da solicitação enviada, ligue para getVIESDataAsyncResult função, fornecendo o valor do token como parâmetro de entrada.

Nota importante!

A função foi preparada como uma solução alternativa para o erro retornado pelo sistema VIES: “The maximum number of concurrent requests has been reached" (MS_MAX_CONCURRENT_REQ). Recomendamos usá-lo ao enviar solicitações de Alemanha (DE) e França (FR), que retornou o erro acima mencionado.
Até que o processo de verificação de todos os números de IVA da UE enviados na solicitação seja concluído, todas as tentativas subsequentes serão rejeitadas e o erro será corrigido “The maximum number of batch request has been reached, please re-submit your request later“.

getVIESDataAsyncResult– a função permite que você recupere resultados em lote com base no token retornado pelo getVIESDataAsync função.

O exemplo a seguir ilustra como as funções são usadas em bibliotecas:

C#
C/C++
Java
JavaScript
PHP
Pitão
Visual básico

// 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 da UE transmitido na chamada em lote, os atributos são consistentes com a resposta ao getVIESData função são retornadas.

Recuperando informações sobre o status da conta do usuário

A função permite que você baixe todas as informações básicas sobre a conta do usuário, que são exibidas após o login na conta no portal viesapi.eu. A função também retorna informações sobre o número máximo de consultas disponíveis no plano selecionado (por exemplo, 5.000 para o plano Business) e o número total de todas as consultas feitas no mês atual na conta do usuário.

Atenção! Chamar a função faz não aumentar o número de consultas feitas.

O exemplo a seguir ilustra como usar as funções de biblioteca.

C#
C/C++
Java
JavaScript
PHP
Pitão
Visual básico

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

Registrando uma biblioteca .NET como um objeto COM

o viesapiLibrary.dll biblioteca pode ser registrada no sistema Windows como o chamado COM objeto. Em seguida, as funções da biblioteca podem ser referenciadas a partir de muitas linguagens de programação diferentes e aplicativos prontos, incl. Microsoft Excel, Access, SQL Server, Dynamics ou Visual FoxPro.

Para registrar uma biblioteca como um objeto COM, siga estas etapas:

Faça o download do biblioteca .NET arquivar e descompactá-lo em um disco local para qualquer local.
Vá para o diretório com arquivos de biblioteca descompactados e encontre o com-register.bat Arquivo.
Selecione os com-register.bat arquivo com o mouse e selecione o Run as administrator comando no menu de contexto.

Usando a biblioteca .NET no MS Excel

As funções da biblioteca viesapiLibrary.dll podem ser usadas no aplicativo MS Excel para escrever suas próprias funções e procedimentos no Visual Basic Língua. Para que isso seja possível, é necessário:

Registro a viesapiLibrary.dll biblioteca como um COM objeto em Windows.
Inicie o aplicativo Excel. Selecione os DEVELOPER guia na faixa de opções e, em seguida, clique no Visual Basic botão.
No Visual Basic for Application janela, selecione Tools e depois References do cardápio. No Available References lista, localize e selecione VIESAPI Service Client for .NET Framework (C#). Confirme sua seleção com o OK botão.
De Insert cardápio, escolha Module e cole o código de função apresentado nos exemplos para Visual Basic na nova janela.
Finalmente, valores apropriados de w para viesapi.ID e viesapi.Key deve ser definido. O método de obtenção da chave e da chave de acesso é descrito no capítulo Gerando o identificador e a chave de acesso

Bibliotecas de programação VIES (.net, java, php, python, javascript, c/c++)

Bibliotecas de programação VIES

Integração

Autenticação

Verificando os números de IVA da UE

Verificação de números de IVA da UE com endereço de comerciante analisado

Verificação em lote (assíncrona) de números de IVA da UE

Recuperando informações sobre o status da conta do usuário

Registrando uma biblioteca .NET como um objeto COM

Usando a biblioteca .NET no MS Excel