聚合/文件导入契约复核日期: 2026-07-10
安全边界
PayAPIKey 托管接口不接收中转站管理员 Token、渠道 Key、Cookie 或会话。原生 API 读取必须在你控制的本地 connector/sidecar 中完成；托管端只接收去敏后的计费元数据。
支持范围
模式
聚合/文件导入
字段族
voapi-v2
授权方式
v2 原始 JWT
能力
聚合用量参考 · 用量 CSV 导入 · 规范 JSON 导入 · 有限的 Key 模板倍率上下文
凭据边界
VoAPI v2 使用原始 JWT，而非 One API 的 Bearer 方式。JWT 只能保留在本地，绝不能提交给 PayAPIKey。
读取流程
- 1用本地 connector 读取 /api/dash/statistics 做聚合核对，或从管理端导出结算周期的请求级计费记录。
- 2移除 Key、Cookie、会话、提示词和响应正文，仅保留账单字段。
- 3在浏览器工作台中按下游、上游、支付三类分别导入 CSV/JSON，或转换成规范 JSON 后调用 /api/v1/reconcile。
原生资源
| 用途 | 方法与路径 | 权限 | 说明 |
|---|---|---|---|
| 用户与部署上下文 | GET /api/user/info | 已授权用户 | VoAPI v2 响应 envelope 为 {code,data,msg,rid}。 |
| 聚合仪表盘统计 | GET /api/dash/statistics | 已授权用户 | 仅能做聚合核对，不能给出 Request ID 级漏单结论。 |
| Key 模板上下文 | GET /api/keys/template | 已授权用户 | 只提供有限的分组/倍率信息，不等于完整历史定价。 |
本地请求头（示意）
Authorization: $VOAPI_JWT字段映射
映射在 connector/sidecar 或 /api/v1/normalize 中完成。历史记录没有 request_id 时会生成合成 ID，但这不能保证请求级上游匹配。
| 源字段 | 规范字段 | 说明 |
|---|---|---|
statistics interval | period.start / period.end | VoAPI v2 提供的是聚合区间，不是单次请求时间。 |
usedBasicBalance + usedBindBalance | aggregate downstream consumption | 仅作为聚合参考；只有取得可靠的源导出时，才能在本地转换为规范请求记录。 |
key template group | pricing metadata | 只提供有限的分组/倍率上下文，不是历史价格快照。 |
已知限制
- 已验证的 v2 用量接口为聚合级，无法提供精确对账所需的请求、模型、渠道和 Token 分类。
- VoAPI v2 与旧 One/New API 协议不同，鉴权和响应 envelope 均不能混用。
- 获得版本化导出契约前，请用去敏规范 CSV/JSON 做 Request ID 级对账。
结论：VoAPI v2 可做聚合级本地读取；Request ID 级精确对账当前只支持规范 CSV/JSON 文件导入。