订阅与审批
接口级凭证需要先订阅目标接口，审批通过后才能调用。订阅同时约束有效期和日调用量，是 API 开放过程中的授权载体。
角色与入口
| 角色 | 入口 | 能做什么 |
|---|---|---|
| 调用方 | 接口详情页、账户中心 → 订阅申请 | 提交申请、撤回审批中的申请 |
| 接口负责人 / 管理员 | 账户中心 → 审批中心 | 通过、拒绝、终止订阅申请 |
| 订阅方 | 账户中心 → 我的订阅 | 查看自己的订阅、退订 |
| 接口负责人 / 管理员 | 账户中心 → 订阅管理 | 查看项目内全部订阅、冻结、解冻、续订、退订、查看调用统计 |
提交订阅申请
在接口详情页点击「订阅申请」，填写：
| 字段 | 必填 | 说明 |
|---|---|---|
| 调用凭证 | 是 | 选择当前账号下的应用凭证；没有凭证时提示先创建 |
| 订阅接口 | — | 只读，展示接口名称和接口 ID |
| 日调用量 | 否 | 正整数，留空表示不限额 |
| 有效期 | 是 | 长期有效或自定义起止日期 |
| 申请理由 | 是 | 最多 200 字，需说明用途 |
提交规则：
- 同一凭证对同一接口只能存在一条生效中或待生效的订阅；
- 同一凭证存在审批中的申请时不能重复提交；
- 长期有效在数据上按 100 年有效期保存；
- 自定义有效期必须选择完整的起止日期；
- 已有授权且距到期超过 7 天时，不能重复申请；
- 永久授权无需重复申请。
提交后会给接口负责人发送站内消息。
审批
审批人在 账户中心 → 审批中心 处理订阅申请，可执行：
| 操作 | 结果 |
|---|---|
| 通过 | 创建订阅并激活，自动建立接口授权，通知申请人 |
| 拒绝 | 申请关闭，记录审批意见，通知申请人 |
| 终止 | 回收由该申请产生的授权；订阅已激活时同时退订 |
审批时可以在申请日调用量的基础上调整最终额度，留空表示不限额。只有接口负责人和管理员能处理对应申请。
申请状态：
| 状态 | 含义 |
|---|---|
审批中 process | 等待审批，可撤回 |
已通过 pass | 审批通过并已激活订阅 |
已拒绝 reject | 审批拒绝 |
已终止 stop | 授权被终止，订阅同步失效 |
已撤回 revoke | 申请人主动撤回 |
订阅列表与状态
订阅状态：
| 状态 | 含义 | 能否调用 |
|---|---|---|
待生效 pending | 订阅已创建但尚未生效 | 否 |
生效中 active | 正常可用 | 是 |
已过期 expired | 超过有效期，可由定时任务翻转 | 否 |
已退订 unsubscribed | 调用方或审批人主动退订 | 否 |
已冻结 frozen | 被管理员冻结 | 否 |
订阅列表展示订阅 ID、名称、凭证、申请人、状态、有效期、日调用量和操作。
调用量配额
- 日调用量按订阅维度统计，每天零点重置；
- 请求前先原子预留额度，达到上限直接拒绝；
- 下游失败、客户端取消或非成功响应会释放本次预留，失败请求不占额度；
- 配额超 限返回 HTTP 429，业务码
40023； - 留空表示不限额。
冻结与解冻
- 只有「生效中」的订阅可以冻结；
- 冻结会同时禁用该订阅产生的接口授权，调用返回业务码
40021； - 只有「已冻结」的订阅可以解冻，解冻后恢复授权和剩余有效期；
- 冻结不会改变有效期，也不会清空当日已用配额。
续订
- 只有「已过期」的订阅可以续订；
- 续订时必须指定新的到期日，可同时调整日调用量；
- 续订后状态恢复为「生效中」，重新建立授权，并重置配额计数；
- 续订不会补发过期期间的调用权限。
退订
- 「已过期」或「已退订」的订阅不能再次退订；
- 退订会立即禁用授权，调用方不能再访问接口；
- 退订会清理授权投影和配额计数，不影响其他凭证或其他订阅。
到期与提醒
系统每小时执行一次订阅生命周期任务：
- 把到期日早于今天的「生效中」订阅翻转为「已过期」，同时回收授权、刷新运行态缓存；
- 在到期前 7 天、3 天、1 天发送站内提醒，同一级别只提醒一次；
- 到期后发送到期通知，提示续订。
网关在定时任务翻转前也会按到期日兜底拦截，避免窗口期内继续调用。
调用统计
在订阅管理中可查看单个订阅的调用统计：
- 统计维度：日期、调用量、成功量、失败量、成功率、流量、平均耗时；
- 支持按环境和时间范围筛选；
- 支持导出统计结果。
统计口径与 API 日志一致，只统计经过网关的调用。
通知
以下事件会产生站内消息：
- 提交订阅申请后通知接口负责人；
- 审批通过、拒绝、终止后通知申请人；
- 订阅冻结、解冻、续订、退订；
- 到期前分级提醒与到期通知。
常见问题
| 现象 | 原因 | 处理 |
|---|---|---|
| 申请按钮不可用 | 接口免认证，或已有审批中的申请 | 免认证接口无需申请；审批中请等待结果 |
| 提示凭证已永久授权 | 当前凭证已有永久 有效授权 | 直接调用，无需重复申请 |
| 提示授权未进入可续期窗口 | 距到期超过 7 天 | 临近到期后再提交申请 |
| 调用返回 40021 | 订阅被冻结、过期、退订，或接口不在订阅范围 | 检查订阅状态并联系管理员 |
| 调用返回 40023 | 当日调用量达到上限 | 等待次日重置或申请调整额度 |
| 订阅已过期但页面仍显示生效中 | 定时任务每小时执行一次 | 等待任务执行，网关已按到期日兜底拦截 |