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

Быстрый старт

Общая схема работы

  • Клиент — покупатель магазина, который оформляет заказ и использует бонусную программу.
  • Платформа — сервис Bonus-bot, где хранятся балансы, правила начисления/списания и события по клиенту.
  • Сайт — интернет-магазин или витрина (например, Tilda), где клиент проходит оформление заказа.

Схема процесса

Сайт Платформа Корзина Покупка Webhook Уведомление
  1. Клиент переходит на сайт и начинает оформление заказа.
  2. Клиент переходит по ссылке и регистрируется на платформе Bonus-bot удобным и разрешённым способом. Сейчас доступны Max, VK, Telegram и Email. Каждый способ администратор магазина может включать или отключать в настройках.
  3. Клиент возвращается в корзину и проходит авторизацию. Доступные варианты: по коду из мессенджера или по email. При входе по коду клиент получает 6-значный код в один из доступных мессенджеров. При входе по email используются данные, заданные при регистрации (email и пароль).
  4. Клиент видит баланс и доступные суммы накопления/списания, выбирает тип операции и завершает покупку.
  5. После оформления заказа сайт отправляет webhook в платформу Bonus-bot для регистрации бонусной операции.
  6. Платформа Bonus-bot регистрирует операцию и отправляет клиенту уведомление.

Начало настройки интеграции

  1. Зарегистрируйтесь и создайте магазин на платформе b.bonus-bot.ru.
  2. Настройте в магазине нужные способы авторизации клиента.
  3. Перейдите в настройки интеграции и активируйте интеграцию Tilda.
  4. Включите или отключите способ авторизации по email.
  5. Сгенерируйте токен безопасности для webhook на этой странице. Для дополнительной безопасности рекомендуется перевыпускать токен раз в месяц.
  6. Получите shop_id (UUID магазина) из URL-строки браузера.
  7. Реализуйте взаимодействие с API по разделам ниже.

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

  • Обязательный заголовок для фронтовых вызовов: 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)

Тело запроса

Рекомендуемый формат телефона: +79991234567 (без пробелов и скобок).

json
{
  "phone": "+79991234567"
}

Успешный ответ, 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":"+79991234567"}'

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": "+79991234567",
  "phone_code": "123456"
}

Успешный ответ, 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

Рекомендуется использовать прямой вызов через b.bonus-bot.ru. В этом случае заголовок GUID не требуется.

Заголовки

  • 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" — списание и начисление.

Пример (рекомендуемый: прямой webhook в b.bonus-bot.ru)

bash
curl -X POST "https://b.bonus-bot.ru/api/v1/integration/apply" \
  -H "Content-Type: application/json" \
  -H "X-Integration-Secret: <integration_secret_token>" \
  -d '{"shop_id":"00000000-0000-0000-0000-000000000000","id":"11111111-1111-1111-1111-111111111111","balls":300,"type_operation":"-","session_token":"<session_token>","payment":{"amount":1200}}'

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

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

json
{ "test": "test" }

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

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.