Ohjelmointikirjastojen avulla voit etsiä yrittäjätietoja syötetyn ALV-numeron perusteella. Tällä hetkellä API-kirjastot ovat saatavilla seuraaville ohjelmointikielille:

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

API tarjoaa seuraavat ominaisuudet:

• getVIESData – toiminto, jolla varmistetaan minkä tahansa Euroopan unionin jäsenvaltion myöntämän EU:n ALV-numeron toiminta,
• getAccountStatus –toiminto, joka hakee käyttäjätiliä koskevia ajantasaisia tietoja.

Liittäminen

Kaikki kirjastot lähdekoodeilla ovat ladattavissa osoitteessa ladata sivu. Lisäksi kirjastojen lähdekoodi on saatavilla myös virallisessa arkistossamme osoitteessa Github.

Kirjaston integrointitapa riippuu valitusta ohjelmointikielestä. Niille kielille, jotka tukevat kirjastojen hallintaa keskustietovaraston perusteella, on mahdollista käyttää sitä.

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

Todennus

Oikean todennuksen suorittamiseksi oikeat arvot id ja key parametrit tulee antaa asiakasobjektin rakentamisen aikana. The id parametrin tulee sisältää kelvollinen valtuutuksessa käytetty avaintunnus. The key parametrin tulee sisältää valtuutukseen käytetyn avaimen kelvollinen arvo. Käyttäjä luo avaimen tunnisteen ja avaimen kirjautuessaan sisään tililleen viesapi.eu portaali. Avainten ja tunnisteiden luontiprosessi on kuvattu yksityiskohtaisesti edellä.

Seuraava esimerkki havainnollistaa kirjastotoimintojen käyttöä:

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"

Huomio! Todennusprosessissa käytetään asiakkaan tietokoneen nykyistä aikaa. Siksi, jos todennusongelmia yritetään muodostaa yhteyttä viesapi.eu-järjestelmään, varmista ensin, että tietokoneella tai palvelimella, josta yhteys muodostetaan, on oikea aika ja aikavyöhyke. Lisätietoja viesapi.eu-järjestelmän käyttämästä tiedustelujen todentamismenetelmästä löytyy tässä.

EU:n ALV-numeroiden tarkistaminen

EU:n ALV-numero vahvistetaan soittamalla numeroon getVIESData() -toiminto, jonka parametri on EU:n ALV-numero, jonka haluamme varmistaa. Toiminto mahdollistaa kaikkien Euroopan unionin jäsenvaltioiden myöntämien EU-alv-numeroiden tarkistamisen.

Seuraava esimerkki havainnollistaa funktioiden käyttöä kirjastoissa:

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

Palautetun objektin attribuutit

Yksityiskohtainen kuvaus palautetuista määritteistä:

• uid – Viesapi.eu:n luoma yksilöllinen kyselytunniste,
• countryCode – maakoodi, johon tiedustelussa ilmoitettuun EU:n ALV-numeroon liittyvä yritys on rekisteröity,
• vatNumber – kyselyssä ilmoitetun varmennetun yrityksen EU-alv-numero,
• valid – vastaus VIES-palvelusta, joka kertoo tarkastetun yksikön nykyisestä EU-arvonlisäverotilasta:
  • true – tiedustelussa annettu EU:n ALV-numero on voimassa,
  • false – kyselyssä annettu EU:n ALV-numero ei ole kelvollinen,
• traderName – yrityksen toiminimi,
• traderCompanyType – palautti aina merkkijonon "-",
• traderAddress – yrityksen osoite, johon yritys on rekisteröity,
• id – VIES-järjestelmän luoma yksilöllinen kyselytunniste
• date – kyselyn suorituspäivämäärä
• source – tietolähde, aina: http://ec.europa.eu

Haetaan tietoja käyttäjän tilin tilasta

Toiminnon avulla voit ladata kaikki käyttäjätilin perustiedot, jotka näkyvät tilille kirjautumisen jälkeen viesapi.eu-portaalissa. Toiminto palauttaa myös tiedot valitussa suunnitelmassa käytettävissä olevien kyselyjen enimmäismäärästä (esim. Liiketoimintasuunnitelmassa 5 000) ja kaikkien kuluvan kuukauden aikana tehtyjen kyselyjen kokonaismäärästä käyttäjän tilillä.

Huomio! Toiminnon kutsuminen tekee ei lisäänny tehtyjen kyselyiden määrä.

Seuraava esimerkki havainnollistaa kirjastotoimintojen käyttöä.

// 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-kirjaston rekisteröinti COM-objektiksi

The viesapiLibrary.dll kirjasto voidaan rekisteröidä Windows-järjestelmään ns COM esine. Tällöin kirjaston toimintoihin voidaan viitata useista eri ohjelmointikielistä ja valmiista sovelluksista, mm. Microsoft Excel, Access, SQL Server, Dynamics tai Visual FoxPro.

Voit rekisteröidä kirjaston COM-objektiksi seuraavasti:

1. Lataa .NET-kirjasto arkistoi ja pura se paikalliselle levylle mihin tahansa paikkaan.
2. Mene hakemistoon, jossa on pakkaamattomia kirjastotiedostoja ja etsi com-register.bat tiedosto.
3. Valitse com-register.bat tiedosto hiirellä ja valitse Run as administrator komento pikavalikosta.

.NET-kirjaston käyttäminen MS Excelissä

ViesapiLibrary.dll-kirjaston toimintoja voidaan käyttää MS Excel -sovelluksessa omien toimintojen ja menettelyjen kirjoittamiseen Visual Basic Kieli. Jotta se olisi mahdollista, on välttämätöntä:

1. Rekisteröidy the viesapiLibrary.dll kirjasto kuten a COM esine päällä Windows.
2. Käynnistä Excel-sovellus. Valitse DEVELOPER -välilehti nauhassa ja napsauta sitten Visual Basic -painiketta.
3. Vuonna Visual Basic for Application ikkuna, valitse Tools ja sitten References valikosta. Vuonna Available References luettelo, etsi ja valitse VIESAPI Service Client for .NET Framework (C#). Vahvista valintasi painamalla OK -painiketta.
4. alkaen Insert valikko, valitse Module ja liitä Visual Basicin esimerkeissä esitetty toimintokoodi uuteen ikkunaan.
5. Lopuksi sopivat w:n arvot for viesapi.ID ja viesapi.Key pitäisi asettaa. Avaimen ja pääsyavaimen hankintatapa kuvataan luvussa Tunnisteen ja pääsyavaimen luominen