Aplikácia
Pre vývojárov

Verejné API Punkto

Zabuduj vernostný program Punkto do vlastného produktu — prideľuj a uplatňuj body, generuj QR kódy na uplatnenie, over si zostatok zákazníka, jeho odporúčací odkaz, meno a avatar.

Požiadať o prístupPrihlás sa do svojho firemného panela a podaj žiadosť — je to zadarmo.

Ako to funguje

1

Odošli žiadosť

Vo svojom firemnom paneli → Nastavenia → API nám napíš, čo staviaš a prečo potrebuješ prístup.

2

Posúdime ju

Náš tím žiadosť skontroluje — zvyčajne do pár dní.

3

Získaj svoj kľúč

Po schválení sa tvoj API kľúč zobrazí v paneli. Skopíruj si ho hneď — z bezpečnostných dôvodov sa zobrazí len raz.

Autentifikácia

Každá požiadavka potrebuje tvoj API kľúč ako Bearer token v hlavičke Authorization. Všetky endpointy fungujú v mene tvojej firmy; zákazníci sú identifikovaní telefónnym číslom, keďže aplikácie tretích strán nemajú interné ID zákazníka Punkto.

Authorization: Bearer $PUNKTO_API_KEY

Endpointy

GET/business

Profil tvojej firmy

Načítaj verejné údaje o svojej firme aj konfiguráciu bodov/zliav — otváracie hodiny, adresu, počet bodov na menovú jednotku, maximálny pomer zľavy a pásma — aby sa tvoja integrácia dokázala nakonfigurovať sama namiesto natvrdo zadaných limitov.

Požiadavka

curl https://api.punkto.app/api/public/v1/business \
  -H "Authorization: Bearer $PUNKTO_API_KEY"

Odpoveď

{
  "business": {
    "id": "cknq0abc10000...",
    "name": "Coffee Corner",
    "slug": "coffee-corner",
    "city": "Warszawa",
    "workingHours": { "mon": { "open": "08:00", "close": "18:00" } },
    "pointsPerCurrencyUnit": 0.1,
    "maxDiscountRatio": 0.2,
    "maxDiscountPerReceipt": null,
    "discountTiers": null,
    "category": { "slug": "cafes", "name": "Cafes" }
  }
}
POST/points/earn

Prideliť body

Pripíš zákazníkovi body po nákupe — rovnakou sadzbou ako pri skenovaní QR kódu priamo v aplikácii (zaokrúhlené nadol).

Požiadavka

curl -X POST https://api.punkto.app/api/public/v1/points/earn \
  -H "Authorization: Bearer $PUNKTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone": "+48123456789", "amount": 49.90}'

Odpoveď

{
  "balance": 5,
  "transaction": {
    "id": "cknq0x1a20001...",
    "type": "earn",
    "points": 5,
    "createdAt": "2026-09-23T23:16:50.250Z"
  }
}
POST/points/redeem

Odpočítať body

Uplatni body ako zľavu voči sume účtenky. Suma je automaticky obmedzená tvojimi nastavenými limitmi zľavy.

Požiadavka

curl -X POST https://api.punkto.app/api/public/v1/points/redeem \
  -H "Authorization: Bearer $PUNKTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone": "+48123456789", "points": 20, "receiptAmount": 49.90}'

Odpoveď

{
  "balance": 130,
  "discountAmount": 20,
  "transaction": {
    "id": "cknq0x1a20002...",
    "type": "redeem",
    "points": 20,
    "createdAt": "2026-09-23T23:18:12.104Z"
  }
}
POST/points/redeem-code

Vygenerovať QR kód na uplatnenie

Vydaj krátkodobý kód (2 minúty), ktorý zákazník môže použiť na osobné uplatnenie bodov. Hodnotu `code` si vykresli ako QR sám, alebo nechaj zákazníka zadať 6-miestny `shortCode`.

Požiadavka

curl -X POST https://api.punkto.app/api/public/v1/points/redeem-code \
  -H "Authorization: Bearer $PUNKTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone": "+48123456789", "points": 20}'

Odpoveď

{
  "code": "eyJhbGciOiJIUzI1NiIs...",
  "shortCode": "482913",
  "expiresIn": 120,
  "requestedPoints": 20,
  "grantedPoints": 20,
  "capped": false
}
GET/businesses

Zoznam firiem

Verejný zoznam aktívnych firiem Punkto — rovnaký, aký sa zobrazuje v zákazníckej aplikácii.

Požiadavka

curl https://api.punkto.app/api/public/v1/businesses \
  -H "Authorization: Bearer $PUNKTO_API_KEY"

Odpoveď

{
  "businesses": [
    {
      "id": "cknq0abc10000...",
      "slug": "coffee-corner",
      "name": "Coffee Corner",
      "logoUrl": "https://...",
      "city": "Warszawa",
      "category": { "slug": "cafes", "name": "Cafes" }
    }
  ]
}
GET/rewards

Zoznam tvojich ponúk

