API реселлера: коды и тарифы

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

Пачки кодов

Пачка создаётся методом POST /code-batches (право codes, нужен Idempotency-Key): label, count до 200, amount_usd до 5000 на код. Необязательно: key_expires_days или key_expires_hours (сколько живёт ключ после активации кода, по умолчанию 90 дней) и codes_valid_until (до какого момента код можно активировать, ISO 8601; позже неактивированные коды отзываются сами и резерв возвращается).

curl -s -X POST https://app.oneprovider.dev/partner/v1/code-batches \
-H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Idempotency-Key: batch-oct-001" \
-H "Content-Type: application/json" \
-d '{"label":"October promo","count":50,"amount_usd":"5.00","key_expires_hours":24,"codes_valid_until":"2026-12-31T23:59:59Z"}'

Пачка только резервирует стоимость (count x amount_usd) на балансе реселлера: она должна помещаться в «Свободно», но деньги не списываются. Когда код активируют, он становится ключом, лимит которого остаётся в резерве, а списание идёт по мере расхода. Отзыв неактивированных кодов возвращает резерв. Объект пачки: id, label, count, amount_usd, used, revoked, key_expires_hours, key_expires_days, codes_valid_until, created_at.

# list batches, read one, list its codes
curl -s https://app.oneprovider.dev/partner/v1/code-batches -H "Authorization: Bearer $OP_PARTNER_TOKEN"
curl -s https://app.oneprovider.dev/partner/v1/code-batches/<batch id> -H "Authorization: Bearer $OP_PARTNER_TOKEN"
curl -s "https://app.oneprovider.dev/partner/v1/code-batches/<batch id>/codes?status=active&limit=100" \
-H "Authorization: Bearer $OP_PARTNER_TOKEN"
# revoke what is still unredeemed
curl -s -X POST https://app.oneprovider.dev/partner/v1/code-batches/<batch id>/revoke -H "Authorization: Bearer $OP_PARTNER_TOKEN"

Объект кода: code, status (активен, погашен, отозван: active/used/revoked), amount_usd, batch_id, redeemed_at, key_id. Статус одного кода: GET /codes/{code}.

Погасить код через API

Если вы сами превращаете код в ключ, вызовите POST /codes/{code}/redeem (нужен Idempotency-Key). Клиента можно указать через customer_id или customer_external_id.

curl -s -X POST https://app.oneprovider.dev/partner/v1/codes/<code>/redeem \
-H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Idempotency-Key: redeem-<code>" \
-H "Content-Type: application/json" \
-d '{"customer_external_id":"user-77"}'

Ответ 201 содержит ключ и его секрет (один раз). Уже погашенный код даёт 409 code_used, отозванный 409 code_revoked.

Тарифы

Тариф это ваша цена клиентам: сколько USD получает ключ, сколько и в какой валюте клиент платит вам, на какой срок. Тарифы нужны для POST /orders (параметр plan_id). Максимум 20 тарифов (409 plan_limit). Чтение тарифов требует право read, изменение plans.

curl -s -X POST https://app.oneprovider.dev/partner/v1/plans \
-H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"Start 10 USD","balance_usd":"10.00","price":"890.00","currency":"RUB","expires_days":30,"sort":1,"active":true}'
curl -s -X PATCH https://app.oneprovider.dev/partner/v1/plans/<plan id> -H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Content-Type: application/json" -d '{"active":false}'
curl -s -X DELETE https://app.oneprovider.dev/partner/v1/plans/<plan id> -H "Authorization: Bearer $OP_PARTNER_TOKEN"

GET /pricing возвращает лимиты, в которые надо укладываться: минимум и максимум суммы ключа, максимальный срок, максимум суммы кода, размер пачки, число тарифов и токенов.