Billberry partneri liides (API)

Üldine

Billberry API tugineb HTTP ja REST printsiipidele. See tähendab ressursside-põhist aadresside struktuuri, semantilisi veakoode, MIME tüüpidega versioneerimist ja HTTP-s defineeritud funktsionaalsuse eelistamist teistele variantidele.

Billberry API aadress

https://api.billberry.ee

Põhjalikuma API spetsifikatsiooni leiab SwaggerHubist kui ka OpenAPI v3 formaadis (OpenAPI v3 enda spetsifikatsioon).

API spetsifikatsioon SwaggerHubis   API spetsifikatsioon OpenAPI v3 formaadis

Autentimine

API päringute autentimiseks on vajalik eelnevalt genereerida partneri API võti. Partnerina saad ühe võtmega ligi kõikide oma klientide e-arvetele. Võtmeid saad hallata Billberry partneri lehel, mille lingi saad partneriks hakates meilitsi.

Võtit genereerides kuvatakse sulle võtme identifikaator ja parool. Näiteks:

Identifikaatori alusel saad võtme hiljem partneri lehel tuvastada, kui soovid aeg-ajalt vanu võtmeid uute vastu vahetada. API võtmed on 16-baidised juhuslikud numbrid (kuvatud hex-formaadis), nii et soovi korral võid neid andmebaasis hoida ka binaarformaadis (BLOB).

HTTP päringute autentimine käib läbi Authorization päise ja Basic autentimise. Kasutajanimeks on API võtme identifikaator, parooliks võti. Näidisvõtme puhul oleks HTTP päring välja selline:

GET /partners/{partnerId}/organizations HTTP/1.1
Host: api.billberry.ee
Authorization: Basic NDI6MmFiOTYzOTBjN2RiZTM0MzlkZTc0ZDBjOWIwYjE3Njc=
Accept: application/vnd.billberry.partner-organization+json; v=1

Curliga pärides saab API võtme id ja parooli anda --user parameetriga:

curl --user 42:2ab96390c7dbe3439de74d0c9b0b1767 https://api.billberry.ee/…

Kuna partneri võti annab ligipääsu nii klientidele registreerimisele kui ka nende arvetele, ei tohi klientidel olla ligipääs partneri võtmele. Vastasel juhul saab üks klient teiste nimel arveid saata ja teiste arveid alla laadida. Kui on soov teha Billberry API päringuid klientide arvutitest (desktop programmide puhul), saab Billberryga genereerida kliendi-spetsiifilisi API võtmeid.

Versioneerimine

API versioneerimine toimib läbi päringutele kaasa antud Accept ja Content-Type päiste ning MIME tüüpide. API spetsifikatsioonis leiad iga päringu juures sisu ja vastuse MIME tüübid ning nende skeemid.

Näiteks, arvete metadata esimese versiooni MIME tüüp on:

application/vnd.billberry.invoice+json; v=1

Ühe versiooni raames ei muudeta ega eemaldata kunagi kirjeldatud atribuute. JSON formaadis vastuste puhul võib aga arvestada, et atribuute võib juurde lisanduda, kuid see ei tohiks vastuste tõlgendamisel probleeme tekitada. Tundmatuid atribuute saab parsides lihtsalt ignoreerida.

Vigade käsitlus

Billberry API tagastab ebaõnnestunud päringute korral HTTP vastuse veakoodiga (status code vahemikus 400–599) ja põhjusega (status message/reason phrase).

Võimalikud veateated on kirjeldatud API spetsifikatsioonis iga päringu juures, kuid igaks juhuks tasub arvestada, et veasõnumeid võib lisanduda. Peamiselt on nad mõeldud arendajatele, kuigi vajadusel võib neid kuvada ka lõppkasutajatele — midagi salajast neis ei leidu.

Näiteks saates e-arvet ettevõttele, mis e-arveid vastu ei võta, vastab Billberry veakoodiga 409 ja põhjendusega Organization Doesn't Accept E-Invoices.

POST /partners/{partnerId}/invoices HTTP/1.1
Host: api.billberry.ee
Content-Type: application/xml
Accept: application/vnd.billberry.invoice+json; v=1

