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 (kasutadesAPI key
, väärtustest_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 (alativiesapi.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