EDI

From services.krediidiinfo.ee
Revision as of 16:01, 18 January 2017 by Rait (talk | contribs) (→‎Autentimine)
Jump to navigation Jump to search

Sissejuhatus

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 ning sellest arusaamine eeldab orienteerumist järgmistes valdkondades:

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 - elektroonilise dokumentide saatja ja/või vastuvõtja.
  • vahendaja - Vahendaja on 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.


Tutvustus

EDI olemust on lihtne kirjeldada kasutades postkasti metafoori. Sisuliselt võib EDI-t vaadelda kui postkastide teenuse pakkujat.


Kui klient (saatja) A soovib saata arvet teisele kliendile (saaja) B, siis annab ta arve EDI-le ning EDI paigutab arve kliendi B ostuarvete postkasti. Klient B kontrollib ja tühjendab regulaarselt oma ostuarvete postkasti.


Iga klient saab EDI-sse lasta paigaldada oma postkasti. EDI ise postkastide paigaldamisega ei tegele vaid see käib läbi EDI lepinguliste partnerite ehk vahendajate. Praktikas on enamasti vahendajateks raamatupidamise programmid, kes soovivad oma klientidele pakkuda e-arvete saatmise ja vastuvõtmise teenust.


Kui klient tuleb oma postkasti kontrollima, siis peab EDI aru saama kellega on tegemist. See on vajalik, et takistada võõrastesse postkastidesse piilumist ja lubada vaadata vaid oma postkasti. Selle probleemi lahendamiseks väljastatakse iga kliendi jaoks oma parool ehk kliendi token. Tokeni peab küsima ja kliendile edastama vahendaja. NB! Token tuleb hoida saladuses! Kes iganes teab kliendi tokenit saab esineda kliendi nimel.


EDI üldised kasutuslood koos kasutajate rollidega:


Edi kasutuslugude diagramm.png

Arendajale

Sammud vahendaja arendajale liidese integreerimiseks.


  • Loe läbi kogu dokumentatsioon
  • Küsi Creditinfo käest vahendaja token testserveri jaoks.
  • Realiseeri kasutuslood, mis kasutavad vahendaja tokenit.
    • kliendi lisamine
    • kliendi eemaldamine
    • kliendi tokeni uuendamine

Nüüd saab klient ennast registreerida ja kliendi tokeni abil oma müügiarveid saata ja ostuarveid vastu võtta.

  • Realiseeri kasutuslood, mis kasutavad kliendi tokenit:
    • müügiarvete saatmine
    • müügiarvete vastuvõtmine
  • kui kõik valmis ja testkeskkonnas toimib, siis peab vahendaja sõlmima Creditinfoga lepingu ning koos lepinguga väljastatakse live serveri vahendaja token. Vaheta testserveri domeeni nimetus live serveri oma vastu ning asenda testserveri vahendaja token live serveri vahendaja tokeniga. Ongi kõik.


Liidese üldine kirjeldus

Peatükis selgitatakse täpsemalt üldiseid EDI loomisel kasutatud tehnilisi põhimõtteid.


Asukoht

Creditinfo EDI asub serveris services.krediidiinfo.ee, suhtlemine toimub ainult üle HTTPS-i.

Creditinfo elektrooniliste dokumentide vahendusteenusega (EDI) suhtlemine toimub REST liidese kaudu.


Arenduse jaoks on olemas eraldi testserver.


Autentimine

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: 


    POST /edi/sales-invoices
    Authorization: Bearer xxxx


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. Edaspidi on dokumentatsioonis vahendaja token viidatud stringiga xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx ja klienditoken stringiga yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy. 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.


Token tuleb hoida saladuses, 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.

Veahaldus

Kehtivad kõik 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.


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 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: 

    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.
  • application/vnd.ki.einvoice+xml; version=1.2 - Arve Eesti E-arve XML versioon 1.2 formaadis.


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.


REST liidese dokumentatsioon

Klientide haldamine

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:

  • 201 - klient edukalt registreeritud
  • 400 - viga payloadis
  • 401 - HTTP päises token puudu, token vigane või ei kehti enam
  • 409 - ei registreeritud, sest klient on juba EDI-is registreeritud.
  • 415 - HTTP päises ei ole Content-Type väärtuseks application/vnd.ki.edi+json; version=1.0

