Biblioteci de programare VIES

Bibliotecile de programare vă permit să căutați datele antreprenorilor pe baza numărului UE de TVA introdus. În prezent, bibliotecile API sunt disponibile pentru următoarele limbaje de programare:

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

API oferă următoarele caracteristici:

  • getVIESData – funcția de confirmare a activității numărului de TVA al UE atribuit de oricare dintre statele membre ale Uniunii Europene,
  • getVIESDataParsedfuncția de confirmare a activității numărului de TVA al UE atribuit de oricare dintre statele membre ale Uniunii Europene și de a returna adresa comerciantului analizat,
  • getVIESDataAsync – funcție asincronă, care, pe baza lotului trimis de numere de TVA, vă permite să obțineți statutul actual de TVA în UE și datele comerciantului.
  • getVIESDataAsyncResult – funcția vă permite să preluați rezultatele lotului pe baza simbolului returnat de funcția getVIESDataAsync
  • getAccountStatus – funcție de preluare a informațiilor actualizate despre contul de utilizator.

Integrare

Toate bibliotecile cu coduri sursă sunt disponibile pentru descărcare de pe Descarca pagină. În plus, codul sursă pentru biblioteci este disponibil și în depozitul nostru oficial de pe Github.

Modul de integrare a bibliotecii depinde de limbajul de programare selectat. Pentru acele limbi care acceptă gestionarea bibliotecii pe baza unui depozit central, este posibil să o utilizați.

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

Autentificare

Pentru a efectua autentificarea corectă, valorile corecte ale id și key parametrii trebuie furnizați în timpul construcției obiectului client. The id parametrul ar trebui să conțină un identificator de cheie valid utilizat pentru autorizare. The key parametrul ar trebui să conțină o valoare validă a cheii utilizate pentru autorizare. Identificatorul cheii și cheia sunt generate de utilizator după conectarea la contul său de pe viesapi.eu portal. Procesul de generare a cheilor și a identificatorilor a fost detaliat mai sus.

Următorul exemplu ilustrează modul de utilizare a funcțiilor bibliotecii:

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"

Atenţie! Ora curentă a computerului clientului este utilizată în timpul procesului de autentificare. Prin urmare, în cazul unor probleme de autentificare atunci când încercați să vă conectați la sistemul viesapi.eu, asigurați-vă mai întâi că computerul sau serverul de pe care se stabilește conexiunea are ora și fusul orar actual corect. Mai multe informații despre metoda utilizată de sistemul viesapi.eu pentru autentificarea întrebărilor pot fi găsite Aici.

Verificarea numerelor de TVA UE

Numărul de TVA al UE este confirmat apelând la getVIESData funcția, al cărei parametru este numărul de TVA al UE pe care dorim să-l verificăm. Funcția permite verificarea numerelor de TVA UE emise de toate statele membre ale Uniunii Europene.

Următorul exemplu ilustrează modul în care funcțiile sunt utilizate în biblioteci:

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

Descrierea detaliată a atributelor returnate:

  • uid – identificatorul unic de interogare generat de viesapi.eu,
  • countryCode – codul țării în care este înregistrată societatea asociată cu numărul de TVA UE furnizat în anchetă,
  • vatNumber – Numărul de TVA UE al companiei verificate furnizat în anchetă,
  • valid – răspuns din partea serviciului VIES, care informează cu privire la statutul actual de TVA UE al entității verificate:
    • true – numărul de TVA al UE furnizat în cerere este valabil,
    • false – numărul de TVA al UE furnizat în cerere nu este valid,
  • traderName – denumirea comercială a companiei,
  • traderCompanyType – a returnat întotdeauna un șir de caractere „-”,
  • traderAddress – adresa firmei la care este înregistrată societatea,
  • id – identificatorul unic de interogare generat de sistemul VIES (Numărul de consultare)
  • date – data executării interogării
  • source – sursa de date, întotdeauna: http://ec.europa.eu

Verificarea numerelor de TVA UE cu adresa comerciantului analizată

De asemenea, puteți confirma numărul de TVA al UE sunând la getVIESDataParsed funcția, al cărei parametru este numărul de TVA al UE pe care dorim să-l verificăm. Apelând această funcție, pe lângă informațiile despre statutul de contribuabil TVA, primiți și adresa comerciantului analizat.

Nota! Din cauza lipsei datelor returnate de VIES pentru comercianții din Germania și Spania, funcția o face nu se intoarce o adresă de comerciant analizată (traderAddressComponent) pentru aceste țări.

Disclaimer important

Funcția de analiză folosește algoritmi externi AI și API-uri pentru a extrage automat atribute precum: orașul, codul poștal, strada cu numărul străzii (numărul clădirii) și numărul casei, așa că nu putem garanta funcționarea corectă a lui 100%.

Următorul exemplu ilustrează modul în care funcțiile sunt utilizate în biblioteci:

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

