Готовые интеграции BOT-T (bott-examples)

Пошаговая инструкция для начинающих: как подключить готовые сценарии без программирования с нуля.

Репозиторий с примерами: github.com/Purt09/bott-examples
Рабочие PHP-скрипты уже размещены на сервере: https://custom.bot-t.com/
Папки python/ и javascript/ в репозитории — только учебные примеры (их нужно разворачивать на своём сервере). В этой инструкции используются готовые PHP-ссылки на custom.bot-t.com.

1. Что вообще происходит

Упрощённая схема для магазина:

sequenceDiagram
    participant Покупатель
    participant BOT-T
    participant Ваш_URL as custom.bot-t.com

    Покупатель->>BOT-T: Оплатил заказ
    BOT-T->>Ваш_URL: POST с данными заказа
    Ваш_URL->>BOT-T: API (например начислить баланс)
    BOT-T->>Покупатель: Выдача товара / уведомление

Покупатель оплачивает товар в боте.
BOT-T отправляет POST-запрос на URL, который вы указали в настройках товара.
PHP-скрипт на custom.bot-t.com обрабатывает запрос и при необходимости вызывает API BOT-T (например, пополнение баланса).
BOT-T завершает выдачу товара покупателю.

Вам не нужно писать свой сервер, если подходит готовый PHP-пример — достаточно скопировать ссылку в личный кабинет и подставить свои параметры.

2. Что понадобится перед стартом

Параметр	Где взять	Зачем
ID бота (`bot_id`)	ЛК BOT-T, раздел бота	Числовой идентификатор бота в системе
Токен бота (`token`)	Настройки бота / BotFather	Доступ к API BOT-T от имени бота
ID пользователя бота (`bot_user_id`)	ЛК → пользователи бота	Нужен для сценариев «начислить не покупателю, а другому»
Коэффициент (`coef`)	Вы задаёте сами	Доля от суммы или количества (см. каждый сценарий)
Тип товара	Настройки категории магазина	Для проверки товара — только «Уникальный товар»

Важно про деньги:

В webhook заказа поле amount — сумма в копейках (минимальных единицах валюты).
В API add-balance поле sum передаётся в рублях (или основных единицах валюты), с копейками после запятой. Готовые скрипты уже переводят копейки в рубли (÷ 100).

Безопасность: токен бота в URL виден в настройках ЛК и в логах. Не публикуйте готовую ссылку в открытом доступе. Для продакшена со временем лучше свой сервер и секреты вне URL — но для старта допустимы примеры на custom.bot-t.com, как задумано в репозитории.

3. Где в ЛК вставлять ссылки

Магазин: уведомление после оплаты

Откройте Магазин → нужная категория (товар).
Раздел «Управление API» (или настройки API категории).
Поле «URL вебхука (уведомление после оплаты заказа)» — сюда вставляется ссылка вида:
https://custom.bot-t.com/cashback/index.php?bot_id=...&token=...&coef=...
Сохраните.

Сюда подходят: cashback, balance, bonususer, bonususerfix, gift-send.

Магазин: проверка товара перед выдачей

Только для типа товара «Уникальный товар».

Тот же раздел «Управление API».
Поле «URL вебхука (проверка товара перед выдачей клиенту)».
Пример: https://custom.bot-t.com/product-check/accept.php — всегда разрешить строку
или https://custom.bot-t.com/product-check/reject.php — всегда отклонить (для теста).

Обратная связь (форма в сообщении бота)

Сообщение с типом «Обратная связь» → настройки API формы.
Тип интеграции: пользовательский / Custom (свой URL).
В поле URL (публичный адрес обработчика) укажите, например:
https://custom.bot-t.com/feedback/repeat-and-message.php

4. Формат данных от BOT-T

4.1. Webhook после оплаты заказа


Метод	`POST`
Content-Type	`application/x-www-form-urlencoded`
Параметры в URL	Ваши настройки: `bot_id`, `token`, `coef`, `bot_user_id`, `gift_id` и т.д.

Основные поля в теле запроса (POST):

Поле	Описание
`id`	Номер заказа
`count`	Количество единиц
`amount`	Сумма заказа в копейках
`status`	Статус заказа (`1` — оплачен)
`botUser[id]`	ID покупателя в боте (для начисления ему)
`botUser`, `user`, `category`, `product`, …	Полные данные заказа (как в справке ЛК)

Ответ вашего скрипта: достаточно HTTP 2xx (пустое тело допустимо). BOT-T повторит отправку при ошибке (до нескольких попыток).

Статусы заказа (кратко): 0 — ждёт оплаты, 1 — оплачен, 5 — выполнен. Скрипт gift-send обрабатывает только status=1, остальные сценарии на custom.bot-t.com рассчитаны на вызов после успешной оплаты.

4.2. API начисления баланса (вызывают скрипты сами)

Готовые PHP-скрипты вызывают:

