Bodovkabodovka.sk

Napojenie pokladne a e-shopu

Pokladňa, e-shop alebo web môže sám pripisovať body, uplatňovať odmeny a zakladať karty. Stačí jedna HTTPS požiadavka s JSON telom. Ak pokladňu predajne napojiť nevieme, body pripisuje obsluha v administrácii.

1. API kľúč

Vedúci predajne si kľúč vytvorí v administrácii: Nastavenia → Napojenie → Vytvoriť nový API kľúč. Kľúč sa ukáže len raz. Nový kľúč zruší starý. Kľúč patrí na server pokladne alebo e-shopu, nikdy nie do kódu stránky v prehliadači.

POST https://bodovka.sk/api/karta/v1
Authorization: Bearer bdk_vasa-predajna_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Content-Type: application/json

Každá požiadavka má pole akcia. Odpoveď je JSON. Pri chybe má HTTP kód 4xx a pole error so slovenským popisom, ktorý môžete ukázať obsluhe.

2. Akcie

akciapoliačo urobí
kartakod alebo telefon alebo emailVráti kartu: body, pečiatky, kredit, vstupy, aktuálnu zľavu v % a či má zákazník nárok na odmenu.
nakupkod / telefon / email, suma, doklad, prevadzka?Pripíše nákup podľa programu predajne. doklad je jedinečné číslo nákupu z vášho systému. Ten istý doklad sa nikdy nepripíše dvakrát, požiadavku preto môžete bezpečne zopakovať.
odmenakod, body?Uplatní odmenu. Pri bodovom programe vráti zlava v eurách. body určí, koľko bodov sa odpíše (predvolene jedna odmena).
kreditkod, suma, dokladDarčeková karta: kladná suma nabije kredit, záporná ním zaplatí. Ak na karte nie je dosť kreditu, vráti chybu.
vstupkod, doklad?Odpíše jeden vstup z permanentky. Ak skončila platnosť alebo vstupy, vráti chybu.
novameno, telefon, email?, suhlas: true, marketing?Založí kartu, napríklad pri registrácii v e-shope. Vráti číslo karty a odkaz, ktorým si ju zákazník otvorí v mobile. suhlas potvrdzuje súhlas so spracovaním údajov. marketing je samostatný a nepovinný súhlas s novinkami.

prevadzka je presný názov prevádzky z Nastavení predajne. Pri jednej prevádzke ho vynechajte.

Príklad: nákup z pokladne

curl -X POST https://bodovka.sk/api/karta/v1 \
  -H "Authorization: Bearer $BODOVKA_KLUC" \
  -H "Content-Type: application/json" \
  -d '{"akcia":"nakup","kod":"7683681964","suma":23.80,"doklad":"BL-2026-001234"}'
{
  "pripisane": { "body": 23, "peciatky": 0, "zlava": 0 },
  "karta": { "kod": "7683681964", "meno": "Jana Nováková", "body": 95, "peciatky": 0,
             "kredit": 0, "vstupy": 0, "zlavaPct": 0, "stav": { "moze": false, "veta": "Máte 95 bodov (1,90 €). …" } }
}

Číslo karty

Číslo karty má 10 číslic, posledná je kontrolná podľa Luhnovho algoritmu. Čítačka ho prečíta z QR kódu v mobile zákazníka aj z čiarového kódu (Code 128) na fyzickej karte. QR kód fyzickej karty obsahuje odkaz, číslo je v ňom za ?c=.

3. Webhooky

Ak v Nastaveniach zadáte adresu webhooku, pri každej udalosti na ňu pošleme POST s JSON telom. Udalosti sú nakup, odmena, nova_karta, kredit, permanentka, vstup a test. Posielame ich aj vtedy, keď body pripíše obsluha alebo automat z pokladne.

POST https://vas-eshop.sk/bodovka
X-Bodovka-Udalost: nakup
X-Bodovka-Podpis: sha256=5d41402abc4b2a76b9719d911017c592…

{ "udalost": "nakup", "predajna": "vasa-predajna", "cas": "2026-10-10T14:03:11.000Z",
  "karta": { "kod": "7683681964", "meno": "Jana Nováková", "body": 95, "peciatky": 0, "kredit": 0, "vstupy": 0, … },
  "data": { "suma": 23.8, "body": 23, "zdroj": "predajna" } }

Podpis je HMAC-SHA256 celého tela. Kľúčom je „kľúč na overenie podpisu“ z Nastavení. Webhook čaká na odpoveď najviac 5 sekúnd a pri chybe sa neopakuje. Na stav karty sa preto vždy môžete opýtať akciou karta.

// Node.js – overenie podpisu
const ok = 'sha256=' + crypto.createHmac('sha256', KLUC_WEBHOOKU).update(teloPoziadavky).digest('hex')
  === req.headers['x-bodovka-podpis'];

4. Pravidlá

Testovať môžete na vlastnej predajni: vytvorte si skúšobnú kartu v administrácii a po skúške ju zmažte. Každý pohyb je zapísaný v histórii karty.