分销商 API 订单

搭建您自己的店铺：客户向您付款，您调用 POST /orders 并获得密钥。按 external_order_id 实现幂等，以及为现有密钥充值。

销售流程

1. 您的客户在您的网站上通过您自己的收银台向您付款（OneProvider 不参与这笔付款）。
2. 您的服务器收到付款确认后，调用 POST /orders。
3. OneProvider 在您的分销商余额上预留密钥额度（资金随消耗扣除），并创建一个状态为 completed 的订单。
4. 您把响应中的密钥交给客户，也可以一并附上 dashboard_url。

订单要么发放一个新密钥（kind: "new_key"），要么为现有密钥充值（传入 key_id 时为 kind: "topup"）。

创建订单

交付内容由套餐（plan_id，见兑换码与套餐 ）决定，或直接由金额决定：limit_usd 以及 expires_days 或 expires_hours。客户可以通过 customer_id 或 customer_external_id 传入（事先创建好的客户）。charged_amount 和 charged_currency 字段记录客户实际向您支付的金额和币种；它们用于 GET /stats，不影响扣费。

curl -s -X POST https://app.oneprovider.dev/partner/v1/orders \
-H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Idempotency-Key: shop-1042" \
-H "Content-Type: application/json" \
-d '{
"external_order_id": "shop-1042",
"limit_usd": "10.00",
"expires_days": 30,
"customer_external_id": "user-77",
"name": "anna-main",
"charged_amount": "890.00",
"charged_currency": "RUB"
}'

{
"id": 42,
"external_order_id": "shop-1042",
"status": "completed",
"kind": "new_key",
"key_id": "<key id>",
"amount_usd": "10.00",
"charged_amount": "890.00",
"charged_currency": "RUB",
"created_at": "2026-10-08T12:00:00Z",
"key": {
"id": "<key id>",
"name": "anna-main",
"status": "active",
"limit_usd": "10.00",
"expires_at": "2026-11-07T12:00:00Z",
"dashboard_url": "<dashboard link>",
"key": "sk-..."
}
}

key 是密钥对象（与发放响应中的相同），密钥本身在 key.key 中。它只在新密钥的 POST /orders 响应中出现（以及对其完全相同的重复请求中）；GET /orders 和 GET /orders/{id} 不包含它。请在记录订单的同一个事务中保存密钥。当订单来自没有期限的套餐（expires_never）时，密钥的 expires_at 为 null。

按 external_order_id 实现幂等

external_order_id 是您系统中的订单号。用相同的订单号和相同的参数重复请求，不会发放第二个密钥，也不会重复扣费：您会得到同一个订单和同一个密钥（连同相同的 secret，因此响应在途中丢失时，重复调用即可取回）。相同的订单号搭配不同的参数会返回 409 external_order_id_conflict。这样，超时或连接中断后可以放心重试。您可以用 GET /orders?external_order_id=shop-1042 查找订单。

为现有密钥充值

传入 key_id 和金额（limit_usd 或套餐）：

curl -s -X POST https://app.oneprovider.dev/partner/v1/orders \
-H "Authorization: Bearer $OP_PARTNER_TOKEN" \
-H "Idempotency-Key: shop-1043" \
-H "Content-Type: application/json" \
-d '{"external_order_id":"shop-1043","key_id":"<key id>","limit_usd":"10.00","charged_amount":"890.00","charged_currency":"RUB"}'

响应中的 kind 为 topup，且不含 secret。该金额会加到密钥的总额度上，并且和其他操作一样必须在“可用”（Free）范围内（先预留，随消耗扣除）。

付款处理示例（Python）

import os
import requests
BASE = "https://app.oneprovider.dev/partner/v1"
HEADERS = {"Authorization": "Bearer " + os.environ["OP_PARTNER_TOKEN"]}
def fulfil_paid_order(order_no: str, user_id: str, plan_id, paid: str, currency: str) -> dict:
"""Call it after YOUR payment provider confirmed the payment (it may be called twice)."""
r = requests.post(
BASE + "/orders",
headers={**HEADERS, "Idempotency-Key": "order-" + order_no},
json={
"external_order_id": order_no,
"plan_id": plan_id,
"customer_external_id": user_id,
"charged_amount": paid,
"charged_currency": currency,
},
timeout=30,
)
if r.status_code == 409 and r.json()["error"]["code"] == "insufficient_balance":
raise RuntimeError("Top up the reseller balance, then retry the same call")
r.raise_for_status()
order = r.json()
# order["key"] (the key object, the secret is order["key"]["key"]) is present on a new_key order, a repeat returns it again
return order

请关注 available_usd 并订阅 balance.low Webhook，以便在订单遇到 409 insufficient_balance 之前充值。见 Webhook 。