API реселлера: авторизация
Bearer-токены, права доступа, белый список IP, лимит запросов, коды ошибок, ключи идемпотентности и пагинация партнёрского API OneProvider. С примерами.
Bearer-токены, права доступа, белый список IP, лимит запросов, коды ошибок, ключи идемпотентности и пагинация партнёрского API.
Все модели, характеристики и цены Индекс документации для AI-агентов:https://oneprovider.dev/docs/llms.txt Токены
Токен выглядит как rsk_ и 40 символов. Его создают в кабинете (вкладка реселлера, «API и интеграции»), значение показывается один раз: мы храним только хеш и последние 4 символа. Активных токенов может быть до 10, любой токен можно отозвать в любой момент.
httpAuthorization: Bearer rsk_...Права (scopes)
У токена есть набор прав. Права независимы: keys не включает read. Метод GET /me доступен любому действующему токену. Без нужного права ответ 403 forbidden_scope.
| Scope | Что открывает |
|---|---|
read | Чтение: баланс и проводки, цены, модели, клиенты, ключи, заказы, тарифы, статистика, журнал действий GET /audit (все GET, кроме кодов и вебхуков). |
keys | Запись: клиенты (в том числе блокировка), выпуск, изменение, пауза, пополнение, перевыпуск (rotate) и удаление ключей, POST /orders. |
codes | Пачки кодов и сами коды (чтение, создание, отзыв, погашение). Коды это секреты, поэтому отдельное право. |
plans | Создание, изменение и удаление тарифов (чтение тарифов в read). |
billing | Пополнение баланса реселлера: POST /balance/topups и статус платежа. |
webhooks | Управление вебхуками, тест и журнал доставок. |
support | Зарезервировано под будущие методы поддержки. |
bot | Чтение состояния ботов и касс: GET /bot и GET /payment-providers (токенов в ответах нет). Подключение ботов только в кабинете. |
Для каждого метода право указано в справочнике .
Белый список IP
Токен можно привязать к списку адресов IPv4/IPv6 или сетей CIDR. Запрос с другого адреса получает 403 ip_not_allowed. Список задаётся при создании токена.
Лимит запросов
20 запросов в секунду на токен. При превышении: 429 rate_limited и заголовок Retry-After. Подождите указанное число секунд и повторите.
Ошибки
Любая ошибка возвращается в одной форме. Тот же идентификатор приходит в заголовке X-Request-Id: назовите его в поддержке.
{
"error": {
"code": "insufficient_balance",
"message": "Not enough free reseller balance for this key.",
"request_id": "req_..."
}
}Ориентируйтесь на error.code, а не на текст сообщения.
| HTTP | code | Значение |
|---|---|---|
| 400 | invalid | Поле отсутствует или вне допустимого диапазона. |
| 400 | bad_request | Запрос не удалось разобрать. |
| 400 | idempotency_key_required | Нет заголовка Idempotency-Key на методе, который тратит деньги. |
| 400 | invalid_url | Адрес вебхука не прошёл проверку (только https, без IP-адресов и внутренних сетей). |
| 400 | limit_below_spent | Новый лимит ключа меньше уже потраченного. |
| 401 | unauthorized | Токен не передан, не существует или отозван. |
| 403 | forbidden_scope | У токена нет нужного права (scope). |
| 403 | ip_not_allowed | IP-адрес запроса не входит в белый список токена. |
| 403 | reseller_disabled | Реселлеру закрыт доступ: все его токены отвечают так. |
| 403 | banned | Аккаунт заблокирован. |
| 404 | not_found | Объект не найден или принадлежит другому реселлеру. |
| 404 | key_not_found | Ключ не найден. |
| 409 | insufficient_balance | Сумма не помещается в «Свободно» (available_usd), см. правило денег. |
| 409 | idempotency_key_reused | Тот же Idempotency-Key уже использован с другим телом запроса: возьмите новый ключ. |
| 409 | fund_first | Сначала пополните баланс реселлера. |
| 409 | not_activated | Кабинет реселлера ещё не активирован. |
| 409 | name_taken | Ключ с таким именем уже есть. |
| 409 | key_limit | Достигнут максимум ключей. |
| 409 | plan_limit | Достигнут максимум тарифов (20). |
| 409 | customer_limit | Достигнут максимум клиентов (10 000). |
| 409 | code_used | Код уже погашен. |
| 409 | code_revoked | Код отозван. |
| 409 | external_order_id_conflict | external_order_id уже использован с другими параметрами. |
| 409 | customer_exists | Клиент с таким external_id уже есть. |
| 409 | customer_blocked | Клиент заблокирован: ключи, заказы и погашения для него отклоняются. |
| 409 | token_limit | Достигнут максимум активных токенов (10). |
| 409 | webhook_limit | Достигнут максимум вебхуков (5). |
| 429 | rate_limited | Больше 20 запросов в секунду; подождите Retry-After секунд. |
| 501 | sandbox_not_implemented | Песочница (rsk_test_...) пока не реализована. |
| 503 | provider_unavailable | Платёжный или модельный провайдер временно недоступен: повторите позже. |
Идемпотентность
Методы, которые тратят деньги, требуют заголовок Idempotency-Key (1..128 символов); без него ответ 400 idempotency_key_required. Они отмечены в справочнике. Повтор запроса с тем же ключом (в рамках реселлера) не потратит деньги второй раз и вернёт тот же объект. Для нового платежа или заказа берите новый ключ; у POST /orders личность заказа определяет external_order_id.
curl -s -X POST https://app.oneprovider.dev/partner/v1/keys \
-H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"name":"client-1","limit_usd":"10.00"}'Храните ключ идемпотентности вместе с вашей записью о заказе, чтобы при сетевой ошибке повторить ровно тот же запрос.
Пагинация
Списки принимают ?limit=1..100 (по умолчанию 50) и &cursor=. Ответ: {"items": [...], "next": "<cursor>"}; next равен null на последней странице. Курсор непрозрачный: передавайте его как есть.
curl -s "https://app.oneprovider.dev/partner/v1/keys?limit=100&cursor=<next from the previous page>" \
-H "Authorization: Bearer $OP_PARTNER_TOKEN"Песочница
Тестовые токены rsk_test_... скоро. Пока такой токен получает 501 sandbox_not_implemented.