REST API dokumentatsioon

Sissejuhatus

Meie pakutav API kasutab standardset HTTP-protokolli. Kõik API funktsioonid kasutavad HTTP GET meetodit. Iga funktsiooni kutsumine nõuab päringu autoriseerimist. Päringu autoriseerimise andmed saadetakse HTTP päises.

Tootmisteenus

Viesapi.eu süsteemi funktsionaalsust kasutada sooviva üksuse registreerimine on vajalik. Selleks minge lehele Registreerimine lehele ja täitke vastav vorm. Viesapi.eu süsteemi kasutamise eelduseks on nõustumine Kasutustingimused. Ankeedi õigesti täitmine ja nupu klõpsamine Registreeri nuppu loob konto viesapi.eu süsteemis ja selle automaatse aktiveerimise.

Esmakordsel sisselogimisel genereeritakse automaatselt identifikaator koos vastava võtmega. Identifikaator on avalik ega vaja kaitset, samas kui võti on privaatne ja seda ei tohiks kolmandatele isikutele kättesaadavaks teha.

Tootmisteenuse aadress: https://viesapi.eu/api

Testteenus

Kõigi jagatud teekide täielikku funktsionaalsust saab kontrollida jagatud teekide abil Testige VIES API-d. Test API abil on võimalik kontrollida kõiki tasulistes pakettides pakutavaid funktsioone ilma et oleks vaja kontot luua.

Testi teenindusaadress: https://viesapi.eu/api-test

API liidese määratlus

API üksikasjalik definitsioon on saadaval OpenAPI-ga ühilduvas vormingus ja selle saab alla laadida YAML-failina siin.

API on saadaval ka kliendiliidesena Swagger kasutajaliides.

Päringu täitmine

Näide testsaidile päringu tegemisest:

GET /api-test/get/vies/euvat/PL7171642051 HTTP/1.1
Saatejuht: viesapi.eu:443
Autoriseerimine: MAC id="api_key_id", ts="unix_timestamp", nonce="random_str", mac="b64_calculated_mac_value"
Kasutajaagent: VIESAPIClient/kliendi_versioon platvormi_nimi/platvormi_versioon

Kus:

  • api_key_id – API võtme identifikaator (tootmiskeskkonnas registreerimisel genereeritud identifikaatori väärtus, testkeskkonnas test_id väärtus),
  • unix_timestamp – hetkeaeg sekundite arvu kujul alates nn unixi ajastu,
  • random_str – juhuslik string, iga päringu jaoks erinev (min. 8 tähemärki, max. 16 tähemärki),
  • b64_calculated_mac_value – arvutatud HMAC (kasutades API key, väärtus test_key testkeskkonnas),
  • client_version – kliendi versioon (meie teekides on see meie API teegi versioon, nt 1.2.3),
  • platform_name – API kliendiplatvormi nimi (meie teekides on see teegi keele nimi, nt JAVA, PHP, .NET, Python),
  • platform_version – API kliendiplatvormi versioon (meie teekides on see teegikeskkonna versioon, nt JAVA jaoks 17 või PHP jaoks 7.4).

Kõik veebisaidilt tagastatud vastused on XML-vormingus.

Autentimistaotlus

Kasutatava autoriseerimismeetodi kirjeldus: HTTP-autentimine: MAC-juurdepääsu autentimine. Iga meie veebisaidi päring tuleb seda meetodit kasutades autentida. Autoriseerimine seisneb HMAC SHA256 arvutamises korralikult ettevalmistatud stringist ja tulemuse saatmises HTTP päises.

Näide

Funktsiooni HMAC sisendstring on:
ts + '\n' + nonce + '\n' + method + '\n' + path + '\n' + host + '\n' + port + '\n\n'

Kus:

  • ts – hetkeaeg sekundite arvu kujul alates nn unixi ajastu, peaksite alati esitama praeguse päringu täitmise aja (serveri tolerants +/- 10 min praeguse aja suhtes),
  • nonce – juhuslik string, iga päringu jaoks erinev (min. 8 tähemärki, max. 16 tähemärki),
  • method - HTTP-meetodi nimi (alati GET),
  • path – täidetava päringu URL-i tee,
  • host – VIES API serveri nimi (alati viesapi.eu),
  • port - VIES API serveri pordi number (alati 443),
  • ’\n’ – reavahetusmärk (ASCII kood 10, 0x0A).

KMKR-numbri PL7171642051 päringu puhul, mis saadeti testteenusele 2019-11-25 00:00:00 UTC, näeb HMAC-funktsiooni sisendstring välja järgmine:
str = "1574640000\ndt831hs59s\nGET\n/api-test/get/vies/euvat/PL7171642051\nviesapi.eu\n443\n\n"

Selle näite sisendstringi faili saab alla laadida siin.

Valmistatud stringist arvutame HMAC SHA256, mille HMAC parooliks anname API key, st test API puhul väärtus test_key:

HMAC_SHA256(str, "test_key") = 7776a12b958233ce60dd0f16b8d141e80472a1ee3b1e1fb136d7abe34cb59306

Funktsioon HMAC SHA256 tagastab 32 binaarbaiti (näidatud ülal kui a hex loetavuse jaoks). Laadige alla kahendväärtusega fail siin.

Arvutatud HMAC-i binaarne väärtus tuleks kodeerida Base64 algoritmiga, saame:

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