REST API -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
Isäntä: viesapi.eu:443
Valtuutus: MAC id="api_key_id", ts="unix_timestamp", nonce="random_str", mac="b64_calculated_mac_value"
User-Agent: VIESAPIClient/client_version alustan_nimi/alustan_versio

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. JAVA:lle 17 tai PHP:lle 7.4).

Kaikki sivuston palauttamat vastaukset ovat XML-muodossa.

Todennuspyyntö

Käytetty lupamenetelmä: HTTP-todennus: MAC Access Authentication. Jokainen verkkosivustollemme tehty kysely on todennettu tällä menetelmällä. 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=

This value should be sent as MAC value in the header with data for authorization. Finally:

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

On Linux machine required MAC value can be calculated in one step using this command:

$ 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