OneProvider

分销商 API 兑换码与套餐

通过 OneProvider 分销商 API 批量签发和撤销兑换码、把兑换码兑换成密钥，并管理您的资费套餐。内含示例。

通过分销商 API 发放兑换码批次、作废兑换码、把兑换码兑换成密钥，并管理您的资费套餐。

全部模型、功能与价格 面向 AI 智能体的文档索引： https://oneprovider.dev/docs/llms.txt

兑换码批次

批次通过 POST /code-batches 创建（权限 codes；必须带 Idempotency-Key 请求头）：label、count 最多 200、每个兑换码的 amount_usd 最多 5000。可选：key_expires_days 或 key_expires_hours（兑换码激活后密钥的有效时长，默认 90 天），或 key_expires_never: true（永久有效的密钥，额度仍然生效；不能与有效时长同时使用），以及 codes_valid_until（兑换码可激活到何时，ISO 8601，须是将来的时间，且最多 2 年之内；过此时间，未激活的兑换码会自动作废，预留金额退回）。

bash 
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 × amount_usd）：这部分必须在“可用”（Free）范围内，但不会扣款。兑换码激活后会变成一个额度继续预留的密钥，随消耗再扣款。作废未激活的兑换码会释放预留金额。批次对象：id、label、count、amount_usd、used、revoked、key_expires_hours、key_expires_days、key_expires_never、codes_valid_until、created_at（密钥永久有效的批次和采用默认 90 天的批次，其 key_expires_hours 和 key_expires_days 都是 null：用 key_expires_never 区分）。GET /code-batches/{id} 还包含 activations：谁在何时激活了哪个兑换码（code_tail、redeemed_at、key_id），按时间倒序，最多 1000 条；作废的响应还包含 revoked_now 和 refunded_usd。

bash 
# 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：active/used/revoked）、amount_usd、batch_id、redeemed_at、key_id。单个兑换码的状态：GET /codes/{code}。

兑换码属于机密 兑换码对持有者来说就是钱。因此每个兑换码方法都需要单独的 codes 权限：不要把它授予不需要的 token。您的客户也可以在公开的兑换页面上兑换兑换码。

通过 API 兑换兑换码

如果由您自己把兑换码变成密钥，请调用 POST /codes/{code}/redeem（必须带 Idempotency-Key 请求头）。客户可以通过 customer_id 或 customer_external_id 传入。

bash 
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 响应包含密钥及其 secret（用相同 Idempotency-Key 重复同一次调用，会返回同一个密钥）。已通过其他方式兑换的兑换码返回 409 code_used，已作废的返回 409 code_revoked；同时传 customer_id 和 customer_external_id 返回 400 invalid，已封禁的客户返回 409 customer_blocked。

套餐

套餐是您面向客户的定价：密钥获得多少 USD，客户向您支付多少、用哪种币种，以及有效多久。套餐用于 POST /orders（参数 plan_id）。最多 20 个套餐（409 plan_limit）。读取套餐需要 read 权限，修改套餐需要 plans。

套餐字段
字段说明
name名称，最多 40 个字符。
balance_usd密钥获得的金额。
price, currency您向客户收取的价格及其币种：USD、RUB、XTR 或 USDT。
expires_days / expires_hours密钥有效期：1 到 365 天，或 1 到 8760 小时（二选一；默认 30 天）。响应中带有 expires_hours（以它为准）；有效期不是整数天时，expires_days 为 null。
expires_nevertrue：该套餐的密钥永不过期（余额上限仍然生效）。不能与 expires_days 或 expires_hours 同时使用（400 invalid）。此时响应中的 expires_hours 和 expires_days 为 null。
sort, active显示顺序和是否在售的标志。
bash 
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 返回需要遵守的限制：密钥金额的最小值和最大值、最长有效期、兑换码金额上限、批次大小、套餐和 token 的数量、有效密钥的数量（key_limit），以及 plan_currencies（套餐可用的币种）。创建套餐时可以带 Idempotency-Key（可选）：重复调用返回同一个套餐，而不会再创建一个。未提及有效期的 PATCH 会保持原有效期不变。只要该套餐上还有未完成的机器人购买，就拒绝删除、涨价和更换币种（409 plan_in_use）。

最后更新: 2026-11-08 发现问题？ @Oneproviderhelpbot