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

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

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

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

  • getVIESData – функція підтвердження діяльності номера ПДВ ЄС, присвоєного будь-якою з держав-членів Європейського Союзу,
  • 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);
}
// 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 – унікальний ідентифікатор запиту, згенерований системою VIES
  • 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-об’єкт, виконайте такі дії:

  1. Завантажити .NET бібліотека заархівувати та розпакувати на локальний диск у будь-яке місце.
  2. Перейдіть до каталогу з розпакованими файлами бібліотеки та знайдіть com-register.bat файл.
  3. Виберіть com-register.bat файл за допомогою миші та виберіть Run as administrator команду з контекстного меню.

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

Функції бібліотеки viesapiLibrary.dll можна використовувати в програмі MS Excel для написання власних функцій і процедур у Visual Basic мова. Щоб це стало можливим, необхідно:

  1. зареєструватися в viesapiLibrary.dll бібліотека як а COM об'єкт на Windows.
  2. Запустіть програму Excel. Виберіть DEVELOPER вкладку на стрічці, а потім клацніть Visual Basic кнопку.
  3. В Visual Basic for Application вікно, виберіть Tools і потім References з меню. В Available References список, знайдіть і виберіть VIESAPI Service Client for .NET Framework (C#). Підтвердьте свій вибір за допомогою OK кнопку.
  4. Від Insert меню, виберіть Module і вставте код функції, представлений у прикладах для Visual Basic, у нове вікно.
  5. Нарешті, відповідні значення w для viesapi.ID і viesapi.Key слід встановити. Спосіб отримання ключа та ключа доступу описано в розділі Генерація ідентифікатора та ключа доступу