<E_Invoice>…</E_Invoice>

HTTP/1.1 409 Organization Doesn't Accept E-Invoices

Kui Accept päisesse lisada Billberry veateate MIME tüüp application/vnd.billberry.error+json; v=1, saab veaobjekti ka JSONis. Vea põhjendus leidub sel juhul peale staatuserea ka message atribuudis:

POST /partners/{partnerId}/invoices HTTP/1.1
Host: api.billberry.ee
Content-Type: application/xml
Accept:
  application/vnd.billberry.invoice+json; v=1,
  application/vnd.billberry.error+json; v=1

<E_Invoice>…</E_Invoice>

HTTP/1.1 409 Organization Doesn't Accept E-Invoices
Content-Type: application/vnd.billberry.error+json; v=1

{
  "message": "Organization Doesn't Accept E-Invoices"
}

Klientide haldamine

Enne kui saad kliendi nimel e-arveid saata, pead kliendi Billberry süsteemis registreerima. Registreerimine aitab kontrollida, et saadetav arve on sinu kliendilt kui ka võimaldab Billberry ja partneri vahelist arveldust. Kuutasulise partnerluse korral hakkab kuutasu arvestus registreerimise päevast.

Enne e-arvete saatmist on vajalik klienti autentida ning ettevõtte esindusõigust kontrollida. Kuna partneri liidese puhul klient ise Billberrys kontot ei tee, jääb see kohustus partneri kanda. Autentimiseks sobivad nii füüsilised isikutuvastuse meetodid kui ka Eesti e-identiteedi digilahendused (ID-kaart jt). Esindusõigust saab kontrollida e-Äriregistrist. Erandjuhtudel võib esindusõiguse kinnituseks lugeda ka pangaülekannet ettevõtte kontolt. Pangakonto ligipääsust võib eeldada, et raamatupidajale on antud esindusõigus. Kliendi registreerimisega Billberry APIs kinnitad, et oled esindusõigust kontrollinud.

Partneri klientide ressurss

/partners/{partnerId}/organizations

Partneri kliendi MIME tüüp

application/vnd.billberry.partner-organization+json; v=1

Kliendi registreerimine

Kliendi saad registreerida PUT /partners/{partnerId}/organizations/{registryCode} päringuga, asendades {partnerId} partneri identifikaatoriga ja {registryCode} kliendi registrikoodiga.

E-arvete saatmise registreerimiseks pole päringule sisu vaja anda.

PUT /partners/{partnerId}/organizations/{registryCode} HTTP/1.1
Host: api.billberry.ee
Accept: application/vnd.billberry.partner-organization+json; v=1

Eduka registreerimise vastuseks on organisatsiooni JSON koos registreerimise kellaajaga.

HTTP/1.1 201 Organization Registered
Content-Type: application/vnd.billberry.partner-organization+json; v=1

{
  "registryCode": "16122596",
  "createdAt": "2021-06-18T13:37:42.666Z",
  "deletedAt": null,
  "sendingEnabled": true,
  "receivingEnabled": false,
  "receivingOperator": null
}

Topeltpäringute pärast muretsema ei pea. Kui klient oli juba registreeritud ning saatmise või vastuvõtmise staatust ei muudetud, on päringu vastuseks 200 Organization Up-to-Date.

E-arvete vastuvõtmise sisselülitamiseks tuleb PUT päringule kaasa anda ka sisu, millega saab eraldi sisse lülitada nii saatmise kui ka vastuvõtmise.

PUT /partners/{partnerId}/organizations/{registryCode} HTTP/1.1
Host: api.billberry.ee
Accept: application/vnd.billberry.partner-organization+json; v=1
Content-Type: application/vnd.billberry.partner-organization+json; v=1

{
  "sendingEnabled": true,
  "receivingEnabled": true
}

Peale vastuvõtmise sisselülitamist registreerib Billberry end Äriregistris su kliendi e-arvete operaatoriks. Nii teavad teised e-arve operaatorid, kuhu kliendile suunatud e-arved edasi saata. Enne Äriregistris seose jõustumist tuleb su kliendil Billberry e-Äriregistris kinnitada. Peale kinnitust kajastub muutus vastuvõtjate registris südaöösel.

