请求与响应
请求地址
| 当前环境 | API Base URL |
|---|---|
| 测试环境 | https://b.t.robot-daily.com |
text
{API_BASE_URL}{完整 Path}
例如：https://api.example.com/api/v1/open/viewers/upserthttps://api.example.com 是占位示例，请替换为部署方提供的当前环境 API Origin。所有接口使用 HTTPS、POST、UTF-8 JSON；不带 URL 查询参数，不在 Path 后添加 /，也不对 Path 做百分号编码。
公共请求头
| 请求头 | 必填 | 格式 |
|---|---|---|
Content-Type | 是 | application/json |
X-API-Key | 是 | 当前商户有效的 API Key |
X-Timestamp | 是 | Unix 时间戳，单位秒，十进制字符串；不是毫秒 |
X-Nonce | 是 | 每次请求新生成，16–128 字符，只含 A-Z a-z 0-9 _ -；推荐 16 个随机字节的 32 位 hex |
X-Signature | 是 | HMAC-SHA256 结果，64 位小写 hex；见 签名算法 |
每个签名头只能出现一次。请求体不压缩，Content-Encoding 省略或为 identity。API Key 自带商户身份，不传 X-Tenant-ID，无需 Cookie 或 Authorization。
当前示例配置允许时间偏差 ±300 秒、请求体最多 1 MiB；这些是可配置值，实际环境以部署方约定为准。调用服务器应同步时钟。
参数约定
- JSON 字段名区分大小写，不允许额外未知字段，且请求体只能包含一个 JSON 对象。
integer是 JSON 非负整数；UID 目前为 10000–9999999，可安全作为 JavaScript 数字使用。- 时长单位为秒，时间字符串为 UTC RFC3339（
2026-10-12T08:00:00Z）。 - 参数表中的「必填」按 HTTP 实际校验标注。观看查询的
playbackMode、明细的sort和pageSize必须显式填写，不能依赖默认值。 null、省略与空字符串可能有不同含义，具体看对应字段。响应「始终返回：否」表示字段可能省略，不保证返回 null。
成功响应
HTTP 200，格式为：
json
{"requestId":"req-example","data":{"viewer":{"uid":10000,"externalUserId":"customer-10001","phone":null,"displayName":"张三"},"created":true}}没有统一的 code: 0 或 success: true。业务结果在 data；各页分别说明内部结构。
错误响应
使用非 2xx HTTP 状态，通常为 JSON：
json
{"requestId":"req-example","error":{"code":"OPEN_API_UNAUTHORIZED","message":"Open API 认证失败"}}error.details 是可选附加信息。程序判断 error.code，不要依赖中文 message。代理、TLS 或网络错误也可能没有 JSON 响应。
错误码与排查 提供处理建议。任何重试都需要新的 timestamp、nonce 和签名；网络超时不代表业务未执行。