统计接口

更新时间:
复制 MD 格式

响应至少提供一个非空 ID,另一个可缺省、null 或空字符串;两个都有时必须属于同一用户。只有三方 ID 时由办公侧在当前组织内映射;未绑定用户必须返回内部 ID。

客户应固定使用一种账本主键,不按绑定状态自动切换,绑定/解绑不应重置用量或额度。

统计以已完成的数据日期 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,不悄悄修改页号或页大小。同值以固定选择的 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"
}

字段

类型

要求

rows

array

无结果为 [];不得为 null

rows[].qw_user_id / rows[].external_user_id

string 或 null

至少一个非空;内部 ID 必须属于当前组织,三方 ID 按 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

已绑定用户保留上述三方 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 响应继续兼容。

参数

位置

要求

external_user_id

path

第三方用户 ID,作为单个路径段进行 URL 编码

qw_user_id

query

当前组织内部用户 UUID,办公侧始终提供

ds

query

查询结束日期

days

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,不自动改查最新日期。当前身份已解绑或成员已移除时,不推断历史账户归属。