REST API -dokumentaatio

VIES API REST -dokumentaatio

Johdanto

Tarjoamamme API käyttää tavallista HTTP-protokollaa. Kaikki API-toiminnot käyttävät HTTP GET -menetelmää. Jokainen funktiokutsu vaatii kyselyn valtuutuksen. Tietoa kyselyn valtuutusta varten lähetetään HTTP-otsikossa.

Tuotantopalvelu

Viesapi.eu-järjestelmän toimintoja käyttävän tahon rekisteröinti vaaditaan. Voit tehdä tämän siirtymällä kohtaan Rekisteröinti sivulle ja täytä sopiva lomake. Viesapi.eu järjestelmän käytön edellytyksenä on hyväksyntä Käyttöehdot. Täytä lomake oikein ja napsauta Rekisteröidy -painike luo tilin viesapi.eu-järjestelmään ja aktivoi sen automaattisesti.

Kun kirjaudut sisään ensimmäistä kertaa, tunniste luodaan automaattisesti vastaavan avaimen kanssa. Tunniste on julkinen eikä vaadi suojaa, kun taas avain on yksityinen, eikä sitä tule antaa kolmansien osapuolten saataville.

Tuotantopalvelun osoite: https://viesapi.eu/api

Testauspalvelu

Kaikkien jaettujen kirjastojen toimivuus voidaan tarkistaa jaetun kirjaston avulla Testaa VIES API. Testi-API:n avulla on mahdollista tarkistaa kaikki maksullisten suunnitelmien tarjoamat toiminnot ilman tarvetta luoda tiliä.

Testipalvelun osoite: https://viesapi.eu/api-test

API-rajapinnan määritelmä

Yksityiskohtainen sovellusliittymän määritelmä on saatavilla OpenAPI-yhteensopivassa muodossa, ja se voidaan ladata YAML-tiedostona tässä.

API on saatavana myös asiakasliittymänä Swagger UI.

Kyselyn suorittaminen

Esimerkki kyselyn tekemisestä testisivustolle:

GET /api-test/get/vies/euvat/PL7171642051 HTTP/1.1
Host: viesapi.eu:443
Authorization: MAC id="api_key_id", ts="unix_timestamp", nonce="random_str", mac="b64_calculated_mac_value"
User-Agent: VIESAPIClient/client_version platform_name/platform_version
Accept: mime_type

Missä:

  • api_key_id – API-avaimen tunniste (tuotantoympäristössä rekisteröinnin yhteydessä luodun tunnuksen arvo, testiympäristössä test_id:n arvo),
  • unix_timestamp – nykyinen aika sekuntimääränä ns unix aikakausi,
  • random_str – satunnainen merkkijono, jokaiselle kyselylle erilainen (vähintään 8 merkkiä, enintään 16 merkkiä),
  • b64_calculated_mac_value – laskettu HMAC (käyttäen API key, arvo test_key testiympäristössä),
  • client_version – asiakasversio (kirjastoissamme se on API-kirjastomme versio, esim. 1.2.3),
  • platform_name – API-asiakasalustan nimi (kirjastoissamme se on kirjastokielen nimi, esim. JAVA, PHP, .NET, Python),
  • platform_version – API-asiakasalustan versio (kirjastoissamme se on kirjastoympäristön versio, esim. 17 JAVA:lle tai 7.4 PHP:lle),
  • mime_type – MIME-tyypin nimi, jossa vastaus palautetaan, kahta tyyppiä tuetaan: text/xml ja application/json, jos pyyntö ei sisällä Hyväksy-otsikkoa, XML palautetaan oletuksena.

Todennuspyyntö

Lupatiedot on laadittava mukaisesti HTTP-todennus: MAC Access Authentication ja tämä on suositeltu todennusmenetelmä. On myös mahdollista käyttää HTTP-todennus: Perustodennus Käytä sitä kuitenkin turvallisuussyistä vain, jos ensimmäisen menetelmän käyttäminen ei jostain syystä ole mahdollista.

Jokainen verkkosivustollemme lähetettävä kysely on todennettu jommallakummalla kahdesta saatavilla olevasta menetelmästä.

Tapa 1 – HMAC (suositus)

Käytetty lupamenetelmä: HTTP-todennus: MAC Access Authentication. Valtuutus koostuu HMAC SHA256:n laskemisesta oikein valmistetusta merkkijonosta ja tuloksen lähettämisestä HTTP-otsikossa.

Esimerkki

