DOCS

兑换会员权益

已绑定 QQ 的用户可使用一次性兑换码开通或顺延对应的会员组权益，并返回更新后的会员快照。

总览私有部署数据抓取流程OAuth 文档API 文档
返回 API 列表
post/api/v1/auth/memberships/redeem
api.auth.memberships.redeem

COST

扣费规则

每次请求按固定额度扣费，不随返回条数变化。

固定 50 点额度/次

实际扣费以响应头 x-api-cost 为准。

请求说明

参数

准备就绪

当前接口没有额外请求参数

响应说明

状态码与响应格式

200

兑换成功并返回最新会员权益。

响应头

x-api-remainx-api-cost
application/jsonobject

响应结构 

{
    "type": "object",
    "required": [
        "ok",
        "data",
        "error"
    ],
    "properties": {
        "ok": {
            "type": "boolean",
            "required": true
        },
        "data": {
            "type": "object",
            "required": true,
            "shape": {
                "type": "object",
                "required": [
                    "code",
                    "redeemedAt",
                    "durationDays",
                    "membership",
                    "memberships"
                ],
                "properties": {
                    "code": {
                        "type": "string",
                        "required": true
                    },
                    "redeemedAt": {
                        "type": "integer",
                        "required": true
                    },
                    "durationDays": {
                        "type": "integer",
                        "required": true
                    },
                    "membership": {
                        "type": "object",
                        "required": true,
                        "shape": {
                            "type": "object",
                            "required": [
                                "groupId",
                                "status",
                                "startsAt",
                                "expiresAt",
                                "group"
                            ],
                            "properties": {
                                "groupId": {
                                    "type": "string",
                                    "required": true
                                },
                                "status": {
                                    "type": "active | scheduled",
                                    "required": true,
                                    "enum": [
                                        "active",
                                        "scheduled"
                                    ]
                                },
                                "startsAt": {
                                    "type": "integer",
                                    "required": true
                                },
                                "expiresAt": {
                                    "type": "integer",
                                    "required": true
                                },
                                "group": {
                                    "type": "object",
                                    "required": true,
                                    "shape": {
                                        "type": "object",
                                        "required": [
                                            "id",
                                            "name"
                                        ],
                                        "properties": {
                                            "id": {
                                                "type": "string",
                                                "required": true
                                            },
                                            "name": {
                                                "type": "string",
                                                "required": true
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "memberships": {
                        "type": "object",
                        "required": true,
                        "shape": {
                            "type": "object",
                            "required": [
                                "userId",
                                "asOf",
                                "items",
                                "catalog",
                                "accountScopes",
                                "effectiveQuota",
                                "quotaBreakdown"
                            ],
                            "properties": {
                                "userId": {
                                    "type": "string",
                                    "required": true
                                },
                                "asOf": {
                                    "type": "integer",
                                    "required": true
                                },
                                "items": {
                                    "type": "array<object>",
                                    "required": true,
                                    "shape": {
                                        "type": "array",
                                        "items": {
                                            "type": "object"
                                        }
                                    }
                                },
                                "catalog": {
                                    "type": "array<object>",
                                    "required": true,
                                    "shape": {
                                        "type": "array",
                                        "items": {
                                            "type": "object"
                                        }
                                    }
                                },
                                "accountScopes": {
                                    "type": "array<string>",
                                    "required": true,
                                    "shape": {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        }
                                    }
                                },
                                "effectiveQuota": {
                                    "type": "object",
                                    "required": true,
                                    "shape": {
                                        "type": "object"
                                    }
                                },
                                "quotaBreakdown": {
                                    "type": "object",
                                    "required": true,
                                    "shape": {
                                        "type": "object"
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "error": {
            "type": "string",
            "required": true
        }
    }
}

示例响应 

{
    "ok": true,
    "data": {
        "code": "CRH-7K3M-9Q2W-X8NP-4R6T",
        "redeemedAt": 1784131200,
        "durationDays": 30,
        "membership": {
            "groupId": "supporter",
            "status": "active",
            "startsAt": 1784131200,
            "expiresAt": 1786723200,
            "group": {
                "id": "supporter",
                "name": "Supporter"
            }
        },
        "memberships": {
            "userId": "example-user",
            "asOf": 1784131200,
            "accountScopes": [
                "api.auth.me.read",
                "api.auth.memberships.redeem"
            ]
        }
    },
    "error": ""
}
400

兑换码格式或请求体无效。

application/jsonobject

响应结构 

{
    "type": "object",
    "required": [
        "ok",
        "data",
        "error"
    ],
    "properties": {
        "ok": {
            "type": "boolean",
            "required": true
        },
        "data": {
            "type": "string",
            "required": true
        },
        "error": {
            "type": "string",
            "required": true
        }
    }
}

示例响应 

{
    "ok": false,
    "data": "兑换码格式无效",
    "error": "invalid_membership_code"
}
401

请求未携带有效认证信息。

application/jsonobject

响应结构 

{
    "type": "object",
    "required": [
        "ok",
        "data",
        "error"
    ],
    "properties": {
        "ok": {
            "type": "boolean",
            "required": true
        },
        "data": {
            "type": "string",
            "required": true
        },
        "error": {
            "type": "string",
            "required": true
        }
    }
}

示例响应 

{
    "ok": false,
    "data": "API Key 无效或已过期。",
    "error": "invalid_api_key"
}
403

缺少兑换权限或额度上限不足。

application/jsonobject

响应结构 

{
    "type": "object",
    "required": [
        "ok",
        "data",
        "error"
    ],
    "properties": {
        "ok": {
            "type": "boolean",
            "required": true
        },
        "data": {
            "type": "string",
            "required": true
        },
        "error": {
            "type": "string",
            "required": true
        }
    }
}

示例响应 

{
    "ok": false,
    "data": "API Key 无效或已过期。",
    "error": "invalid_api_key"
}
404

兑换码不存在。

application/jsonobject

响应结构 

{
    "type": "object",
    "required": [
        "ok",
        "data",
        "error"
    ],
    "properties": {
        "ok": {
            "type": "boolean",
            "required": true
        },
        "data": {
            "type": "string",
            "required": true
        },
        "error": {
            "type": "string",
            "required": true
        }
    }
}

示例响应 

{
    "ok": false,
    "data": "兑换码不存在",
    "error": "membership_code_not_found"
}
409

用户未绑定 QQ、兑换码已使用或对应会员组当前不可用。

application/jsonobject

响应结构 

{
    "type": "object",
    "required": [
        "ok",
        "data",
        "error"
    ],
    "properties": {
        "ok": {
            "type": "boolean",
            "required": true
        },
        "data": {
            "type": "string",
            "required": true
        },
        "error": {
            "type": "string",
            "required": true
        }
    }
}

示例响应 

{
    "ok": false,
    "data": "兑换码已被使用",
    "error": "membership_code_already_used"
}