Descrierea detaliată a atributelor returnate:

  • uid – identificatorul unic de interogare generat de viesapi.eu,
  • countryCode – codul țării în care este înregistrată societatea asociată cu numărul de TVA UE furnizat în anchetă,
  • vatNumber – Numărul de TVA UE al companiei verificate furnizat în anchetă,
  • valid – răspuns din partea serviciului VIES, care informează cu privire la statutul actual de TVA UE al entității verificate:
    • true – numărul de TVA al UE furnizat în cerere este valabil,
    • false – numărul de TVA al UE furnizat în cerere nu este valid,
  • traderName – denumirea comercială a companiei,
  • traderCompanyType – a returnat întotdeauna un șir de caractere „-”,
  • traderAddress – adresa firmei la care este înregistrată compania (format original)
  • traderAddressComponentdetaliile adresei grupării componentelor
    • country – numele țării comerciant în limba sa națională
    • postalCode – codul poștal al adresei comerciantului
    • city – orasul adresa comerciantului
    • street -strada adresei comerciantului
    • streetNumber – numărul stradal al adresei comerciantului
    • houseNumber – numarul locuintei adresei comerciantului
  • id – identificatorul unic de interogare generat de sistemul VIES (Numărul de consultare)
  • date – data executării interogării
  • source – sursa de date, întotdeauna: http://ec.europa.eu

Verificarea loturilor (asincrone) a numerelor de TVA UE

getVIESDataAsync – funcție asincronă, care, pe baza lotului trimis de numere de TVA, vă permite să obțineți statutul actual de TVA în UE și datele comerciantului.
Ca parametru, furnizați o matrice de șiruri care să conțină numere de TVA UE pentru care trebuie verificat statutul de contribuabil cu TVA în UE, iar datele utilizatorului ar trebui descărcate.

Numărul minim de numere de TVA UE trimise este 2, iar cel maxim este de 99.

O funcție numită corect returnează un token, care este necesar pentru a prelua rezultatele solicitării. Următorul exemplu ilustrează modul în care funcțiile sunt utilizate în biblioteci:

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

Datorită naturii asincrone a funcției, rezultatele pot fi preluate după aproximativ 2-3 minute. Nu contează dacă în cerere au fost trimise 2 sau 99 de numere de TVA UE.

Dacă cel puțin un număr de TVA UE transmis în cerere are un format incorect, sistemul returnează o eroare „Numărul de TVA este invalid”.

Pentru a prelua rezultatele pentru cererea trimisă, sunați la getVIESDataAsyncResult funcția, furnizând valoarea simbolului ca parametru de intrare.

Notă importantă!

  1. Funcția a fost pregătită ca o soluție pentru eroarea returnată de sistemul VIES: „The maximum number of concurrent requests has been reached” (MS_MAX_CONCURRENT_REQ). Vă recomandăm să îl utilizați atunci când trimiteți cereri pentru Germania (DE) și Franța (FR), care a returnat eroarea menționată mai sus.
  2. Până la finalizarea procesului de verificare a tuturor numerelor de TVA UE trimise în cerere, toate încercările ulterioare vor fi respinse și eroarea va fi corectată „The maximum number of batch request has been reached, please re-submit your request later“.

getVIESDataAsyncResult– funcția vă permite să preluați rezultatele lotului pe baza simbolului returnat de getVIESDataAsync funcţie.

Următorul exemplu ilustrează modul în care funcțiile sunt utilizate în biblioteci:

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

Pentru fiecare număr de TVA UE transmis în apelul de lot, atribute compatibile cu răspunsul la getVIESData funcția sunt returnate.

Preluarea informațiilor despre starea contului utilizatorului

Funcția vă permite să descărcați toate informațiile de bază despre contul de utilizator, care sunt afișate după conectarea la cont pe portalul viesapi.eu. Funcția returnează, de asemenea, informații despre numărul maxim de interogări disponibile în planul selectat (de ex. 5.000 pentru planul de afaceri) și numărul total al tuturor interogărilor efectuate în luna curentă în contul utilizatorului.

Atenţie! Apelarea funcției face nu crește numărul de interogări efectuate.

Următorul exemplu ilustrează modul de utilizare a funcțiilor bibliotecii.

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

Înregistrarea unei biblioteci .NET ca obiect COM

The viesapiLibrary.dll biblioteca poate fi înregistrată în sistemul Windows ca așa-numita COM obiect. Apoi, funcțiile bibliotecii pot fi referite din multe limbaje de programare diferite și aplicații gata făcute, inclusiv. Microsoft Excel, Access, SQL Server, Dynamics sau Visual FoxPro.

Pentru a înregistra o bibliotecă ca obiect COM, urmați acești pași:

  1. Descărcați biblioteca .NET arhivați și despachetați-l pe un disc local în orice locație.
  2. Accesați directorul cu fișiere de bibliotecă dezambalate și găsiți com-register.bat fişier.
  3. Selectează com-register.bat fișier cu mouse-ul și selectați Run as administrator comanda din meniul contextual.

Utilizarea bibliotecii .NET în MS Excel

Funcțiile bibliotecii viesapiLibrary.dll pot fi utilizate în aplicația MS Excel pentru a scrie propriile funcții și proceduri în Visual Basic limba. Pentru a face posibilă, este necesar să:

  1. Inregistreaza-te cel viesapiLibrary.dll biblioteca ca a COM obiect pe Windows.
  2. Porniți aplicația Excel. Selectează DEVELOPER pe panglică și apoi faceți clic pe Visual Basic buton.
  3. În Visual Basic for Application fereastra, selectați Tools și apoi References din meniu. În Available References listează, găsește și selectează VIESAPI Service Client for .NET Framework (C#). Confirmați selecția cu OK buton.
  4. De la Insert meniu, alege Module și lipiți codul funcției prezentat în exemplele pentru Visual Basic în noua fereastră.
  5. În cele din urmă, valorile adecvate ale lui w pentru viesapi.ID și viesapi.Key ar trebui setat. Metoda de obținere a cheii și a cheii de acces este descrisă în capitol Generarea identificatorului și a cheii de acces