HMAC-funktion syöttömerkkijono on:
ts + '\n' + nonce + '\n' + method + '\n' + path + '\n' + host + '\n' + port + '\n\n'

Missä:

  • ts – nykyinen aika sekuntimääränä ns unix aikakausi, sinun tulee aina antaa nykyinen kyselyn suoritusaika (palvelimen toleranssi +/- 10 min suhteessa nykyiseen aikaan),
  • nonce – satunnainen merkkijono, jokaiselle kyselylle erilainen (vähintään 8 merkkiä, enintään 16 merkkiä),
  • method - HTTP-menetelmän nimi (aina GET),
  • path – suoritettavan kyselyn URL-osoite,
  • host – VIES API -palvelimen nimi (aina viesapi.eu),
  • port – VIES API -palvelimen portin numero (aina 443),
  • ’\n’ – rivinvaihtomerkki (ASCII-koodi 10, 0x0A).

Testipalveluun 2019-11-25 00:00:00 UTC lähetetyn ALV-numeron PL7171642051 kyselyn HMAC-funktion syöttömerkkijono näyttää tältä:
str = "1574640000\ndt831hs59s\nGET\n/api-test/get/vies/euvat/PL7171642051\nviesapi.eu\n443\n\n"

Tämän esimerkin syöttömerkkijonotiedosto voidaan ladata tässä.

Valmistetusta merkkijonosta laskemme HMAC SHA256:n, jonka HMAC-salasanaksi annamme API key, eli testi-API:n tapauksessa arvo test_key:

HMAC_SHA256(str, "test_key") = 7776a12b958233ce60dd0f16b8d141e80472a1ee3b1e1fb136d7abe34cb59306

HMAC SHA256 -funktio palauttaa 32 binaaritavua (näkyy yllä muodossa a hex merkkijono luettavuuden vuoksi). Lataa tiedosto binääriarvolla tässä.

Lasketun HMAC:n binääriarvo tulisi koodata Base64-algoritmilla, saamme:

d3ahK5WCM85g3Q8WuNFB6ARyoe47Hh+xNter40y1kwY=

Tämä arvo tulee lähettää MAC-arvona valtuutustietojen otsikossa. Lopuksi:

Authorization: MAC id="test_id", ts="1574640000", nonce="dt831hs59s", mac="d3ahK5WCM85g3Q8WuNFB6ARyoe47Hh+xNter40y1kwY="

Linux-koneessa vaadittu MAC-arvo voidaan laskea yhdessä vaiheessa tällä komennolla:

$ echo -e -n "1574640000\ndt831hs59s\nGET\n/api-test/get/vies/euvat/PL7171642051\nviesapi.eu\n443\n\n" | openssl dgst -sha256 -hmac "test_key" -binary | openssl enc -base64

Tapa 2 – Perustodennus

Tämän käytetyn valtuutustavan määrittely: HTTP-todennus: Perustodennus.

Esimerkki 1

Base64-funktion syöttömerkkijono on:

str = key_id + ':' + key

Missä:

  • key_id – API-avaimen tunniste (jos kyseessä on testiympäristö, test_id merkkijono),
  • key – API-avain (testiympäristön tapauksessa merkkijono test_key).

Testiympäristössä Base64-funktion syöttömerkkijono on:

str = "test_id:test_key"

Base64-funktion käytön jälkeen saamme:

Base64(str) = dGVzdF9pZDp0ZXN0X2tleQ==

Tämä arvo tulee lähettää perusarvona valtuutustietojen otsikossa. Lopulta:

Authorization: Basic dGVzdF9pZDp0ZXN0X2tleQ==

Esimerkki 2

Seuraava esimerkki näyttää kyselyn, joka voidaan käynnistää kohdassa a Testiympäristö verkkoselaimesta. Kopioi ja liitä se selaimen osoitepalkkiin:

https://test_id:test_key@viesapi.eu/api-test/get/vies/euvat/PL7171642051

Missä:

  • test_id – autentikoimaan tuotannossa ympäristöön, parametrin tulee sisältää kelvollinen valtuutukseen käytetty avaintunniste,
  • test_key – autentikoimaan tuotannossa ympäristössä, 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 (API keys välilehti). See the dokumentointi sivulta saat lisätietoja tunnuksesta ja avainten luomisesta.

hanki VIESData vastaus

Jos pyyntö käsitellään oikein, syntyy seuraava vastaus:

