响应至少提供一个非空 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 | 含义 |
|
| 长期限额配置;仍按计费周期计量 |
| 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"
}
字段 | 类型 | 要求 |
| string | 与请求组织完全一致 |
| string / integer | 固定 |
| string | 可接受的最小限额 |
| string 或 null | 不小于 minimum;null 表示没有已知配置上限,不表示成员无限额度 |
| string | 当前周期的非空标识 |
| RFC3339 string | 起始包含、截止不包含;end 严格晚于 start |
| string | 固定 |
| 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 时的要求 |
| string 或 null | 至少一个非空;每个提供的 ID 都必须匹配对应请求用户 |
| string |
|
| string | 非空,来自已应用的“设置成员限额”请求 |
| integer | 已应用 revision,必须大于 0 |
| string | 真实限额、已用、剩余,均为 minor |
| string | 有效期类型与非空周期 ID |
| string 或 null | 与有效期类型一致 |
| RFC3339 string | 实际额度更新时间 |
| 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"
}
]
}'
请求字段 | 类型 | 要求 |
| string | 非空绑定标识,由调用方提供,原样回显 |
| array | 恰好一项 |
| string | 当前组织的内部用户 UUID,办公侧始终提供 |
| string | 保留原三方 ID;未绑定时为空字符串 |
| integer | 大于 0 的目标版本 |
| string | 绝对限额,minor 单位 |
| string |
|
| string | 本次额度周期 |
| 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 不会被当作扩展关闭,也不会自动回退为默认额度。