Tehniline dokumentatsioon e-arveldaja API arendajale

21.11.2022

Järgmised alampunktid on mõeldud arendajale, kes soovib e-arveldaja APIga liidestuda.

Liidestamise käigus tekkinud tehnilistel küsimustel palume pöörduda @email   

 

API ressursid/teenused

Pakutavad teenused ja nende kasutatavad andmestruktuurid on kirjeldatud kasutades OpenAPI spetsifikatsiooni versiooni 3.1 YAML formaadis. Tegemist on JSON-in JSON-out RESTful teenustega.

API rakendusserveri aadress:

DEMO: https://demo-rmp-api.rik.ee (testimiseks saab kasutada demo/koolitus ühinguid)

LIVE: https://rmp-api.rik.ee

Päringud tuleb saata korrektse adapteri versiooni suunas, nt rakendusserveri aadressil /v1

Teenuste värskeim kirjeldus on saadaval API rakendusserverist aadressil /openapi.yaml

Dokumentatsiooni HTML versioon (kättesaadav ainult inglise keeles) on mh kättesaadaval API rakendusserverist aadressil /api.html

Testleht, päringute kontrollimiseks (sisaldab ka muuhulgas võtmest headerite genereerimise võimekust) kätte saadav API rakendusserverist aadressil /test.html

 

API äriloogiline töövoog

Äriloogiline töövöög, mis leiab aset rakenduskihis, sõltub konkreetsest päringust ja seda hõlmavast kasutusjuhust. Tüüpprotsess jaotub järgmisteks sammudeks:

  • Liidestuva infosüsteemi autentimine ja autoriseerimine – päringu päises olevat ApiKey-d kontrollitakse süsteemis registreeritud andmete vastu. Kui sellist ApiKey-d ei eksisteeri või see ei ole lubatud väliselt IP aadressilt, logitakse negatiivne juurdepääsusündmus. Piisava arvu negatiivsete juurdepääsusündmuste esinemisel etteantud ajavahemikus blokeeritakse juurdepääs väliselt IP aadressilt teatud perioodiks. Kui ApiKey on olemas ja korrektne, lubatakse päringu töötlusel jätkuda.
  • Käivitatava teenuse tuvastamine URList – API tuvastab ruutingutabeli põhjal käivitatava teenuse või selle puudumisel tagastab vea.
  • Päring valideeritakse kasutatava teenuse OpenAPI spetsifikatsiooni vastu – sisendi vorming (üldreeglina puudub või JSON andmestik), sisu ja struktuur (kohustuslikud ja lubatud väljad jne). Spetsifikatsioonile mittevastavad päringud lükatakse veaga tagasi.
  • Teenus teostab sisendile vastavad andmepäringud ja -töötlused.
  • Teenus tagastab JSON kujul vastuse või erandjuhul (kui päringu vastuseks on üks fail) vastava faili vahetul binaarkujul standardse HTTP vastusena.

 

Päringute autentimine ja autoriseerimine

API teenustele annab ligipääsu ApiKey „võti“, mida e-arveldajat kasutav ettevõte saab genereerida e-arveldaja seadistusmoodulis

Iga ApiKey võtme avalik osa sisaldab unikaalset identifikaatorit ja krüptograafilist „allkirja“ brute-force identifikaatorite ära-arvamise võimaluse tõrjumiseks. ApiKey võtme „salasõna“ osa kasutatakse päringu signeerimiseks (replay rünnakute ärahoidmiseks). Lisaks sisaldab e-arveldaja andmebaas ApiKey kohta täiendavat privaatset infot, nt lubatud IP aadresse jms.

Iga päring API teenustele peab sisaldama X-AUTH-QUERYTIME nimelist HTTP päist, mis sisaldab sekundilise täpsusega päringu teostamise kellaaega UTC ajatsoonis (nt: 2011-11-04T00:05:23).

