响应至少提供一个非空 ID,另一个可缺省、null 或空字符串;两个都有时必须属于同一用户。只有三方 ID 时由办公侧在当前组织内映射;未绑定用户必须返回内部 ID。
客户应固定使用一种账本主键,不按绑定状态自动切换,绑定/解绑不应重置用量或额度。
统计以已完成的数据日期 ds 为基准。先准备好该日期的全部数据,再通过“获取最新统计日期”接口发布日期;千问办公读取组织概览和全部成员分页,校验通过后才发布本地快照。
日期、周期与金额
参数或字段 | 约定 |
|
|
|
|
| ds 所在计费周期开始日至 ds |
| 含 ds 在内的最近 7 / 30 个自然日 |
| ds 所在月月初至 ds |
| ds 上一个完整自然月 |
| 必须等于请求 ds,是日期,不是 RFC3339 时间戳 |
用量及余额 | credit 主单位的 JSON number,非负,最多四位小数 |
比率 | 百分点; |
五个周期都必须支持,日期起止均包含。每天已知无消费返回 0;未知值仅在允许可空的字段返回 null,不得把未完成数据填成零。组织总量、成员合计和每日趋势应使用同一口径。
所有请求携带公共 Header。下列 JSON 是完整成功示例;同一日期只有一个测试成员,最近 7 天每天消费 10 credit,共 70 credit。
获取最新统计日期
GET /spi/v1/usage/meta
无请求体和查询参数。HTTP 200:
{
"ds": "2026-09-17"
}
只有五个周期的组织用量概览和成员用量列表全部分页均可读取,才返回该日期。没有完整数据时返回 {"ds":null},不要默认填今天。
统计调度默认北京时间 04:00 加安装级稳定错峰 0–1 小时;落后 T-1 时默认再等一小时重试一次。应与交付方确认数据就绪时间。办公页面显示的是本地已成功发布的日期,不一定等于本接口刚返回的日期。
查询组织用量概览
GET /spi/v1/usage/overview?ds=2026-09-17&period=7d
参数 | 类型 | 要求 |
| string | 必填,已发布的数据日期 |
| string | 必填, |
HTTP 200:
{
"qw_org_id": "11111111-1111-4111-8111-111111111111",
"ds": "2026-09-17",
"subscribed": true,
"period": {
"key": "7d",
"label": "最近7天",
"start_date": "2026-09-11",
"end_date": "2026-09-17",
"days": 7
},
"metrics": {
"total_credits_used": 70,
"daily_average_credits": 10,
"active_member_count": 1,
"seat_count": 10,
"active_member_rate": 10
},
"quota_snapshot": {
"remaining_credits": 930,
"cycle_start_date": "2026-09-01",
"cycle_end_date": "2026-09-30",
"next_reset_date": "2026-10-01"
},
"daily_trend": [
{
"date": "2026-09-11",
"credits": 10
},
{
"date": "2026-09-12",
"credits": 10
},
{
"date": "2026-09-13",
"credits": 10
},
{
"date": "2026-09-14",
"credits": 10
},
{
"date": "2026-09-15",
"credits": 10
},
{
"date": "2026-09-16",
"credits": 10
},
{
"date": "2026-09-17",
"credits": 10
}
],
"last_data_update_time": "2026-09-17",
"timezone": "Asia/Shanghai",
"retention_days": 90
}
字段 | 类型 | 要求 |
| string | 请求中的千问办公组织 UUID,不是企业账本租户 ID |
| date string | 均与请求 ds 一致 |
| boolean | 有效 BYOK 数据必须为 true,表示统计可用;不要求购买模型套餐 |
| object | key 匹配请求;起止与周期一致;days 为实际天数 |
| number | 等于该周期成员用量及每日用量的合计 |
| number | 总量除以 days |
| integer | 周期内有消费的去重人数 |
| integer | 统计人数基数,不赋予办公席位 |
| number 或 null | active / seat × 100;seat 为 0 时为 null |
| number 或 null | ds 时点的周期剩余额度,未知可为 null |
| date string | ds 所在计费周期的完整起止日期,均包含 |
| date string 或 null | 下一重置日期;未知为 null |
| array | 日期升序、不重复,完整覆盖所选周期 |
| string / integer | 固定时区;正整数保留天数,与实际服务约定一致 |
纯按量系统无法提供余额或下一重置日时保留 null;没有计费周期时,接入时约定自然月并提供真实周期起止。不要用查询时的实时余额填历史 quota_snapshot;实时组织额度使用 查询组织额度。90 天是示例及建议值,不是平台替企业承诺的保留期。
查询成员用量列表
GET /spi/v1/usage/members?ds=2026-09-17&period=7d&page_no=1&page_size=200&sort=used_credits&order=desc
参数 | 类型 | 约束 |
| string | 与“查询组织用量概览”接口一致 |
| integer | 从 1 开始 |
| integer | 1–200 |
| string |
|
| string |
|
| 可选 string | 最长 200 字符,不含控制字符 |
参数错误返回 HTTP 400,不悄悄修改页号或页大小。同值以固定选择的 qw_user_id 或 external_user_id 保持稳定次序,null 最后。
{
"rows": [
{
"qw_user_id": "22222222-2222-4222-8222-222222222222",
"external_user_id": "employee-1001",
"user_name": "示例成员",
"used_credits": 70,
"cycle_used_credits": 70,
"cycle_quota_credits": 500,
"quota_usage_rate": 14,
"last_used_at": "2026-09-17T16:00:00+08:00",
"status": "active",
"avatar": null
}
],
"total": 1,
"page_no": 1,
"page_size": 200,
"has_more": false,
"next_reset_date": "2026-10-01",
"last_data_update_time": "2026-09-17"
}
字段 | 类型 | 要求 |
| array | 无结果为 [];不得为 null |
| string 或 null | 至少一个非空;内部 ID 必须属于当前组织,三方 ID 按 IAM 当前绑定映射,双 ID 必须一致 |
| number | 请求 period 内的消费 |
| number | ds 所在计费周期起始日至 ds 的消费,与请求 period 无关 |
| number 或 null | ds 所在周期限额,未知为 null |
| number 或 null | 周期已用 / 周期限额 × 100;可超过 100;限额为 0 或未知时为 null |
| string 或 null | 建议 RFC3339;无使用记录时为 null |
| string 或 null | 补充信息;办公展示身份与部门优先使用 IAM 快照 |
| integer | 当前筛选条件下的完整去重人数 |
| integer | 与请求一致 |
| boolean | 与页号、行数和 total 一致 |
| date string 或 null | 下一重置日 |
| date string | 等于请求 ds |
同一个 ds 的分页必须稳定:非末页不能短页,不能跨页重复用户或改变 total。千问办公会读取全部页,不只导入前 200 人;重复、遗漏、无法解析的身份或组织不匹配会导致整批失败,保留原已发布快照。
查询成员每日用量趋势
GET /spi/v1/usage/members/employee-1001/trend?ds=2026-09-17&days=3
已绑定用户保留上述三方 ID 路径,并额外携带 qw_user_id query。
未绑定用户使用 GET /spi/v1/usage/members/trend?qw_user_id=22222222-2222-4222-8222-222222222222&ds=2026-09-17&days=3;不把内部 ID 填入三方 ID 路径。
旧客户的三方 ID 路径及仅三方 ID 响应继续兼容。
参数 | 位置 | 要求 |
| path | 第三方用户 ID,作为单个路径段进行 URL 编码 |
| query | 当前组织内部用户 UUID,办公侧始终提供 |
| query | 查询结束日期 |
| query | 整数,1–30 |
{
"qw_user_id": "22222222-2222-4222-8222-222222222222",
"external_user_id": "employee-1001",
"user_name": "示例成员",
"start_date": "2026-09-15",
"end_date": "2026-09-17",
"points": [
{
"date": "2026-09-15",
"credits": 10
},
{
"date": "2026-09-16",
"credits": 10
},
{
"date": "2026-09-17",
"credits": 10
}
],
"last_data_update_time": "2026-09-17"
}
响应至少一个 ID 必须匹配请求,两个都有时分别校验;start_date 为 ds-(days-1),end_date 和 last_data_update_time 均为 ds。
points 连续、升序、恰好 days 条,credits 为非负 credit 数字;姓名为可空补充字段。
成员每日用量趋势按需读取,企业服务至少需保留办公侧仍展示的两个已发布批次对应的趋势数据。过期数据返回 snapshot_not_found,不自动改查最新日期。当前身份已解绑或成员已移除时,不推断历史账户归属。