01 / AUTH
快连接入的鉴权方式与凭证管理
鉴权凭证在控制台「开发者」页签下按应用生成，一个应用对应一个凭证，凭证可随时吊销。
curl -sS -X POST "https://api.kuialaian.com.cn/v1/auth/token" \
-H "Content-Type: application/json" \
-d '{
"app_id": "kl_app_erpbatch",
"app_secret": "6f0a1c93de5b47a8",
"grant_type": "client_credentials"
}'- 令牌有效期 2 小时，过期后重新换取，旧令牌在过期后 5 分钟内仍可被接受以容忍时钟偏差。
- 每个应用凭证的调用频率上限为 120 次每分钟，超限返回 HTTP 429 与错误码
KL_RATE_LIMITED。 - 令牌在控制台可查看最近 3 次使用时间，异常调用会触发一次通知邮件。
- 令牌签发记录按应用保留 30 天数据，可用统计视图核对测试阶段与生产阶段的调用场景分布。
02 / API
快连接入对接接口清单
共 4 个接口，路径前缀均为 /v1，请求与响应均为 JSON 格式，字段命名使用下划线风格。
接口参数
| 接口 | 方法 | 路径 | 关键参数 |
|---|---|---|---|
| 鉴权换取令牌 | POST | /v1/auth/token | app_id / app_secret / grant_type |
| 设备批量下发 | POST | /v1/devices/batch | template_id / device_count / concurrency |
| 用量查询 | GET | /v1/usage/summary | period / group / format |
| 工单创建 | POST | /v1/tickets | subject / priority / device_ids |
03 / EXAMPLE
快连接入的三个调用示例
示例中的应用编号、批次编号与设备指纹均为演示格式，替换为自有值后即可联调。
curl -sS -X POST "https://api.kuialaian.com.cn/v1/devices/batch" \
-H "Authorization: Bearer kl_e_9f2c7a41b6d84e0fa3c5" \
-H "Content-Type: application/json" \
-d '{
"batch_id": "bt-20261023-0917",
"template_id": "tpl-hq-eu-03",
"device_count": 200,
"concurrency": 200,
"rollout": "canary",
"canary_ratio": 10
}'import requests
TOKEN = "kl_e_9f2c7a41b6d84e0fa3c5"
resp = requests.get(
"https://api.kuialaian.com.cn/v1/usage/summary",
headers={"Authorization": f"Bearer {TOKEN}"},
params={"period": "2026-10", "group": "shanghai-office", "format": "json"},
timeout=15,
)
data = resp.json()
print(data["device_count"], data["traffic_gb"], data["billing_cycle_days"])curl -sS -X POST "https://api.kuialaian.com.cn/v1/tickets" \
-H "Authorization: Bearer kl_e_9f2c7a41b6d84e0fa3c5" \
-H "Content-Type: application/json" \
-d '{
"subject": "eu-line-el01-delay",
"priority": "high",
"device_ids": ["dev-8f31a0c2", "dev-2b7de419"],
"remark": "EL-01 延迟均值 186 毫秒之外还有 3 台设备超过 400 毫秒"
}'示例中的字段口径与官方文档 v4.2.0 版本的参数表一致，返回结果以统计数据形式呈现，可直接用于与控制台页面比对。
04 / PARAMS
快连接入设备下发接口字段说明
字段说明以官方文档 v4.2.0 版本的参数表为准，未列出的字段会被服务端忽略但仍返回 200 状态。
下发接口参数表
| 参数 | 类型 | 必填 | 约束与说明 |
|---|---|---|---|
| batch_id | string | 是 | 批次唯一编号，建议包含日期，长度不超过 32 个字符 |
| template_id | string | 是 | 必须引用已发布状态的模板 |
| device_count | number | 是 | 本次下发设备数量，最大 200 |
| concurrency | number | 否 | 并发数，最大 200，缺省按设备数量的 1/4 计算 |
| rollout | enum | 否 | canary 或 full，默认 canary |
| canary_ratio | number | 否 | 灰度比例，取 5、10 或 25 |
| policy.fail_threshold | number | 否 | 失败台数阈值，缺省 3 |
| policy.auto_rollback | boolean | 否 | 是否自动回滚，默认 true |
05 / ERRORS
快连接入的常见错误码
错误响应体包含 code、message 与 request_id 三个字段，request_id 可直接提交工单用于排查。
错误码对照
| 错误码 | HTTP 状态 | 含义 | 处理建议 |
|---|---|---|---|
| KL_RATE_LIMITED | 429 | 超过 120 次每分钟频率上限 | 退避 30 秒后重试 |
| KL_TEMPLATE_NOT_FOUND | 404 | 模板编号不存在 | 核对模板是否已发布 |
| KL_DEVICE_OFFLINE | 409 | 存在离线的目标设备 | 先在台账中剔除离线设备 |
| KL_CONCURRENCY_EXCEEDED | 400 | 并发数超过 200 | 按分组拆分后重新提交 |
| KL_SCOPE_MISSING | 403 | 凭证缺少设备下发权限 | 在控制台为应用补授权限 |
| KL_BILLING_LOCKED | 423 | 账期存在未结费用 | 先完成 30 天账期结算 |
错误码表中的状态码依据服务端校验逻辑统计，实测触发 120 次每分钟限流时返回 429 状态，与文档版本 v4.2.0 的行为一致。
06 / SSO
快连接入身份系统的两个方案
SSO 与接口鉴权互相独立：接口走应用凭证，人员登录走企业身份系统。
SSO 方案
| 方案 | 协议 | 配置项 | 生效方式 |
|---|---|---|---|
| 方案 A | SAML 2.0 | Entity ID 与证书 | 保存后 15 分钟内生效 |
| 方案 B | OIDC | Issuer 与 Client ID | 保存后 15 分钟内生效 |
SCIM 用户同步按 15 分钟一次执行，同步后的账号立即出现在设备台账中，成员退订释放的席位在下一个账期计算时不再计入。
07 / LINK
快连接入相关页面继续阅读
接口跑通之后，建议对照台账字段与计费口径再做一次自检。