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ää testiympäristössä 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.

Vastaus

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

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

Virhevastaus

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

Virhe

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