VIES Programming Libraries

Бібліотеки програмування дозволяють здійснювати пошук даних про підприємців за введеним ЄС номером ПДВ. Наразі бібліотеки API доступні для таких мов програмування:

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

API надає такі функції:

getVIESData – функція підтвердження діяльності номера ПДВ ЄС, присвоєного будь-якою з держав-членів Європейського Союзу,
getVIESDataParsed – function to confirm the activity of the EU VAT number assigned by any of the European Union Member States and return the parsed trader address,
getAccountStatus – function for retrieving up-to-date information about the user account.

Інтеграція

Усі бібліотеки з вихідними кодами доступні для завантаження на Завантажити сторінки. Крім того, вихідний код для бібліотек також доступний у нашому офіційному репозиторії на 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);
}

// 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\n", viesapi_get_last_err(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());
}

// 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 u'Error: ' + viesapi.get_last_error()

' 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 – unique query identifier generated by the VIES system (Consultation Number)
date – дата виконання запиту
source – джерело даних, завжди: http://ec.europa.eu

Checking EU VAT numbers with parsed trader address

You can also confirm the EU VAT number by calling the 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.

Note! Due to the lack of data returned by VIES for traders from Germany and Spain, the function does not return a parsed trader address (traderAddressComponent) for these countries.

Наступний приклад ілюструє, як функції використовуються в бібліотеках:

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);
}

// 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\n", viesapi_get_last_err(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());
}

// 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 u'Error: ' + viesapi.get_last_error()

' 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 – company address where the company is registered (oryginal format)
traderAddressComponent – component grouping address details
- country – trader country code
- postalCode – postal code of the trader’s address
- city – city of the trader’s address
- street -street of the trader’s address
- streetNumber – street number of the trader’s address
- houseNumber – house number of the trader’s address
id – unique query identifier generated by the VIES system (Consultation Number)
date – дата виконання запиту
source – джерело даних, завжди: http://ec.europa.eu

Отримання інформації про стан облікового запису користувача

Функція дозволяє завантажити всю основну інформацію про обліковий запис користувача, яка відображається після входу в обліковий запис на порталі 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 слід встановити. Спосіб отримання ключа та ключа доступу описано в розділі Генерація ідентифікатора та ключа доступу

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

VIES Programming Libraries

Інтеграція

Аутентифікація

Перевірка номерів ПДВ ЄС

Атрибути повернутого об'єкта

Checking EU VAT numbers with parsed trader address

Атрибути повернутого об'єкта

Отримання інформації про стан облікового запису користувача

Реєстрація бібліотеки .NET як COM-об’єкта

Використання бібліотеки .NET в MS Excel