Payloadis peab määratlema registreeritava kliendi äriregistrikoodi ja riigi. Payload peab olema JSON formaadis. Struktuur:

  • clientId - EDI-sse lisatud kliendi äriregistrikood.


Näide päringust: 

    POST /edi/clients
    Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
    Content-Type: application/vnd.ki.edi+json; version=1.0;

    {"clientId":"10256137"}

Vastuses on päises Location väärtuseks kliendi URI ning payloadis kliendi info. Payloadi struktuur:

  • clientId - EDI-sse lisatud kliendi äriregistrikood.
  • mediatorId - kliendi lisanud vahendaja äriregistrikood.

Näide vastusest: 

    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"}

GET /edi/clients/{clientId}

Kliendi andmete pärimine. Kasutatakse selleks, et kindlaks teha kas ja kelle poolt on klient EDI-s registreeritud.

Vastuse koodid:

  • 200 - päring õnnestus, payloadis kliendi andmed
  • 401 - HTTP päises token puudu, token vigane või ei kehti enam
  • 404 - klient pole EDI-s registreeritud
  • 406 - HTTP päises ei ole Accept väärtuseks application/vnd.ki.edi+json; version=1.0


Näide päringust: 

    GET /clients/10245137
    Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
    Accept: application/vnd.ki.edi+json; version=1.0

Vastuseks on kliendi andmed JSON formaadis. Struktuur:

  • clientId - EDI-sse lisatud kliendi äriregistrikood.
  • mediatorId - kliendi lisanud vahendaja äriregistrikood.

Näide vastusest: 

    HTTP/1.1 200 OK
    Content-Type: application/vnd.ki.edi+json; version=1.0

    {"clientId":"10245137","mediatorId":"00000000"}


DELETE /edi/clients/{clientId}

Kliendi kustutamine EDI-st.

Vastuse koodid:

  • 204 - kustutamine õnnestus
  • 401 - HTTP päises token puudu, token vigane või ei kehti enam
  • 403 - puuduvad õigused kustutada kuna klient on registreeritud teise vahendaja poolt
  • 404 - klienti pole EDI-s registreeritud.

Näide päringust: 

    DELETE /edi/clients/10245137
    Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Näide vastusest: 

    HTTP/1.1 204 No Content


POST /edi/clients/tokens

Kliendi tokeni loomine või uuendamine.

Vastuse koodid:

  • 201 - tokeni uuendamine õnnestus, payloadis uus token
  • 400 - viga payloadis
  • 401 - HTTP päises token puudu, token vigane või ei kehti enam
  • 404 - klient pole EDI-is registreeritud
  • 403 - tokenit ei saa uuendada, sest klient on teise vahendaja poolt registreeritud
  • 415 - HTTP päises ei ole Content-Type väärtuseks application/vnd.ki.edi+json; version=1.0


Päringu payloadiks on kliendi äriregistrikood JSON formaadis. Struktuur:

  • clientId - kliendi äriregistrikood


Näide päringust: 

    POST /edi/clients/tokens
    Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
    Content-Type: application/vnd.ki.edi+json; version=1.0

    {"clientId":"10256137"}

Vastuse struktuur:

  • token - kliendi token

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: 


    HTTP/1.1 201 Created
    Content-Type: application/vnd.ki.edi+json; version=1.0

    {"token":"SmpSxVEhp1IKhbr24R6D5yAda3odN4Vh"}


Müügiarvete saatmine

Müügiarve saatmine koosneb kolmest etapist. Etapid on kujutatud all oleval järgnevusdiagrammil:

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:

  • 200 - kliendile saab EDI kaudu e-arvet saata.
  • 404 - kliendile ei saa EDI kaudu e-arvet saata.

Näide päringust: 

    GET /edi/purchase-invoices/receivers/10245137


Näide vastusest: 

    HTTP/1.1 200 OK


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:

  • 201 - müügiarve salvestamine õnnestus. Vastuse päises on väljas Location müügiarve URI.
  • 400 - payloadis olev e-arve ei valideeru.
  • 401 - HTTP päises kliendi token puudu, token vigane või ei kehti enam
  • 413 - payload liiga suur. Lubatud on maksimaalselt 1MB.
  • 415 - HTTP päises ei ole Content-Type väärtuseks application/vnd.ki.invoice+xml; version=1.11

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: 

POST /edi/sales-invoices
Content-Type: application/vnd.ki.einvoice+xml; version=1.11
Authorization: Bearer yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy

