API zľavových kódov

Rozhranie na overovanie a uplatňovanie zľavových kódov. Je oddelené od poukazov — má vlastnú databázu aj vlastné kľúče, takže ho môže používať ktorýkoľvek systém s platbou, aj taký, ktorý s poukazmi nemá nič spoločné.

Základná adresa: https://discount.voucher.monster/api/v1

Prihlásenie

Ku každej požiadavke patrí kľúč v hlavičke Authorization: Bearer dsc_… (prípadne X-Api-Key: dsc_…). Kľúč vydáva správca systému a platí vždy len v jednom priestore — kódy iných priestorov sú preň neviditeľné.

Oprávnenie	Čo umožňuje
verify	overiť kód a spočítať zľavu (má každý kľúč)
redeem	rezervovať, potvrdiť a uvoľniť uplatnenie
manage	zakladať a vypínať kódy, stornovať uplatnenia

Ako to funguje

Objednávka väčšinou vzniká skôr, než sa zaplatí, a platba môže zlyhať. Uplatnenie kódu preto prebieha v dvoch krokoch: najprv sa rezervuje (drží si miesto), po úhrade sa potvrdí.

1. zákazník zadá kód   →  POST /codes/{kód}/quote      (nič sa nemení)
2. zakladá sa platba   →  POST /codes/{kód}/reserve    (vráti token)
3. platba prešla       →  POST /reservations/{token}/confirm
   platba zlyhala      →  POST /reservations/{token}/release

Endpointy

Metóda	Cesta	Oprávnenie	Popis
GET	/ping	verify	kontrola kľúča a spojenia
GET	/codes	manage	zoznam kódov v priestore
POST	/codes	manage	založenie kódu
GET	/codes/{kód}	verify	stav kódu bez väzby na objednávku
POST	/codes/{kód}/quote	verify	spočíta zľavu, nič nemení
POST	/codes/{kód}/reserve	redeem	obsadí použitie, vráti token
POST	/codes/{kód}/redeem	redeem	rezervácia a potvrdenie naraz
POST	/codes/{kód}/disable	manage	vypne kód
GET	/reservations/{token}	verify	stav rezervácie
POST	/reservations/{token}/confirm	redeem	platba prešla
POST	/reservations/{token}/release	redeem	platba zlyhala, miesto sa vracia
POST	/reservations/{token}/refund	manage	storno už potvrdeného uplatnenia

Príklad

Overenie kódu

curl -X POST https://discount.voucher.monster/api/v1/codes/LETO2026/quote \
     -H "Authorization: Bearer dsc_…" \
     -H "Content-Type: application/json" \
     -d '{"amount": 120.00}'

{
    "valid": true,
    "status": "valid",
    "message": "Zľavový kód bol uplatnený.",
    "code": "LETO2026",
    "order_amount": 120.00,
    "discount_amount": 24.00,
    "final_amount": 96.00,
    "currency": "EUR",
    "discount_type": "percent",
    "discount_value": 20,
    "valid_to": "2026-09-30",
    "remaining_uses": 47
}

Rezervácia a potvrdenie

curl -X POST https://discount.voucher.monster/api/v1/codes/LETO2026/reserve \
     -H "Authorization: Bearer dsc_…" \
     -H "Content-Type: application/json" \
     -d '{"amount": 120.00, "order_ref": "objednavka-4711"}'

# → {"valid": true, …, "token": "9f2c…", "expires_at": "2026-08-17T15:24:00+00:00"}

curl -X POST https://discount.voucher.monster/api/v1/reservations/9f2c…/confirm \
     -H "Authorization: Bearer dsc_…"

Založenie kódu

curl -X POST https://discount.voucher.monster/api/v1/codes \
     -H "Authorization: Bearer dsc_…" \
     -H "Content-Type: application/json" \
     -d '{
           "code": "VIANOCE",
           "discount_type": "percent",
           "discount_value": 15,
           "max_uses": 100,
           "valid_from": "2026-12-01",
           "valid_to": "2026-12-24",
           "min_order_amount": 30,
           "max_discount_amount": 50
         }'

Bez poľa code systém vygeneruje náhodný kód sám. Prázdne max_uses znamená neobmedzený počet použití, prázdne valid_from / valid_to neobmedzenú platnosť.

Stavy a chyby

Odpoveď na /quote a /reserve obsahuje pole status. Neplatný kód nie je chyba formátu — telo je bežná odpoveď s "valid": false (pri /reserve s návratovým kódom 409).

status	Význam
valid	kód sa dá uplatniť
not_found	kód v tomto priestore neexistuje
inactive	kód alebo celý priestor je vypnutý
not_yet_valid	platnosť ešte nezačala
expired	platnosť skončila
used_up	kód je vyčerpaný
min_order	objednávka je nižšia než minimum kódu
exceeds_order	zľava je vyššia než hodnota objednávky
currency_mismatch	kód platí v inej mene
invalid_amount	suma objednávky je nula alebo záporná

Chyby prihlásenia a smerovania majú tvar {"error": "…", "message": "…"}: 401 missing_api_key, 401 invalid_api_key, 403 insufficient_scope, 403 scope_inactive, 404 not_found, 404 unknown_endpoint, 405 method_not_allowed, 422 validation_failed.

Kľúč

O kľúč požiadajte na halo@sportlikenow.com. Kľúč sa zobrazí jediný raz — v databáze zostáva len jeho odtlačok, takže spätne ho nevie zistiť nikto vrátane nás.