Библиотеки за програмиране на VIES

Програмните библиотеки ви позволяват да търсите данни за предприемачи въз основа на въведения ДДС ЕС номер. Понастоящем API библиотеките са налични за следните езици за програмиране:

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

API предоставя следните функции:

getVIESData – функция за потвърждаване на дейността на ЕС ДДС номер, даден от която и да е от държавите-членки на Европейския съюз,
getVIESDataParsed – функция за потвърждаване на дейността на ДДС номер в ЕС, присвоен от която и да е от държавите-членки на Европейския съюз, и връщане на анализирания адрес на търговец,
getVIESDataAsync – asynchronous function, which, based on the sent batch of VAT numbers, allows you to obtain the current EU VAT status and trader data.
getVIESDataAsyncResult – the function allows you to retrieve batch results based on the token returned by the getVIESDataAsync function
getAccountStatus – функция за извличане на актуална информация за потребителския акаунт.

Интеграция

Всички библиотеки с изходни кодове са достъпни за изтегляне на Изтегли страница. В допълнение, изходният код за библиотеките също е достъпен в нашето официално хранилище на Github.

Начинът на интегриране на библиотеката зависи от избрания език за програмиране. За тези езици, които поддържат управление на библиотеката, базирано на централно хранилище, е възможно да го използвате.

C#
C/C++
Java
JavaScript
PHP
Python
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

Удостоверяване

За да извършите правилното удостоверяване, правилните стойности на id и key параметри трябва да бъдат предвидени при изграждането на обекта на клиента. The id параметърът трябва да съдържа валиден ключов идентификатор, използван за оторизация. The key параметърът трябва да съдържа валидна стойност на ключа, използван за оторизация. Идентификаторът на ключа и ключът се генерират от потребителя след влизане в акаунта му на viesapi.eu портал. Процесът на генериране на ключовете и идентификаторите е описан по-горе.

Следният пример илюстрира как да използвате библиотечните функции:

C#
C/C++
Java
JavaScript
PHP
Python
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"

внимание! По време на процеса на удостоверяване се използва текущото време на компютъра на клиента. Ето защо, в случай на проблеми с удостоверяването, когато се опитвате да се свържете със системата viesapi.eu, първо се уверете, че компютърът или сървърът, от който се осъществява връзката, има правилното текущо време и часова зона. Повече информация за метода, използван от системата viesapi.eu за удостоверяване на запитвания, можете да намерите тук.

Проверка на ДДС номера в ЕС

ДДС номерът на ЕС се потвърждава чрез обаждане на getVIESData функция, чийто параметър е ДДС номерът на ЕС, който искаме да проверим. Функцията позволява проверка на ДДС номера на ЕС, издадени от всички държави-членки на Европейския съюз.

Следният пример илюстрира как се използват функции в библиотеки:

C#
C/C++
Java
JavaScript
PHP
Python
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

Подробно описание на върнатите атрибути:

uid – уникален идентификатор на заявка, генериран от viesapi.eu,
countryCode – код на държавата, в която е регистрирано дружеството, свързано с ДДС номера в ЕС, предоставен в запитването,
vatNumber – ЕС ДДС номер на проверената компания, посочен в запитването,
valid – отговор от услугата VIES, информиращ за текущия статут по ДДС в ЕС на проверяваното лице:
- true – ДДС номерът на ЕС, предоставен в запитването, е валиден,
- false – ДДС номерът на ЕС, предоставен в запитването, не е валиден,
traderName – търговско наименование на фирмата,
traderCompanyType – винаги връщаше низ от знаци „-“,
traderAddress – адрес на фирмата, където е регистрирана фирмата,
id – уникален идентификатор на заявка, генериран от системата VIES (номер за консултация)
date – дата на изпълнение на заявката
source – източник на данни, винаги: http://ec.europa.eu

Проверка на ДДС номера в ЕС с анализиран адрес на търговец

Можете също да потвърдите ДДС номера в ЕС, като се обадите на getVIESDataParsed function, the parameter of which is the EU VAT number that we want to verify. By calling this function, in addition to information about the VAT taxpayer status, you also receive the parsed trader address.

Забележка! Due to the lack of data returned by VIES for traders from Germany and Spain, the function does не се връща анализиран адрес на търговец (traderAddressComponent) за тези страни.

Важен отказ от отговорност

Функцията за синтактичен анализ използва външни AI алгоритми и API за автоматично извличане на атрибути като: град, пощенски код, улица с номер на улица (номер на сграда) и номер на къща, така че не можем да гарантираме правилната работа на 100%.

Следният пример илюстрира как се използват функции в библиотеки:

C#
C/C++
Java
JavaScript
PHP
Python
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

Подробно описание на върнатите атрибути:

