Бібліотеки програмування VIES
Бібліотеки програмування дозволяють здійснювати пошук даних про підприємців за введеним ЄС номером ПДВ. Наразі бібліотеки API доступні для таких мов програмування:
- .NET (C#, Visual Basic)
- Java
- JavaScript (Node.js)
- PHP
- Python
- C/C++
API надає такі функції:
getVIESData
– функція підтвердження діяльності номера ПДВ ЄС, присвоєного будь-якою з держав-членів Європейського Союзу,getVIESDataParsed
– функція для підтвердження діяльності номеру платника ПДВ ЄС, присвоєного будь-якою з держав-членів Європейського Союзу, і повернення проаналізованої адреси торговця,getVIESDataAsync
– асинхронна функція, яка на основі надісланої партії номерів ПДВ дозволяє отримати поточний статус ПДВ ЄС і дані трейдера.getVIESDataAsyncResult
– функція дозволяє отримувати пакетні результати на основі маркера, повернутого функцією getVIESDataAsyncgetAccountStatus
– функція для отримання актуальної інформації про обліковий запис користувача.
Інтеграція
Усі бібліотеки з вихідними кодами доступні для завантаження на Завантажити сторінки. Крім того, вихідний код для бібліотек також доступний у нашому офіційному репозиторії на 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
) для цих країн.
Важливе застереження
Функція синтаксичного аналізу використовує зовнішні алгоритми штучного інтелекту та 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
бібліотека як а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
слід встановити. Спосіб отримання ключа та ключа доступу описано в розділі Генерація ідентифікатора та ключа доступу