A programkönyvtárak lehetővé teszik a vállalkozók adatainak keresését a megadott ÁFA EU-szám alapján. Jelenleg az API-könyvtárak a következő programozási nyelvekhez érhetők el:

• .NET (C#, Visual Basic)
• Jáva
• JavaScript (Node.js)
• PHP
• Piton
• C/C++

Az API a következő szolgáltatásokat nyújtja:

• getVIESData – az Európai Unió bármely tagállama által kiadott EU adószám tevékenységének megerősítésére szolgáló funkció,
• getAccountStatus – funkció a felhasználói fiókkal kapcsolatos naprakész információk lekérésére.

Integráció

Minden forráskóddal rendelkező könyvtár letölthető a webhelyről Letöltés oldalon. Ezen kívül a könyvtárak forráskódja is elérhető hivatalos tárhelyünkben a következő címen: Github.

A könyvtár integrálásának módja a kiválasztott programozási nyelvtől függ. Azokon a nyelveken, amelyek támogatják a központi tárhelyen alapuló könyvtárkezelést, lehetséges a használata.

// 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

Hitelesítés

A helyes hitelesítés végrehajtásához a megfelelő értékeket a id és key paramétereket kell megadni az ügyfélobjektum felépítése során. Az id paraméternek tartalmaznia kell az engedélyezéshez használt érvényes kulcsazonosítót. Az key paraméternek tartalmaznia kell az engedélyezéshez használt kulcs érvényes értékét. A kulcsazonosítót és a kulcsot a felhasználó állítja elő, miután bejelentkezett a fiókjába viesapi.eu portál. A kulcsok és azonosítók létrehozásának folyamatát fentebb részleteztük.

A következő példa bemutatja a könyvtári függvények használatát:

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"

Figyelem! A hitelesítési folyamat során az ügyfél számítógépének aktuális ideje kerül felhasználásra. Ezért ha a viesapi.eu rendszerhez való csatlakozáskor hitelesítési problémák lépnek fel, először győződjön meg arról, hogy a számítógép vagy a szerver, amelyről a kapcsolat létrejön, a megfelelő aktuális idővel és időzónával rendelkezik. A viesapi.eu rendszer által a megkeresések hitelesítésére használt módszerről bővebb információ található itt.

EU adószámok ellenőrzése

Az EU-s adószám visszaigazolása a telefonszámon történik getVIESData() függvényt, melynek paramétere az ellenőrizni kívánt EU-s áfaszám. A funkció lehetővé teszi az Európai Unió összes tagállama által kibocsátott EU adószámok ellenőrzését.

A következő példa bemutatja a függvények használatát a könyvtárakban:

// 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

A visszaadott objektum attribútumai

A visszaadott attribútumok részletes leírása:

• uid – a viesapi.eu által generált egyedi lekérdezési azonosító,
• countryCode – országkód, amelyben a megkeresésben megadott EU-adószámmal összefüggő céget bejegyezték,
• vatNumber – a megkeresésben megadott ellenőrzött cég EU adószáma,
• valid – a VIES szolgáltatás válasza, amely tájékoztat az ellenőrzött entitás aktuális EU ÁFA státuszáról:
  • true – a megkeresésben megadott EU adószám érvényes,
  • false – a megkeresésben megadott EU adószám nem érvényes,
• traderName - a cég kereskedelmi neve,
• traderCompanyType – mindig egy „-” karakterláncot adott vissza,
• traderAddress - a cég címe, ahol a cég be van jegyezve,
• id – a VIES rendszer által generált egyedi lekérdezési azonosító
• date – a lekérdezés végrehajtásának dátuma
• source – adatforrás, mindig: http://ec.europa.eu

Információk lekérése a felhasználói fiók állapotáról

A funkció lehetővé teszi a felhasználói fiókkal kapcsolatos összes alapvető információ letöltését, amely a fiókba való bejelentkezés után jelenik meg a viesapi.eu portálon. A függvény információkat ad vissza a kiválasztott terv keretében elérhető lekérdezések maximális számáról (pl. 5000 az Üzleti tervnél), valamint az aktuális hónapban a felhasználói fiókban végrehajtott összes lekérdezés számáról.

Figyelem! A függvény meghívása igen nem növeli a lekérdezések száma.

A következő példa bemutatja a könyvtári függvények használatát.

// 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-könyvtár regisztrálása COM-objektumként

Az viesapiLibrary.dll könyvtár regisztrálható a Windows rendszerben ún COM tárgy. Ekkor számos programozási nyelvből és kész alkalmazásból hivatkozhatunk a könyvtár funkcióira, pl. Microsoft Excel, Access, SQL Server, Dynamics vagy Visual FoxPro.

Egy könyvtár COM-objektumként történő regisztrálásához kövesse az alábbi lépéseket:

1. Töltse le a .NET könyvtár archiválja és csomagolja ki egy helyi lemezre tetszőleges helyre.
2. Lépjen a kicsomagolt könyvtári fájlokat tartalmazó könyvtárba, és keresse meg a com-register.bat fájlt.
3. Válaszd ki a com-register.bat fájlt az egérrel, és válassza ki a Run as administrator parancsot a helyi menüből.

A .NET könyvtár használata MS Excelben

A viesapiLibrary.dll könyvtár funkciói az MS Excel alkalmazásban használhatók saját függvények és eljárások írására a Visual Basic nyelv. Ahhoz, hogy ez lehetséges legyen, szükséges:

1. Regisztráció az viesapiLibrary.dll könyvtár, mint a COM tárgy be Windows.
2. Indítsa el az Excel alkalmazást. Válaszd ki a DEVELOPER fület a szalagon, majd kattintson a gombra Visual Basic gomb.
3. Ban,-ben Visual Basic for Application ablakban válassza ki Tools és akkor References menüből. Ban,-ben Available References listázza, keresse meg és válassza ki VIESAPI Service Client for .NET Framework (C#). Erősítse meg választását a gombbal OK gomb.
4. Tól Insert menüből válassza ki Module és illessze be a Visual Basic példáiban bemutatott függvénykódot az új ablakba.
5. Végül a megfelelő w értékei viesapi.ID és viesapi.Key be kell állítani. A kulcs és a hozzáférési kulcs megszerzésének módját a fejezet ismerteti Az azonosító és a hozzáférési kulcs generálása