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
 
(12 intermediate revisions by one other user not shown)
Line 1: Line 1:
= Tutvustus =
Teenus on suletud alates 01.01.2021
 
== Eesmärk ==
 
Creditinfo 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 Creditinfo 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''' - Creditinfo 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 ==
 
Creditinfo elektrooniliste dokumentide vahendusteenusega (EDI) suhtlemine toimub [https://en.wikipedia.org/wiki/Representational_state_transfer REST] liidese kaudu.
 
Creditinfo EDI asub serveris services.krediidiinfo.ee, suhtlemine toimub ainult üle HTTPS-i.
 
== 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 võib tulevikus tulla E-arve XML versiooniga 1.3).
 
Selleks, et vahet teha erinevatel representatsioonidel (nii formaat kui versioon), kasutatakse EDI-s andmete liigutamisel alati meediatüüpi. Kui päringu tegija saadab XML-i või JSON-it (näiteks POST-iga), siis peab ta alati määrama Content-Type-s 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.
* '''application/vnd.ki.einvoice+xml; version=1.2''' - Arve Eesti E-arve XML versioon 1.2 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.
 
== Testkeskkond ==
 
 
Testimiseks ja arendamiseks on eraldi testserver serveris katseklaas.krediidiinfo.ee. Ehk siis kui tavapärane URI-i on https://services.krediidiinfo.ee/edi/purchase-invoices, siis testserveri poole pöördumisel tuleb kasutada hoopis http://katseklaas.krediidiinfo.ee/edi/purchase-invoices.
 
Testserveri kasutamiseks on vaja küsida Creditinfo käest vahendaja tokenit testserverisse.
 
= 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.
 
Vahendajad saavad tokeni Creditinfo käest pärast EDI kasutuslepingu sõlmimist ning see saadetakse krüpteeritult. Selle tokeniga saab vahendaja registreerida kliente ja küsida või uuendada kliendi tokenit.
 
 
'''<span style="color:red">Token tuleb hoida saladuses</span>''', sest selle põhjal toimub päringu tegija autentimine ja autoriseerimine. Teades vahendaja tokenit võib vahendaja nimel suvalisi kliente registreerida või eemaldada. Samuti peavad klientide tokenid olema salvestatud turvaliselt ning selle eest vastutab vahendaja. Kõik tokeniga seotud päringud peavad toimuma üle HTTPS ühenduse, et vältida ''man-in-the-middle'' rünnakut.
 
Kui pöördute abi saamiseks Creditinfo tehnilise toe poole ning e-postiga on vaja saata HTTP päringu päis ja keha, siis eemaldage saadetavatest andmetest tokenid. Creditinfo ei küsi kunagi kogu teie tokenit, vajadusel võib Creditinfo küsida silumisel vaid kolme esimest ja/või viimast sümbolit.
 
==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>
 
 
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 vahendamine =
 
 
== Sissejuhatus ==
 
E-arveid saavad saata või vastu võtta vaid need kliendid, kes on EDI-is registreeritud.
 
EDI-s saavad oma kliente registreerida vahendajad. Pärast registreerimist peavad vahendajad pärima ka <i>access tokeni</i> ning edastama selle kliendile.
 
Näidistes on kliendi access tokenina kasutatud stringi ''yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy''. Tegelikus rakenduses tuleb see asendada õige tokeniga.
 
 
== Müügiarvete saatmine ==
 
Müügiarve saatmine koosneb kolmest etapist. Etapid on kujutatud all oleval järgnevusdiagrammil:
 
[[File:Send-sales-invoice-sequence-diagram.png]]
 
=== HEAD /edi/purchase-invoices/receivers/{receiverId} ===
 
Kas kliendile saab EDI kaudu e-arvet saata?
 
''receiverId'' on kliendi äriregistrikood, kelle kohta soovitakse teada, kas e-arvet saab saata või mitte.
 
Vastuse koodid:
    <ul>
        <li><strong>200</strong> - kliendile saab EDI kaudu e-arvet saata.</li>
        <li><strong>404</strong> - kliendile ei saa EDI kaudu e-arvet saata.</li>
    </ul>
 
Näide päringust:
 
<pre>
    GET /edi/purchase-invoices/receivers/10245137
</pre>
 
 
Näide vastusest:
<pre>
    HTTP/1.1 200 OK
</pre>
 
 
NB! See päring ei vaja autentimist!
 
Mõistlik on päringu tegemisel kasutada HEAD meetodit, sest päringu vastuse sisu pole tähtis (info saab kätte vastuse koodist) ning HEAD päringute korral on paremad võimalused kasutada ära puhverserverite võimalusi.
 
 
===POST /edi/sales-invoices===
 
E-arve XML-i üles laadimine EDI serverisse.
 
Vastuste koodid:
    <ul>
        <li><strong>201</strong> - müügiarve salvestamine õnnestus.
            Vastuse päises on väljas <i>Location</i> müügiarve URI.
        </li>
        <li><strong>400</strong> - payloadis olev e-arve ei valideeru.</li>
        <li><strong>401</strong> - HTTP päises kliendi token puudu, token vigane või ei kehti enam</li>
        <li><strong>413</strong> - payload liiga suur. Lubatud on maksimaalselt 1MB.</li>
        <li><strong>415</strong> - HTTP päises ei ole <i>Content-Type</i> väärtuseks <i>application/vnd.ki.invoice+xml;
                version=1.11</i></li>
    </ul>
 
Lubatud ''Content-Type'' väärtused:
* '''application/vnd.ki.einvoice+xml; version=1.11'''
* '''application/vnd.ki.einvoice+xml; version=1.2'''
 
HTTP päringu payloadiks on E-arve XML-i (versioon 1.11).
 
Näide päringust:
 
<pre>
POST /edi/sales-invoices
Content-Type: application/vnd.ki.einvoice+xml; version=1.11
Authorization: Bearer yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy
 
&lt;E_Invoice&gt;
  &lt;Invoice&gt;
    &lt;!-- e-arve sisu --&gt;
  &lt;/Invoice&gt;
&lt;/E_Invoice&gt;
</pre>
 
Näide vastusest:
 
<pre>
    HTTP/1.1 201 Created
    Location: https://services.krediidiinfo.ee/edi/sales-invoices/23423
</pre>
 
 
EDI-sse üles laetavad XML-id ei tohi olla suuremad kui 1MB.
 
201 vastuse korral on päises väljas ''Location'' müügiarve URI EDI-s. Selle URI pihta saab teha HEAD päringu ning kontrollida, kas arve saaja on arve juba kätte saanud või mitte. Kui HEAD  päringu vastuseks on 200, siis pole arvet kätte saadud. Kui päringu vastuseks on 404, siis on arve saaja arve kätte saanud ja EDI serverist kustutanud.
 
===GET /edi/sales-invoices/{invoiceId}===
 
Kontrollpäring tegemaks kindlaks kas arve saaja on arve kätte saanud.
 
URI saadakse ''POST /edi/sales-invoices'' vastuse päisest ''Location'' parameetrist.
 
Vastuste koodid:
    <ul>
        <li><strong>200</strong> - arve pole veel jõudnud adressaadini.</li>
        <li><strong>401</strong> - HTTP päises kliendi token puudu, token vigane või ei kehti enam</li>
        <li><strong>404</strong> - arve on jõudnud aadresaadini</li>
    </ul>
 
 
Päring tagastab tühivastuse, seega võib teha HEAD päringu.
 
Arve saaja on kohustatud pärast arve kätte saamist kustutama arve EDI-st. Seega kui arve on kustutatud, siis järelikult võib selle lugeda kohale jõudnuks.
 
Näide päringust:
 
<pre>
    HEAD /edi/sales-invoices/23423
    Authorization: Bearer yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy
</pre>
 
 
Näide vastusest:
 
<pre>
    HTTP/1.1 200 OK
</pre>
 
==Ostuarvete vastuvõtmine==
 
 
[[File:Receive-purchase-invoices-sequence-diagram.png]]
 
 
===GET /edi/purchase-invoices===
 
EDI-s olevate ostuarvete pärimine.
 
Vastuste koodid:
    <ul>
        <li><strong>200</strong> - serveris olevate ostuarvete URI-de massiiv JSON formaadis.</li>
        <li><strong>401</strong> - HTTP päises kliendi token puudu, token vigane või ei kehti enam</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>
 
 
Vastuseks on EDI-is olevate ostuarvete URI-de massiiv JSON formaadis.
 
Arvete URI-d on sorteeritud saabumise järjekorras, so varem saabunud asuvad eespool.
 
Korraga ei tagastata kõiki EDI-s olevaid ostuarveid, massiivi pikkus limiteeritakse dünaamiliselt vastavalt koormusele.
 
Arve saaja on kohustatud pärast arve alla laadimist kustutama ostuarve EDI-st. Kui vanemad eest kustutatakse, siis tulevad päringusse välja uuemad.
 
Näide päringust:
 
<pre>
    GET /edi/purchase-invoices
    Authorization: Bearer yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy
    Accept: application/vnd.ki.edi+json; version=1.0
</pre>
 
 
Näide vastusest:
 
<pre>
    HTTP/1.1 200 OK
    Content-Type: application/vnd.ki.edi+json; version=1.0
 
    ["https://services.krediidiinfo.ee/edi/purchase-invoices/23423", https://services.krediidiinfo.ee/edi/purchase-invoices/29092"]
</pre>
 
 
 
Kui EDI-s ostuarved puuduvad, siis on vastuseks tühimassiiv. Näide:
 
<pre>
    HTTP/1.1 200 OK
    Content-Type: application/vnd.ki.edi+json; version=1.0
 
    []
</pre>
 
 
Vastuses olevate URI-dega saab alla laadida ostuarve XML-i ja kustutada ostuarvet EDI-ist.  Alla laadimine toimub HTTP GET meetodiga (vt GET /edi/purchase-invoices/{invoiceId}) ja kustutamine HTTP DELETE (vt DELETE /edi/purchase-invoices/{invoiceId}) meetodiga.
 
===GET /edi/purchase-invoices/{invoiceId}===
 
Ostuarve alla laadimine.
 
Vastuste koodid:
    <ul>
        <li><strong>200</strong> - payloadis arve soovitud formaadis.</li>
        <li><strong>401</strong> - HTTP päises kliendi token puudu, token vigane või ei kehti enam</li>
        <li><strong>403</strong> - päring keelatud, ostuarve on teise kliendi oma.</li>
        <li><strong>404</strong> - müügiarvet EDI serveris ei leitud.</li>
        <li><strong>406</strong> - Server ei suuda saata vastust, mida klient on soovinud <i>Accept</i> parameetriga.
            Praegu toetakse ainult meediatüüpi <i>application/vnd.ki.einvoice+xml; version=1.11</i> (Tulevikus on plaan
            sama liidese kaudu lubada ka PDF versiooni küsimist, sellisel juhul peab Accept väärtuseks olema
            application/pdf).
    </ul>
 
Lubatud ''Accept'' väärtused:
* application/vnd.ki.einvoice+xml
* application/vnd.ki.einvoice+xml; version=1.11
* application/vnd.ki.einvoice+xml; version=1.2
* application/pdf
 
Päringuks kasutatav URI saadakse päringu <i>GET /edi/purchase-invoices</i> payloadist.
 
Näide ostuarve XML-i alla laadimise päringust:
 
<pre>
    GET /edi/purchase-invoices/23423
    Authorization: Bearer yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy
    Accept: application/vnd.ki.einvoice+xml;
</pre>
 
Näide vastusest:
 
<pre>
    HTTP/1.1 200 OK
    Content-Type: application/vnd.ki.einvoice+xml; version=1.11
 
    &lt;E_Invoice&gt;
      &lt;Invoice&gt;
      &lt;!-- e-arve sisu --&gt;
      &lt;/Invoice&gt;
    &lt;/E_Invoice&gt;
</pre>
 
Päringu päises ''Accept'' tuleb anda ette meediatüüp mida päringu saaja suudab töödelda.
 
Soovituslik on kasutada meediatüüpi ''application/vnd.ki.einvoice+xml'' (ilma versiooni numbrita!). Sellisel juhul tagastatakse e-arve selles formaadis nagu saatja selle saatis. Content-Type-is on määratud sisu meediatüüp koos versiooni numbriga ning vastuvõtja peab alati kontrollima, kas ta suudab vastavat versiooni töödelda või mitte. Kui ei, siis jääb veel võimalus proovida pärida arve PDF versiooni. Selline lähenemine tagab, et arvete vastuvõtmine jääb toimima ka siis kui osad kasutajad on läinud üle uuele e-arve versioonile.
 
 
Lisaks XML kujule saab küsida ka arve PDF versiooni.
 
<pre>
    Accept: application/pdf
</pre>
 
Kui EDI ei suuda pärinut täita (saatja ei ole PDF versiooni kaasa pannud), siis tagastatakse vastusena 406.
 
===DELETE /edi/purchase-invoices/{invoiceId}===
 
Ostuarve kustutamine EDI-st.
 
URI saadakse päringu <i>GET /edi/purchase-invoices</i> payloadist.
 
Vastuste koodid:
    <ul>
        <li><strong>204</strong> - ostuarve kustutamine õnnestus.</li>
        <li><strong>401</strong> - HTTP päises kliendi token puudu, token vigane või ei kehti enam</li>
        <li><strong>403</strong> - päring keelatud, ostuarve on teise kliendi oma.</li>
        <li><strong>404</strong> - müügiarvet EDI serveris ei leitud.</li>
    </ul>
 
Näide päringust:
 
<pre>
    DELETE /edi/purchase-invoices/23423
    Authorization: Bearer yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy
</pre>
 
Näide vastusest:
 
<pre>
    HTTP/1.1 204 No Content
</pre>
 
== Arve PDF formaadis ==
 
E-arve ver 1.2 XML-i saab lisada arve pdf formaadis.
 
Näide:
 
<pre>
&lt;?xml version="1.0" encoding="UTF-8"&gt;
&lt;E_Invoice xsi:noNamespaceSchemaLocation="e-invoice_ver1.2.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"&gt;
    &lt;Invoice&gt;
        &lt;!-- arve andmed näite lihtsuse huvides välja jäetud --&gt;
        &lt;AttachmentFile&gt;
            &lt;FileBase64&gt;base64 encoded binary data of PDF&lt;/FileBase64&gt;
        &lt;/AttachmentFile&gt;
    &lt;/Invoice&gt;
&lt;/E_Invoice&gt;
</pre>
 
= Lisad =
 
== cURL ==
 
Üks võimalik viis EDI liidesega suhelda otse käsurealt testimise eesmärgil on CLI programmiga [https://en.wikipedia.org/wiki/CURL cURL].
 
 
Näide 1:
<pre>
    $> curl -i "https://katseklaas.krediidiinfo.ee/edi/clients/tokens" -X POST -d '{"clientId": "10256137"}' -H "Authorization: Bearer zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz" -H "Content-Type: application/vnd.ki.edi+json; version=1.0"
</pre>
 
Päringus tuleb ''zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz'' asendada õige tokeniga (vastavalt meetodile kas vahendaja või kliendi oma!).
 
Võtmete selgitused:
* ''-i'' annab korralduse trükkida konsoolile nii vastuse päis kui payload.
* -X POST teha POST päring. Kui on vaja teha GET päring, siis võib ära jätta. DELETE korral asendada POST DELETE-ga.
* -d päringu payload Content-Type formaadis. Võib ära jätta kui päring ei nõua.
* -H päringu päise lisamine.
 
 
Näide 2 (toimib ka ilma tokenita):
 
<pre>
    $> curl -i "https://katseklaas.krediidiinfo.ee/edi/purchase-invoices/receivers/10245137"
</pre>
 
ja vastus:
 
<pre>
HTTP/1.0 404 Not Found
Date: Mon, 16 May 2016 11:16:30 GMT
Server: Apache
Cache-Control: no-cache
Content-Length: 16
Connection: close
Content-Type: text/plain;charset=UTF-8
 
Is not receiver.
</pre>
 
Näide 3 (e-arve XML-i uploadimine jooksvas kataloogis asuvast failist ''invoice.xml''):
 
<pre>
    $> curl -i "http://services.krediidiinfo.ee/edi/sales-invoices" -X POST -d @invoice.xml -H "Authorization: Bearer zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz" -H "Content-Type: application/vnd.ki.einvoice+json; version=1.11"
</pre>
 
== Viited ==
* [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"