Aplikacja
Dla programistów

Publiczne API Punkto

Osadź program lojalnościowy Punkto we własnym produkcie — naliczaj i odejmuj punkty, generuj kody QR do wymiany punktów, sprawdzaj saldo klienta, link polecający, imię i awatar.

Poproś o dostępZaloguj się do panelu firmy, aby złożyć wniosek — to bezpłatne.

Jak to działa

1

Złóż wniosek

W panelu firmy → Ustawienia → API opisz, co budujesz i po co potrzebujesz dostępu.

2

Sprawdzamy wniosek

Nasz zespół weryfikuje zgłoszenie — zwykle w ciągu kilku dni.

3

Otrzymujesz klucz

Po zatwierdzeniu klucz API pojawi się w panelu. Skopiuj go od razu — ze względów bezpieczeństwa pokazujemy go tylko raz.

Uwierzytelnianie

Każde żądanie wymaga klucza API jako tokenu Bearer w nagłówku Authorization. Wszystkie endpointy działają w imieniu Twojej firmy; klienci są identyfikowani po numerze telefonu, ponieważ zewnętrzne aplikacje nie mają wewnętrznego identyfikatora klienta Punkto.

Authorization: Bearer $PUNKTO_API_KEY

Endpointy

GET/business

Profil Twojej firmy

Odczytaj publiczne dane swojej firmy oraz konfigurację punktów/rabatów — godziny, adres, liczbę punktów na jednostkę waluty, maksymalny procent rabatu i progi — dzięki temu integracja sama się skonfiguruje zamiast zaszywać limity na sztywno.

Żądanie

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

Odpowiedź

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

Naliczanie punktów

Naliczaj punkty klientowi po zakupie — ta sama stawka co w aplikacyjnym skanowaniu QR (zaokrąglana w dół).

Żądanie

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

Odpowiedź

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

Odejmowanie punktów

Wymień punkty na rabat od kwoty paragonu. Kwota jest automatycznie ograniczana zgodnie z Twoimi ustawieniami rabatów.

Żądanie

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

Odpowiedź

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

Generowanie kodu QR do wymiany

Wystaw krótkotrwały kod (2 minuty), którym klient wymieni punkty na miejscu. Wyrenderuj `code` jako QR samodzielnie albo pozwól wpisać 6-cyfrowy `shortCode`.

Żądanie

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

Odpowiedź

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

Lista firm

Publiczny katalog aktywnych firm Punkto — ta sama lista, którą widać w aplikacji klienta.

Żądanie

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

Odpowiedź

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

Lista Twoich nagród

Katalog specjalnych ofert/nagród Twojej firmy — ta sama lista, którą widać w popupie ze szczegółami firmy w aplikacji klienta.

Żądanie

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

Odpowiedź

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

Wymiana nagrody

Wymień konkretną nazwaną nagrodę dla klienta (np. „Darmowa kawa”) zamiast ogólnego rabatu za punkty — odejmuje jej koszt w punktach z salda klienta.

Żądanie

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

Odpowiedź

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

Lista Twoich produktów/usług

Katalog produktów/usług Twojej firmy — ta sama lista, którą widać w aplikacji klienta.

Żądanie

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

Odpowiedź

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

Saldo punktów klienta

Sprawdź, ile punktów ma aktualnie klient.

Żądanie

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

Odpowiedź

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

Historia punktów klienta

Transakcje punktowe klienta w Twojej firmie, od najnowszych — przydatne do rozliczeń. Ograniczone do `limit` wierszy (domyślnie 50, maks. 200).

Żądanie

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

Odpowiedź

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

Link polecający klienta

Pobierz kod polecający klienta — nowi użytkownicy, którzy go wpiszą, zostaną powiązani jako polecony przez niego.

Żądanie

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

Odpowiedź

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

Imię i awatar klienta

Odczytaj wyświetlaną nazwę i awatar klienta.

Żądanie

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

Odpowiedź

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

Aktualizacja imienia i awatara

Zaktualizuj wyświetlaną nazwę i/lub adres URL awatara klienta.

Żądanie

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

Odpowiedź

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

Warto wiedzieć

  • Klienci są identyfikowani po numerze telefonu — aplikacja zewnętrzna nie ma wewnętrznego identyfikatora klienta Punkto.
  • Jeśli numer telefonu nie należy do zarejestrowanego klienta Punkto, endpoint zwraca 404 zamiast tworzyć konto.
  • Naliczone punkty są zaokrąglane w dół; wymieniane punkty automatycznie respektują skonfigurowane przez Ciebie progi rabatowe — nie musisz dodawać własnej logiki.

Gotowy na integrację?

Wnioski są weryfikowane przez nasz zespół, dopóki publiczne API jest dopracowywane — opowiedz nam o swojej aplikacji, a odezwiemy się.

Poproś o dostęp

Pobierz aplikację partnera

Zdobywaj nowych klientów szybko i tanio

App StoreGoogle Play