Katalóg špeciálnych ponúk/odmien tvojej firmy — rovnaký zoznam, aký sa zobrazuje v okne s detailom firmy v zákazníckej aplikácii.

Požiadavka

curl https://api.punkto.app/api/public/v1/rewards \
  -H "Authorization: Bearer $PUNKTO_API_KEY"

Odpoveď

{
  "rewards": [
    {
      "id": "cknq0rwd10000...",
      "name": "Free coffee",
      "costPoints": 100,
      "discountType": "amount",
      "discountValue": 10
    }
  ]
}
POST/rewards/:rewardId/redeem

Uplatniť odmenu

Uplatni pre zákazníka konkrétnu pomenovanú odmenu (napr. „Káva zadarmo“) namiesto všeobecnej zľavy za body — z jeho zostatku odpočíta jej cenu v bodoch.

Požiadavka

curl -X POST https://api.punkto.app/api/public/v1/rewards/cknq0rwd10000.../redeem \
  -H "Authorization: Bearer $PUNKTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone": "+48123456789"}'

Odpoveď

{
  "balance": 50,
  "reward": { "id": "cknq0rwd10000...", "name": "Free coffee", "costPoints": 100 },
  "transaction": {
    "id": "cknq0x1a20003...",
    "type": "redeem",
    "points": -100,
    "createdAt": "2026-09-23T23:53:15.497Z"
  }
}
GET/products

Zoznam tvojich produktov/služieb

Katalóg produktov/služieb tvojej firmy — rovnaký zoznam, aký sa zobrazuje v zákazníckej aplikácii.

Požiadavka

curl https://api.punkto.app/api/public/v1/products \
  -H "Authorization: Bearer $PUNKTO_API_KEY"

Odpoveď

{
  "products": [
    { "id": "cknq0prd10000...", "name": "Cappuccino", "price": 14.5, "emoji": "☕" }
  ]
}
GET/customers/:phone/balance

Zostatok bodov zákazníka

Zisti, koľko bodov má zákazník aktuálne k dispozícii.

Požiadavka

curl https://api.punkto.app/api/public/v1/customers/+48123456789/balance \
  -H "Authorization: Bearer $PUNKTO_API_KEY"

Odpoveď

{
  "points": 150
}
GET/customers/:phone/history

História bodov zákazníka

Transakcie zákazníka s bodmi u tvojej firmy, od najnovších — užitočné na porovnávanie. Obmedzené na `limit` riadkov (predvolene 50, max. 200).

Požiadavka

curl "https://api.punkto.app/api/public/v1/customers/+48123456789/history?limit=20" \
  -H "Authorization: Bearer $PUNKTO_API_KEY"

Odpoveď

{
  "transactions": [
    { "id": "cknq0x1a20001...", "type": "earn", "points": 5, "createdAt": "2026-09-23T23:16:50.250Z" },
    { "id": "cknq0x1a20002...", "type": "redeem", "points": -20, "createdAt": "2026-09-23T23:18:12.104Z" }
  ]
}
GET/customers/:phone/referral

Odporúčací odkaz zákazníka

Získaj odporúčací kód zákazníka — noví používatelia, ktorí ho zadajú pri registrácii, sa priradia ako jeho odporúčaní.

Požiadavka

curl https://api.punkto.app/api/public/v1/customers/+48123456789/referral \
  -H "Authorization: Bearer $PUNKTO_API_KEY"

Odpoveď

{
  "referralCode": "GT2DEY"
}
GET/customers/:phone/profile

Meno a avatar zákazníka

Načítaj zobrazované meno a avatar zákazníka.

Požiadavka

curl https://api.punkto.app/api/public/v1/customers/+48123456789/profile \
  -H "Authorization: Bearer $PUNKTO_API_KEY"

Odpoveď

{
  "name": "Anna Kowalska",
  "avatarUrl": "https://..."
}
PATCH/customers/:phone/profile

Aktualizovať meno a avatar

Aktualizuj zobrazované meno a/alebo URL avatara zákazníka.

Požiadavka

curl -X PATCH https://api.punkto.app/api/public/v1/customers/+48123456789/profile \
  -H "Authorization: Bearer $PUNKTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Anna Kowalska"}'

Odpoveď

{
  "name": "Anna Kowalska",
  "avatarUrl": "https://..."
}

Dobré vedieť

  • Zákazníci sú identifikovaní telefónnym číslom — aplikácia tretej strany nemá k dispozícii interné ID zákazníka Punkto.
  • Ak telefónne číslo nepatrí registrovanému zákazníkovi Punkto, endpoint vráti 404 namiesto vytvorenia účtu.
  • Získané body sa zaokrúhľujú nadol; uplatnené body automaticky rešpektujú tvoje nastavené pásma zľavy — na tvojej strane netreba žiadnu ďalšiu logiku.

Pripravený integrovať?

Žiadosti posudzuje náš tím, kým verejné API ešte dokončujeme — napíš nám o svojej aplikácii a ozveme sa ti.

Požiadať o prístup

Stiahni si aplikáciu partnera

Získavaj nových zákazníkov rýchlo a lacno

App StoreGoogle Play