API уведомления

Вебхуки магазина BOT-T

Настройка: Магазин → категория/товар → API (два поля URL).

---

Общие правила

Параметр	Значение
Метод	POST
Content-Type	application/x-www-form-urlencoded
Кодировка	UTF-8
Повторы (уведомление после оплаты)	До 3 попыток с паузой 0,5 с и 1 с при ошибке сети
IP-источник	Серверы BOT-T (фиксированный пул; при необходимости уточняйте у поддержки)

Вложенные объекты (category, user, reviews и т.д.) передаются в формате полей с квадратными скобками, (category[id]=10, user[telegram_id]=123). Парсер на вашей стороне должен уметь разбирать такую структуру (или принимать тело как application/x-www-form-urlencoded и восстанавливать дерево).

---

1. Уведомление после оплаты заказа

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

Когда отправляется: после успешной оплаты заказа — статус заказа переведён в «Оплачен» (ACTIVE, код 1). Товар уже зарезервирован/выдан внутри BOT-T; уведомление уходит асинхронно (очередь).

Условие: у категории/товара включён блок API и указан корректный HTTP(S) URL.

Тело запроса (корневые поля)

Поле	Тип	Описание
id	int	ID заказа в BOT-T
count	int	Количество единиц в заказе
status	int	Статус заказа на момент отправки (обычно 1 — оплачен)
price	string	Сумма для отображения (с валютой), например 150.00 ₽
amount	int	Сумма в минимальных единицах валюты (копейки)
discount	int	Скидка по заказу (минимальные единицы)
created_at	string	Дата/время создания заказа, Y-m-d H:i:s (часовой пояс бота)
category	object	Категория/товар заказа (см. ниже)
user	object | null	Пользователь Telegram (может быть null для гостевых сценариев)
botUser	object | null	Пользователь бота (связь с ботом, баланс, ключи)
product	object	Выданный товар в заказе (см. ниже)
reviews	object	Только если к заказу привязана заполненная форма обратной связи (см. раздел 3)

Объект product

Поле	Тип	Описание
type	string	Тип представления: text, link, pay (до оплаты в других API не приходит в этом вебхуке)
data	string	Содержимое: ключи, ссылки, текст, путь к файлу и т.д. — зависит от типа товара

Для заказа с несколькими строками товара в data может быть несколько значений, разделённых переводом строки \n.

Объект category (основные поля)

Поле	Тип	Описание
id	int	ID записи категории/товара
category_id	int	ID в дереве каталога
parent	object | null	Родительская категория (та же структура) или null
children	array	Дочерние элементы (если есть)
photo	object | null	Фото категории
design	object	title, description, instruction, image, template_id, deployed, count, discount, discount_text
price	object	full, amount, currency (id, code, letter, code_digital), discount, old_price
setting	object	min_count, max_count, count, is_ban_coupon, is_change_count, is_block_feedback, is_view_ordered_user, is_check_captcha
type	int	Числовой тип категории (папка, уникальный товар, API+обратная связь и т.д.)
typeObg	object	id, title — расшифровка типа
status	int	Статус категории
is_view	bool	Показывается в витрине
is_hide	bool	Скрыт
api_id	int | null	ID настроек API
feedback_id	int | null	ID формы обратной связи, если привязана
message_notice_id	int | null	ID уведомления
salesman	object | null	Продавец (пользователь)

Объект user

Поле	Тип	Описание
id	int	ID пользователя в BOT-T
telegram_id	int	Telegram user id
username	string	@username без @
first_name	string	Имя
last_name	string	Фамилия
link	string	HTML-ссылка или @username для отображения
type	string	Тип чата: private, group, supergroup, channel

Объект botUser

Поле	Тип	Описание
id	int	ID пользователя бота
bot_id	int	ID бота
user	object | null	Вложенный user
ref	object | null	Реферер
money	int	Баланс в минимальных единицах
status	object	id, title
create_at	int	Unix-время создания
created_time	string	Дата создания
update_at	int	Unix-время обновления
updated_time	string	Дата обновления
expectation	string | null	Служебное состояние диалога
secret_user_key	string | null	Секретный ключ (для Web App / API пользователя)

Ожидаемый ответ вашего сервера

Любой HTTP-код 2xx (200–299). Тело ответа не разбирается. При ошибке BOT-T повторит запрос (см. «Повторы»).

Статусы заказа (status)

Код	Смысл
0	Ожидает оплаты
1	Оплачен
4	В работе
5	Исполнен
6	Ожидает исполнителя (услуги)
2	Ошибка
7	Отменён

В этом вебхуке после оплаты обычно приходит 1.

---

2. Проверка товара перед выдачей

Поле в ЛК: «URL вебхука (проверка товара перед выдачей клиенту)».

Когда используется: только для типа товара «Уникальный товар». Вызывается до оплаты, в момент создания заказа (резервирование строк со склада): для каждой единицы товара в заказе.