<E_Invoice>
  <Invoice>
    <!-- e-arve sisu -->
  </Invoice>
</E_Invoice>

Näide vastusest: 

    HTTP/1.1 201 Created
    Location: https://services.krediidiinfo.ee/edi/sales-invoices/23423


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:

  • 200 - arve pole veel jõudnud adressaadini.
  • 401 - HTTP päises kliendi token puudu, token vigane või ei kehti enam
  • 404 - arve on jõudnud aadresaadini


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: 

    HEAD /edi/sales-invoices/23423
    Authorization: Bearer yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy


Näide vastusest: 

    HTTP/1.1 200 OK

Ostuarvete vastuvõtmine

Receive-purchase-invoices-sequence-diagram.png


GET /edi/purchase-invoices

EDI-s olevate ostuarvete pärimine.

Vastuste koodid:

  • 200 - serveris olevate ostuarvete URI-de massiiv JSON formaadis.
  • 401 - HTTP päises kliendi token puudu, token vigane või ei kehti enam
  • 406 - HTTP päises ei ole Accept väärtuseks application/vnd.ki.edi+json; version=1.0


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: 

    GET /edi/purchase-invoices
    Authorization: Bearer yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy
    Accept: application/vnd.ki.edi+json; version=1.0


Näide vastusest: 

    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"]


Kui EDI-s ostuarved puuduvad, siis on vastuseks tühimassiiv. Näide: 

    HTTP/1.1 200 OK
    Content-Type: application/vnd.ki.edi+json; version=1.0

    []


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:

  • 200 - payloadis arve soovitud formaadis.
  • 401 - HTTP päises kliendi token puudu, token vigane või ei kehti enam
  • 403 - päring keelatud, ostuarve on teise kliendi oma.
  • 404 - müügiarvet EDI serveris ei leitud.
  • 406 - Server ei suuda saata vastust, mida klient on soovinud Accept parameetriga. Praegu toetakse ainult meediatüüpi application/vnd.ki.einvoice+xml; version=1.11 (Tulevikus on plaan sama liidese kaudu lubada ka PDF versiooni küsimist, sellisel juhul peab Accept väärtuseks olema application/pdf).

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 GET /edi/purchase-invoices payloadist.

Näide ostuarve XML-i alla laadimise päringust: 

    GET /edi/purchase-invoices/23423
    Authorization: Bearer yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy
    Accept: application/vnd.ki.einvoice+xml;

Näide vastusest: 

    HTTP/1.1 200 OK
    Content-Type: application/vnd.ki.einvoice+xml; version=1.11

    <E_Invoice>
       <Invoice>
       <!-- e-arve sisu -->
       </Invoice>
    </E_Invoice>

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. 

    Accept: application/pdf

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 GET /edi/purchase-invoices payloadist.

Vastuste koodid:

  • 204 - ostuarve kustutamine õnnestus.
  • 401 - HTTP päises kliendi token puudu, token vigane või ei kehti enam
  • 403 - päring keelatud, ostuarve on teise kliendi oma.
  • 404 - müügiarvet EDI serveris ei leitud.

Näide päringust: 

    DELETE /edi/purchase-invoices/23423
    Authorization: Bearer yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy

Näide vastusest: 

    HTTP/1.1 204 No Content

Arve PDF formaadis

E-arve ver 1.2 XML-i saab lisada arve pdf formaadis.

Näide: 

<?xml version="1.0" encoding="UTF-8">
<E_Invoice xsi:noNamespaceSchemaLocation="e-invoice_ver1.2.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <Invoice>
        <!-- arve andmed näite lihtsuse huvides välja jäetud -->
        <AttachmentFile>
            <FileBase64>base64 encoded binary data of PDF</FileBase64>
        </AttachmentFile>
    </Invoice>
</E_Invoice>

Lisad

cURL

Üks võimalik viis EDI liidesega suhelda otse käsurealt testimise eesmärgil on CLI programmiga cURL.


Näide 1: 

    $> 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"

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): 

    $> curl -i "https://katseklaas.krediidiinfo.ee/edi/purchase-invoices/receivers/10245137"

ja vastus: 

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.

Näide 3 (e-arve XML-i uploadimine jooksvas kataloogis asuvast failist invoice.xml): 

    $> 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"

Viited

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