Приложение
Для разработчиков

Публичный API Punkto

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

Запросить доступВойдите в кабинет бизнеса, чтобы подать заявку — это бесплатно.

Как это работает

1

Отправьте заявку

В кабинете бизнеса → Настройки → API расскажите, что вы создаёте и зачем вам доступ.

2

Мы рассматриваем заявку

Наша команда проверяет заявку — обычно в течение пары дней.

3

Получите ключ

После одобрения 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 дорабатывается, заявки рассматривает наша команда — расскажите о своём приложении, и мы свяжемся с вами.

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

Скачать приложение партнёра

Получайте новых клиентов быстро и недорого

App StoreGoogle Play