vies api - getVIESDataParsed

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 (alkuperäinen muoto),
  • traderAddressComponent – komponenttien ryhmittelyn osoitetiedot – valinnainen attribuutti, ei koskaan palauteta tässä funktiossa.
  • id – VIES-järjestelmän luoma yksilöllinen kyselytunniste (konsultointinumero),
  • date – kyselyn suorituspäivämäärä
  • source – tietolähde, aina: http://ec.europa.eu

getVIESDataParsed vastaus

Jos pyyntö käsitellään oikein, syntyy seuraava vastaus:

vies rest API -datan jäsennetyn vastauksen

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 rekisteröintinimi (alkuperäinen muoto),
  • traderNameComponents – komponenttiryhmittymän yrityksen oikeudellinen muoto:
    • name – yrityksen nimi traderName-lomakkeella (ilman oikeudellista muotoa),
    • legalForm – oikeudellisen muodon nimi, joka on poimittu traderName-tiedoista (ilman yrityksen nimeä),
    • legalFormCanonicalId – oikeudellisen muodon sanakirjatunniste,
    • legalFromCanonicalName – oikeudellisen muodon sanakirjanimi,
  • traderCompanyType – palautti aina merkkijonon "-",
  • traderAddress – yrityksen osoite, johon yritys on rekisteröity (alkuperäinen muoto),
  • traderAddressComponent – komponenttien ryhmittelyn osoitetiedot:
    • country – kauppiaan maan nimi sen omalla kielellä,
    • postalCode – elinkeinonharjoittajan osoitteen postinumero,
    • city – elinkeinonharjoittajan osoitteen kaupunki,
    • street -elinkeinonharjoittajan osoitteen katuosoite,
    • streetNumber – elinkeinonharjoittajan osoitteen katuosoite,
    • houseNumber – elinkeinonharjoittajan osoitteen mukainen talonumero,
  • id – VIES-järjestelmän luoma yksilöllinen kyselytunniste (konsultointinumero),
  • date – kyselyn suorituspäivämäärä,
  • source – tietolähde, aina: http://ec.europa.eu
oikeudellinen lomakeKanoninen tunniste oikeudellinen lomakeKanoninen nimi kirjaston luettelonimi
0 Tuntematon TUNTEMATON
1 Yksityisyrittäjä YKSITYISOMISTAJA
2 Osakeyhtiö RAJOITETUN_VASTUUN_YHTIÖ
3 Avoin yhtiö YLEINEN_KUMPPANUUS
4 Osakeyhtiö YHTEINEN_OSAKE_YHTIÖ
5 Kommandiittiyhtiö RAJOITETTU_KUMPPANUUS
6 Yksityinen osakeyhtiö YKSITYINEN_RAJOITETTU_VASTUUSYRITYS
7 Yhden jäsenen osakeyhtiö YHDEN_JÄSENEN_YHTIÖ
8 Yksinkertainen osakeyhtiö YKSINKERTAINEN_RAJOITETTU_VASTUUSYRITYS
9 Yhden jäsenen osakeyhtiö YHDEN JÄSENEN RAJOITETTU_VASTUUSYRITYS
10 Yksinkertaistettu osakeyhtiö YKSINKERTAISTETTU_YHTEINEN_OSAKEYHTIÖ
11 Pieni yritys PIENI_YRITYS
12 Kommandiittiyhtiö RAJOITETTU_YHTEISPARTNERSHIP
13 Ammatillinen kumppanuus AMMATTIMAINEN_KUMPPANUUS
14 Kommandiittiyhtiö RAJOITETUN_VASTUUN_YHTEISÖ
15 Yksityinen kumppanuus YKSITYINEN_KUMPPANUUS
16 Osakeyhtiö Kommandiittiyhtiö RAJOITETUN_VASTUUN_YRITYKSEN_RAJOITETTU_YHTEISKUMPPANUUS
17 Osakeyhtiö Kommandiittiyhtiö RAJOITETTU_VASTUUSYHTIÖ_RAJOITETTU_YHTEISPARTNERSHIP
18 Julkinen laitos JULKINEN_LAITOS

Tärkeä vastuuvapauslauseke!

Jäsennystoiminto käyttää ulkoisia tekoälyalgoritmeja ja API:ita poimimaan automaattisesti attribuutteja, kuten: kaupunki, postinumero, katu katunumeroineen (rakennuksen numero) ja talonumero, joten emme voi taata sen 100% oikeaa toimintaa.

getVIESDataAsync vastaus

Jos pyyntö käsitellään oikein, syntyy seuraava vastaus:

