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 skupine artiklov, stanje na kartici

1.7

1.10.2018

zamenjava bu_id z bu_uid v url-jih

Opis

Dostop do eBlagajna podatkov je omogočen preko RESTful storitve z oAuth 2.0 avtentikacijo, odgovori so vedno v JSON formatu.

Naslov

Testni naslov:

Produkcijski naslov:

Produkcijski naslov še ni delujoč.

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": "/api.dev.eblagajna.com/v1/bu/3db3ef35ca9a8410ca810c8a53c8ad70571e9583ce535c1195505877d161c560/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.

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

Skupine artiklov

Skupine artiklov imajo omočeno samo branje - vse ali samo ena po ID-ju.

Primer enega vrnjenega objekta:

{
  "id": 1,
  "name": "Topli napitki",
  "family_id": 1,
  "tax_id": 1,
  "walk_id": 0,
  "order_printer_id": 0,
  "order": 999,
  "color": "16752762",
  "enabled": true,
  "added": "2018-05-03T14:29:12+02:00",
  "last_change": "2018-05-03T14:29:12+02:00",
  "additional_tax_id": null,
  "data": null
}

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 /api.dev.eblagajna.com/v1/bu/{{bu_uid}}/customers se doda parameter search, po katerem se poiščejo ujemajoče stranke in sicer po vseh poljih (naziv, telefon, naslov, …).

Podjetje

Podatki podjetja za izbrano stranko, podpira GET, POST, PATCH, DELETE:

Polja podjetja
  • 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

Polja naslovov (odebeljena so pri dodajanju obvezna)
  • 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

Polja telefonskih Å¡tevilk (odebeljena so pri dodajanju obvezna)
  • 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.

Možna stanja so:
  • 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.

Polja 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

  • 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. Berejno, dodajajo in urejajo preko naslednjih naslovov:

Polja artiklov
  • 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:

Pravila so sestavljena iz naslednjih polj
  • 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.

Polja stanja na kartici:
  • 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
    }
  }
}