API реселлера: ключи и клиенты

Выпуск, пополнение, пауза и удаление ключей клиентов и управление списком клиентов через партнёрский API, с примерами curl.

Объект ключа

Выпустить ключ

POST /keys (право keys, нужен Idempotency-Key). Обязательны name и limit_usd; необязательны expires_days (1..365, по умолчанию 30) или expires_hours (1..8760, например 1 для часового ключа; оба сразу нельзя), customer_id, customer_label, concurrency.

curl -s -X POST https://app.oneprovider.dev/partner/v1/keys \
-H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Idempotency-Key: key-anna-001" \
-H "Content-Type: application/json" \
-d '{"name":"anna-main","limit_usd":"25.00","expires_days":30,"customer_label":"Anna"}'
# a one-hour key
curl -s -X POST https://app.oneprovider.dev/partner/v1/keys -H "Authorization: Bearer $OP_PARTNER_TOKEN" -H "Idempotency-Key: key-trial-001" -H "Content-Type: application/json" -d '{"name":"trial","limit_usd":"1.00","expires_hours":1}'

Несколько одинаковых ключей сразу: POST /keys/bulk с полями count (1..50), name_prefix и теми же limit_usd, expires_days/expires_hours. Ключи называются {name_prefix}-1 … {name_prefix}-N. Вся сумма count x limit_usd проверяется заранее; если вызов всё же оборвался, повторите его с тем же Idempotency-Key: уже созданные ключи вернутся снова, остальные будут выпущены.

{
"id": "<key id>",
"name": "anna-main",
"customer_label": "Anna",
"status": "active",
"limit_usd": "25.00",
"spent_usd": "0.00",
"remaining_usd": "25.00",
"expires_at": "2026-11-07T12:00:00Z",
"dashboard_url": "<dashboard link>",
"key": "sk-..."
}

Лимит ключа резервируется на балансе реселлера. Если он не помещается в «Свободно» (available_usd), ответ 409 insufficient_balance; повтор имени даёт 409 name_taken, достижение максимума ключей даёт 409 key_limit.

Список и чтение

# active keys of one customer
curl -s "https://app.oneprovider.dev/partner/v1/keys?status=active&customer_id=<customer id>&limit=50" \
-H "Authorization: Bearer $OP_PARTNER_TOKEN"
# one key (no secret) with dashboard_url
curl -s https://app.oneprovider.dev/partner/v1/keys/<key id> \
-H "Authorization: Bearer $OP_PARTNER_TOKEN"

Фильтры: status, query (поиск по имени и метке), customer_id. Расход по дням GET /keys/{id}/usage пока возвращает {"items": []}: расход по дням скоро.

Изменить, пополнить, пауза

# change the limit / expiry / name / label / concurrency
curl -s -X PATCH https://app.oneprovider.dev/partner/v1/keys/<key id> \
-H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Content-Type: application/json" \
-d '{"limit_usd":"40.00"}'
# add 10.00 USD to the key limit
curl -s -X POST https://app.oneprovider.dev/partner/v1/keys/<key id>/topup \
-H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Idempotency-Key: topup-anna-001" \
-H "Content-Type: application/json" \
-d '{"amount_usd":"10.00"}'
# pause and resume
curl -s -X POST https://app.oneprovider.dev/partner/v1/keys/<key id>/pause -H "Authorization: Bearer $OP_PARTNER_TOKEN"
curl -s -X POST https://app.oneprovider.dev/partner/v1/keys/<key id>/resume -H "Authorization: Bearer $OP_PARTNER_TOKEN"

limit_usd в PATCH это новый общий лимит; ниже уже потраченного его поставить нельзя (400 limit_below_spent). Рост лимита, как и новый ключ, должен помещаться в «Свободно». Снижение лимита сразу возвращает неизрасходованную разницу в «Свободно». Пауза резерв не снимает.

Удалить ключ

curl -s -X DELETE https://app.oneprovider.dev/partner/v1/keys/<key id> \
-H "Authorization: Bearer $OP_PARTNER_TOKEN"

Ответ 200 {"state":"deleted"} означает, что ключ удалён сразу; 202 {"state":"deleting"} означает, что удаление идёт. Неизрасходованный остаток лимита сразу возвращается в «Свободно».

Перевыпустить ключ (rotate)

POST /keys/{id}/rotate (право keys, нужен Idempotency-Key): новый секрет для того же клиента, например если старый утёк. Старый секрет перестаёт работать сразу. Неизрасходованный остаток и срок действия переходят на новый ключ.

curl -s -X POST https://app.oneprovider.dev/partner/v1/keys/<key id>/rotate \
-H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Idempotency-Key: rotate-anna-001"

Это новый ключ с новым id: история расхода остаётся у старого (теперь удалённого) ключа. Ответ 201 содержит объект ключа, key (новый секрет, один раз) и rotated_from (id старого ключа). Ошибки: 404 key_not_found, 409 key_limit, 503 provider_unavailable.

Клиенты

Клиент это ваш покупатель. Ключи, заказы и коды можно привязывать к нему: свой идентификатор хранится в external_id (уникален, до 64 символов).

curl -s -X POST https://app.oneprovider.dev/partner/v1/customers \
-H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Content-Type: application/json" \
-d '{"external_id":"user-77","name":"Anna","note":"from the Telegram shop"}'
curl -s "https://app.oneprovider.dev/partner/v1/customers?external_id=user-77" \
-H "Authorization: Bearer $OP_PARTNER_TOKEN"

Объект клиента: id, external_id, name, note, blocked, keys_count, created_at. Изменить имя и заметку: PATCH /customers/{id}. Повтор external_id даёт 409 customer_exists.

Заблокировать клиента

curl -s -X PATCH https://app.oneprovider.dev/partner/v1/customers/<customer id> \
-H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Content-Type: application/json" \
-d '{"blocked":true}'

Блокировка (право keys) ставит на паузу все живые ключи клиента и помечает его blocked: true. Выпуск ключей, заказы и погашения кодов для него отвечают 409 customer_blocked. Разблокировка ({"blocked":false}) возобновляет только те ключи, которые остановила блокировка: ключи, которые вы поставили на паузу сами, остаются на паузе.