Spremembe
| verzija | datum | opis |
|---|---|---|
1.1 |
28.11.2016 |
strankam dodano iskanje po besedilu |
1.2 |
7.12.2016 |
strankam dodano polje loyalty_groups, dodani dostopni točki za zvestobo/popuste - skupine uporabnikov in pravila |
1.3 |
8.12.2016 |
popravljena in dokončana dokumentacija za naročila |
1.4 |
19.1.2017 |
dodan status za izbrisana naročila, dodani načini dostave pri pravilih za zvestobo |
1.5 |
23.1.2017 |
dodana dostopna točka za načine plačil in status za osebni prevzem na naročilu |
1.6 |
24.9.2018 |
dodana dostopna točka za prodajne skupine, stanje na kartici |
1.7 |
1.10.2018 |
zamenjava bu_id z bu_uid v url-jih |
1.8 |
30.4.2020 |
dodane dostopne točke za komentarje artiklov in skupin, tipi prodajnih skupin, grafične mize, sestavnice, zaloga nabavnih artiklov, podjetja, na naročilu dodana možnost označbe grafične mize in podjetja |
1.9 |
6.4.2022 |
dodane dostopne točke za podatke o računu, dostopna točka za fiskaliziranje 3th party računa, dostopna točka za pošiljanje načina plačila. |
Opis
Dostop do eBlagajna podatkov je omogočen preko RESTful storitve z oAuth 2.0 avtentikacijo, odgovori so vedno v JSON formatu.
Naslov
Produkcijski naslov:
Dostop
Avtentikacija je omogočena samo s client_credentials grant_type-om na naslovu:
Od vašega kontakta boste dobili Client ID (client_id) in Client Secret (client_secret) podatka, ki ju uporabite kot parametra v naslovu zahtevka ali kot glavo (HTTP Header) na zgornji naslov. Pošljeta pa se lahko tudi v Authorization HTTP glavi.
Kot odgovor dobite žeton (access token), ki ga nato lahko uporabljate za dostop do ostalih dostopnih točk. Žeton je veljaven 1 uro.
Oblika odgovora in paginacija
Uspešni odgovor je vedno v isti obliki in sicer JSON objekt ki vsebuje vsaj lastnosti count in results. Count pove število vseh rezultatov, results pa vsebuje seznam vrnjenih objektov.
Če je število vrnjenih objektov večje od :object_limit: potem se nad rezultati avtomatsko izvede paginacija. Vrnjenih je prvih :object_limit:, naslednje pa se dobi tako da se kot parameter pošlje ključ page z ustrezno številko strani ki se potrebuje. Za lažjo navigacijo pa tak odgovor vsebuje še lastnosti previous in next, ki hranita polni naslov do prejšnje ali naslednje strani, če le ta obstaja.
Delni primer odogovora:
{
"count": 415,
"next": "https://api.eblagajna.com/v1/bu/{{bu_uid}}/articles?access_token=
token123&page=2",
"limit": 100,
"results": [
{
"id": 1,
"name": "Aperol spritz",
"gross_price": 4,
"enabled": true,
"group_name": "COCKTAIL",
"student_voucher": true,
"last_change": "2016-07-02T13:46:32+02:00"
}
]
}
Napake
Napake pri dostopu vedno vrnejo JSON objekt v isti obliki, sama koda (HTTP response code) pa tudi ustreza napaki ki se je zgodila. V primeru uspešne zahteve je koda vedno 200.
Objekt vsebuje lastnosti error s kratkim imenom napake in error description z daljšim opisom.
Primer napake zaradi napačnega žetona, v tem primeru je vrnjena koda 401 (Unauthorized):
{
"error": "unauthorized",
"error_description": "You do not have permission to access this resource."
}
Dostopne točke
Vsi naslovi dostopnih točk vsebujejo isti začetek, in sicer verzijo API in UID poslovne enote za katero se podatke bere ali ureja. Ta UID vam tudi posreduje vaš kontakt, nanj in na vaše dostopne podatke so vezane tudi pravice za dostop do posameznih dostopnih točk.
Primer (za lastno uporabo nadomestite {{bu_uid}} z dejanskim):
Vsako dodajanje, urejanje in brisanje je preko HTTP metod, vsebina pa mora biti poslana v JSON obliki kot telo zahtevka. Dodajanje je vedno preko metode POST, urejanje preko PATCH in brisanje preko DELETE. Brisanje vedno samo spremeni status posameznega objekta in ga s tem onemogoči - objekt se nikoli ne pobriše.
Komentarji artiklov
Komentarji artiklov imajo omočeno samo branje - vsi ali samo en po ID-ju.
Primer enega vrnjenega objekta:
{
"count":81,
"results":[
{
"id":2,
"article_id":229,
"comment":"Led"
},
{
"id":3,
"article_id":293,
"comment":"Toplo mleko"
},
{
"id":4,
"article_id":291,
"comment":"Brez ledu"
}
]
}
Tipi prodajnih skupin
Tipi prodajnih skupin imajo omočeno samo branje - vsi ali samo en po ID-ju.
Primer enega vrnjenega objekta:
{
"count":4,
"results":[
{
"id":1,
"name":"Pijača",
"added":"-0001-11-30T00:00:00+01:00",
"last_changed":"2016-11-23T23:46:43+01:00",
"enabled":true
},
{
"id":2,
"name":"Hrana",
"added":"-0001-11-30T00:00:00+01:00",
"last_changed":"2016-11-29T13:27:24+01:00",
"enabled":true
},
{
"id":3,
"name":"Cigareti",
"added":"-0001-11-30T00:00:00+01:00",
"last_changed":"-0001-11-30T00:00:00+01:00",
"enabled":true
},
{
"id":4,
"name":"Ostalo",
"added":"-0001-11-30T00:00:00+01:00",
"last_changed":"-0001-11-30T00:00:00+01:00",
"enabled":true
}
]
}
Komentarji prodajnih skupin
Komentarji prodajnih skupin imajo omočeno samo branje - vsi ali samo en po ID-ju.
Primer enega vrnjenega objekta:
{
"count":3,
"results":[
{
"id":2,
"article_group_id":20,
"group_comment":"Dodatek majoneza"
},
{
"id":3,
"article_group_id":25,
"group_comment":"Dodatek smetana"
},
{
"id":4,
"article_group_id":25,
"group_comment":"Led"
}
]
}
Prodajne skupine
Prodajne skupine imajo omočeno samo branje - vsi ali samo en po ID-ju.
Primer enega vrnjenega objekta:
{
"count":2,
"results":[
{
"id":1,
"name":"KAVE",
"family_id":1,
"tax_id":1,
"walk_id":0,
"order_printer_id":1,
"order":8,
"color":"16303217",
"enabled":true,
"last_change":"2020-03-02T12:38:58+01:00",
"added":"-0001-11-30T00:00:00+01:00",
"additional_tax_id":null,
"data":null
},
{
"id":2,
"name":"Sokovi",
"family_id":1,
"tax_id":1,
"walk_id":1,
"order_printer_id":0,
"order":999,
"color":"16757350",
"enabled":false,
"last_change":"2017-01-22T13:22:58+01:00",
"added":"-0001-11-30T00:00:00+01:00",
"additional_tax_id":null,
"data":null
}
]
}
Artikli
Artikli imajo omočeno samo branje - vsi ali samo en po ID-ju.
Primer enega vrnjenega objekta:
{
"id": 1,
"name": "MALA SOLATA",
"gross_price": 1.5,
"enabled": true,
"group_name": "SOLATE",
"student_voucher": false,
"last_change": "2016-01-14T10:32:01+01:00"
}
Grafične mize
Grafične mize imajo omočeno samo branje - vsi ali samo en po ID-ju. V orderju se v
Primer enega vrnjenega objekta:
{
"count":3,
"results":[
{
"SPODNJI VRT":[
{
"position_id":"1229",
"position_name":"Miza 1"
},
{
"position_id":"1230",
"position_name":"Miza 2"
},
{
"position_id":"1231",
"position_name":"Miza 3"
}
]
}
]
}
Sestavnice
Sestavnice imajo omočeno samo branje - vsi ali samo en po ID-ju.
Primer enega vrnjenega objekta:
{
"count":2,
"results":[
{
"id":675,
"article_id":5,
"item_id":306,
"subitem_id":0,
"quantity":1
},
{
"id":688,
"article_id":6,
"item_id":307,
"subitem_id":0,
"quantity":0.5
}
]
}
Zaloga
Zaloga ima omočeno samo branje - vsi ali samo en po ID-ju.
Primer enega vrnjenega objekta:
{
"count":3,
"results":[
{
"item_id":"313",
"item_name":"Vodka Absolut Elyx 0,03l",
"qty":"6.0000",
"today_qty":null
},
{
"item_id":"35",
"item_name":"Amaro Ramazzotti",
"qty":"6.3600",
"today_qty":null
},
{
"item_id":"136",
"item_name":"Ballantines 17Y",
"qty":"1.8800",
"today_qty":null
}
]
}
Podjetja
Podatki podjetja, podpira GET, POST, PATCH, DELETE:
https://api.eblagajna.com/v1/bu/{{bu_uid}}/companies/ (GET) https://api.eblagajna.com/v1/bu/{{bu_uid}}/companies/{{company_taxnum}}/ (GET, POST, PATCH, DELETE)
-
vat_id - davčna številka podjetja, če že obstaja se bodo podatki samo prepisali oz. spremenili
-
tax_commited - podjetje je davčni zavezanec
-
name - naziv podjetja
-
address - uradni naslov podjetja
-
postnum - poštna številka
-
post - ime pošte
-
discount - avtomatski popust na podjetje, za račune izdane z blagajne
-
comment - komentar podjetja, za interno uporabo
-
enabled - ali je podjetje omogočeno
Primer enega vrnjenega objekta:
{
"count":1,
"results":[
{
"id":"16",
"vat_id":"12345679",
"tax_commited":"1",
"name":"TEST D.O.O.",
"address":"TESTNA ULICA 111",
"postnum":"1000",
"post":"LJUBLJANA",
"country":"SI",
"discount":"0.00",
"status":"1"
}
]
}
Stranke
Stranke imajo bolj zahtevno strukturo. Vsaka stranka ima lahko povezano eno podjetje za izdajanje originalnih računov. Če stranka ta zapis vsebuje bo račun vedno izstavljen na podjetje. Poleg podjetja pa ima stranka tudi en ali več naslovov in eno ali več telefonskih številk. Vsak od teh zapisov se ureja posebej.
Dostop do strank:
Stranko se doda s POST metodo na prvi naslov, vsebovati pa mora vsaj polje name, opcijsko pa še comment in status. Kot odogovor se dobi novo ustvarjeni objekt, ki že vsebuje id na katerega se sklicujete za dodajanje podjetja, naslova ali telefonske številke stranki, kar se naredi na spodnjih naslovih. Urejanje poteka preko PATCH metode na 2. zgornji naslov, prav tako z JSON objektom s popravljenimi polji z novimi vrednostmi.+ Za dodajanje stranke z naslovom in telefonsko številko je postopek tak da se najprej doda stranko, s pridobljenim ID-jem stranke pa se nato doda še naslov in telefonsko številko.
Iskanje po strankah
Omogočeno je iskanje po strankah (poleg neposrednega dostopa preko ID-ja stranke). V običajni zahtevek za seznam strank se doda parameter search, po katerem se poiščejo ujemajoče stranke in sicer po vseh poljih (naziv, telefon, naslov, …).
Podjetje za izbrano stranko
Podatki podjetja za izbrano stranko, podpira GET, POST, PATCH, DELETE:
-
vat_id - davčna številka podjetja, če že obstaja se bodo podatki samo prepisali oz. spremenili
-
tax_commited - podjetje je davčni zavezanec
-
name - naziv podjetja
-
address - uradni naslov podjetja
-
postnum - poštna številka
-
post - ime pošte
-
discount - avtomatski popust na podjetje, za račune izdane z blagajne
-
comment - komentar podjetja, za interno uporabo
-
enabled - ali je podjetje omogočeno
Naslovi
-
address - naslov stranke
-
house_no - hišna številka stranke
-
postnum - poštna številka
-
post - ime pošte
-
comment - komentar naslova, lahko se označi ali je naslov domači, služben, … ni prikazan nikjer
-
enabled - ali je naslov omogočen za uporabo
Telefonske številke
-
phone - telefonska številka
-
comment - komentar telefonske številke, lahko se označi ali je številka domača, mobilna, službena, …
-
enabled - ali je telefonska številka omogočena za uporabo
Naročila
Ta dostopna točka omogoča pregled in dodajanje naročil. Vsako naročilo in sprememba se avtomatsko sinhronizira na blagajno in če je potrebno natisne tudi kuhinjsko navodilo. Artikli v naročilih morajo vsebovati ID-je eBlagajne, cena naročila in samih artiklov mora biti že izračunana - API ne preverja cen in izračunov, zaradi vseh različnih opcij popustov, dodatkov, ipd. Dodajanje naročil vrne ID naročila preko katerega se kasneje lahko preverja status/stanje naročila. Pomembno je, da se najprej doda naročilo šele nato se doda vsak artikel posebe na to naročilo. Spodaj je opis dodajanja artiklov preko dostopne točke v katero navedemo id naročila, ki ga dobimo v odgovoru.
-
0 - naročilo je bilo preklicano iz blagajne (zavrnjneno)
-
1 - v pošiljanju na blagajno, v tem primeru pregled naročila ni možen saj mora sistem počakati da blagajna sama vstavi podatek
-
2 - na blagajni, pomeni da je naročilo že sinhronizirano na blagajno in čaka na izstavitev računa
-
3 - izstavljen račun
-
4 - v dostavi, v primeru da se na blagajni uporablja sistem za prevzemanje naročil za dostavo
Preklicana naročila se nikoli ne prikažejo na seznamu vseh naročil.
-
name - ime naročila, podatek prikazan na blagajni, računu in kuhinjskem navodilu
-
customer - ID stranke za katero se naročilo dodaja
-
customer_address - ID naslova stranke za katero se naročilo dodaja
-
customer_phone - ID telefonske številke stranke za katero se naročilo dodaja
-
price - skupna cena naročila
-
position - ID grafične mize, če stranka uporablja grafične mize
-
company - ID podjetja za katero se naročilo dodaja
-
takeaway - boolean vrednost, se nastavi če je naročilo za osebni prevzem, se upošteva samo če je na blagajni vklopljen sistem za dostavo
-
enabled - status naročila
Odgovor je v obliki:
{
"count": 1,
"results": [
{
"id": "64019ab1-4b70-4cb2-bac1-31cce375e7a2",
"articles":["11fc4786-7a3a-47d0-9bd6-c8336377ee40", "077a1631-711b-4634-8fa4-5188361eb04f"],
"status": 2
}
]
}
Artikli
Vsako naročilo vsebuje seznam artiklov. Artikli so vrnjeni samo kot seznam ID-jev povezanih z naročilom. Berejo, dodajajo in urejajo se preko naslednjih naslovov:
-
article_id - ID artikla ki se dobi preko dostopne točke za artikle
-
comment - komentar artikla. Tukaj se vpišejo navodila za kuhinjo - možni dodatki in opcije. V obliki array-a
-
quantity - količina, če ni podana je vedno 1
-
discount - možen popust na artiklu
-
price - cena na enoto
-
price_sum - preračunana cena glede na količino in popust
-
enabled - ali je artikel omogočen
|
OPOZORILO
|
Spremembe na naročilih in artiklih niso vidne takoj, saj mora sistem počakati da naročilo obdela blagajna! |
Zvestoba
Zvestoba je sistem za računanje točk zvestobe, popustov, akcij, dobroimetja, … Dostopni točki vrneta skupine strank in pravila za računanje. Vsaka stranka lahko pripada eni ali večim skupinam, na katere so lahko vezana pravila. Naslov za seznam strank:
Naslov za seznam pravil je:
-
id - ID pravila
-
description - opis pravila ki ga vnese stranka sama, za lažje
-
loyalty_groups - seznam skupin za katere pravilo velja
-
type - za kateri tip stranke/naročila velja pravilo, možne vrednosti so:
-
article - pravilo velja za izbrane artikle
-
group - pravilo velja za izbrane skupine
-
all - pravilo velja za vsa naročila
-
coupon - pravilo velja za naročila z določenim kuponom (za popust ali dobroimetje)
-
-
type_data - podatki povezani s tipom (type), če pravilo velja za artikle ali skupino potem je to seznam ID-jev artiklov ali skupin, za tipa all in coupon je to polje prazno
-
rule - dejansko pravilo, pove na kakšen način naj se zvestoba upošteva. Možne opcije so:
-
coupon - izstavi se kupon za dobroimetje ali popust
-
discount - upošteva se popust
-
entry - vstopnina - povezana z artiklom
-
gratis - pravilo za akcije "plačaš x dobiš x+1"
-
payment - pravilo povezano z načini plačil (npr.: x% popusta na gotovino)
-
-
rule_data - dodatni pogoji in podatki vezani na pravila:
-
discount
-
percent ali value - za kakšno vrednost se zmanjša plačilo
-
min_value - opcijsko, minimalna vrednost celotnega naročila da se popust upošteva
-
apply_to - opciji match in invoice, pove ali se popust upošteva na celotno naročilo ali samo na ujemajoče artikle in skupine (iz polj type in type_data)
-
-
gratis
-
quantity - na kakšno količino ujemajočih artiklov/skupin se pravilo upošteva
-
gratis - kakšna količina ujemajočih artiklov/skupin je zastonj
-
-
…
-
-
scope - opciji invoice in all, se uporabljata predvsem pri dobroimetjih in povesta ali se pravilo upošteva na stranko na splošno ali samo pri trenutnem naročilu
-
combine - ali se pravilo lahko sešteva z drugimi
-
delivery - ali se pravilo upošteva pri dostavi, osebnem prevzemu ali obeh, možne vrednosti:
-
both - upošteva se pri obeh načinih
-
delivery - upošteva se samo za dostavo
-
takeaway - upošteva se samo pri osebnem prevzemu
-
-
data_from - čas od kdaj naprej pravilo velja
-
date_to - čas do kdaj pravilo velja
-
days - seznam dni ob katerih se pravilo upošteva (npr.: določeni popusti so lahko veljavni samo čez vikend)
-
hour_from in hour_to - ob katerih urah se popust upošteva
-
validity - koliko časa se pravilo upošteva pri posamezni stranki (samo v primeru da je scope all, predvsem za namene dobroimetja in mesečnih akcij v stilu "vsaka 10 kava je zastonj")
-
enabled - ali je pravilo aktivno
V primeru da se popusti ne seštevajo (polje combine) so opcije na izbiro in jih izbere uporabnik sam. Če obstaja več enakih pravil (glede na enak type in rule) samo z razliko v vrednostih se upošteva najvišji popust.
Primer odgovora:
{
"count": 3,
"results": [
{
"id": 1,
"description": "kave imajo 50% popusta če je stranka v skupini \"1\" ali \"2\",
samo ob vikendih med 8h in 12h uro",
"loyalty_groups": [
1,
2
],
"type": "group",
"type_data": [
1
],
"rule": "discount",
"rule_data": {
"percent": 50,
"apply_to": "match"
},
"scope": "invoice",
"combine": true,
"date_from": null,
"date_to": null,
"days": {
"monday": false,
"tuesday": false,
"wednesday": false,
"thursday": false,
"friday": false,
"saturday": true,
"sunday": true
},
"hour_from": "08:00",
"hour_to": "12:00",
"validity": null,
"enabled": true
},
{
"id": 2,
"description": "plačaš 2 dobiš 3",
"loyalty_groups": [],
"type": "group",
"type_data": [
1,
2
],
"rule": "gratis",
"rule_data": {
"quantity": 2,
"gratis": 1
},
"scope": "invoice",
"combine": false,
"date_from": null,
"date_to": null,
"days": null,
"hour_from": null,
"hour_to": null,
"validity": null,
"enabled": true
},
{
"id": 3,
"description": "nakupi nad 15€ imajo 10% popusta",
"loyalty_groups": [],
"type": "all",
"type_data": [],
"rule": "discount",
"rule_data": {
"percent": 10,
"min_value": 15,
"apply_to": "invoice"
},
"scope": "invoice",
"combine": false,
"date_from": null,
"date_to": null,
"days": null,
"hour_from": null,
"hour_to": null,
"validity": null,
"enabled": true
}
]
}
Stanje na kartici
Naslov za stanje na kartici - vsi ali samo en po ID-ju kartice ali po nazivu kupca.
-
id - id kupca
-
card_id - id kartice
-
customer_name - naziv končnega kupca
-
company - podatki o podjetu, kateremu pripada kupec (če obstaja povezava)
-
end_customer - podatki o končnem kupcu
-
value - vrednost na kartici
Primer odgovora:
{
"count": 1,
"results": [
{
"customer_id": "add661db-fdcb-47e5-9cbf-e476ad6340fc",
"card_id": "0012225272",
"customer_name": "16",
"company": null,
"end_customer": "16",
"value": 19.9
}
]
}
Načini plačil
Seznam načinov plačil ki obstajajo v eBlagajna sistemu na izbrani poslovni enoti. Vsebujejo tudi privzete popuste na plačilu in možno vrednost naročila, ki se uporablja za študentske bone (vrednost je avtomatsko odšteta od končnega zneska naročila, pri izstavitvi računa). Naslov za plačila:
Primer odgovora:
{
"count": 1,
"results": [
{
"id": 1,
"payment": "Gotovina",
"ask_for_customer": false,
"ask_for_comment": false,
"discount": 0,
"value": 0,
"data": null,
"enabled": true
}
]
}
Računi
Podatki o računu
Naslov za pridobitev podatkov o izdanem računu, namenjeno za generiranje izpisa računa za stranko (pdf).
Odgovor je v obliki:
{
"count": 1,
"results": [
{
"invoice": {
"name": "testing",
"timestamp": "2022-02-01 00:32:35",
"customer_id": null,
"price": "24.000000",
"super_discount": "0.00",
"time_closed": "2022-02-01 00:32:35",
"user_name": "Natakar 1",
"c_taxnum": null,
"c_taxc": null,
"c_name": null,
"c_address": null,
"c_postnum": null,
"c_post": null,
"c_country": null,
"invoice_num": "RAC-14-67",
"c_status": null,
"customer_data": "",
"customer_address": "",
"customer_phone": "",
"customer_data_name": null,
"customer_data_comment": null,
"customer_address_address": null,
"customer_address_post": null,
"customer_phone_phone": null,
"some_detail": null,
"comment": "",
"embassy_or_export_wo_tax": "0",
"pos_description": "Blagajna 1"
},
"articles": [
{
"article_id": "1",
"article_name": "Test Ne Dela 0,03l",
"qty": "2.00",
"discount": "0.00",
"price_sum": "20.000",
"price": "10.000",
"tax_id": "1",
"comment": "[]",
"invoice_article_status": "1"
},
{
"article_id": "2",
"article_name": "Blue Lagoon Test",
"qty": "1.00",
"discount": "0.00",
"price_sum": "1.000",
"price": "1.000",
"tax_id": "1",
"comment": "[]",
"invoice_article_status": "1"
},
{
"article_id": "3",
"article_name": "Caprinja1",
"qty": "1.00",
"discount": "0.00",
"price_sum": "3.000",
"price": "3.000",
"tax_id": "1",
"comment": "[]",
"invoice_article_status": "1"
}
],
"taxes": [
{
"SUB_tax_id": "1",
"SUB_time": "2022-02-01 00:32:35",
"gross_price": "24.00",
"tax": "22.0000",
"neto_price": "19.67",
"tax_price": "4.33"
}
],
"payments": [
{
"payment_method_id": "1",
"type_id": "1",
"payment_name": "Gotovina",
"price": "24.00"
}
],
"additional": {
"zoi": "e02e06cb4b7f32614ccb8ddaea5e6314",
"eor": ""
}
}
]
}
Davčno potrjevanje računa
Dostopna točka za pošiljanje podatkov o računu, katerega želite davčno potrditi.
-
invoice_id - številka računa,
-
price - znesek računa,
-
timestamp - datum računa v obliki (2022-01-01T15:22:05)
-
prs_taxnum - davčna številka prodajalca
-
taxes - array davkov [1.7, 22, 1.39, 0.31] index 0 = bruto vrednost, potem stopnja ddv, potem, neto vrednost in še vrednost ddv-ja
-
retry - true ali false - pomeni ali se račun potrjuje prvič ali se potrjuje ponovno zaradi kakršega koli razloga (napake)
Odgovor je v obliki:
{
"count": 2,
"results": {
"zoi": "abd4aff619d7dff94a401fc2cba22ee3",
"eor": "83405d3c-d2ea-4dfd-b7d6-cc3965049498"
}
}