分销商 API 的工作方式

分销商平台如何运作：分销商余额、预留金额、客户密钥、兑换码、套餐，以及个人中心中的所有功能——都可以通过 REST API 用于您自己的网站或机器人。

运作方式

分销商按批发价为自己的余额充值，并以密钥和兑换码的形式向客户出售 token。您在个人中心（app.oneprovider.dev 的“分销商”栏目）里能做的一切，也都可以通过 API 完成，因此您可以搭建自己的网站、机器人或收银台。

• 分销商余额。以 USD 计价，与您的个人资金分开。您按批发价充值；GET /pricing 会返回每 1 USD 的价格和折扣。
• 客户密钥。每个密钥都有 USD 消费额度和有效期（由套餐或兑换码批次生成的密钥也可以永久有效：此时 expires_at 为 null，额度仍然生效）。您的客户像使用任何 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

资金不是在您创建时扣除，而是在客户拿到并消耗额度时扣除。在此之前，资金只是被预留：

• 兑换码批次只会预留金额。作废未激活的兑换码会释放预留金额。
• 兑换码激活后会变成一个密钥，其额度继续保持预留。
• 发放密钥会预留它的额度；密钥产生的消耗再从分销商余额中扣除。
• 删除密钥或调低其额度，会立即把未使用的部分退回“可用”（Free）。
• 暂停密钥时，它的预留金额保持不变。

每个新密钥、每次密钥充值和每个兑换码批次，都必须在“可用”（Free）范围内；否则返回 409 insufficient_balance。三个数字都来自 GET /balance：balance_usd、reserved_usd、available_usd。

第一个请求

1. 在个人中心打开“分销商”栏目的“API 与设置”，创建一个 token。其值只显示一次。
2. 把 token 放进服务器的环境变量，然后调用 /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 。

为分销商余额充值

可用的支付服务商及其最低金额在 GET /balance 的 topup_providers 中。使用 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 Webhook 事件通知。

审计日志

GET /audit（权限 read）返回您账户中所有操作的日志：包括在个人中心中的操作、通过 API token 的操作和系统操作。日志行不可更改（没有编辑或删除的路由），也从不包含机密：没有密钥、token、兑换码或 Webhook secret。对象只作简要显示：密钥末尾、批次标记或套餐名称。

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 或 bot（分销商的店铺机器人）。money（操作未涉及资金时为 null）显示预留和扣除的带符号变化；available_after 可能为 null。响应的 actions 中还附有完整的操作列表：

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

约定

• Base URL：https://app.oneprovider.dev/partner/v1。
• 全部使用 JSON；金额是保留两位小数的 USD 字符串（"12.50"）；时间为 ISO 8601 UTC（2026-10-08T12:00:00Z）。
• 只能从您的服务器调用 API：这里没有 CORS，token 也绝不能放进浏览器或移动应用。
• token、权限、速率限制、错误、幂等性和分页：授权与限制 。

下一步

• 密钥与客户 ：发放、充值、暂停、删除。
• 订单 ：如何搭建您自己的网站。
• 兑换码与套餐 。
• Webhook ：事件与签名验证。
• 方法参考 和 openapi.yaml 。