1. 准备连接信息

信息	要求
服务地址	例如 `https://spi.example.com/adapter`；从千问办公 Biz 服务所在网络可达
SPI Token	企业服务签发的独立 Bearer Token，与模型 Key、开放平台 Key 分开
组织 ID	千问办公组织 UUID，并在企业服务绑定到正确账本租户
测试用户	IAM 已绑定的第三方用户 ID，企业系统中也能识别
数据与周期	明确可读取的完整统计日期、计费周期及测试额度

配置的是服务地址前缀，千问办公会在其后追加 /spi/v1/...。填写 https://spi.example.com/adapter 时，“获取最新统计日期”接口的实际调用地址是 https://spi.example.com/adapter/spi/v1/usage/meta；不要再次填写 /spi/v1。

允许 HTTP/HTTPS、域名、IPv4、方括号包围的 IPv6、自定义端口和路径前缀。地址不得含用户名密码、query、fragment、空白或无效端口。HTTP 会明文传输 Token，仅用于可信内网；HTTPS 校验系统信任证书及域名/IP，不支持跳过校验。服务必须直接响应，不依赖重定向。

2. 实现公共请求与响应

Header	必需	接收方处理
`Authorization: Bearer <SPI_TOKEN>`	是	校验凭据，并核对它是否允许访问请求组织
`X-QwenWork-Organization-Id`	是	千问办公组织 UUID；不要直接当成企业账本 ID
`X-QwenWork-Request-Id`	是	记录用于诊断；不是用户身份或幂等键
`Accept: application/json`	是	返回 JSON
`Content-Type: application/json`	有 JSON 请求体时	按 UTF-8 JSON 解析
`Idempotency-Key`	设置成员限额时	相同写入重试的关联键，见额度写入
`traceparent`	可选	链路追踪

不能仅信任组织 Header；必须验证 Token 对该组织的授权。成员 ID 使用第三方身份，不能用姓名、邮箱或内部 UUID 替代。

响应约定

成功固定为 HTTP 200 和规定的 JSON 对象，不额外套 data，不返回 204 或 HTML。空集合为 []；可空未知值为 null，不能伪造为 0。失败使用非 200 状态，详见错误处理。

限额与统计SPI 调用默认超时 10 秒、成功响应上限 1 MiB、错误体上限 32 KiB。SDK 不自动重试 GET，后台任务沿用自身重试预算。手动连通性检测是单独的 5 秒请求。

3. 发起首次只读请求

将真实 Token 通过终端会话的安全方式注入 SPI_TOKEN，不要把它写入文档或提交到代码仓库。设置其余测试参数：

export SPI_BASE_URL='https://spi.example.com/adapter'
export SPI_ORG_ID='11111111-1111-4111-8111-111111111111'

调用获取最新统计日期：

curl --fail-with-body --max-time 10 \
  "${SPI_BASE_URL%/}/spi/v1/usage/meta" \
  -H "Authorization: Bearer ${SPI_TOKEN}" \
  -H "X-QwenWork-Organization-Id: ${SPI_ORG_ID}" \
  -H 'X-QwenWork-Request-Id: spi-demo-usage-meta' \
  -H 'Accept: application/json'

预期 HTTP 200：

{"ds":"2026-09-17"}

这个日期表示五个统计周期、组织概览和全部成员分页已经完整可查。尚无完整数据时返回 {"ds":null}。示例日期仅用于演示，不要在生产接口固定返回它。

4. 在控制台配置

使用具有 SPI 管理权限的管理员账号，进入“开放平台 → 扩展配置 → BYOK限额和统计”。
填写服务地址和 Token。首次启用必须提供 Token；已保存后输入框不回显，留空沿用现有值，修改地址也可沿用。
点击“检测连通性”。请求从 Biz 服务发出，即使扩展关闭或草稿尚未保存也能检测。
按下一节完成联调，再由管理员保存并启用整组扩展。

检测只确认“获取最新统计日期”接口返回 HTTP 200，不校验响应 JSON，也不调用其他七个接口。检测成功不保存配置、不启动统计同步；保存和启用也不以检测成功为前置条件。

5. 按顺序完成业务联调

顺序	操作	通过标准
1	校验组织、测试用户及凭据	错误 Token、越权组织被拒绝；用户与 IAM 绑定一致
2	查询额度规则、当前周期和组织额度	周期有效；组织一致；额度单位与类型正确
3	在测试组织设置 500 credit 成员限额	“设置成员限额”接口收到 `"5000000"`，确认响应完整匹配请求
4	模型侧产生测试消费	使用同一第三方身份计量，限额修改不清零已用量
5	完成一个新的统计日期	发布 ds 前，组织用量概览和成员用量列表的五周期数据完整且合计一致
6	完成办公侧统计刷新并查询成员每日用量趋势	页面日期正确；组织、成员、每日趋势口径一致

关闭扩展会暂停相关额度派发；启用后通过原后台任务自动同步。已发布统计按日期刷新，关闭或换址不会重写同日快照。各项失败的判断方式见联调验收与排障。

快速开始