REST API dokumentatsioon

VIES API REST 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),

Veakoodid

Allolevas tabelis on loetletud kõik võimalikud vead, mille REST API-d ja programmeerimisteegid tagastavad.

Veakood Veateade
8 Sobimatu taotluse vorming
10 Kehtetu API tee
11 Siseteenuse viga
22 EL-i KMKR number on kehtetu
23 Andmete hankimine VIES-süsteemist ebaõnnestus
26 See funktsioon pole praegu valitud plaani puhul saadaval
27 See funktsioon ei toeta seda otsingurežiimi
33 Testrežiimis ei ole antud andmete päringuid võimalik teha
35 Juurdepääsupäringu autoriseerimine pole vajalik
36 Teenus pole plaaniliste tehniliste tööde tõttu ajutiselt saadaval
43 Käesoleva kuu kasutajapäringute arvu ei õnnestunud tuua
54 Vale kuupäev või kellaaeg kasutaja arvutis või süsteemis
55 Vale MAC-stringi väärtus päringu mandaatidega päises
57 Vale võtmeväärtus päringu mandaatidega päises
58 Selle liikmesriigi samaaegsete päringute maksimaalne arv on täis
59 Liikmesriigis esitatud taotlus ei vasta või pole saadaval
101 Ühenduse IP-number ei ühti API-võtmele määratud IP-numbriga
102 API võti on blokeeritud
103 Kehtetu API võti
104 Valitud plaani jaoks saadaolevate päringute maksimaalne arv on täis
105 Konto on blokeeritud või kustutatud
106 Kehtetu konto tüüp
107 Ettemaksukontole pole tasutud
108 Kehtetu API võtme ID
201 VIES API teenusega ühenduse loomine ebaõnnestus
202 VIES API teenuse vastuse vorming on vale
203 Vale numbritüüp
204 NIP on kehtetu
205 EL-i KMKR on kehtetu
206 Funktsioon genereeris erandi
207 Kuupäeva vorming on vale
208 Vale sisendparameeter