POST https://api.bot-t.com/v1/bot/user/add-balance?token={TOKEN}

Тело (form или JSON — в примерах используется form):

Поле	Описание
`bot_id`	ID бота
`user_id`	bot_user_id — кому начислить
`sum`	Сумма в рублях (например `10.50`)
`comment`	Текст в истории баланса (необязательно в balance)

Ответ API: {"result": true, "data": ...} или {"result": false, "message": "..."}.

4.3. Проверка строки товара (уникальный товар)


Метод	`POST`
Тело	`product` — одна строка со склада

Ответ (JSON):

{"success": true}

или

{"success": false}

true — строка подходит, переходим к следующей единице заказа.
false — строка снимается с продажи, BOT-T берёт следующую.
Ошибка HTTP или не JSON — заказ не выполняется.

4.4. Обратная связь (Custom API)


Метод	`POST`
Тело	Данные ответа на форму (поля анкеты)

Ответ (JSON):

Успех с сообщением пользователю:

{
  "result": true,
  "data": {
    "message": "Текст ответа покупателю в Telegram",
    "is_repeat": false
  }
}

Отклонение:

{
  "result": false,
  "message": "Причина отказа"
}

Если is_repeat: true, бот снова покажет форму (удобно для «исправьте ответ»).

5. Сценарии по шагам

Базовый шаблон ссылки:

https://custom.bot-t.com/{папка}/index.php?bot_id={ID}&token={TOKEN}&...

Подставьте свои значения без фигурных скобок.

5.1. Cashback покупателю

Задача: после оплаты вернуть покупателю часть суммы на внутренний баланс бота.

Ссылка для ЛК:

https://custom.bot-t.com/cashback/index.php?bot_id=1&token=ВАШ_ТОКЕН&coef=0.02

Параметр	Значение
`coef=0.02`	2% от суммы заказа (`amount` в копейках × 0.02)
`coef=0.05`	5% и т.д.

Кому начисляется: покупатель из заказа (botUser[id]).

Пример: заказ на 1000 ₽ → amount=100000 коп. → cashback 2% → 20 ₽ на баланс.

Куда вставить: «URL вебхука (уведомление после оплаты заказа)».

Исходник PHP: cashback/index.php

5.2. Бонус за количество товара (balance)

Задача: начислить покупателю фиксированную сумму за каждую купленную единицу, не от общей суммы чека.

Ссылка:

https://custom.bot-t.com/balance/index.php?bot_id=1&token=ВАШ_ТОКЕН&coef=1

Формула: count × 100 копеек × coef → перевод в рубли для API.

coef	Смысл (при coef=1)
`1`	1 ₽ за каждую единицу (`count=3` → 3 ₽)
`0.5`	50 коп. за единицу
`10`	10 ₽ за единицу

Кому: покупатель (botUser[id]).

Куда вставить: URL после оплаты.

Исходник: balance/index.php

5.3. Отчисление другому пользователю, процент (bonususer)

Задача: после каждой оплаты начислять партнёру / рефереру / админу долю от суммы заказа (не покупателю).

Ссылка:

https://custom.bot-t.com/bonususer/index.php?bot_id=1&token=ВАШ_ТОКЕН&bot_user_id=42&coef=0.1

Параметр	Описание
`bot_user_id`	Кому начислить (ID в боте, не Telegram ID)
`coef=0.1`	10% от `amount` заказа

Как узнать bot_user_id: ЛК → пользователи бота → откройте карточку нужного человека → ID пользователя в контексте бота.

Куда вставить: URL после оплаты.

Исходник: bonususer/index.php

5.4. Фиксированное отчисление другому пользователю (bonususerfix)

Задача: после каждой оплаты начислять одну и ту же сумму указанному пользователю, независимо от суммы заказа.

Ссылка:

https://custom.bot-t.com/bonususerfix/index.php?bot_id=1&token=ВАШ_ТОКЕН&bot_user_id=42&amount=5000

Параметр	Описание
`amount`	Сумма в копейках (`5000` = 50 ₽)
`bot_user_id`	Кому начислить

В комментарии к балансу попадёт номер заказа.

Куда вставить: URL после оплаты.

Исходник: bonususerfix/index.php

5.5. Отправка Telegram-подарка после оплаты (gift-send)

Задача: когда заказ оплачен, бот через API BOT-T отправляет покупателю Telegram Gift.

Ссылка:

https://custom.bot-t.com/gift-send/index.php?bot_id=1&token=ВАШ_ТОКЕН&gift_id=ID_ПОДАРКА

Опционально уведомление админу в личку:

&admin_id=123456789

(admin_id — Telegram ID админа, цифрами.)

Параметр	Описание
`gift_id`	Идентификатор подарка из каталога Telegram / настроек BOT-T
`status` в POST	Обрабатывается только `1` (оплачен)
Повтор webhook	Повторно подарок не отправится (файл-метка `sent_{order_id}.lock` на сервере)

