跳到主要内容

POST /api/private/v1/redemptions

兑换卡密，为指定客户激活对应套餐。

兑换成功后的套餐生效规则与 POST /api/private/v1/subscriptions/activate 完全一致。

鉴权​

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

请求体​

{
  "code": "ABC-DEF-GHI",
  "customer": { "type": "external_user_id", "value": "u_1001" },
  "autoCreate": false
}
字段类型必填说明
codestring是卡密字符串
customerobject否目标客户标识
customer.typestring是标识类型，最大 16 个字符
customer.valuestring是标识值，最大 128 个字符
autoCreateboolean否客户不存在时是否自动创建，默认 false

当 autoCreate=true 且客户不存在时：

  • 若 customer.type="username"，系统直接用 customer.value 作为新客户用户名
  • 否则系统生成内部用户名，并把传入标识写入客户标识表

成功响应​

{
  "ok": true,
  "requestId": "req_123",
  "data": {
    "customer": {
      "id": 1,
      "username": "customer_001",
      "created": false
    },
    "subscriptions": [
      {
        "id": 10,
        "planId": 2,
        "planName": "Pro",
        "validFrom": "2026-03-21T00:00:00.000Z",
        "validTo": "2026-04-21T00:00:00.000Z"
      }
    ]
  }
}

可能错误​

  • 404 CODE_NOT_FOUND
  • 404 CUSTOMER_NOT_FOUND
  • 409 CODE_ALREADY_REDEEMED
  • 409 REDUNDANT_PERMANENT_PURCHASE
  • 409 PERMANENT_TAIL_CONFLICT
  • 403 CUSTOMER_PROJECT_MISMATCH
  • 400 INVALID_PLAN_VALUE
  • 400 INVALID_SUBSCRIPTION_CHAIN