Для розробників

Публічний API Punkto

Вбудуйте програму лояльності Punkto у свій продукт — нараховуйте та списуйте бали, генеруйте QR-коди для списання, перевіряйте баланс клієнта, реферальне посилання, ім'я та аватар.

Запросити доступУвійдіть у кабінет бізнесу, щоб подати заявку — це безкоштовно.

Як це працює

Надішліть заявку

У кабінеті бізнесу → Налаштування → API розкажіть, що ви створюєте і навіщо вам доступ.

Ми розглядаємо заявку

Наша команда перевіряє заявку — зазвичай протягом кількох днів.

Отримайте ключ

Після схвалення API-ключ з'явиться в кабінеті. Скопіюйте його одразу — з міркувань безпеки він показується лише один раз.

Автентифікація

Кожен запит потребує API-ключ як Bearer-токен у заголовку Authorization. Усі ендпоінти діють від імені вашого бізнесу; клієнти визначаються за номером телефону, оскільки сторонні застосунки не мають внутрішнього ідентифікатора клієнта Punkto.

Authorization: Bearer $PUNKTO_API_KEY

Ендпоінти

GET/business

Профіль вашого бізнесу

Прочитайте публічні дані свого бізнесу та налаштування балів/знижок — години роботи, адресу, кількість балів на одиницю валюти, максимальний відсоток знижки та рівні — щоб інтеграція налаштовувалася сама, а не захардкоджувала ліміти.

Запит

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

Відповідь

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

Нарахування балів

Нарахуйте бали клієнту після покупки — за тим самим тарифом, що й сканування QR у застосунку (округлення вниз).

Запит

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

Відповідь

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

POST/points/redeem

Списання балів

Спишіть бали як знижку від суми чека. Сума автоматично обмежується налаштованими лімітами знижок.

Запит

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

Відповідь

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

POST/points/redeem-code

Генерація QR-коду для списання

Видайте короткочасний код (2 хвилини), яким клієнт спише бали на місці. Відрендеріть `code` як QR самостійно або дозвольте ввести 6-значний `shortCode`.

Запит

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

Відповідь

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

GET/businesses

Список бізнесів

Публічний каталог активних бізнесів Punkto — той самий список, що видно в застосунку клієнта.

Запит

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

Відповідь

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

GET/rewards

Список ваших нагород

Каталог спеціальних пропозицій/нагород вашого бізнесу — той самий список, що видно у спливному вікні з деталями бізнесу в застосунку клієнта.

Запит

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

Відповідь

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

POST/rewards/:rewardId/redeem

Погашення нагороди

Погасіть конкретну названу нагороду для клієнта (наприклад, «Безкоштовна кава») замість звичайної знижки за бали — спише її вартість у балах з балансу клієнта.

Запит

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

Відповідь

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

Список ваших товарів/послуг

Каталог товарів/послуг вашого бізнесу — той самий список, що видно в застосунку клієнта.

Запит

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

Відповідь

{
  "products": [
    { "id": "cknq0prd10000...", "name": "Cappuccino", "price": 14.5, "emoji": "☕" }
  ]
}

GET/customers/:phone/balance

Баланс балів клієнта

Дізнайтеся, скільки балів зараз має клієнт.

Запит

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

Відповідь

{
  "points": 150
}

GET/customers/:phone/history

Історія балів клієнта

Транзакції з балами клієнта у вашому бізнесі, від найновіших — корисно для звірки. Обмежено `limit` рядками (за замовчуванням 50, максимум 200).

Запит

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

Відповідь

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

Реферальне посилання клієнта

Отримайте реферальний код клієнта — нові користувачі, які його введуть, будуть прив'язані як запрошені ним.

Запит

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

Відповідь

{
  "referralCode": "GT2DEY"
}

GET/customers/:phone/profile

Ім'я та аватар клієнта

Прочитайте відображуване ім'я та аватар клієнта.

Запит

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

Відповідь

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

PATCH/customers/:phone/profile

Оновлення імені та аватара

Оновіть відображуване ім'я та/або URL аватара клієнта.

Запит

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

Відповідь

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

Варто знати

Клієнти визначаються за номером телефону — сторонній застосунок не має внутрішнього ідентифікатора клієнта Punkto.
Якщо номер телефону не належить зареєстрованому клієнту Punkto, ендпоінт поверне 404, а не створить акаунт.
Нараховані бали округлюються вниз; списувані бали автоматично враховують налаштовані вами рівні знижок — додаткова логіка на вашому боці не потрібна.

Готові інтегруватися?

Поки публічний API допрацьовується, заявки розглядає наша команда — розкажіть про свій застосунок, і ми зв'яжемося з вами.

Запросити доступ

Публічний API Punkto

Як це працює

Надішліть заявку

Ми розглядаємо заявку

Отримайте ключ

Автентифікація

Ендпоінти

Профіль вашого бізнесу

Нарахування балів

Списання балів

Генерація QR-коду для списання

Список бізнесів

Список ваших нагород

Погашення нагороди

Список ваших товарів/послуг

Баланс балів клієнта

Історія балів клієнта

Реферальне посилання клієнта

Ім'я та аватар клієнта

Оновлення імені та аватара

Варто знати

Готові інтегруватися?

Завантажити застосунок партнера