EDI
Tutvustus
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 REST liidese kaudu.
Meediatüübid
Meediatüüp (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:
GET /edi/sales-invoices/234Fxdr
Accept: application/vnd.ki.einvoice+xml; version=1.11
Ning vastuseks on:
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>
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:
GET /edi/sales-invoices/234Fxdr
Accept: application/pdf
Ning vastuseks on:
HTTP/1.1 200 OK
Content-Type: application/pdf
/pdf-sisu/
Struktuur
EDI jaoks on defineeritud oma meediatüübi nimeruum kujul application/vnd.ki.edi
Vajadusel lisatakse meediatüübile " 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; version=1.0.
Versioonide haldamine
URI-d, mis edastavad ressursi representatsiooni, peavad alati sisaldama meediatüübis valikulise parameetrina versiooni numbrit.
Näide:
GET /edi/clients/10256137
Content-Type: application/vnd.ki.edi+json; version=1.0
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:
401 Unauthorized
Content-Type: plain/text
WWW-Authenticate: Bearer realm="e-invoice.krediidiinfo.ee"
Access token missing in HTTP header.
Näide vastusest kui kasutatakse kehtetud token'it:
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.
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.