EDI: Difference between revisions

From services.krediidiinfo.ee
Jump to navigation Jump to search
(Replaced content with "Teenus on suletud alates 01.01.2021")
Tag: Replaced
 
(42 intermediate revisions by 2 users not shown)
Line 1: Line 1:
= Tutvustus =
Teenus on suletud alates 01.01.2021
 
== Eesmärk ==
 
Krediidiinfo elektrooniliste dokumentide vahendusteenuse (EDI) eesmärgiks on vahendada elektroonilisi dokumente klientide infosüsteemide vahel.
 
Teenuse klientideks on mikro- ja väikeettevõtted, kelle mahud kuus ei ole suured ning kes kasutavad igapäevatööks mõnda majandustarkvara.
 
Esimeses järgus on EDI vahendusel võimalik saata vaid e-arveid, kuid tulevikus laiendatakse edastatavate dokumentide baasi.
 
== Sihtgrupp ==
 
EDI teenuse sihtgrupiks on majandustarkvara teenuse pakkujad (vahendajad). Majandustarkvara teenuse pakkujad saavad Krediidiinfo EDI teenust pakkuda edasi oma klientidele, integreerides selle oma tootesse.
 
== Eeldused ==
 
Käesolev dokumentatsioon on mõeldud vahendajate arendajatele.
 
EDI liidese disaini aitab mõista orienteerumine järgmistes valdkondades:
 
* HTTP
* REST
 
= Mõisted =
 
*'''EDI''' - Krediidiinfo elektrooniliste dokumentide vahendusteenust. Akronüüm on võetud üldisemast terminist Electronic data interchange, kuna annab hästi edasi teenuse sisu.
 
*'''klient''' - vahendaja teenust kasutav klient. Pärast vahendaja poolt registreerumist võib klient pöörduda otse EDI serveri poole.
 
*'''vahendaja''' - Majandustarkvara teenuse pakkuja, kes on oma tarkvarasse integreerinud klientidele võimaluse saata ja vastu võtta elektroonilisi dokumente läbi EDI. Vahendaja ülesanne on tuvastada klient, kliendi registreerimine EDI-s ning kliendi ja EDI liidese nõuete kohane toimimine.
 
 
= Liidese tehniline kirjeldus =
 
 
== Ülevaade ==
 
