资金核验
在工作台提交采购充值，等待平台确认实际到账。
完成信号：采购余额大于 0PARTNER API · V1
从一笔测试订单，
到稳定的充值交付。
代理商只对接 Quefa。支付、充值、CDK、订单状态与通知使用同一套业务编号；底层供应连接不会进入你的前端、日志或客户页面。
API Base
https://你的生产域名/v101 · QUICKSTART
四段接入航道
每一步都有明确的完成信号。不要在密钥未审核、资金未核验时直接测试写接口。
开通 API
提交用途，审核通过后创建应用密钥；Secret 只显示一次。
完成信号：API 状态为“已开通”创建订单
读取商品实时供货价，选择平台代收或余额采购。
完成信号：获得 order_id回调验收
验签 Webhook，并用查单接口确认支付与充值终态。
完成信号：测试通知 2xx两种收款模式并存
platform_collect：Quefa 向客户收款，不扣代理采购余额。agent_collect：代理自行收客户款，Quefa 按供货价扣采购余额。
02 · AUTHENTICATION
服务端 HMAC 签名
密钥只能放在代理商服务端。浏览器、移动端和公开仓库不得保存 client_secret。
每次请求携带
X-Partner-Id租户标识X-Key-Id应用密钥标识X-Timestamp当前 Unix 秒X-Nonce每次请求唯一X-Signature64 位小写十六进制- 写请求再带
Idempotency-Key
Canonical string
METHOD
PATH
CANONICAL_QUERY
TIMESTAMP
NONCE
KEY_ID
IDEMPOTENCY_KEY
SHA256_HEX(RAW_BODY)03 · ORDERS
创建第一笔订单
下单前先调用 GET /v1/products。价格、可售状态和履约方式以实时响应为准，不能写死。
POST /v1/orders
{
"merchant_order_no": "SHOP-20260927-0001",
"product_code": "chatgpt_plus_1m",
"quantity": 1,
"sale_amount": "135.00",
"collection_mode": "platform_collect"
}pending等待付款
paid支付已确认
running充值处理中
succeeded充值成功
04 · REDEMPTION
托管入口或自建兑换页
普通商城优先跳转订单返回的 fulfillment_url。需要自有品牌页面时，由代理后端签名调用兑换接口。
Quefa 托管入口
客户凭据直接提交给 Quefa，代理商不接触敏感资料。开发量最小，适合快速上线。
打开 fulfillment_url代理商自建页面
浏览器只请求代理自己的后端，由后端签名调用 Quefa。不得让浏览器直连接口。
POST /v1/redemptions白标边界
代理和客户只看到 Quefa 商品、订单、QF-兑换码及统一状态。供应域名、供应订单号、原始 CDK、卡数据与内部错误不会返回。
05 · WEBHOOKS
通知用于加速，查单用于确认
先以原始请求体验签，再按 event_id 幂等入库，最后快速返回 2xx。通知可能重复且不保证严格顺序。
order.paidcdk.issuedfulfillment.succeededfulfillment.failedrefund.succeededwebhook.testWebhook signature
signed = timestamp + "." + RAW_BODY
signature = HMAC_SHA256(webhook_secret, signed)06 · RELIABILITY
重试前先判断结果是否未知
支付、充值和退款的网络超时不等于失败。优先查询原订单；需要重试写请求时保持相同业务幂等键。
| 场景 | 动作 | 禁止动作 |
|---|---|---|
| HTTP 202 / queued | 轮询或等待 Webhook | 显示“充值成功” |
| 429 / 503 | 原幂等键指数退避 | 换订单号重复提交 |
| 请求超时 | 先查原订单 | 直接判失败 |
| succeeded | 展示终态并停止轮询 | 被旧的 running 覆盖 |