Bonus-bot — шапка (встраивание)
API интеграции для внешних разработчиков — Bonus-bot

Быстрый старт (5 шагов)

  1. Получите shop_id (UUID магазина) и integration_secret_token (для webhook-режима).
  2. На фронте выполняйте логин клиента в интеграции и сохраните session_token.
  3. Перед оформлением заказа вызовите /integration/balance и покажите пользователю доступные опции.
  4. После подтверждения заказа вызовите /integration/apply.
  5. Для серверного webhook отправляйте X-Integration-Secret + shop_id + session_token.

Модель авторизации

  • Обязательный заголовок для фронтовых вызовов: X-Shop-Id: <shop_uuid>
  • При вызовах через api.bonus-bot.ru также обязателен GUID: 69f9b580-6d8d-4a65-9245-949cc149b861
  • После успешного логина: Authorization: Bearer <session_token>
  • Срок жизни session_token: до 24 часов (в текущей конфигурации)

1) Запрос кода по телефону

POST /api/v1/integration/phone-code/request

Нужен для сценария входа по телефону и одноразовому коду.

Заголовки

  • Content-Type: application/json
  • X-Shop-Id: <shop_uuid>
  • GUID: 69f9b580-6d8d-4a65-9245-949cc149b861 (если домен api.bonus-bot.ru)

Тело запроса

json
{
  "phone": "+7 (999) 123-45-67"
}

Успешный ответ, HTTP 200

json
{
  "success": true,
  "expires_in": 300
}

Пример

bash
curl -X POST "https://api.bonus-bot.ru/api/v1/integration/phone-code/request" \
  -H "Content-Type: application/json" \
  -H "GUID: 69f9b580-6d8d-4a65-9245-949cc149b861" \
  -H "X-Shop-Id: 00000000-0000-0000-0000-000000000000" \
  -d '{"phone":"+7 (999) 123-45-67"}'

2) Вход и получение сессии интеграции

POST /api/v1/integration/login

Заголовки

  • Content-Type: application/json
  • X-Shop-Id: <shop_uuid>
  • GUID: 69f9b580-6d8d-4a65-9245-949cc149b861 (если домен api.bonus-bot.ru)

Вариант A: email и пароль

json
{
  "email": "client@example.com",
  "password": "secret"
}

Вариант B: телефон и код phone_code

json
{
  "phone": "+7 (999) 123-45-67",
  "phone_code": "123456"
}

Вариант C: telegram_code (из Mini App)

json
{
  "telegram_code": "AB12CD34"
}

Успешный ответ, HTTP 200

json
{
  "session_token": "<token>",
  "client_id": "11111111-1111-1111-1111-111111111111",
  "expires_in": 86400
}

Пример

bash
curl -X POST "https://api.bonus-bot.ru/api/v1/integration/login" \
  -H "Content-Type: application/json" \
  -H "GUID: 69f9b580-6d8d-4a65-9245-949cc149b861" \
  -H "X-Shop-Id: 00000000-0000-0000-0000-000000000000" \
  -d '{"email":"client@example.com","password":"secret"}'

3) Баланс и доступные суммы бонусов

POST /api/v1/integration/balance

Заголовки

  • Content-Type: application/json
  • X-Shop-Id: <shop_uuid>
  • Authorization: Bearer <session_token>
  • GUID: 69f9b580-6d8d-4a65-9245-949cc149b861 (если домен api.bonus-bot.ru)

Тело запроса

json
{
  "summa": 1500,
  "products": [
    { "amount": 600 },
    { "amount": 900 }
  ]
}

Успешный ответ, HTTP 200

json
{
  "id": "11111111-1111-1111-1111-111111111111",
  "summa": 1500,
  "balance": 2300,
  "candidate_del": 450,
  "candidate_add": 75
}

Пример