Не используется для типов «API + обратная связь», «Неуникальный», «Файл», «Услуга» и др.

Запрос

Параметр	Значение
Метод	POST
Content-Type	application/x-www-form-urlencoded
Тело	одно поле

Поле	Тип	Описание
product	string	Одна строка склада (ключ, логин:пароль, код и т.д.)

Логика на стороне BOT-T

1. Берётся одна свободная строка товара.
2. POST на ваш URL с product.
3. Разбор JSON-ответа.
4. success: false — строка снимается с продажи, берётся следующая (цикл для count заказа).
5. success: true — строка закрепляется за заказом, переход к следующей единице.
6. HTTP ≠ 200 или невалидный JSON — заказ не создаётся, покупателю ошибка.

Ожидаемый ответ

Параметр	Значение
HTTP	200
Content-Type	application/json (рекомендуется)
Тело	JSON-объект с полем success

JSON

{"success": true}

или

JSON

{"success": false}

success	Действие BOT-T
true	Строка валидна, используется в заказе
false	Строка удаляется из продажи, подбирается другая
отсутствует / не JSON / HTTP ≠ 200	Ошибка, заказ не оформляется

---

3. Оплата заказа в категории «API + обратная связь»

Тип категории в магазине: обработка на внешнем сервере (в ЛК: «API + обратная связь»).

Сценарий

1. Покупатель заполняет форму обратной связи, привязанную к товару (feedback_id в категории).
2. Оформляется и оплачивается заказ (Telegram, баланс, внешняя оплата через API магазина и т.д.).
3. После успешной оплаты BOT-T отправляет тот же вебхук, что в разделе 1 («уведомление после оплаты»), на URL из поля create.

Отличие от обычного магазина

Дополнительно передаётся поле reviews — объект с ответами пользователя на форму обратной связи, если заявка привязана к заказу.

Структура reviews:

Поле	Тип	Описание
id	int	ID заявки (ответа на форму)
feedback_id	int	ID формы обратной связи
answer	string	Сводный текст: все вопросы и ответы одной строкой
created_time	string	Начало заполнения, Y-m-d H:i
notice_time	string | null	Время напоминания
deleted_time	string	Планируемое удаление заявки
status	object	id, title — статус заявки (0 в процессе, 1 не прочитан, 2 прочитан, 3 отвечен)
items	array	Детализация по каждому вопросу (см. ниже)
data	string | null	Спец. данные формы (JSON-строка, напр. order_id для доставки)
adminAnswer	object | null	Ответ администратора (сообщение), если уже есть
user	object	Кто заполнил форму
bot_id	int	ID бота

Элемент items[]

Поле	Тип	Описание
id	int	ID поля формы
type	int	Тип вопроса: 1 — ввод текста, 2 — файл, 3 — выбор, 4 — развилка
answer_id	int	ID заявки
main_input	object	Метаданные вопроса (текст, настройки)
input	object	Для типа 1: id, answer (текст ответа)
file	object	Для типа 2: массив files[] с id, file, type, link (ссылка на скачивание)
select	object	Для типа 3: выбранные options[]
crossroad	object	Для типа 4: выбранная ветка

Поле product в корне заказа для этого типа обычно содержит настройки API (ключи, URL внешнего сервиса в формате ключ:значение построчно), а не готовый ключ для покупателя — выдача часто выполняется вашим сервером по данным из reviews и product.

Ожидаемый ответ

Как в разделе 1: HTTP 2xx, тело не проверяется.

---

Порядок вызовов (уникальный товар + API)

mermaid

sequenceDiagram
    participant U as Покупатель
    participant BT as BOT-T
    participant You as Ваш сервер

    U->>BT: Создать заказ
    loop На каждую единицу count
        BT->>You: POST проверка product
        You-->>BT: {"success": true/false}
    end
    U->>BT: Оплата
    BT->>You: POST уведомление заказ (раздел 1)
    You-->>BT: HTTP 2xx

Для «API + обратная связь» шаг «проверка product» обычно не выполняется; после оплаты — вебхук раздела 1 + reviews.

---

Безопасность (рекомендации)

• Принимайте запросы только по HTTPS.
• Проверяйте источник (IP, секрет в query/path, подпись — реализуете на своей стороне; BOT-T секрет в URL по умолчанию не добавляет).
• Не логируйте secret_user_key и содержимое product в открытые логи.
• Обрабатывайте вебхук идемпотентно: повторная доставка с тем же id заказа возможна.

---

Связанные API (не вебхуки)

Действие	Кто вызывает	Описание
POST /v1/shop/order/success-order	Ваш backend	Вручную засчитать оплату (внешний эквайринг)
POST /v1/shoppublic/order/get-product	Сайт покупателя	Выдача товара по orderKey после оплаты