VIES API saadaVIESDataAsync vastaus

Yksityiskohtainen kuvaus palautetuista määritteistä:

  • token – Viesapi.eu:n luoma batch token (guid) tulee käyttää getVIESDataAsync-funktion kutsumiseen (2-3 minuutin kuluttua) tulosten saamiseksi.

getVIESDataAsyncResult vastaus

Jos pyyntö käsitellään oikein, tulee luoda seuraava vastaus, joka sisältää luettelon objekteista, joiden tiedot VIES on palauttanut:

vies api getVIESDataAsyncResults

Yksityiskohtainen kuvaus palautetuista määritteistä:

  • numbers – joukko objekteja, joiden VIES palauttaa tulokset, jotka vastaavat getVIESDataAsync-funktion kutsupyynnössä lähetettyjä EU:n ALV-numeroita
    • 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 (alkuperäinen muoto),
    • id – VIES-järjestelmän luoma yksilöllinen kyselytunniste (konsultointinumero),
    • date – kyselyn suorituspäivämäärä
    • source – tietolähde, aina: http://ec.europa.eu
  • errors – joukko objekteja, joissa on virheitä, jotka VIES on palauttanut getVIESDataAsync-funktion kutsupyynnössä lähetetyille EU:n ALV-numerotiedoille
    • 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,
    • error – tiedot tälle tietylle EU:n ALV-numerolle palautetusta virheestä
    • date – kyselyn suorituspäivämäärä
    • source – tietolähde, aina: http://ec.europa.eu

Virhevastaus

Jos pyynnön käsittelyyn liittyy virhe, palautetaan seuraava virhesanoma:

vies rest api virhevastaus

Yksityiskohtainen kuvaus palautetuista määritteistä:

  • code – ainutlaatuinen virhekoodi automaattista virheenkäsittelyä varten,
  • description – ihmisen siepattavissa oleva virhekuvaus,
  • details – myksityiskohtainen virhekuvaus (valinnainen),

Virhekoodit

Alla olevassa taulukossa on lueteltu kaikki mahdolliset REST-sovellusliittymien ja ohjelmointikirjastojen palauttamat virheet:

Virhekoodi Virheilmoitus
8 Virheellinen pyynnön muoto
10 Virheellinen API-polku
11 Sisäinen palveluvirhe
22 EU:n ALV-numero on virheellinen
23 Tietojen hakeminen VIES-järjestelmästä epäonnistui
26 Tämä ominaisuus ei ole käytettävissä tällä hetkellä valitussa sopimuksessa
27 Tämä toiminto ei tue tätä hakutilaa
33 Annettujen tietojen kysely ei ole mahdollista testitilassa
35 Pääsykyselyn valtuutusta ei vaadita
36 Palvelu on väliaikaisesti poissa käytöstä teknisten töiden vuoksi
43 Kuluvan kuukauden käyttäjäkyselyjen määrää ei voitu hakea
54 Väärä päivämäärä tai aika käyttäjän tietokoneessa tai järjestelmässä
55 Virheellinen MAC-merkkijonoarvo otsikossa kyselyn tunnistetiedoilla
57 Virheellinen avainarvo otsikossa kyselyn tunnistetiedoilla
58 Tämän jäsenvaltion samanaikaisten kyselyjen enimmäismäärä on saavutettu
59 Hakemukseen jäsenvaltiossa ei vastata tai se ei ole saatavilla
62 Erä on edelleen käsittelyssä, yritä uudelleen myöhään
63 Eräpyyntöjen enimmäismäärä on saavutettu. Lähetä pyyntösi myöhemmin uudelleen
101 Yhteyden IP-numero ei vastaa API-avaimelle määritettyä IP-numeroa
102 API-avain on estetty
103 Virheellinen API-avain
104 Valitun suunnitelman käytettävissä olevien kyselyjen enimmäismäärä on saavutettu
105 Tili estetty tai poistettu
106 Virheellinen tilityyppi
107 Ennakkomaksutiliä ei ole maksettu
108 Virheellinen API-avaimen tunnus
201 Yhteyden muodostaminen VIES API -palveluun epäonnistui
202 VIES API -palveluvastauksen muoto on virheellinen
203 Virheellinen numerotyyppi
204 NIP on virheellinen
205 EU:n ALV-tunnus on virheellinen
206 Toiminto loi poikkeuksen
207 Päivämäärän muoto on virheellinen
208 Virheellinen syöttöparametri
209 Erän kokorajoitus ylitetty [2-99]