单位与有效期

额度接口金额统一使用非负十进制整数字符串，单位为 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，响应必须按请求次序逐个返回，不可漏项。

{"external_user_ids":["employee-1001"]}

HTTP 200：

{
  "organization_id":"11111111-1111-4111-8111-111111111111",
  "items":[{
    "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 时的要求
`external_user_id`	string	与对应请求 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":[{
    "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":[{"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[].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 或跨系统事务；超时不代表企业服务未执行。未匹配的确认响应会被视为失败，继续走现有重试流程。

查询组织额度

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 不会被当作扩展关闭，也不会自动回退为默认额度。