# 请求与响应

## 请求地址

| 当前环境 | API Base URL |
|---|---|
| 测试环境 | https://b.t.robot-daily.com |

```text
{API_BASE_URL}{完整 Path}
例如：https://api.example.com/api/v1/open/viewers/upsert
```

`https://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；见 [签名算法](./signature.md) |

每个签名头只能出现一次。请求体不压缩，`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 响应。

[错误码与排查](./errors.md) 提供处理建议。任何重试都需要新的 timestamp、nonce 和签名；网络超时不代表业务未执行。