On võimalik, et su kliendi ettevõte juba kasutab Billberryt e-arvete vastuvõtmiseks. Sellisel juhul e-Äriregistris seost uuesti kinnitama ei pea. Kliendi operaatori leiad receivingOperator atribuudist. Kui seal on juba "billberry", jõuavad sissetulnud arved kohe sinu kui partnerini.

Registreerides klient ilma saatmise või vastuvõtmise sisselülitamiseta, ei pea sa kliendi eest tasuma, kuid saad talle siiski genereerida kliendi-spetsiifilise API võtme. Nii saad genereeritud võtme uue kliendi arvutisse paigaldada, kuid alles hiljem e-arvelduse sisse lülitada, ilma et peaksid kliendilt võtmete kopeerimist paluma.

Klientide loetelu

Registreeritud klientide loetelu saad GET /partners/{partnerId}/organizations päringuga, asendades {partnerId} partneri identifikaatoriga..

GET /partners/{partnerId}/organizations HTTP/1.1
Host: api.billberry.ee
Accept: application/vnd.billberry.partner-organization+json; v=1

Hetkel kuvatakse vaid aktiivseid kliendisuhteid. Tulevikus võib päringule juurde tulla ka parameetreid kustutatud kliendisuhete pärimiseks.

Kliendi eemaldamine

Kui soovid kliendisuhte Billberry süsteemist eemaldada, saad seda teha DELETE /partners/{partnerId}/organizations/{registryCode} päringuga, asendades {partnerId} partneri identifikaatoriga.

DELETE /partners/{partnerId}/organizations/{registryCode} HTTP/1.1
Host: api.billberry.ee

HTTP/1.1 204 Organization Unregistered

Klienti eemaldades kustutatakse ka kõik kliendi aktiivsed API võtmed.

Klientide API võtmete haldamine

Kui soovid anda oma klientidele võimaluse otse vastu Billberry APIt päringuid teha — näiteks arendades serverita desktop programmi — siis tasub selleks igale kliendile genereerida organisatsiooni-spetsiifiline API võti. Partneri võtit klientidele jagada ei tohi — nii annaksid võimaluse ühel kliendil teiste nimel arveid saata ja teiste arveid alla laadida.

Kui arendad serveripoolset tarkvara, pole kliendivõtmeid vaja.

Pane tähele, et kliendi-spetsifiilist API võtit kasutades tuleks päringud suunata Billberry kliendi API vastu. Tehniliselt on kõik identne partneri APIga, ainult et kliendi puhul on aadressid ilma /partner/{partnerId} prefiksita. Näiteks arveid saad pärida /invoices/received aadressilt ja saata /invoices päringuga.

Miks eraldi aadressid kliendi-spetsiifilise võtme puhul? Selleks, et API oleks organisatsiooni-spetsiifiliste võtmete puhul alati sama, sõltumata kas võti on genereeritud kliendi poolt (Billberry veebis) või partneri poolt (läbi partneri API). Nii saab sama tarkvara muutuseta toetada ka kasutusjuhtu, kus klient ise Billberry veebist API võtme rakendusse kopeerib. Partneri võtmega seevastu saab ligi korraga kõikidele partneri klientide arvetele ja see väärib kas või vigade vältimiseks teist aadressi.

Partneri kliendi võtme ressurss

/partners/{partnerId}/organizations/{registryCode}/sessions

Partneri kliendi võtme MIME tüüp

application/vnd.billberry.session+json; v=1

Kliendi võtme genereerimine

Peale kliendi registreerimist saad genereerida uusi kliendi-spetsiifilisi API võtmeid POST /partners/{partnerId}/organizations/{registryCode}/sessions päringuga, asendades {partnerId} partneri identifikaatoriga ning {registryCode} kliendi registrikoodiga.

POST /partners/{partnerId}/organizations/{registryCode}/sessions HTTP/1.1
Host: api.billberry.ee
Accept: application/vnd.billberry.session+json; v=1

Päringu peale kuvatakse loodud session koos identifikaatori (id) ja parooliga (token):

HTTP/1.1 201 Session Created
Content-Type: application/vnd.billberry.session+json; v=1