Iga päring API teenustele peab sisaldama X-AUTH-KEY nimelist HTTP päist, mis sisaldab kooloniga eraldatult:

  • ApiKey avalik võti, mis on tõstutundlik ja tuleb edastada täpselt e-arveldajas esitatud kujul
    (nt: RWksIHNpaW4gdGVnZWxpa3VsdCBlaSBvbGUgcGFyaXMgQXBpS2V5LWQsIGFnYSB0dWJsaSBrYXRzZS4gSmFyZ21pc2VzIHR1a2lzIG9uIGphcnNrdSBtaWRhZ2kgaHV2aXRhdmFtYXQ=);
  • Päringu signatuuri BASE64(HMAC-SHA-384(„apikeyid:aeg:url“, ApiKeySalasõna)), kus:
    • apikeyid on ApiKey unikaalne identifikaator
      (esitatud e-arveldajas, nt: 530156f2101045438c8c3513eed6e893)
    • aeg on X-AUTH-QUERYTIME päises edastatav päringu teostamise aeg
    • url on pöördutava teenuse absoluutne path
      ilma protokolli ja serverikomponendita, nt: /v1/journals/62307/document_user)
    • ApiKeySalasõna on e-arveldajas esitatud ApiKey salasõna.

Nt: RWksIHNpaW4gdGVnZ…Wxpa3RhZ2kgaHV2aXRhdmFtYXQ=:6JMLK6Gt…KJmbTWrCs/XcCaSV

Kui API teenustesse saabub uus päring, millel puudub X-AUTH-KEY päis, tagastatakse HTTP 401 veakood.

API pärib andmebaasist unikaalse identifikaatori põhjal ApiKey privaatsed andmed ning kontrollib ApiKey-s sisalduvat krüptograafilist „allkirja“ süsteemi andmete vastu. Kui ApiKey ei ole kehtiv mis iganes põhjusel, logitakse negatiivne juurdepääsusündmus ja tagastatakse HTTP 401 veakood.

Kui päringus puudub X-AUTH-QUERYTIME päis või päringu teostamise aeg erineb serveri ajast kummaski suunas 5 või enam minutit, logitakse negatiivne juurdepääsusündmus ja tagastatakse HTTP 401 veakood.

Kui päringu signatuur ei ole kehtiv, logitakse negatiivne juurdepääsusündmus ja tagastatakse HTTP 401 veakood.

Kui päringu allikaks olevat IP aadressilt on etteantud perioodis logitud rohkem kui etteantud arv negatiivseid juurdepääsusündmusi, blokeeritakse päring etteantud ajaks sõltumata millestki muust, sh päises olla võivast pädevast ApiKey väärtusest. Seda tehakse brute-force ära-arvamisrünnete vältimiseks. Logitakse negatiivne juurdepääsusündmus ja tagastatakse HTTP 401 veakood.

 

Kontrollperiood Min. neg. sündmuste arv Blokeeritud periood
Viimased 5 minutit     10

 Kuni negatiivsete sündmuste arv langeb alla kõigi piiride
Viimased 60 minutit     30  Kuni negatiivsete sündmuste arv langeb alla kõigi piiride
Viimased 24 tundi     60

 Kuni negatiivsete sündmuste arv langeb alla kõigi piiride

Muudel juhtudel käivitatakse API teenus.

 

Päringute logimine

Ettevõtte esindusõiguslik isik saab autenditud (edukate) päringute logiga tutvuda kasutajaliidese kaudu API võtmete halduses.

 

API võtmete haldus kasutajaliideses

API võtmeid saab ettevõtte esindusõiguslik isik hallata Seadistuste mooduli Üldised seadistused vaates.

api2

Kasutaja saab siit:

  • lisada uusi API võtmeid;
  • muuta olemasolevate võtmete üldandmeid (nimi, ligipääsetavad funktsioonid ja lubatud IP aadressid);
  • laadida alla olemasolevate võtmete avalikke võtmeid (ApiKey avalik võti);
  • vaadata võtmete kasutus ajalugu;
  • kustutada võtmeid.