Krediidiinfo elektrooniliste dokumentide vahendusteenusega (EDI) suhtlemine toimub [https://en.wikipedia.org/wiki/Representational_state_transfer REST] liidese kaudu.
 
 
== Meediatüübid ==
 
Meediatüüp ([https://en.wikipedia.org/wiki/Media_type Media Type]) on identifikaator, mis kirjeldab ära interneti vahendusel edastatava informatsiooni tähenduse.
 
HTTP päises kasutatakse meediatüüpe parameetrites Accept ja Content-Type. Päringus saab kirjeldada täpselt mis kujul vastust soovitakse (Accept) või edastatakse (Content-Type).
 
=== Vajadus ===
 
Teoorias on EDI ülesanne lihtne, edastada ettevõtte A elektrooniline dokument D ettevõttele B. Praktikas on aga ülesanne keerulisem. Eelkõige seepärast, et üks ja sama mõiste (näiteks arve, tellimus) võib olla mitmel kujul.
 
REST põhimõtete järgi eristatakse ressurssi ja selle representatsiooni. Ressurss on näiteks arve, representatsioon on sama arve elektroonilisel kujul kas PDF, XML või JSON formaadis. Lisaks erinevatele formaatidele muutuvad ajas ka representatsioonide versioonid (näiteks on juba loodud aga pole veel kasutusse võetud E-arve XML versioon 1.2)
 
Selleks, et vahet teha erinevatel representatsioonidel (nii formaat kui versioon), kasutatakse EDI-s andmete liigutamsiel alati meediatüüpi. Kui päringu tegija saadab XML-i või JSON-it (näiteks POST-iga), siis peab ta Content-Type-s määrama meediatüübi. Kui päritakse EDI-st andmeid (näiteks müügiarvet XML kujul), siis peab päringu tegija määrama päringu päisesse Accept väljas soovitud meediatüübi.
 
Eelneva illustreerimiseks toome näited. Oletame, et soovime pärida müügiarve XML-i. Päring peab siis välja nägema selline:
 
<pre>
    GET /edi/sales-invoices/234Fxdr
    Accept: application/vnd.ki.einvoice+xml; version=1.11
</pre>
 
Ning vastuseks on:
 
<pre>
    HTTP/1.1 200 OK
    Content-Type: application/vnd.ki.einvoice+xml; version=1.11
 
    <E_Invoice><Invoice> <!-- sisu lihtsuse mõttes välja jäetud --> </Invoice></E_Invoice>
</pre>
 
application/vnd.ki.einvoice+xml; version=1.11 on EDI poolt defineeritud meediatüüp.
 
Tänu meediatüübile saab EDI server aru mis formaadis andmeid soovitakse ning vastuvõtja kuidas andmeid töödelda.
 
Oletame, et kasutaja soovib sama arvet PDF versioonis. Siis tuleb teha sama päring, aga kasutada teist meediatüüpi:
 
<pre>
    GET /edi/sales-invoices/234Fxdr
    Accept: application/pdf
</pre>
 
Ning vastuseks on:
 
<pre>
    HTTP/1.1 200 OK
    Content-Type: application/pdf
 
    /pdf-sisu/
</pre>
 
 
==Struktuur==
 
 
EDI jaoks on defineeritud oma meediatüübi nimeruum kujul '''application/vnd.ki.edi'''
 
Vajadusel lisatakse meediatüübile [https://en.wikipedia.org/wiki/Media_type#Suffix" suffiks] (+json, +xml), mis kirjeldab kasutatavat formaati.
 
 
Kõige lõppu lisatakse valikulise parameeterina (optional parameter) versiooni number.
Näide: ''application/vnd.ki.edi+json; <strong>version=1.0</strong>''.
 
 
=== Versioonide haldamine ===
 
URI-d, mis edastavad ressursi representatsiooni, peavad alati sisaldama meediatüübis valikulise parameetrina versiooni numbrit.
 
Näide:
 
<pre>
    GET /edi/clients/10256137
    Content-Type: application/vnd.ki.edi+json; version=1.0
</pre>
 
Kui päringus puudub Accept väärtus või väärtus on vale,
siis tagastatakse vastus koodiga 415 (Unknown Media Type).
 
Tänu versiooni numbrile meediatüübis on paremini juhitav EDI edasine arendamine. Kui EDI liidest täiendatakse, siis jäävad toimima seni integreeritud rakendused, sest server oskab aru saada, millise liidese versiooni vastust soovitakse.
 
 
===Kasutatavad meediatüübid===
 
 
* '''application/vnd.ki.edi''' - EDI üldine nimeruum.
* '''application/vnd.ki.einvoice+xml; version=1.11''' - Arve Eesti E-arve XML versioon 1.11 formaadis.
 
=== Veahaldus ===
 
 
Kehtivad kõik [http://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml HTTP staatuse
        koodide tähendused].
 
4xx vigade puhul on probleem päringus ning samal kujul päringut korrata ei tohi.
 
Dokumentatsioonis on iga päringu korral ära toodud kõikvõimalikud oodatavad vastuse koodid.
 
 
Üldised vea vastusekoodid, mis võivad tulla enamuse päringute puhul, on koodiga 401, 406 ja 415.
 
Vastuse kood 401 tähendab probleemi tokeniga. See on kas puudu või ei kehti enam.
 
Näide vastusest, kui päring on tehtud ilma access token'ita:
 
 
<pre>
    401 Unauthorized
    Content-Type: plain/text
    WWW-Authenticate: Bearer realm="e-invoice.krediidiinfo.ee"
 
    Access token missing in HTTP header.
</pre>
 
 
Näide vastusest kui kasutatakse kehtetud token'it:
 
<pre>
    HTTP/1.1 401 Unauthorized
    WWW-Authenticate: Bearer realm="e-invoice.krediidiinfo.ee",
    error="invalid_token",
    error_description="The access token is invalid"
    Content-Type: plain/text
 
    Invalid access token in HTTP header.
</pre>
 
Vastuse kood 406 tähendab, et päringu headeris on Accept väljas meediatüüp, mida server ei suuda tagastada.
 
Vastuse kood 415 tähendab, et POST, PUT või PATCH päringu headeris on Content-Type, millest server ei saa aru.
 
 
EDI server on rangem meediatüüpide suhtes. Näiteks Accept puhul tuleb määratleda üks konkreetne soovitud meediatüüp. Kui saadakse veakood 406 või 415, siis on esimese asjana soovitav võrrelda dokumentatsiooni näidises toodud Accept (406 korral) või Content-Type (415 korral) väärtust tegelikult kasutatuga. Samuti kontrollida, et Accept asemel ei ole kgemata kasutatud Content-Type-i ja vastupidi.
 
= Autentimine =
 
 
== Põhimõtted ==
 
Kõik päringud vajavad kasutaja autentimist.
 
Autentimine toimub ''access token''-iga, mis tuleb lisada iga HTTP päringu päises ''Authorization'' välja.
 
Näide HTTP päisest koos tokeniga ''xxxx'':
 
 
<pre>
    POST /edi/sales-invoices
    Authorization: Bearer xxxx
</pre>
 
 
Tokeni põhjal tehakse kindlaks päringu tegija ning vastavalt sellele lubatakse/keelatakse juurdepääsud ressurssidele. Näiteks kui klient teeb oma tokeniga päringu ''GET /edi/purchase-invoices'', siis on vastuseks vaid selle kliendi ostuarved, mitte kõik serveris olevad ostuarved.
 
Oluline on eristada '''vahendaja''' ja '''kliendi''' tokenit. Vahendaja saab teha päringuid kliendi andmete küsimiseks, kliendi registreerimiseks või kustutamiseks ja kliendi tokeni uuendamist. Klient saab päringuid teha vaid siis kui vahendaja on kliendi EDI-s registreerinud, uuendanud kliendi tokeni ja selle kliendile edastanud. Kui vahendaja soovib teha päringut kliendi nimel, siis peab vahendaja kasutama kliendi tokenit.
 
 
Vahendaja saab oma token-i Krediidiinfo käest pärast EDI kasutuslepingu sõlmimist.
 
 
<p style="color:red">
        Hetkel on liides beta staadiumis ning ei ole reaalses äris kasutusel. Seni kuni programm on beta staadiumis,
        on liidese proovimiseks võimalik kasutada <strong>vahendaja</strong> tokenit
        <i>xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx</i>.
        Võib lisada suvalist ettevõtet kliendiks ja saata suvalisi arveid.
        Kui programm läheb live-i, siis tühjendatakse kogu EDI sisu ja kustutatakse
        ka see avalik token.
</p>
 
Kõik tokeniga tehtavad päringud peab tegema üle HTTPS ühenduse, vältimaks man-in-the-middle rünnakut.
 
 
==Liidese kirjeldus==
 
 
EDI klientide haldamisega tegelevad vahendajad. Vahendaja ülesanne on uue kliendi registreerimine EDI-s  ning uue kliendi jaoks tokeni pärimine ja edastamine kliendile.
 
 
===POST /edi/clients===
 
Kliendi registreerimine EDI-s.
 
Vastuse koodid:
    <ul>
        <li><strong>201</strong> - klient edukalt registreeritud</li>
        <li><strong>400</strong> - viga payloadis</li>
        <li><strong>401</strong> - HTTP päises token puudu, token vigane või ei kehti enam</li>
        <li><strong>409</strong> - ei registreeritud, sest klient on juba EDI-is registreeritud.</li>
        <li><strong>415</strong> - HTTP päises ei ole <i>Content-Type</i> väärtuseks <i>application/vnd.ki.edi+json; version=1.0</i></li>
    </ul>
 
Payloadis peab määratlema registreeritava kliendi äriregistrikoodi ja riigi. Payload peab olema JSON formaadis.  Struktuur:
 
    <ul>
        <li><i>clientId</i> - EDI-sse lisatud kliendi äriregistrikood.</li>
    </ul>
    </p>
 
Näide päringust:
 
<pre>
    POST /edi/clients
    Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
    Content-Type: application/vnd.ki.edi+json; version=1.0;
 
    {"clientId":"10256137"}
</pre>
 
Vastuses on päises <i>Location</i> väärtuseks kliendi URI ning payloadis kliendi info. Payloadi struktuur:
 
    <ul>
        <li><i>clientId</i> - EDI-sse lisatud kliendi äriregistrikood.</li>
        <li><i>mediatorId</i> - kliendi lisanud vahendaja äriregistrikood.</li>
    </ul>
 
Näide vastusest:
 
<pre>
    HTTP/1.1 201 Created
    Content-Type: application/vnd.ki.edi+json; version=1.0
    Location: https://services.krediidiinfo.ee/edi/clients/10245137
 
    {"clientId":"10245137","mediatorId":"00000000"}
</pre>
 
===GET /edi/clients/{clientId}===
 
Kliendi andmete pärimine. Kasutatakse selleks, et kindlaks teha kas ja kelle poolt on klient EDI-s registreeritud.
 
Vastuse koodid:
    <ul>
        <li><strong>200</strong> - päring õnnestus, payloadis kliendi andmed</li>
        <li><strong>401</strong> - HTTP päises token puudu, token vigane või ei kehti enam</li>
        <li><strong>404</strong> - klient pole EDI-s registreeritud</li>
        <li><strong>406</strong> - HTTP päises ei ole <i>Accept</i> väärtuseks <i>application/vnd.ki.edi+json; version=1.0</i></li>
    </ul>
 
 
Näide päringust:
 
<pre>
    GET /clients/10245137
    Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
    Accept: application/vnd.ki.edi+json; version=1.0
</pre>
 
Vastuseks on kliendi andmed JSON formaadis. Struktuur:
 
    <ul>
        <li><i>clientId</i> - EDI-sse lisatud kliendi äriregistrikood.</li>
        <li><i>mediatorId</i> - kliendi lisanud vahendaja äriregistrikood.</li>
    </ul>
 
Näide vastusest:
 
<pre>
    HTTP/1.1 200 OK
    Content-Type: application/vnd.ki.edi+json; version=1.0
 
    {"clientId":"10245137","mediatorId":"00000000"}
</pre>
 
 
 
===DELETE /edi/clients/{clientId}===
 
Kliendi kustutamine EDI-st.
 
Vastuse koodid:
    <ul>
        <li><strong>204</strong> - kustutamine õnnestus</li>
        <li><strong>401</strong> - HTTP päises token puudu, token vigane või ei kehti enam</li>
        <li><strong>403</strong> - puuduvad õigused kustutada kuna klient on registreeritud teise vahendaja poolt</li>
        <li><strong>404</strong> - klienti pole EDI-s registreeritud.</li>
    </ul>
 
Näide päringust:
 
<pre>
    DELETE /edi/clients/10245137
    Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
</pre>
 
Näide vastusest:
 
<pre>
    HTTP/1.1 204 No Content
</pre>
 
 
 
===POST /edi/clients/tokens===
 
Kliendi tokeni loomine või uuendamine.
 
Vastuse koodid:
    <ul>
        <li><strong>201</strong> - tokeni uuendamine õnnestus, payloadis uus token</li>
        <li><strong>400</strong> - viga payloadis</li>
        <li><strong>401</strong> - HTTP päises token puudu, token vigane või ei kehti enam</li>
        <li><strong>404</strong> - klient pole EDI-is registreeritud</li>
        <li><strong>403</strong> - tokenit ei saa uuendada, sest klient on teise vahendaja poolt registreeritud</li>
        <li><strong>415</strong> - HTTP päises ei ole <i>Content-Type</i> väärtuseks <i>application/vnd.ki.edi+json; version=1.0</i></li>
    </ul>
 
 
Päringu payloadiks on kliendi äriregistrikood JSON formaadis. Struktuur:
 
    <ul>
        <li><i>clientId</i> - kliendi äriregistrikood</li>
    </ul>
 
 
Näide päringust:
 
<pre>
    POST /edi/clients/tokens
    Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
    Content-Type: application/vnd.ki.edi+json; version=1.0
 
    {"clientId":"10256137"}
</pre>
 
Vastuse struktuur:
    <ul>
        <li><i>token</i> - kliendi token</li>
    </ul>
 
Vahendaja peab vaastuseks saadud tokeni edastama kliendile. Selle tokeni abil saab klient ennast autentida EDI serveris.
 
Tokeni pikkus on kuni 64 tähemärki.
 
 
Näide vastusest:
 
 
<pre>
    HTTP/1.1 201 Created
    Content-Type: application/vnd.ki.edi+json; version=1.0
 
    {"token":"SmpSxVEhp1IKhbr24R6D5yAda3odN4Vh"}
</pre>
 
= E-arvete vahendus =
 
= Lisad =
 
* [https://github.com/raigu/kiediclient Näidisklient PHP-s]

Latest revision as of 10:15, 7 April 2021

Teenus on suletud alates 01.01.2021

Retrieved from "https://services.krediidiinfo.ee/wiki/index.php?title=EDI&oldid=1092"