{
  "id": 42,
  "registryCode": "16122596",
  "createdAt": "2020-06-18T13:37:42.666Z",
  "token": "2ab96390c7dbe3439de74d0c9b0b1767"
}

Parooli ehk tokenit kuvatakse vaid korra peale võtme loomist. Võtme identifikaatorit ja parooli kasuta Authorization päises Basic autentimise jaoks, nagu partneri võtme puhul.

Kliendi võtmete loetelu

Loetelu partneri genereeritud kliendi võtmetest saad GET /partners/{partnerId}/organizations/{registryCode}/sessions päringuga, asendades {partnerId} partneri identifikaatoriga ning {registryCode} kliendi registrikoodiga.

GET /partners/{partnerId}/organizations/{registryCode}/sessions HTTP/1.1
Host: api.billberry.ee
Accept: application/vnd.billberry.session+json; v=1

Hetkel kuvatakse vaid aktiivseid võtmeid. Tulevikus võib päringule juurde tulla ka parameetreid kustutatud võtmete pärimiseks.

Kliendi võtmete kustutamine

Kui soovid kliendi võtme tühistada, saad seda teha DELETE /partners/{partnerId}/organizations/{registryCode}/sessions/{sessionId} päringuga, asendades {partnerId} partneri identifikaatoriga, {registryCode} kliendi registrikoodiga ning {sessionId} sessiooni identifikaatoriga.

DELETE /partners/{partnerId}/organizations/{registryCode}/sessions/{sessionId} HTTP/1.1
Host: api.billberry.ee

HTTP/1.1 204 Session Deleted

Arvete saatmine ja vastuvõtmine

Kui kliendid on registreeritud, saad nende nimel e-arveid saatma hakata.

Arvete ressurss

/partners/{partnerId}/invoices

Arvete ressurss kliendi-spetsiifilise võtme puhul

/invoices

Arvete MIME tüüp

application/vnd.billberry.invoice+json; v=1

E-arve saatmine

Eesti e-arve standardile vastavaid e-arveid saad saata POST /partners/{partnerId}/invoices päringuga, asendades {partnerId} partneri identifikaatoriga.

POST /partners/{partnerId}/invoices HTTP/1.1
Host: api.billberry.ee
Content-Type: application/xml
Accept: application/vnd.billberry.invoice+json; v=1
X-Send: immediately

<E_Invoice>…</E_Invoice>

Hetkel on toetatud vaid sünkroonne saatmine (päis X-Send: immediately). See tähendab, et päring ei saa vastust enne, kui teine operaator on arve vastu võtnud või tagasi lükanud. Tavaliselt võtab see alla sekundi. Sünkroonsus vähendab riski, et e-arve kaduma läheb, kui teine operaator peaks otsustama e-arvet hiljem mitte vastu võtta. Samuti lihtsustab see e-arve saatmise tehnilist poolt, sest API kliendina ei pea sa hakkama hiljem arve staatust pärima.

Teistele operaatoritele edastamise päringu maksimumkestus on 15 sekundit. Kui teine operaator selle aja sees ei vasta, saad veateate 504 ${Operator} Timeout, kus ${Operator} tähistab operaatori nime.

Kui e-arve on õigesti vormistatud ja ostja võtab e-arveid vastu, saad vastuseks 201 Sent.

HTTP/1.1 201 Sent
Content-Type: application/vnd.billberry.invoice+json; v=1

{
  "id": 42,
  "type": "debit",
  "registryCode": "16122596",
  "senderRegistryCode": "16122596",
  "senderName": "Seller Company OÜ",
  "receiverRegistryCode": "16122597",
  "receiverName": "Buyer Company OÜ",
  "number": "INV123",
  "date": "2020-06-18",
  "dueDate": "2020-06-25",
  "receivedAt": null,
  "receivedFromOperator": null,
  "receivedFileId": null,
  "receivedExternalId": null,
  "sentAt": "2020-06-18T13:37:42.666Z",
  "sentToOperator": "billberry",
  "sentFileId": "42",
  "sentExternalId": "43"
}

