API pre pokladne a integrácie

Každá karta Loyo má sériové číslo v tvare LY-XXXXXXXX. QR kód na karte (Apple Wallet, Google Wallet aj webová karta) obsahuje adresuhttps://loyo.sk/s/LY-XXXXXXXX, aby ju otvoril aj bežný fotoaparát.

Pokladňa s bežnou čítačkou čiarových kódov dostane tento text ako klávesnicový vstup. Môžete z neho vybrať sériové číslo sami (časť za posledným lomítkom), alebo poslať celý text URL-enkódovaný – API ho rozpozná.

# celý text z QR, URL-enkódovaný – API z neho vyberie sériové číslo
curl https://loyo.sk/api/v1/karty/https%3A%2F%2Floyo.sk%2Fs%2FLY-7KQ2M9XA \
  -H "Authorization: Bearer loyo_live_VAS_KLUC"

Základná adresa API je https://loyo.sk/api/v1. Telá požiadaviek aj odpovede sú JSON (UTF-8), sumy sú vždy v centoch.

API kľúč loyo_live_… si vytvoríte v /app/integracie. Zobrazí sa iba raz – uložte si ho do nastavení pokladne. Posiela sa v hlavičke každej požiadavky:

Authorization: Bearer loyo_live_VAS_KLUC

Kľúč má plný prístup ku kartám vašej prevádzky. Používajte ho len zo servera alebo z pokladne – nikdy ho nevkladajte do aplikácie v mobile zákazníka ani do webovej stránky. Ak sa kľúč dostane von, v Integráciách ho zrušte a vytvorte nový.

Overenie nastavenia:

curl https://loyo.sk/api/v1/ja -H "Authorization: Bearer loyo_live_VAS_KLUC"

1. Zákazník ukáže kartu, pokladňa zistí jej stav

   Obsluha hneď vidí meno, počet pečiatok či kredit. Tento krok je voliteľný – ak chcete len zapísať nákup, choďte rovno na krok dva.

   curl https://loyo.sk/api/v1/karty/LY-7KQ2M9XA \
     -H "Authorization: Bearer loyo_live_VAS_KLUC"

   {
     "karta": {
       "seriove_cislo": "LY-7KQ2M9XA",
       "program": { "nazov": "Káva u Zuzky", "typ": "peciatky" },
       "zakaznik": { "meno": "Jana Nováková" },
       "stav": "aktivna",
       "peciatky": 7,
       "peciatky_na_odmenu": 8,
       "odmeny": 0,
       "odkazy": { "web": "https://loyo.sk/karta/LY-7KQ2M9XA" }
     }
   }

2. Po uzavretí účtu pokladňa zapíše návštevu

   Jedno volanie pre všetky typy programov. Pri pečiatkach pribudne pečiatka, pri bodoch a úrovniach body zo sumy, pri cashbacku kredit zo sumy. Ak program počíta zo sumy, je suma_centy povinná.

   curl -X POST https://loyo.sk/api/v1/karty/LY-7KQ2M9XA/navsteva \
     -H "Authorization: Bearer loyo_live_VAS_KLUC" \
     -H "Content-Type: application/json" \
     -d '{ "suma_centy": 1250, "poznamka": "Účtenka 2026-0412" }'

   {
     "karta": { "seriove_cislo": "LY-7KQ2M9XA", "peciatky": 0, "odmeny": 1 },
     "vysledok": { "sprava": "Karta je plná – odmena: Káva zadarmo", "nova_odmena": true }
   }

   Hodnotu vysledok.sprava ukážte obsluhe; ak je nova_odmena pravda, zákazník práve niečo získal. Karta v peňaženke sa aktualizuje sama.

3. Zákazník si uplatní odmenu

   Pri pečiatkach a bodoch odpíše odmenu, pri cashbacku použite čerpanie kreditu so sumou v centoch.

   curl -X POST https://loyo.sk/api/v1/karty/LY-7KQ2M9XA/odmena \
     -H "Authorization: Bearer loyo_live_VAS_KLUC"

