额度接口

更新时间:
复制 MD 格式

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

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

企业额度系统是已应用限额与已用量的权威。千问办公设置成员的绝对限额,企业系统负责执行该限额并返回真实结果。

单位与有效期

额度接口金额统一使用非负十进制整数字符串,单位为 credit_minor,10000 minor = 1 credit,最大值为 9223372036854775807。不要返回 JSON number、浮点数或负数。

本手册使用一个合成场景:成员限额 500 credit、已用 70 credit、剩余 430 credit,组织总额度 1000 credit。当前产品只能配置整数 credit,最低 500;即使“查询额度规则与周期”接口返回更低的最小限额,也不会放宽产品校验。

validity

expires_at

含义

permanent

null

长期限额配置;仍按计费周期计量

current_cycle

RFC3339 时间

当前周期有效;截止为排他边界

公共 Header 和错误约定见快速开始与错误处理。

查询额度规则与周期

GET /spi/v1/quota/context

无请求体和查询参数。千问办公通过本接口读取可配置范围和当前周期;它不返回实时组织余额。

{
  "organization_id": "11111111-1111-4111-8111-111111111111",
  "unit": "credit_minor",
  "scale": 10000,
  "minimum_allowance": "0",
  "maximum_allowance": "100000000",
  "cycle_id": "2026-09",
  "cycle_start": "2026-09-01T00:00:00+08:00",
  "cycle_end": "2026-10-01T00:00:00+08:00",
  "metering_mode": "periodic_ceiling",
  "updated_at": "2026-09-18T03:00:00+08:00"
}

字段

类型

要求

organization_id

string

与请求组织完全一致

unit / scale

string / integer

固定 credit_minor / 10000

minimum_allowance

string

可接受的最小限额

maximum_allowance

string 或 null

不小于 minimum;null 表示没有已知配置上限,不表示成员无限额度

cycle_id

string

当前周期的非空标识

cycle_start / cycle_end

RFC3339 string

起始包含、截止不包含;end 严格晚于 start

metering_mode

string

固定 periodic_ceiling

updated_at

RFC3339 string

额度上下文更新时间

上表字段均应提供,仅 maximum_allowance 可为 null。没有周期或限额执行能力时,不应启用整组扩展。

查询成员额度

POST /spi/v1/quota/users/query
Content-Type: application/json

这是只读 POST。请求包含 1–200 个不重复的内部用户 ID。qw_user_ids 与 external_user_ids 等长、按索引对应;未绑定位置用空字符串占位,不可压缩数组。

兼容旧请求只提供非空且不重复的 external_user_ids。响应仍须按请求次序逐个返回,每项至少一个 ID 与该位置的请求用户匹配,不可漏项。

{
  "qw_user_ids": [
    "22222222-2222-4222-8222-222222222222"
  ],
  "external_user_ids": [
    "employee-1001"
  ]
}

HTTP 200:

{
  "organization_id": "11111111-1111-4111-8111-111111111111",
  "items": [
    {
      "qw_user_id": "22222222-2222-4222-8222-222222222222",
      "external_user_id": "employee-1001",
      "status": "applied",
      "binding_id": "quota-binding-01",
      "applied_revision": 13,
      "allowance": "5000000",
      "used": "700000",
      "remaining": "4300000",
      "validity": "current_cycle",
      "cycle_id": "2026-09",
      "expires_at": "2026-10-01T00:00:00+08:00",
      "updated_at": "2026-09-18T03:00:00+08:00",
      "error_code": null
    }
  ]
}

字段

类型

applied 时的要求

qw_user_id / external_user_id

string 或 null

至少一个非空;每个提供的 ID 都必须匹配对应请求用户

status

string

applied、not_configured 或 not_found

binding_id

string

非空,来自已应用的“设置成员限额”请求

applied_revision

integer

已应用 revision,必须大于 0

allowance / used / remaining

string

真实限额、已用、剩余,均为 minor

validity / cycle_id

string

有效期类型与非空周期 ID

expires_at

string 或 null

与有效期类型一致

updated_at

RFC3339 string

实际额度更新时间

error_code

null

成功项不得携带错误码

尚无配置时明确返回空值:

