代理兑换接口

用已有卡密创建专属兑换链接。顾客在本站确认兑换，你可以在自己的订单页显示处理结果。

服务端鉴权

向站长领取专属代理密钥，保存在你的服务器上。以下两个接口都需要通过 HTTPS 发送这两个请求头。

Authorization: Bearer <PARTNER_KEY>
Content-Type: application/json

代理密钥只用于创建兑换链接和查询本代理的兑换结果。请勿放入网页、应用安装包或发给顾客的链接中。

请求地址使用下方固定路径。发送请求时，请勿附带查询参数、Cookie 或 Origin 请求头。

创建兑换链接

POSThttps://wudi.cdk.bar/api/partner/v1/redemptions

每笔兑换生成一个唯一的 client_request_id。请求超时或断线时，用原卡密和同一个 ID 重试。

client_request_id 最多 128 个字符，以英文字母或数字开头，其余字符可用英文字母、数字和 _ . : -

{
  "code": "<CDK>",
  "client_request_id": "order-20261114-001"
}

保存响应中的 id，把原样返回的 redeem_url 私下发给这位顾客。顾客打开链接后，输入对应的原卡密，在本站完成预检和兑换。创建链接本身不会发起充值。

查看响应示例

{
  "ok": true,
  "id": "<ID>",
  "client_request_id": "order-20261114-001",
  "status": "awaiting_customer",
  "redeem_url": "https://wudi.cdk.bar/#partner=<TOKEN>",
  "expires_at": "2026-11-15T12:00:00Z"
}

查询兑换结果

POSThttps://wudi.cdk.bar/api/partner/v1/status

使用创建链接时的代理密钥，提交保存的 id。此操作只查询进度，可以重复调用。

{"id": "<ID>"}

按响应中的 status 显示进度。兑换失败时，根据 error_code 显示原因；结果待核实时，保留原订单并继续查询。

请从代理服务端轮询结果，本接口没有 webhook。遇到 HTTP 错误时，读取错误响应的 code 字段。

failed · card_reenabled: true 表示原订单充值失败，当前卡密已自动恢复可用。顾客要重试时，请用同一张卡密和新的请求编号创建兑换链接。

retryable_no_task · NO_TASK_FOUND 未查到上游任务。顾客可通过原链接重新验证原账号并继续原订单；链接失效时，可在兑换首页使用原卡密继续。

如果响应带有 preflight_error_code，可向顾客显示 preflight_message，说明最近一次预检失败的原因。原订单仍按 status 和 error_code 跟踪。

HTTP 错误处理

400 INVALID_REQUEST / 415 JSON_REQUIRED: 检查 JSON 请求体、字段、请求头和请求编号。
401 PARTNER_UNAUTHORIZED: 检查专属密钥是否有效，以及请求是否由代理服务端直接发出。
404 INTENT_NOT_FOUND: 核对创建时保存的 id，并使用创建时的同一代理密钥查询。
405 METHOD_NOT_ALLOWED: 使用 POST 请求。
409 REQUEST_CONFLICT / 409 CARD_UNAVAILABLE: 请求编号已绑定其他卡密，或卡密当前无法创建兑换链接。
429 RATE_LIMITED / 503 SERVICE_UNAVAILABLE: 放慢请求频率，稍后使用相同参数重试。

兑换状态与失败原因

awaiting_customer: 等待顾客完成兑换。如果已经尝试过预检，请同时读取 error_code。
queued / running: 已进入队列或正在兑换，稍后查询原订单。
captcha_required: ACTION_REQUIRED · 兑换需要进一步验证。
succeeded: 兑换成功。
failed / cancelled: REDEMPTION_FAILED / REDEMPTION_CANCELLED · 兑换失败或已取消。
manual_review / uncertain: MANUAL_REVIEW / RESULT_UNCERTAIN · 需人工核实或结果尚未确定，请保留原订单。
expired: INTENT_EXPIRED · 顾客确认前链接已到期。
card_unavailable: CARD_UNAVAILABLE · 本链接绑定的卡密已无法用于这次兑换。

预检未通过时如何提示顾客

PLUS_PROMO_INELIGIBLE: 当前账号没有半价资格。
PLUS_PROMO_UNKNOWN: 暂时无法确认半价资格，可稍后用原链接重试。
SESSION_INVALID: 请顾客重新登录获取新的 Session，再回到原兑换链接预检。
SESSION_FORMAT_INVALID: 请顾客重新粘贴完整的 Session JSON。
ACCOUNT_PLAN_INCOMPATIBLE: 当前订阅与卡密不兼容，请核对套餐和订阅来源。
ACCOUNT_CHECK_MISMATCH: 预检返回的账号与顾客填写的账号不一致，请重新获取凭证。
RETRY_ACCOUNT_MISMATCH: 重试原订单时，请顾客使用原账号。
RETRY_PROVIDER_CHANGED: 原订单的服务连接已变更，请联系发卡方。
ACCOUNT_CHECK_UNAVAILABLE: 账号验证暂不可用，可稍后用原链接重试。
ACCOUNT_CHECK_TIMEOUT: 网络超时，请重新充值。