Aplikace
Pro vývojáře

Veřejné API Punkto

Zabuduj věrnostní program Punkto do vlastního produktu — přiděluj a uplatňuj body, generuj QR kódy pro uplatnění, zjišťuj zůstatek zákazníka, doporučující odkaz, jméno a avatar.

Požádat o přístupPřihlas se do panelu své firmy a požádej o přístup — je to zdarma.

Jak to funguje

1

Odešli žádost

V panelu firmy → Nastavení → API nám popiš, co vytváříš a proč potřebuješ přístup.

2

My ji posoudíme

Náš tým žádost zkontroluje — obvykle do pár dní.

3

Získej svůj klíč

Po schválení se API klíč objeví v panelu. Zkopíruj si ho hned — z bezpečnostních důvodů se zobrazí jen jednou.

Autentizace

Každý požadavek potřebuje tvůj API klíč jako Bearer token v hlavičce Authorization. Všechny endpointy fungují jménem tvé firmy; zákazníci jsou identifikováni podle telefonního čísla, protože aplikace třetích stran nemají interní ID zákazníka Punkto.

Authorization: Bearer $PUNKTO_API_KEY

Endpointy

GET/business

Profil tvé firmy

Přečti si veřejné údaje o své firmě a konfiguraci bodů/slev — otevírací dobu, adresu, počet bodů na jednotku měny, maximální poměr slevy a pásma — díky tomu se tvoje integrace může nastavit sama, místo aby měla limity napevno zakódované.

Požadavek

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

Odpověď

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

Přidělení bodů

Připiš body zákazníkovi po nákupu — stejnou sazbou jako při skenování QR v aplikaci (zaokrouhleno dolů).

Požadavek

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

Odpověď

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

Odečtení bodů

Uplatni body jako slevu z celkové částky účtenky. Částka je automaticky omezena tvými nastavenými limity slevy.

Požadavek

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

Odpověď

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

Generování QR kódu pro uplatnění

Vydej krátkodobý kód (2 minuty), který zákazník použije k uplatnění bodů osobně. Vykresli `code` jako QR sám, nebo nech zákazníka zadat 6místný `shortCode`.

Požadavek

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

Odpověď

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

Seznam firem

Veřejný adresář aktivních firem Punkto — stejný seznam, jaký se zobrazuje v aplikaci pro zákazníky.

Požadavek

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

Odpověď

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

Seznam tvých odměn

Katalog speciálních nabídek/odměn tvé firmy — stejný seznam, jaký se zobrazuje v popupu s detailem firmy v aplikaci pro zákazníky.

Požadavek

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

Odpověď

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

Uplatnění odměny

Uplatni konkrétní pojmenovanou odměnu pro zákazníka (např. „Káva zdarma“) místo obecné slevy za body — odečte její cenu v bodech z jeho zůstatku.

Požadavek

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

Odpověď

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

Seznam tvých produktů/služeb

Katalog produktů/služeb tvé firmy — stejný seznam, jaký se zobrazuje v aplikaci pro zákazníky.

Požadavek

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

Odpověď

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

Zůstatek bodů zákazníka

Zjisti, kolik bodů má zákazník aktuálně k dispozici.

Požadavek

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

Odpověď

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

Historie bodů zákazníka

Transakce s body zákazníka u tvé firmy, od nejnovějších — užitečné pro odsouhlasení dat. Omezeno na `limit` řádků (výchozí 50, max. 200).

Požadavek

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

Odpověď

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

Doporučující odkaz zákazníka

Získej doporučující kód zákazníka — noví registrovaní, kteří ho zadají, budou propojeni jako doporučení jím.

Požadavek

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

Odpověď

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

Jméno a avatar zákazníka

Přečti si zobrazované jméno a avatar zákazníka.

Požadavek

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

Odpověď

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

Aktualizace jména a avataru

Aktualizuj zobrazované jméno a/nebo URL avataru zákazníka.

Požadavek

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

Odpověď

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

Dobré vědět

  • Zákazníci jsou identifikováni podle telefonního čísla — aplikace třetí strany nemá k dispozici interní ID zákazníka Punkto.
  • Pokud telefonní číslo nepatří registrovanému zákazníkovi Punkto, endpoint vrátí 404 místo vytvoření účtu.
  • Přidělené body se zaokrouhlují dolů; uplatněné body automaticky respektují tvá nastavená pásma slev — na tvé straně není potřeba žádná další logika.

Připraven(a) na integraci?

Žádosti posuzuje náš tým, dokud se veřejné API ještě dokončuje — popiš nám svou aplikaci a ozveme se.

Požádat o přístup

Stáhni si partnerskou aplikaci

Získávej nové zákazníky rychle a levně

App StoreGoogle Play