{
  "organization_id": "11111111-1111-4111-8111-111111111111",
  "items": [
    {
      "qw_user_id": "22222222-2222-4222-8222-222222222222",
      "external_user_id": "employee-1001",
      "status": "not_configured",
      "binding_id": null,
      "applied_revision": null,
      "allowance": null,
      "used": null,
      "remaining": null,
      "validity": null,
      "cycle_id": null,
      "expires_at": null,
      "updated_at": null,
      "error_code": null
    }
  ]
}

用户不存在时使用 not_found,同样不返回伪造的零额度。组织授权失败必须返回 HTTP 403。队列中尚未执行的目标 revision 不得返回为 applied。

当前 SDK 提供显式查询能力,产品额度派发不强制调用“查询成员额度”接口进行写后回读;也不要把本地配置或派发确认当成实时查询结果。

设置成员限额

PUT /spi/v1/quota/users
Content-Type: application/json
Idempotency-Key: spi-demo-quota-13

每次请求只包含一个成员。千问办公在后台派发额度变更,失败后按已有机制重试;这不是充值请求,不能将 allowance 累加到旧额度或清零已用量。

完整请求示例(沿用快速开始中的终端变量;仅对测试成员执行):

curl --fail-with-body --max-time 10 -X PUT \
  "${SPI_BASE_URL%/}/spi/v1/quota/users" \
  -H "Authorization: Bearer ${SPI_TOKEN}" \
  -H "X-QwenWork-Organization-Id: ${SPI_ORG_ID}" \
  -H 'X-QwenWork-Request-Id: spi-demo-set-member-quota' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: spi-demo-quota-13' \
  --data '{
  "binding_id": "quota-binding-01",
  "items": [
    {
      "qw_user_id": "22222222-2222-4222-8222-222222222222",
      "external_user_id": "employee-1001",
      "desired_revision": 13,
      "allowance": "5000000",
      "validity": "current_cycle",
      "cycle_id": "2026-09",
      "expires_at": "2026-10-01T00:00:00+08:00"
    }
  ]
}'

请求字段

类型

要求

binding_id

string

非空绑定标识,由调用方提供,原样回显

items

array

恰好一项

items[].qw_user_id

string

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

items[].external_user_id

string

保留原三方 ID;未绑定时为空字符串

items[].desired_revision

integer

大于 0 的目标版本

items[].allowance

string

绝对限额,minor 单位

items[].validity

string

permanent 或 current_cycle

items[].cycle_id

string

本次额度周期

items[].expires_at

string 或 null

permanent 为 null;current_cycle 为截止时间

HTTP 200 必须返回查询成员额度的 applied 响应,其中组织、用户、binding、revision、allowance、validity、cycle_id、expires_at 与本次写入一致。

上面“查询成员额度”的成功示例即为本次写入的确认结果;企业服务必须已应用且可回读后才返回成功。

相同组织和相同写入意图的重试使用相同幂等键。企业服务应避免重复执行同一写入,不能把重复请求当作新增充值。千问办公不承诺 exactly-once 或跨系统事务;超时不代表企业服务未执行。未匹配的确认响应会被视为失败,继续走现有重试流程。

升级后的请求新增内部 ID,若旧版本已应用同一 revision 但响应丢失,企业服务可能返回 HTTP 409 和 code=revision_conflict。

办公侧仅在这个明确错误下执行一次“查询成员额度”,完整核对身份、binding、revision、金额、周期、有效期与到期时间;全部一致才确认已生效,不再写入。

查询失败或不一致仍报错;其他错误不自动降级、不通过移除内部 ID 重试。

查询组织额度

GET /spi/v1/quota/org

无请求体、无查询参数,不需要成员身份映射。千问办公查询组织额度时读取本接口,不从成员额度或历史统计推算。

{
  "organization_id": "11111111-1111-4111-8111-111111111111",
  "allowance": "10000000",
  "used": "700000"
}

三个字段均必填;组织必须匹配请求,allowance 和 used 为 minor 整数字符串。示例表示组织总额度 1000 credit、已用 70 credit。允许 used 超过 allowance,以表达真实超用;未知值必须报错,不可返回 null、缺失字段或伪造 0。

“查询组织额度”返回实时数据,查询组织用量概览 返回历史日期快照,两者不要求在不同时间读到同一个值。接口返回 404 不会被当作扩展关闭,也不会自动回退为默认额度。