Документация для партнёра

Как пользоваться кабинетом, API и интеграцией с магазином BOT-T. Эту ссылку можно переслать партнёру.

Содержание

Что нужно для старта
Личный кабинет партнёра
REST API
Интеграция BOT-T
Чеклист запуска

1. Что нужно для старта

Логин и пароль кабинета Выдаёт администратор. Вход: /partner

API-ключ (pk_…) Показывается один раз при создании. Храните в секрете.

Баланс на счёте Единый с балансом ЛК: пополняйте в кабинете пользователя или Telegram-боте; админ тоже может пополнить. С него списывается партнёрская цена.

Если чего-то нет — напишите администратору HiddifySales.

Открыть кабинет Страница входа

2. Личный кабинет партнёра

В кабинете вы контролируете баланс, выдачи ключей и настройки API.

Дашборд: баланс, квоты, выдачи за день/месяц — https://v2raysales.site/partner
Выдачи ключей: статус склада (available / reserved / sold), ссылки, заказы BOT-T.
История баланса: пополнения и списания за ключи.
Раздел API: примеры запросов и URL вебхуков BOT-T.

Баланс партнёра — тот же, что в ЛК привязанного пользователя. Пополняйте в разделе «Баланс» кабинета /partner теми же способами, что и обычные клиенты (карта, СБП, крипта и др.), либо через ЛК/Telegram-бота. Админ тоже может пополнить вручную.

3. REST API

Для своего бота или для наполнения склада BOT-T используйте REST API.

Base URL: https://v2raysales.site/api/v1/partner

Auth: X-API-KEY: pk_... или Authorization: Bearer pk_...

Эндпоинты

Метод	Путь	Назначение
GET	`/tariffs`	Каталог тарифов с вашей ценой (−скидка)
GET	`/servers`	Список серверов и стран (id, country_code)
GET	`/balance`	Единый баланс (с ЛК) и квоты
POST	`/keys`	Выдать trial или платный ключ (можно указать страну)
GET	`/keys/{id}`	Получить выдачу по id
GET	`/keys/by-order?external_order_id=...`	Найти по external_order_id

Склад для BOT-T (billing=on_sale)

Создайте ключ без немедленного списания и вставьте subscription_url в уникальный товар BOT-T.

POST https://v2raysales.site/api/v1/partner/keys
X-API-KEY: pk_YOUR_TOKEN
Content-Type: application/json

{
  "package": "tariff",
  "tariff_id": 12,
  "billing": "on_sale",
  "external_order_id": "stock-1"
}

billing=immediate — списать сразу (свой бот). billing=on_sale — списать после оплаты в BOT-T.

Ошибки REST

error	HTTP
unauthorized	401
forbidden	403
insufficient_balance	402
quota_exceeded	429
validation_error	422
provisioning_failed	503

4. Интеграция BOT-T

В BOT-T для магазина не используется «ваш REST-каталог», а два вебхука на карточке уникального товара.

Создайте ключи через POST /keys с billing=on_sale.
Вставьте полученные subscription_url в строки склада уникального товара.
В настройках API товара укажите URL проверки и уведомления (ниже).
После оплаты BOT-T пришлёт notify — мы спишем баланс и пометим ключ sold.

URL для карточки товара

Проверка до оплаты
https://v2raysales.site/api/v1/partner/bot-t/check?api_key=pk_YOUR_TOKEN

Уведомление после оплаты
https://v2raysales.site/api/v1/partner/bot-t/notify?api_key=pk_YOUR_TOKEN

Ответ на проверку

Только HTTP 200 и JSON вида:

{"success": true}

{"success": false}

true — строка идёт в заказ; false — берётся следующая. Не JSON / не 200 — заказ не создаётся. Лимит: до 20 строк в заказе.

После оплаты (status=1)

Покупатель уже получил ссылку из склада BOT-T. Мы принимаем form-urlencoded (id, status, user[telegram_id], product[data]) и отвечаем любым 2xx.

Повторы до 3 раз обрабатываются идемпотентно по номеру заказа BOT-T.

5. Чеклист запуска

Получили логин кабинета и API-ключ
Пополнили единый баланс (ЛК/бот или админ)
GET /tariffs показывает нужные тарифы и партнёрскую цену
Тестовый POST /keys (immediate или on_sale) возвращает рабочий subscription_url
Для BOT-T: check → success true, notify → баланс списан, ключ sold
В кабинете видны выдача и операция баланса