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

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),
  • mime_type – MIME tüübi nimi, milles vastus tuleks tagastada, toetatakse kahte tüüpi: text/xml ja application/json, kui päring ei sisalda päist Nõustu, tagastatakse vaikimisi XML.

Autentimistaotlus

Autoriseerimisandmed tuleb koostada vastavalt HTTP-autentimine: MAC-juurdepääsu autentimine ja see on soovitatav autentimismeetod. Samuti on võimalik kasutada HTTP autentimine: põhiautentimine meetod, kuid turvakaalutlustel kasutage seda ainult siis, kui esimese meetodi kasutamine pole mingil põhjusel võimalik.

Iga meie veebisaidi päring peab olema autentitud, kasutades ühte kahest saadavuse meetodist.

1. meetod – HMAC (soovitatav)

Kasutatava autoriseerimismeetodi kirjeldus: HTTP-autentimine: MAC-juurdepääsu autentimine. 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=

See väärtus tuleks saata MAC-väärtusena päises koos andmetega autoriseerimiseks. Lõpuks:

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

Linuxi masinas saab vajaliku MAC-väärtuse arvutada ühe sammuga, kasutades seda käsku:

$ 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

2. meetod – põhiautentimine

Selle kasutatud autoriseerimismeetodi spetsifikatsioon: HTTP autentimine: põhiautentimine.

Näide 1

Funktsiooni Base64 sisendstring on:

str = key_id + ':' + key

Kus:

  • key_id – API võtme identifikaator (testkeskkonna puhul test_id string),
  • key – API võti (testkeskkonna puhul string test_key).

Testkeskkonna jaoks on Base64 funktsiooni sisendstring järgmine:

str = "test_id:test_key"

Pärast funktsiooni Base64 rakendamist saame:

Base64(str) = dGVzdF9pZDp0ZXN0X2tleQ==

See väärtus tuleks saata põhiväärtusena päises koos andmetega autoriseerimiseks. Lõppkokkuvõttes:

Authorization: Basic dGVzdF9pZDp0ZXN0X2tleQ==

Näide 2

Järgmine näide näitab päringut, mida saab testkeskkonnas veebibrauserist käivitada. Lihtsalt kopeerige ja kleepige see brauseri aadressiribale:

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

Kus:

  • test_id – autentida lavastuses keskkond, peab parameeter sisaldama kehtivat autoriseerimiseks kasutatavat võtmeidentifikaatorit,
  • test_key – autentida lavastuses keskkonnas, peaks parameeter sisaldama autoriseerimiseks kasutatud võtme kehtivat väärtust.

Võtmeidentifikaatori ja võtme genereerib kasutaja pärast oma kontole sisselogimist viesapi.eu portaal (API keys vahekaart). See the dokumentatsioon leht ID ja võtme genereerimise kohta lisateabe saamiseks.

Vastus

Kui päringut käsitletakse õigesti, genereeritakse järgmine vastus:

Tagastatud atribuutide üksikasjalik kirjeldus:

  • uid – viesapi.eu loodud kordumatu päringu identifikaator,
  • countryCode – riigikood, kus päringus esitatud EL käibemaksukohustuslase numbriga seotud ettevõte on registreeritud,
  • vatNumber – päringus esitatud kontrollitud ettevõtte EL-i käibemaksukohuslase number,
  • valid – VIES-teenuse vastus, mis teavitab kontrollitava üksuse praegusest EL-i käibemaksustaatusest:
    • true – päringus esitatud EL käibemaksukohustuslase number on kehtiv,
    • false – päringus esitatud EL käibemaksukohuslase number ei ole kehtiv,
  • traderName - ettevõtte ärinimi,
  • traderCompanyType – tagastas alati '-' tähemärkide jada,
  • traderAddress - ettevõtte aadress, kus ettevõte on registreeritud,
  • id – VIES-süsteemi poolt genereeritud kordumatu päringu identifikaator
  • date - päringu täitmise kuupäev
  • source – andmeallikas, alati: http://ec.europa.eu

Vastus veale

Taotluse käsitlemisega seotud tõrke korral tagastatakse järgmine veateade:

Viga

Tagastatud atribuutide üksikasjalik kirjeldus:

  • code - unikaalne veakood automaatseks veakäsitluseks,
  • description – inimese poolt tabatav veakirjeldus,
  • details – more üksikasjalik veakirjeldus (valikuline),