统计接口

统计以已完成的数据日期 ds 为基准。先准备好该日期的全部数据，再通过“获取最新统计日期”接口发布日期；千问办公读取组织概览和全部成员分页，校验通过后才发布本地快照。

日期、周期与金额

参数或字段	约定
`ds`	`YYYY-MM-DD`，已完成且不可变的数据日期
`timezone`	`Asia/Shanghai`
`period=cycle`	ds 所在计费周期开始日至 ds
`period=7d` / `30d`	含 ds 在内的最近 7 / 30 个自然日
`period=month`	ds 所在月月初至 ds
`period=last_month`	ds 上一个完整自然月
`last_data_update_time`	必须等于请求 ds，是日期，不是 RFC3339 时间戳
用量及余额	credit 主单位的 JSON number，非负，最多四位小数
比率	百分点；`10` 表示 10%，不是 0.1

五个周期都必须支持，日期起止均包含。每天已知无消费返回 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

参数	类型	要求
`ds`	string	必填，已发布的数据日期
`period`	string	必填，`cycle/7d/30d/month/last_month`

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
}

字段	类型	要求
`qw_org_id`	string	请求中的千问办公组织 UUID，不是企业账本租户 ID
`ds` / `last_data_update_time`	date string	均与请求 ds 一致
`subscribed`	boolean	有效 BYOK 数据必须为 true，表示统计可用；不要求购买模型套餐
`period`	object	key 匹配请求；起止与周期一致；days 为实际天数
`metrics.total_credits_used`	number	等于该周期成员用量及每日用量的合计
`metrics.daily_average_credits`	number	总量除以 days
`metrics.active_member_count`	integer	周期内有消费的去重人数
`metrics.seat_count`	integer	统计人数基数，不赋予办公席位
`metrics.active_member_rate`	number 或 null	active / seat × 100；seat 为 0 时为 null
`quota_snapshot.remaining_credits`	number 或 null	ds 时点的周期剩余额度，未知可为 null
`quota_snapshot.cycle_start_date/cycle_end_date`	date string	ds 所在计费周期的完整起止日期，均包含
`quota_snapshot.next_reset_date`	date string 或 null	下一重置日期；未知为 null
`daily_trend`	array	日期升序、不重复，完整覆盖所选周期
`timezone` / `retention_days`	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

参数	类型	约束
`ds` / `period`	string	与“查询组织用量概览”接口一致
`page_no`	integer	从 1 开始
`page_size`	integer	1–200
`sort`	string	`used_credits/quota_usage_rate/last_used_at`
`order`	string	`asc/desc`
`keyword`	可选 string	最长 200 字符，不含控制字符

参数错误返回 HTTP 400，不悄悄修改页号或页大小。同值以 external_user_id 保持稳定次序，null 最后。

{
  "rows":[{
    "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"
}

字段	类型	要求
`rows`	array	无结果为 []；不得为 null
`rows[].external_user_id`	string	IAM 当前绑定的第三方 ID，原样保留大小写和前导零
`rows[].used_credits`	number	请求 period 内的消费
`rows[].cycle_used_credits`	number	ds 所在计费周期起始日至 ds 的消费，与请求 period 无关
`rows[].cycle_quota_credits`	number 或 null	ds 所在周期限额，未知为 null
`rows[].quota_usage_rate`	number 或 null	周期已用 / 周期限额 × 100；可超过 100；限额为 0 或未知时为 null
`rows[].last_used_at`	string 或 null	建议 RFC3339；无使用记录时为 null
`rows[].user_name/status/avatar`	string 或 null	补充信息；办公展示身份与部门优先使用 IAM 快照
`total`	integer	当前筛选条件下的完整去重人数
`page_no/page_size`	integer	与请求一致
`has_more`	boolean	与页号、行数和 total 一致
`next_reset_date`	date string 或 null	下一重置日
`last_data_update_time`	date string	等于请求 ds

同一个 ds 的分页必须稳定：非末页不能短页，不能跨页重复用户或改变 total。千问办公会读取全部页，不只导入前 200 人；重复、遗漏、未绑定身份或组织不匹配会导致整批失败，保留原已发布快照。

查询成员每日用量趋势

GET /spi/v1/usage/members/employee-1001/trend?ds=2026-09-17&days=3

参数	位置	要求
`external_user_id`	path	第三方用户 ID，作为单个路径段进行 URL 编码
`ds`	query	查询结束日期
`days`	query	整数，1–30

{
  "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"
}

响应 external_user_id 必须匹配请求；start_date 为 ds-(days-1)，end_date 和 last_data_update_time 均为 ds。points 连续、升序、恰好 days 条，credits 为非负 credit 数字；姓名为可空补充字段。

成员每日用量趋势按需读取，企业服务至少需保留办公侧仍展示的两个已发布批次对应的趋势数据。过期数据返回 snapshot_not_found，不自动改查最新日期。当前身份已解绑或成员已移除时，不推断历史账户归属。