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

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

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

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

getVIESData – функция за потвърждаване на дейността на ЕС ДДС номер, даден от която и да е от държавите-членки на Европейския съюз,
getVIESDataParsed – функция за потвърждаване на дейността на ДДС номер в ЕС, присвоен от която и да е от държавите-членки на Европейския съюз, и връщане на анализирания адрес на търговец,
getVIESDataAsync – асинхронна функция, която въз основа на изпратената партида от ДДС номера ви позволява да получите текущия ДДС статус в ЕС и данни за търговеца.
getVIESDataAsyncResult – функцията ви позволява да извличате партидни резултати въз основа на токена, върнат от функцията getVIESDataAsync
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 функция, чийто параметър е ДДС номерът на ЕС, който искаме да проверим. С извикването на тази функция, освен информация за статуса на данъкоплатец по ДДС, получавате и парсирания адрес на търговеца.

Забележка! Поради липсата на данни, върнати от VIES за търговци от Германия и Испания, функцията го прави не се връща анализиран адрес на търговец (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

Партидна (асинхронна) проверка на ДДС номера в ЕС

getVIESDataAsync – асинхронна функция, която въз основа на изпратената партида от ДДС номера ви позволява да получите текущия ДДС статус в ЕС и данни за търговеца.
Като параметър предоставете низов масив, съдържащ ДДС номера в ЕС, за които трябва да се провери статутът на данъкоплатец по ДДС в ЕС и трябва да се изтеглят данните на търговеца.

Минималният брой изпратени ДДС номера в ЕС е 2, а максималният е 99.

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

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

Поради асинхронния характер на функцията, резултатите могат да бъдат извлечени след около 2-3 минути. Няма значение дали в заявката са изпратени 2 или 99 ЕС ДДС номера.

Ако поне един номер по ДДС в ЕС, подаден в заявката, има неправилен формат, системата връща грешка „Номерът по ДДС е невалиден“.

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

Важна забележка!

Функцията е подготвена като заобиколно решение за грешката, върната от системата VIES: „The maximum number of concurrent requests has been reached” (MS_MAX_CONCURRENT_REQ). Препоръчваме да го използвате, когато изпращате заявки за Германия (DE) и Франция (FR), който върна горепосочената грешка.
Докато процесът на проверка на всички ДДС номера в ЕС, изпратени в заявката, не приключи, всички последващи опити ще бъдат отхвърлени и грешката ще бъде коригирана “The maximum number of batch request has been reached, please re-submit your request later“.

getVIESDataAsyncResult– функцията ви позволява да извличате партидни резултати въз основа на токена, върнат от 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

За всеки номер по ДДС в ЕС, предаден в груповото извикване, атрибути, съответстващи на отговора на getVIESData функция се връщат.

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

Функцията ви позволява да изтеглите цялата основна информация за потребителския акаунт, която се показва след влизане в акаунта в портала 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

Интеграция

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

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

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

Партидна (асинхронна) проверка на ДДС номера в ЕС

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

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

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