Управление заказами

Заказы магазина (ShopOrder)

Документация API владельца магазина: статусы, жизненный цикл, все методы /v1/shop/order/*, форматы ответов и примеры.

Авторизация API

Все методы — POST с телом JSON.

Параметр	Где	Обязательность	Описание
`bot_id`	тело	да	ID бота в системе BOT-T
`token` или `botToken`	query или тело	да*	Токен бота
`secretKey`	query	да*	Секретный ключ (альтернатива токену)

* Достаточно либо token/botToken, либо secretKey.

Заголовки:

Content-Type: application/json

Формат ответа:

{ "result": true, "data": ... }

{ "result": false, "message": "текст ошибки" }

Всегда проверяйте result === true перед использованием data.

Хост API: https://api.bot-t.com.
Базовый префикс методов: /v1/shop/order/.

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

ID	Код	Название (RU)	Описание
`0`	`WAIT`	Ожидает оплаты	Заказ создан, товар зарезервирован, оплата не прошла.
`1`	`ACTIVE`	Оплачен	Оплата подтверждена. Товар выдаётся покупателю.
`2`	`ERROR`	Ошибка	Ошибка при обработке. Не учитывается в статистике.
`3`	`DELETED`	Удалён	Служебный; запись может быть удалена из системы.
`4`	`WORKING`	В работе	Смена через `change-status`.
`5`	`COMPLETE`	Выполнен	Заказ полностью исполнен.
`6`	`WAIT_USER`	Ожидает исполнителя	После оплаты для категорий типа «Услуга».
`7`	`CANCEL`	Отменен	Отмена с возвратом средств.
`8`	`BOOKED`	Бронируется	Можно выставить через `change-status`.
`9`	`RETURNED`	Заявлен на возврат	Покупатель подал заявку на возврат.
`10`	`PARTIALLY_RETURNED`	Возвращен частично	Частичный возврат: сумма уменьшена, остаток в статистике.

Оплаченные (можно менять product через update-product):
ACTIVE, WORKING, COMPLETE, WAIT_USER, PARTIALLY_RETURNED.

В выручку обычно не попадают: WAIT, ERROR, RETURNED, CANCEL.

Жизненный цикл (упрощённо)

stateDiagram-v2
    [*] --> WAIT: создание заказа
    WAIT --> ACTIVE: оплата / success-order
    WAIT --> [*]: отмена / reset-order
    ACTIVE --> WAIT_USER: категория «Услуга»
    ACTIVE --> WORKING: change-status
    ACTIVE --> RETURNED: заявка на возврат
    ACTIVE --> COMPLETE: change-status
    WAIT_USER --> WORKING: change-status
    WAIT_USER --> COMPLETE: change-status
    RETURNED --> CANCEL: refund-order 100%
    RETURNED --> PARTIALLY_RETURNED: refund-order percent < 100
    RETURNED --> COMPLETE: отказ в возврате
    WORKING --> COMPLETE: change-status
    ACTIVE --> CANCEL: refund-order 100%
    ACTIVE --> PARTIALLY_RETURNED: refund-order percent < 100

Важно:

success-order — только для WAIT (0). Иначе: Заказ уже оплачен.
change-status нельзя для WAIT — сначала success-order.
update-product — только для оплаченных статусов.
reset-order удаляет заказ и не возвращает деньги.
Для возврата денег — refund-order.

Сводка методов

Метод	URL	Назначение
`index`	`POST .../index`	Список заказов
`view`	`POST .../view`	Один заказ
`find-by-shop-product`	`POST .../find-by-shop-product`	Поиск по строке `product`
`create-order`	`POST .../create-order`	Создать заказ для `bot_user_id`
`create-order-api`	`POST .../create-order-api`	Создать заказ API-категории (`amount`, `product`)
`success-order`	`POST .../success-order`	Подтвердить оплату и выдать товар
`update-product`	`POST .../update-product`	Заменить содержимое заказа (`product`)
`send-product`	`POST .../send-product`	Отправить содержимое покупателю в Telegram
`refund-order`	`POST .../refund-order`	Вернуть деньги на баланс
`change-status`	`POST .../change-status`	Сменить статус
`reset-order`	`POST .../reset-order`	Удалить заказ без возврата
`send-message`	`POST .../send-message`	Отправить сообщение бота покупателю
`send-request`	`POST .../send-request`	Вызов метода Telegram Bot API

Методы подробно

POST /v1/shop/order/index

Список заказов магазина.

Поле	Тип	По умолчанию	Описание
`bot_id`	integer	—	Обязательно
`category_id`	integer	—	`0` — все категории; иначе фильтр
`status`	integer	—	Фильтр по одному статусу (опционально)
`limit`	integer	`20`	Максимум 20
`offset`	integer	`0`	Пагинация

Ответ data: массив объектов списка (см. формат списка).

POST /v1/shop/order/view

Поле	Описание
`bot_id`	ID бота
`order_id`	ID заказа

Ответ data: один объект заказа.

POST /v1/shop/order/find-by-shop-product

Поиск заказа по точному совпадению выданной строки product в shop_product.

Поле	Описание
`bot_id`	ID бота
`product`	Строка товара (точное совпадение)

Ошибки: product не указан, Товар с таким содержимым не найден или не привязан к заказу.

POST /v1/shop/order/create-order

Создаёт заказ для пользователя бота. Цена считается по категории. Статус — WAIT (0).

Поле	Описание
`bot_id`	ID бота
`category_id`	ID категории
`count`	Количество (> 0)
`bot_user_id`	ID пользователя бота

Не для категорий типа API (type = API_FEEDBACK) — для них create-order-api.

POST /v1/shop/order/create-order-api

Создаёт заказ только в категории типа API (API_FEEDBACK, type=5).
Сумма и содержимое задаются явно. Заказ сразу считается оплаченным (через внутренний success).

Поле	Описание
`bot_id`	ID бота
`category_id`	ID API-категории
`count`	Количество (> 0)
`amount`	Сумма в копейках
`product`	Содержимое товара
`bot_user_id`	ID пользователя бота

Ошибка, если категория не API:
Нельзя создать заказ в данной категории, так как категория не является API.

POST /v1/shop/order/success-order

Ручное подтверждение оплаты: WAIT → оплачен, выдача товара, уведомления, вебхук API-модуля (если настроен).

Поле	Описание
`bot_id`	ID бота
`order_id`	ID заказа

POST /v1/shop/order/update-product

Заменяет содержимое выданных позиций заказа (shop_product).

Поле	Тип	Описание
`bot_id`	integer	Обязательно
`order_id`	integer	Обязательно
`product`	string	Обязательно. Новое содержимое, до 9999 символов

Условия:

Заказ должен быть оплачен (isPaid: статусы 1, 4, 5, 6, 10).
Нельзя для WAIT, CANCEL, RETURNED, ERROR и т.п.
Если у заказа одна строка product — она обновляется; иначе старые строки удаляются и создаётся одна новая.

Не отправляет товар покупателю — для этого send-product.

Пример:

{
  "bot_id": 1,
  "order_id": 1001,
  "product": "KEY-ABC-123\nлогин: user\nпароль: secret"
}

Ошибки: product не указан, Продукт слишком длинный..., Нельзя изменить содержимое неоплаченного или отменённого заказа.

POST /v1/shop/order/send-product

Отправляет текущее содержимое заказа покупателю в Telegram
(тот же сценарий, что кнопка «Отправить товар» в ЛК).

Поле	Описание
`bot_id`	ID бота
`order_id`	ID заказа

Нужен telegram_id у покупателя. Если содержимое пустое — стратегия категории пишет в лог «нет товара» и по сути ничего не шлёт.

Типичная связка после вебхука:

update-product
send-product

POST /v1/shop/order/change-status

Поле	Описание
`bot_id`	ID бота
`order_id`	ID заказа
`status`	Новый статус (см. таблицу)

Нельзя менять статус у заказа в WAIT (0).

POST /v1/shop/order/refund-order

Возврат на внутренний баланс покупателя (как кнопка в ЛК). Не путать с reset-order.

Поле	Тип	По умолчанию	Описание
`order_id`	integer	—	Обязательно
`percent`	integer	`100`	Доля суммы, 1–100

percent = 100 → статус CANCEL (7).
percent < 100 → PARTIALLY_RETURNED (10), сумма уменьшается.

Нужны включённые пополнения в боте.

POST /v1/shop/order/reset-order

Удаляет заказ. Деньги не возвращаются. В ответе — данные заказа до удаления.

Поле	Описание
`bot_id`	ID бота
`order_id`	ID заказа

POST /v1/shop/order/send-message

Отправляет покупателю заранее созданное сообщение бота из конструктора.

Поле	Описание
`bot_id`	ID бота
`order_id`	ID заказа
`message_id`	ID сообщения бота

Сообщение должно принадлежать текущему боту.

POST /v1/shop/order/send-request

Произвольный метод Telegram Bot API в чат покупателя. chat_id подставляется из заказа.

Поле	Описание
`bot_id`	ID бота
`order_id`	ID заказа
`method`	Имя метода (например `sendMessage`)
`params`	Объект параметров

Ошибка без Telegram: Нет telegram_id для заказа.

Поля заказа

Поле	Тип	Описание
`id`	integer	ID заказа
`shop_id`	integer	ID магазина
`category_id` / `shop_category_id`	integer	ID категории
`user_id`	integer \| null	ID пользователя платформы
`bot_user_id`	integer \| null	ID пользователя в боте
`bot_clone_id`	integer \| null	Бот-копия
`count`	integer	Количество
`status`	integer	Статус
`amount`	integer	Сумма в копейках
`discount`	integer	Списано с баланса (копейки)
`telegram_id`	integer \| null	Telegram ID
`product`	string / object	Выданный товар
`created_at`	integer / string	Время создания
`coupon`	object \| null	`{ code, discount, type }`

Ответ: список и просмотр

{
  "id": 1001,
  "category_id": 42,
  "count": 1,
  "bot_user_id": 555,
  "user_id": 100500,
  "telegram_id": 182352323552,
  "status": 1,
  "price": {
    "sum": "150.00 ₽",
    "balance_type_id": "ЮKassa",
    "currency": "RUB"
  },
  "product": "ключ-активации-или-текст",
  "created_at": 1716288000,
  "coupon": null
}

Поле	Описание
`status`	Числовой ID статуса
`price.sum`	Отформатированная сумма
`product`	Содержимое позиций, строки через перенос
`coupon`	`{ code, discount, type }` или `null`

Ответ: создание (`create-order`, `create-order-api`)

{
  "id": 1001,
  "count": 1,
  "category": { "...": "объект категории" },
  "user": { "...": "объект пользователя" },
  "botUser": { "...": "объект пользователя бота" },
  "product": {
    "type": "text",
    "data": "содержимое или ссылка на оплату"
  },
  "status": 0,
  "price": "150.00 ₽",
  "amount": 15000,
  "discount": 0,
  "created_at": "2024-05-21 12:00:00"
}

Поле	Описание
`amount`	Копейки
`product.type`	`pay` при `status = 0`; `text` / `button` после оплаты
`product.data`	Текст товара или deep-link `o_{id}`

Создание заказа (общее)

При создании через API:

Лимиты неоплаченных заказов.
Минимальный интервал между заказами.
Цена (акции, скидки, валюта).
Статус WAIT (0), кроме create-order-api.
Бронь товара на время оплаты.

Ссылка на оплату в боте:

https://t.me/{username_бота}?start=o_{order_id}

Публичный API (кратко)

Префикс: https://api.bot-t.com/v1/shoppublic/order/

Метод	Назначение
`create`	Анонимный заказ + `orderKey`
`create-user`	Заказ с `user_id` + `secret_user_key`
`get-product`	Выдача после оплаты по `order_id` + `orderKey`
`get-product-user`	Выдача по `user_id` + `secret_user_key`

Оплаченные для get-product: ACTIVE, WORKING, COMPLETE, WAIT_USER.

Плейсхолдеры в сообщениях бота

Плейсхолдер	Описание
`{ORDER_ID}`	Номер заказа
`{ORDER_TIME}`	Время создания
`{ORDER_PRICE}`	Сумма с валютой
`{ORDER_PRICE_WITHOUT_CURRENCY}`	Сумма / 100
`{ORDER_COUNT}`	Количество
`{ORDER_STATUS}`	Текст статуса
`{COUPON_INFO}`	Купон
`{ORDER_ITEMS_INFO}`	Строка товаров
`{TIME}` / `{TIME_END}`	Бронь / автоотмена
`{LOG}`	Причина отмены

Примеры (PHP)

<?php

const BOT_ID = 1;
const BOT_TOKEN = '123456789:ABCdefGHI...';

function shopOrderRequest(string $action, array $body): array
{
    $url = 'https://api.bot-t.com/v1/shop/order/' . $action . '?botToken=' . urlencode(BOT_TOKEN);
    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
        CURLOPT_POSTFIELDS => json_encode(array_merge(['bot_id' => BOT_ID], $body)),
    ]);
    $raw = curl_exec($ch);
    curl_close($ch);
    $data = json_decode($raw, true);
    if (!is_array($data) || empty($data['result'])) {
        throw new RuntimeException($data['message'] ?? 'API error');
    }
    return $data['data'];
}

$orders = shopOrderRequest('index', [
    'category_id' => 0,
    'status' => 1,
    'limit' => 20,
    'offset' => 0,
]);

$order = shopOrderRequest('view', ['order_id' => 1001]);

shopOrderRequest('change-status', [
    'order_id' => 1001,
    'status' => 4,
]);

shopOrderRequest('success-order', ['order_id' => 1002]);

// После вебхука API-модуля: записать содержимое и отправить покупателю
shopOrderRequest('update-product', [
    'order_id' => 1001,
    'product' => "KEY-ABC-123",
]);
shopOrderRequest('send-product', [
    'order_id' => 1001,
]);

shopOrderRequest('refund-order', ['order_id' => 1001]);
shopOrderRequest('refund-order', [
    'order_id' => 1001,
    'percent' => 50,
]);

В index один status. Несколько статусов — отдельные запросы или фильтр на своей стороне.

Типичные ошибки

Сообщение	Причина
`Заказ уже оплачен`	Повторный `success-order` не в `WAIT`
`Нельзя сменить статус у неоплаченного заказа`	`change-status` при `status = 0`
`Нельзя изменить содержимое неоплаченного или отменённого заказа`	`update-product` для неоплаченного
`product не указан`	Пустой `product` в `update-product` / `find-by-shop-product`
`Продукт слишком длинный, максимальная длина 9999 символов`	`product` > 9999
`Нельзя вернуть деньги у неоплаченного заказа`	`refund-order` для `WAIT`
`Нельзя вернуть деньги у отмененного заказа заказа`	Повторный `refund-order`
`Нельзя вернуть деньги автоматически, так как выключены пополнения`	Выключены пополнения
`Процент возврата должен быть от 1 до 100`	`percent` вне 1–100
`Достигнут лимит неоплаченных заказов`	Лимит WAIT
`not found` / `access`	Чужой `order_id` / `category_id`
`Нет telegram_id для заказа`	Анонимный заказ / нет Telegram

Важные замечания

Суммы: amount — в копейках; price.sum в view — уже строка.
Пользователь: приоритет у bot_user_id, иначе привязка по user_id.
После оплаты: обычный товар → ACTIVE (1); «Услуга» → WAIT_USER (6).
Бронь: неоплаченный заказ может отмениться по таймеру магазина.
API-модуль товара: вебхук после оплаты, затем update-product и send-product.
OpenAPI: Swagger UI на API-хосте (тег Магазин).