Nový zákazník bez karty

Kartu vie vydať aj pokladňa. V odpovedi dostane odkazy, ktoré zákazníkovi pošle SMS-kou alebo e-mailom – po otvorení si kartu pridá do peňaženky jedným ťuknutím.

curl -X POST https://loyo.sk/api/v1/karty \
  -H "Authorization: Bearer loyo_live_VAS_KLUC" \
  -H "Content-Type: application/json" \
  -d '{ "meno": "Jana Nováková", "telefon": "+421 900 000 000" }'
# → 201 a karta.odkazy.web – pošlite zákazníčke SMS-kou

Všetky cesty začínajú https://loyo.sk/api/v1. Zápisové volania vyžadujú aktívne predplatné prevádzky; čítanie funguje vždy.

Parameter {kod} je sériové číslo, celý text z QR (URL-enkódovaný) alebo UUID karty. API vráti len karty vašej prevádzky; cudzie sa tvária, že neexistujú. Každá operácia má v odpovedi celú kartu, takže nemusíte volať GET znova.

Chyby majú vždy rovnaký tvar – strojový kód a slovenský text, ktorý môžete rovno ukázať obsluhe:

{
  "chyba": {
    "kod": "karta",
    "sprava": "Karta je zablokovaná."
  }
}

Pri chybe sa karta nemení – volanie môžete bezpečne zopakovať po oprave vstupu.

• Odporúčame najviac desať požiadaviek za sekundu na jeden kľúč; pokladňa bežne potrebuje jednu na účet.
• Telo požiadavky najviac 64 kB; poznámka najviac 300 znakov, správa zákazníkovi 2 až 300 znakov.
• Pečiatky najviac 30 naraz, body najviac milión naraz, suma nákupu najviac 100 000 €.
• Zoznam kariet vracia najviac 200 záznamov na stranu; história karty najviac 200 transakcií.
• Odpovede sa nekešujú. Ak pokladňa stratí spojenie, zápis zopakujte až po overení histórie karty, aby sa návšteva nezapísala dvakrát.
• Každý zápis sa zapíše do histórie karty s označením kľúča, ktorý ho vykonal – v administrácii viete dohľadať, čo ktorá pokladňa urobila.

Najjednoduchšia integrácia potrebuje jediné volanie po uzavretí účtu. Pseudokód:

# po uzavretí účtu v pokladni
ak zákazník ukázal kartu (naskenované QR obsahuje "LY-"):
    odpoveď = POST /api/v1/karty/{text z QR}/navsteva
              telo { suma_centy: suma_účtu_v_centoch, poznamka: číslo_účtenky }
    ak odpoveď.status == 200:
        zobraz obsluhe odpoveď.vysledok.sprava
        ak odpoveď.vysledok.nova_odmena: zvýrazni „Zákazník má odmenu!“
    inak ak odpoveď.status == 404: „Karta nepatrí tejto prevádzke“
    inak: zobraz odpoveď.chyba.sprava, účet dokonči bez karty

# zákazník chce uplatniť odmenu alebo zaplatiť kreditom
POST /api/v1/karty/{kod}/odmena            (pečiatky, body)
POST /api/v1/karty/{kod}/kredit/cerpanie   telo { centy: 300 }   (cashback)

Pri e-shope zavolajte návštevu po zaplatení objednávky; sériové číslo karty si zákazník zadá v účte alebo ho nájdete cez GET /karty?hladat=email.

Strojový popis API vo formáte OpenAPI 3.1 je na adrese /api/v1/openapi.json. Naimportujte ho do Postmana, Insomnie alebo generátora klientov vo vašom jazyku.

Chýba vám endpoint alebo pripravujete integráciu konkrétnej pokladne? Napíšte na hello@loyo.sk – radi pomôžeme a pripravíme testovací účet.