Куда вставить: URL после оплаты.

Исходник: gift-send/index.php

5.6. Проверка строки товара перед выдачей (product-check)

Задача: перед выдачей каждой строки склада BOT-T спрашивает ваш скрипт: «эта строка годится?».

Всегда разрешить (боевой вариант «пропустить проверку на своей стороне»):

https://custom.bot-t.com/product-check/accept.php

Всегда отклонить (тест, товар будет сниматься со склада по одной строке):

https://custom.bot-t.com/product-check/reject.php

Куда вставить: «URL вебхука (проверка товара перед выдачей клиенту)» — только для уникального товара.

Своя логика: скопируйте accept.php на свой хостинг и внутри анализируйте поле product (ключ, email, статус в вашей базе и т.д.), верните success: true/false.

Исходники: accept.php, reject.php

5.7. Обратная связь (форма feedback)

Готовые обработчики на custom.bot-t.com:

Ссылка	Поведение
feedback/false.php	Отклонить ответ, показать `message` с текстом ошибки
feedback/repeat-and-message.php	Принять, отправить сообщение, повторить форму (`is_repeat: true`)
feedback/save-in-file.php	Отладка: сохранить POST/GET в файлы на сервере (не для продакшена)

Настройка в ЛК: сообщение «Обратная связь» → API → тип Custom → URL обработчика.

Пример ответа «принять и написать пользователю» (если делаете свой PHP):

{
  "result": true,
  "data": {
    "message": "Спасибо! Ваша заявка принята.",
    "is_repeat": false
  }
}

Исходники: feedback/

6. Частые ошибки

Симптом	Что проверить
Баланс не начисляется	Верные `bot_id`, `token`, `bot_user_id`; в логе заказа в ЛК — ответ API `add-balance`
Начислилось «копейки»	`coef` слишком маленький; для cashback смотрите на `amount` в копейках
Начислилось не тому	В bonususer / bonususerfix проверьте `bot_user_id`, не Telegram ID
Подарок не ушёл	`status` заказа должен быть `1`; верный `gift_id`; токен бота
Подарок дважды	Нормально защищено lock-файлом; при переносе на свой хост сохраните эту логику
Проверка товара падает	Только уникальный товар; ответ строго JSON `{"success": true/false}`; HTTP 200
Форма не реагирует	URL в Custom API; ответ JSON с полем `result`
«Пустой» webhook	URL доступен из интернета по HTTPS; нет опечаток в `index.php`

Логи заказа и категории в ЛК показывают текст запросов к вашему URL и ответы — смотрите их первым делом.

7. Python и JavaScript

В репозитории bott-examples:

python/ — те же сценарии для WSGI (gunicorn/uwsgi), см. docstring в python/cashback/index.py и т.д.
javascript/ — примеры на Node.js с common.js.

Они не лежат на custom.bot-t.com. Чтобы использовать Python/JS:

Склонируйте репозиторий на свой VPS/хостинг.
Поднимите HTTP-сервер.
В ЛК укажите свой URL вместо custom.bot-t.com.

Логика параметров (bot_id, token, coef, …) та же, что в таблицах выше.

8. Полезные ссылки

Ресурс	URL
Репозиторий примеров	https://github.com/Purt09/bott-examples
Рабочие PHP-примеры	https://custom.bot-t.com/
Документация API BOT-T	https://bott.readme.io/reference/common
FAQ: cashback по API	https://bot-t.com/faq/HELP/api_gotovye_integracii
FAQ: проверка товара по API	https://bot-t.com/faq/HELP/proverka_tovara_po_api

Шпаргалка: все готовые PHP-URL

Сценарий	URL
Cashback % покупателю	`https://custom.bot-t.com/cashback/index.php?bot_id={ID}&token={TOKEN}&coef=0.02`
Бонус за штуку	`https://custom.bot-t.com/balance/index.php?bot_id={ID}&token={TOKEN}&coef=1`
% партнёру	`https://custom.bot-t.com/bonususer/index.php?bot_id={ID}&token={TOKEN}&bot_user_id={UID}&coef=0.1`
Фикс партнёру	`https://custom.bot-t.com/bonususerfix/index.php?bot_id={ID}&token={TOKEN}&bot_user_id={UID}&amount=5000`
Подарок	`https://custom.bot-t.com/gift-send/index.php?bot_id={ID}&token={TOKEN}&gift_id={GIFT}`
Проверка: OK	`https://custom.bot-t.com/product-check/accept.php`
Проверка: отклонить	`https://custom.bot-t.com/product-check/reject.php`
Форма: отказ	`https://custom.bot-t.com/feedback/false.php`
Форма: повтор	`https://custom.bot-t.com/feedback/repeat-and-message.php`

Замените {ID}, {TOKEN}, {UID}, {GIFT} на свои значения.

Документ составлен по репозиторию Purt09/bott-examples и публичному хостингу примеров custom.bot-t.com.