uid – уникален идентификатор на заявка, генериран от viesapi.eu,
countryCode – код на държавата, в която е регистрирано дружеството, свързано с ДДС номера в ЕС, предоставен в запитването,
vatNumber – ЕС ДДС номер на проверената компания, посочен в запитването,
valid – отговор от услугата VIES, информиращ за текущия статут по ДДС в ЕС на проверяваното лице:
- true – ДДС номерът на ЕС, предоставен в запитването, е валиден,
- false – ДДС номерът на ЕС, предоставен в запитването, не е валиден,
traderName – търговско наименование на фирмата,
traderCompanyType – винаги връщаше низ от знаци „-“,
traderAddress – фирмен адрес, където е регистрирана фирмата (оригинален формат)
traderAddressComponent – подробности за адреса на групирането на компоненти
- country – име на държавата търговец на нейния национален език
- postalCode – пощенски код на адреса на търговеца
- city – град на адреса на търговеца
- street -улица на адреса на търговеца
- streetNumber – номер на адреса на търговеца
- houseNumber – домашен номер на адреса на търговеца
id – уникален идентификатор на заявка, генериран от системата VIES (номер за консултация)
date – дата на изпълнение на заявката
source – източник на данни, винаги: http://ec.europa.eu

Batch (asynchronous) checking EU VAT numbers

getVIESDataAsync – asynchronous function, which, based on the sent batch of VAT numbers, allows you to obtain the current EU VAT status and trader data.
As a parameter, provide a string array containing EU VAT numbers for which the EU VAT taxpayer status is to be checked and the treader’s data should be downloaded.

The minimum number of EU VAT numbers sent is 2, and the maximum is 99.

A correctly called function returns a token, which is necessary to retrieve the request results. The following example illustrates how functions are used in libraries:

C#
C/C++
Java
JavaScript
PHP
Python
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

Due to the asynchronous nature of the function, the results can be retrieved after about 2-3 minutes. It does not matter whether 2 or 99 EU VAT numbers were sent in the request.

If at least one EU VAT number passed in the request has an incorrect format, the system returns an error “The VAT number is invalid”.

To retrieve the results for the sent request, call the getVIESDataAsyncResult function, providing the token value as the input parameter.

Important Note!

The function was prepared as a workaround for the error returned by the VIES system: “The maximum number of concurrent requests has been reached” (MS_MAX_CONCURRENT_REQ). We recommend using it when sending requests for Germany (DE) and France (FR), which returned the above-mentioned error.
Until the process of checking all EU VAT numbers sent in the request is completed, all subsequent attempts will be rejected and the error will be corrected “The maximum number of batch request has been reached, please re-submit your request later“.

getVIESDataAsyncResult– the function allows you to retrieve batch results based on the token returned by the getVIESDataAsync функция.

Следният пример илюстрира как се използват функции в библиотеки:

C#
C/C++
Java
JavaScript
PHP
Python
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

For each EU VAT number passed in the batch call, attributes consistent with the response to the getVIESData function are returned.

Извличане на информация за състоянието на акаунта на потребителя

Функцията ви позволява да изтеглите цялата основна информация за потребителския акаунт, която се показва след влизане в акаунта в портала viesapi.eu. Функцията също така връща информация за максималния брой налични заявки по избрания план (напр. 5000 за Бизнес план) и общия брой на всички заявки, направени през текущия месец в акаунта на потребителя.

внимание! Извикването на функцията прави не се увеличава броя на направените запитвания.

Следващият пример илюстрира как да използвате библиотечните функции.

C#
C/C++
Java
JavaScript
PHP
Python
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

Регистриране на .NET библиотека като COM обект

The viesapiLibrary.dll библиотека може да се регистрира в Windows системата като т.нар COM обект. Тогава функциите на библиотеката могат да бъдат реферирани от много различни програмни езици и готови приложения, вкл. Microsoft Excel, Access, SQL Server, Dynamics или Visual FoxPro.

За да регистрирате библиотека като COM обект, изпълнете следните стъпки:

Изтеглете .NET библиотека архивирайте и го разопаковайте на локален диск на всяко място.
Отидете в директорията с разопаковани библиотечни файлове и намерете com-register.bat файл.
Изберете com-register.bat файл с мишката и изберете Run as administrator команда от контекстното меню.

Използване на .NET библиотеката в MS Excel

Функциите на библиотеката viesapiLibrary.dll могат да се използват в приложението MS Excel, за да напишете свои собствени функции и процедури в Visual Basic език. За да стане възможно, е необходимо:

Регистрирам на viesapiLibrary.dll библиотека като a COM обект на Windows.
Стартирайте приложението Excel. Изберете DEVELOPER на лентата и след това щракнете върху Visual Basic бутон.
В Visual Basic for Application прозорец, изберете Tools и тогава References от менюто. В Available References списък, намиране и избор VIESAPI Service Client for .NET Framework (C#). Потвърдете избора си с OK бутон.
От Insert меню, изберете Module и поставете функционалния код, представен в примерите за Visual Basic, в новия прозорец.
И накрая, подходящи стойности на w за viesapi.ID и viesapi.Key трябва да се настрои. Методът за получаване на ключа и ключа за достъп е описан в главата Генериране на идентификатор и ключ за достъп

Библиотеки за програмиране на VIES (.net, java, php, python, javascript, c/c++)

Библиотеки за програмиране на VIES

Интеграция

Удостоверяване

Проверка на ДДС номера в ЕС

Проверка на ДДС номера в ЕС с анализиран адрес на търговец

Batch (asynchronous) checking EU VAT numbers

Извличане на информация за състоянието на акаунта на потребителя

Регистриране на .NET библиотека като COM обект

Използване на .NET библиотеката в MS Excel