请求约定

查询字符串

GET 使用查询参数传递设备、通道等资源标识以及筛选条件；列表接口按契约接收 keyword、page、pageSize 和 status。每个接口只接受其参数表中声明的字段。查询键不能重复或为空，空格编码为 %20，解析一次后按 RFC 3986 重新编码并排序。

请求体

• GET 请求不得携带 Body、Content-Type 或 Content-Encoding。
• 写操作统一使用 POST 和 application/json，设备、通道、会话等标识与业务参数放在同一个 JSON 对象中。
• 拒绝未知字段和重复 JSON 字段，必填字段见各接口参数表。
• 禁止 Chunked Transfer-Encoding 和压缩请求体。

幂等

标注“幂等键：必需”的写操作必须携带 Idempotency-Key，并将它放入 Canonical Request 第 10 行。

• 相同 Key 和相同命令返回同一个操作结果。
• 相同 Key 和不同命令返回 409 CONFLICT。
• 超时后是否重试由调用方决定，不能自动更换业务命令。

传输协议

平台不会在应用层强制 HTTPS。HTTP 或 HTTPS 由部署环境决定；生产环境应依据网络边界和反向代理策略配置传输安全。