API реселлера: обзор

Как устроена платформа реселлера: баланс реселлера, резерв, ключи клиентов, коды, тарифы и всё то же самое через REST API для вашего сайта или бота.

Как это работает

Реселлер пополняет свой баланс по оптовой цене и продаёт токены своим клиентам ключами и кодами. Всё, что можно сделать в кабинете (вкладка реселлера на app.oneprovider.dev), доступно и через API: так вы собираете собственный сайт, бота или кассу.

• Баланс реселлера. Отдельный от личных денег баланс в USD. Пополняется по оптовой цене: её скидку и цену 1 USD отдаёт GET /pricing.
• Ключи клиентов. Каждый ключ имеет лимит расхода в USD и срок действия. Клиент пользуется ключом как обычным ключом OneProvider.
• Коды. Пачки одноразовых кодов, которые вы продаёте где угодно. Активированный код превращается в ключ с лимитом, равным сумме кода.
• Тарифы. Ваши цены клиентам: сумма на ключ, цена, валюта и срок. По ним выдаются ключи через POST /orders.
• Нейтральный дашборд ключа. У каждого ключа есть ссылка dashboard_url: клиент видит расход и остаток, а ваш бренд и секрет ключа не раскрываются.

Правило денег: резерв и списание

У баланса реселлера три числа:

Reseller balance (balance_usd) = your money on the platform
Reserved (reserved_usd) = unredeemed codes + remaining limits of live keys
Free (available_usd) = Reseller balance - Reserved

Деньги списываются не тогда, когда вы что-то создали, а когда клиент получил и тратит стоимость. До этого они только резервируются:

• Пачка кодов только резервирует сумму. Отзыв неактивированных кодов возвращает резерв.
• Активированный код становится ключом, лимит которого остаётся в резерве.
• Выпуск ключа резервирует его лимит; расход ключа списывает деньги с баланса реселлера.
• Удаление ключа или снижение его лимита сразу возвращает неизрасходованный остаток в «Свободно».
• Пауза ключа резерв не снимает.

Каждый новый ключ, пополнение ключа и пачка кодов должны помещаться в «Свободно»; иначе ответ 409 insufficient_balance. Все три числа отдаёт GET /balance: balance_usd, reserved_usd, available_usd.

Первый запрос

1. В кабинете откройте вкладку реселлера, раздел «API и интеграции», и создайте токен. Значение показывается один раз.
2. Положите токен в переменную окружения на сервере и вызовите /balance:

export OP_PARTNER_TOKEN="rsk_..."
curl -s https://app.oneprovider.dev/partner/v1/balance \
-H "Authorization: Bearer $OP_PARTNER_TOKEN"

{
"balance_usd": "120.00",
"reserved_usd": "35.50",
"available_usd": "84.50"
}

В примере показаны не все поля ответа; суммы всегда строки с двумя знаками. Остальные поля перечислены в справочнике методов и в OpenAPI .

Пополнение баланса реселлера

Список касс и минимальные суммы лежат в topup_providers ответа GET /balance. Платёж создаёт POST /balance/topups (право billing, нужен Idempotency-Key), ссылку на оплату вы отдаёте плательщику.

curl -s -X POST https://app.oneprovider.dev/partner/v1/balance/topups \
-H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Idempotency-Key: topup-2026-10-08-001" \
-H "Content-Type: application/json" \
-d '{"balance_usd":"100.00","provider":"<id from topup_providers>"}'

Ответ содержит order_id и pay_url (201). Статус платежа: GET /balance/topups/{order_id}; о зачислении сообщит событие balance.topped_up вебхука.

Журнал действий

GET /audit (право read) возвращает журнал всех действий на вашем аккаунте: из кабинета, по API-токенам и системные. Записи неизменяемы (методов правки и удаления нет) и никогда не содержат секретов: ни ключей, ни токенов, ни кодов, ни секретов вебхуков. Объект показан только коротко: хвост ключа, название пачки или тарифа.

curl -s "https://app.oneprovider.dev/partner/v1/audit?period=7d&action=key.&limit=50" \
-H "Authorization: Bearer $OP_PARTNER_TOKEN"

{
"items": [
{
"id": "<row id>",
"at": "2026-10-08T12:00:00Z",
"actor": { "kind": "token", "label": "shop backend" },
"action": "key.created",
"object": { "type": "key", "label": "anna-main (...4f2a)" },
"money": { "reserve_delta": "25.00", "debit_delta": "0.00", "available_after": "59.50" },
"ip": "203.0.113.7",
"request_id": "req_..."
}
],
"next": null,
"actions": ["key.created", "key.topped_up"]
}

actor.kind это user, token или system. Поле money (null, если денег действие не касалось) показывает подписанные изменения резерва и списания; available_after может быть null. В ответе также приходит полный список действий actions:

key.created key.topped_up key.limit_changed key.updated key.paused key.resumed key.rotated key.deleted
code_batch.created code_batch.revoked code.redeemed
plan.created plan.updated plan.deleted
token.created token.revoked
webhook.created webhook.deleted webhook.tested
balance.topup order.completed
customer.created customer.updated customer.blocked customer.unblocked
settings.updated account.activated

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

• Базовый адрес: https://app.oneprovider.dev/partner/v1.
• Формат JSON; деньги это строки в USD с двумя знаками ("12.50"); время в ISO 8601 UTC (2026-10-08T12:00:00Z).
• Вызывайте API только с сервера: CORS нет, токен нельзя встраивать в браузер или мобильное приложение.
• Токены, права, лимит запросов, ошибки, идемпотентность и пагинация: Авторизация и права .

Что дальше

• Ключи и клиенты : выпуск, пополнение, пауза, удаление.
• Заказы : как собрать собственный сайт.
• Коды и тарифы .
• Вебхуки : события и проверка подписи.
• Справочник методов и openapi.yaml .