Võimalikud veateated on kirjeldatud API spetsifikatsioonis. Näiteks, üritades saata e-arvet enne kliendi registreerimist, vastab API 403 Invoice Not From A Partner's Organization.

Kõikide atribuutide kirjelduse ja skeemi leiad API spetsifikatsioonist, kuid partnerite jaoks on enim kasulikud ilmselt saatmisega seotud atribuudid. Vastuvõtva operaatori ja arve identifikaatorite abil saab teiste operaatorite võrku kadunud arvete kohta kergemini järelpärimisi teha.

application/vnd.billberry.invoice+json; v=1

E-arvete vastuvõtmine

Oma klientide e-arveid saad GET /partners/{partnerId}/invoices/received päringuga, asendades {partnerId} partneri identifikaatoriga.

GET /partners/{partnerId}/invoices/received HTTP/1.1
Host: api.billberry.ee
Accept: application/vnd.billberry.invoice+json; v=1

HTTP/1.1 200 OK
Content-Type: application/vnd.billberry.invoice+json; v=1
Link: </partners/{partnerId}/invoices/received?id%3e42>; rel="updates"

[{
  "id": 42,
  "type": "debit",
  "registryCode": "16122597",
  "senderRegistryCode": "16122596",
  "senderName": "Seller Company OÜ",
  "receiverRegistryCode": "16122597",
  "receiverName": "Buyer Company OÜ",
  "number": "INV123",
  "date": "2020-06-18",
  "dueDate": "2020-06-25",
  "receivedAt": null,
  "receivedFromOperator": null,
  "receivedFileId": null,
  "receivedExternalId": null,
  "sentAt": "2020-06-18T13:37:42.666Z",
  "sentToOperator": "billberry",
  "sentFileId": "42",
  "sentExternalId": "43"
}]

Väljade detailsema kirjelduse leiad API spetsifikatsioonist, kuid partneri kontekstis läheb esimesena tarvis ilmselt registryCode atribuuti, mis kirjeldab, millise ettevõtte arvega on tegu. Saabunud arvete puhul on registryCode võrdne receiverRegistryCode väärtusega, saadetud arvete puhul senderRegistryCode väärtusega.

Sünkroniseerimine

Arvete regulaarseks sünkroniseerimiseks leiad vastuse Link päisest updates viite, mida pärides saad järgmine kord vastuseks vaid need arved, mis saabusid peale eelmist päringut.

Link: </partners/{partnerId}/invoices/received?id%3e42>; rel="updates"

Eelneva näite põhjal, peale esimest /partners/{partnerId}/invoices/received päringut leiad Link päisest /partners/{partnerId}/invoices/received?id%3e42. Järgmine kord arveid pärides kasuta seda aadressi. Kui vahepeal on saabunud uusi arveid, tagastatakse vaid need. Päringu lõpus võta taas Link päisest uus updates aadress ning pane järgmiseks korraks kõrvale. Iga päringu vastus viitab seega uuele updates lingile. Vanad updates lingid jäävad peale pärimist ka tööle, nii et ebaõnnestunud impordi korral võid lihtsalt sama aadressi uuesti proovida. Kõik laekunud arved saad alati originaalse /partners/{partnerId}/invoices/received päringuga.

Link päise formaati kirjeldavad RFC 8288 ja vanem RFC 5988.

Uusi arveid tasub pärida kord 1–5 minuti tagant, sest kahjuks ei kipu e-arved teiste operaatorite juurest tihedamini saabuma. On ka operaatoreid, kel läheb arvete saatmiseks vähemalt 15–30 minutit.

Kui on soov laekunud arvetest sekundi jooksul teada saada, saab Billberry pakkuda ka Server-Sent Events lahendust eelnevalt kirjeldatud pollimise asemel. Anna huvist meilitsi teada.

Vastuvõetud e-arve XML

Saabunud arvete e-arve standardile vastava XMLi saad kätte GET /partners/{partnerId}/invoices/{invoiceId}.xml aadressilt.

GET /partners/{partnerId}/invoices/{invoiceId}.xml HTTP/1.1
Host: api.billberry.ee
Accept: application/xml

HTTP/1.1 200 OK
Content-Type: application/xml

<E_Invoice>…</E_Invoice>