bash
curl -X POST "https://api.bonus-bot.ru/api/v1/integration/balance" \
  -H "Content-Type: application/json" \
  -H "GUID: 69f9b580-6d8d-4a65-9245-949cc149b861" \
  -H "X-Shop-Id: 00000000-0000-0000-0000-000000000000" \
  -H "Authorization: Bearer <session_token>" \
  -d '{"summa":1500,"products":[{"amount":600},{"amount":900}]}'

4) Применение операции с бонусами при оформлении заказа

POST /api/v1/integration/apply

4.1 Режим браузера (рекомендуется для своего фронтенда)

Заголовки

  • Content-Type: application/json
  • X-Shop-Id: <shop_uuid>
  • Authorization: Bearer <session_token>
  • GUID: 69f9b580-6d8d-4a65-9245-949cc149b861 (если домен api.bonus-bot.ru)

Тело запроса

json
{
  "id": "11111111-1111-1111-1111-111111111111",
  "balls": 300,
  "type_operation": "-",
  "payment": {
    "amount": 1200,
    "products": [
      { "amount": 500 },
      { "amount": 1000 }
    ]
  }
}

4.2 Режим вебхука (кассы, формы Tilda и др.)

Заголовки

  • Content-Type: application/json
  • X-Integration-Secret: <integration_secret_token>
  • GUID: 69f9b580-6d8d-4a65-9245-949cc149b861 — только если webhook идёт через api.bonus-bot.ru

Тело запроса (обязательные поля)

json
{
  "shop_id": "00000000-0000-0000-0000-000000000000",
  "id": "11111111-1111-1111-1111-111111111111",
  "balls": 300,
  "type_operation": "-",
  "session_token": "<session_token>",
  "payment": {
    "amount": 1200
  }
}

Успешный ответ, HTTP 200

json
"success"

type_operation: "-" — только списание; "flower" — только начисление; "sim_flower" — списание и начисление.

Пример (режим браузера)

bash
curl -X POST "https://api.bonus-bot.ru/api/v1/integration/apply" \
  -H "Content-Type: application/json" \
  -H "GUID: 69f9b580-6d8d-4a65-9245-949cc149b861" \
  -H "X-Shop-Id: 00000000-0000-0000-0000-000000000000" \
  -H "Authorization: Bearer <session_token>" \
  -d '{"id":"11111111-1111-1111-1111-111111111111","balls":300,"type_operation":"-","payment":{"amount":1200}}'

5) Проверка вебхука (тестовый запрос)

Для теста webhook можно отправить:

json
{ "test": "test" }

В ответе будет 200 и {}.

Поддерживается также POST /api/v1/integration (без /apply) для совместимости; для новых интеграций используйте только /integration/apply.

6) Обработка ошибок

Коды, которые стоит обрабатывать во внешнем UI:

  • 400 — неверный запрос / ввод
  • 401 — неверные данные или истёкший токен сессии
  • 403 — запрещено (несовпадение shop/token, интеграция выключена, email не подтверждён)
  • 404 — клиент или магазин не найдены
  • 429 — слишком много попыток входа
  • 503 — временная проблема доставки или платформы

У части ошибок detail приходит объектом:

json
{
  "detail": {
    "code": "ONLY_EMAIL_AVAILABLE",
    "message": "..."
  }
}

Рекомендация: показывать пользователю detail.message; по detail.code — ветвить логику интерфейса.

7) Публичные методы виджета Tilda (по желанию)

Если используете штатный Tilda-виджет Bonus-bot:

  • GET /api/v1/public/tilda-widget/{shop_id}/config
  • GET /api/v1/public/tilda-widget/{shop_id}/styles.css
  • GET /api/v1/public/tilda-widget/{shop_id}/tilda-loader.js
  • GET /api/v1/public/tilda-widget/{shop_id}/tilda-bonus.js

Для полностью кастомных интеграций эти URL вызывать не обязательно.

8) Чеклист перед продакшеном

  • Храните integration_secret_token только на сервере
  • Не доверяйте client_id без проверки session_token
  • При истечении сессии — повторный логин и обновление скрытых полей формы
  • Логируйте status, detail, detail.code при ошибках API