# 设备端注册、绑定与激活接口说明

更新日期：2026-09-12。

依据原始《AI电话_首次配网注册与激活_完整流程与详细设计(1)》附件 A、B、C、E、I 整理，仅列设备直接调用 SaaS 的 C01～C11。按本次要求省去辅助流程控制字段，不添加原文没有规定的请求或响应字段。

本文件保留字段列表、中文含义、获取来源和示例。服务端已按此接口契约实现，版本为 `ONBOARDING-1.1`，并按本次要求移除三个辅助流程控制字段。实现与验证记录见[接口对齐说明](设备端接口_文档与当前代码差异.md)；线上发布结果另见[发布记录](onboarding-release-20260912.md)。

## 通用规则

- 设备已完成生产登记，持有出厂写入的 `device_id`、32 字节 `device_key`、`key_version`。
- 全部接口使用 POST，正文为 JSON，不带 query 参数；普通报文上限 8 KiB，配置包上限 32 KiB。
- C01 是无可信时间时可通过专用 HTTP 入口调用的校时接口。其余接口使用严格验证证书和主机名的 HTTPS。
- `<…>` 为占位值，必须使用实际返回值或生成值；示例中的编号、版本、时间不是可直接请求线上服务的数据。
- `string` 为字符串，`integer` 为整数，`boolean` 为 true/false，`object` 为 JSON 对象。UUID 按原文为标准 36 字符 UUID v4；Base64URL 无填充编码末尾不带 `=`。
- 版本、计数按原文范围为 0～2147483647，时间为 Unix 毫秒。字段表中的全部输入均为原文必填字段。

### 请求头

C02～C11 使用下列认证头。C01 的设备编号和密钥版本放在正文中，不要求先提交可信时间戳或普通设备请求签名。

| 字段 | 中文含义 | 怎么获得／填写 |
| --- | --- | --- |
| `Content-Type` | 正文格式 | 固定 `application/json`，C01 也使用。 |
| `X-Device-ID` | 生产设备编号 | 从出厂配置读取，例如 `KP01-AABBCCDDEEFF`。 |
| `X-Key-Version` | 设备认证密钥版本 | 从本机已保存凭据读取，十进制填写。 |
| `X-Timestamp-Ms` | 本次发送时间 | C01 验证并校时后，读取当前可信 UTC 毫秒时间。 |
| `X-Nonce` | 本次发送随机数 | 每次 HTTP 发送生成新的 16 字节安全随机数，做 Base64URL 无填充编码。 |
| `X-Request-ID` | 业务请求编号 | 由设备生成 UUID v4；同一次业务操作重试保留，原始正文也保留。 |
| `Authorization` | 设备请求认证码 | 使用本机 `device_key` 计算签名，填写 `Device-HMAC-SHA256 <64位小写十六进制HMAC>`。 |

签名按附件 B 的 DEVREQ1 规则计算，以下 9 行以 LF 连接，末尾不再加换行：

```text
DEVREQ1
<大写HTTP方法>
<实际path>
<device_id>
<key_version十进制>
<timestamp_ms十进制>
<nonce的Base64URL>
<request_id>
<原始请求正文的SHA256小写十六进制>
```

密钥使用原始 32 字节，不发送密钥本身。网络重试更新随机数、发送时间和签名，但不重新生成同一操作的业务编号、按键事件编号或执行编号。

### 普通响应外层

C02～C11 使用此封装，C01 不使用。成功时读取 `data`，失败时读取 `code`、`message`；设备归属和激活结果以业务状态为准。

| 字段 | 类型 | 中文含义 | 来源／怎么用 |
| --- | --- | --- | --- |
| `ok` | boolean | 本次请求是否成功 | 平台生成；不能单独用它判断设备已完成绑定或激活。 |
| `code` | string | 业务结果码 | 平台返回，成功为 `OK`，失败为对应错误码。 |
| `request_id` | string（UUID） | 请求追踪编号 | 平台返回与本次请求关联的编号，供查找请求记录。 |
| `data` | object | 成功业务输出 | 字段按各接口下表读取。 |
| `server_time_ms` | integer | 平台时间 | 平台生成；原文成功响应中提供，不能替代 C01 的首次可信校时。 |
| `message` | string | 错误中文说明 | 失败时由平台提供，便于提示原因。 |

```json
{
  "ok": true,
  "code": "OK",
  "request_id": "<请求UUID>",
  "data": {},
  "server_time_ms": 1789092000000
}
```

失败示例：

```json
{
  "ok": false,
  "code": "CLAIM_EXPIRED",
  "request_id": "<请求UUID>",
  "message": "绑定确认已过期，请重新发起"
}
```

### 公共设备状态 `state`

下表相对于 `data.state`。按本次删减后的口径列出，状态版本、绑定代数和摘要必须来自同一版返回状态。

| 字段 | 类型 | 中文含义 | 来源／后续使用 |
| --- | --- | --- | --- |
| `device_id` | string | 生产设备编号 | 来自平台生产记录，设备与本机编号核对。 |
| `device_revision` | integer | 平台设备状态版本 | 由平台维护；后续用于 C05、C07、C11。 |
| `binding_generation` | integer | 绑定代数 | 平台随绑定关系变化而更新，初始 0，首次绑定后 1；用于防止旧归属信息被继续使用。 |
| `binding_state` | string | 绑定状态 | 平台根据归属关系返回，取值见下表。 |
| `activation_state` | string | 激活状态 | 平台根据激活任务返回，只有 READY 表示服务已就绪。 |
| `state_hash` | string | 本版状态摘要 | 平台按附件 I.1 计算；设备保存该版状态后在 C07 原样回传。 |

| 字段 | 取值及中文含义 |
| --- | --- |
| `binding_state` | `UNBOUND` 未绑定；`CLAIM_PENDING` 等待按键；`BOUND` 已绑定；`TRANSFER_PENDING` 转移处理中。 |
| `activation_state` | `NOT_STARTED` 未开始；`RESERVED` 已预留；`CONTACT_POSSIBLE` 可能已执行；`REGISTERED_OBSERVED` 已确认注册；`READY` 已就绪；`RECONCILE_REQUIRED` 待对账；`BLOCKED` 被阻止。 |

`state_hash` 按原文对以下内容以 LF 连接后计算 SHA256，输出小写十六进制，末尾无换行：

```text
STATE1
<device_id>
<device_revision>
<binding_generation>
<binding_state>
<activation_state>
```

`device_revision` 是平台状态版本，`binding_generation` 是归属代数，`local_generation` 是设备本地保存序号，`config_version` 是激活配置版本；不能互相代填。

## 接口总览

下面路径前统一加 `/api/v1/device`。

| 编号 | POST 路径 | 用途 |
| --- | --- | --- |
| C01 | `/time-challenges` | 校时并获取注册挑战 |
| C02 | `/register` | 认证设备并登记启动 |
| C03 | `/setup-sessions` | 创建设置会话 |
| C04 | `/handoffs` | 获取可交给手机的一次性绑定入口 |
| C05 | `/poll` | 查询状态及命令 |
| C06 | `/claim-confirmations` | 设备按键确认绑定 |
| C07 | `/state-acks` | 确认已保存绑定状态 |
| C08 | `/activation-attempts` | 申请一次 SDK 执行许可 |
| C09 | `/activation-results` | 上报激活执行结果 |
| C10 | `/activation-acks` | 确认激活结果已保存 |
| C11 | `/setup-close` | 记录设置收尾并关闭入口 |

## C01 校时并取得注册挑战

`POST /api/v1/device/time-challenges`

用途：让设备在时钟不正确时先取得可信时间，再使用严格 HTTPS。只返回时间和挑战，不返回用户资料、登录令牌或火山密钥。

### 输入字段

| 字段 | 类型 | 必填 | 中文含义 | 怎么获得／填写 |
| --- | --- | --- | --- | --- |
| `device_id` | string | 是 | 生产设备编号 | 读取出厂配置：`KP01-` 加 12 位大写十六进制 MAC。 |
| `key_version` | integer | 是 | 认证密钥版本 | 读取本机保存的凭据版本，不是密钥内容。 |
| `boot_id` | string（UUID） | 是 | 本次启动编号 | 设备每次启动生成并保留，后续 C02、C03、C05 沿用。 |
| `client_nonce` | string | 是 | 本次校时随机数 | 设备生成 16 字节安全随机数并做 Base64URL 编码，每次校时重试换新值。 |

输入示例：

```json
{
  "device_id": "KP01-AABBCCDDEEFF",
  "key_version": 1,
  "boot_id": "<本次启动UUID>",
  "client_nonce": "<16字节随机数的Base64URL>"
}
```

### 输出字段

下表为校时响应根对象。

| 字段 | 类型 | 中文含义 | 来源／设备怎么用 |
| --- | --- | --- | --- |
| `payload_b64` | string | 校时数据包 | 平台将下方六个字段序列化并编码；设备用原字符串验签后解码。 |
| `mac_hex` | string | 校时数据认证码 | 平台用本设备密钥计算 TIME1 HMAC，设备使用同一密钥验证。 |

输出示例：

```json
{
  "payload_b64": "<校时数据包的Base64URL>",
  "mac_hex": "<64位小写十六进制HMAC>"
}
```

`payload_b64` 验签后解码字段：

| 字段 | 类型 | 中文含义 | 来源／怎么用 |
| --- | --- | --- | --- |
| `device_id` | string | 设备编号回显 | 核对等于本次请求及本机编号。 |
| `boot_id` | string（UUID） | 启动编号回显 | 核对等于设备本次启动编号。 |
| `client_nonce` | string | 随机数回显 | 核对等于本次新请求的随机数。 |
| `challenge_id` | string（UUID） | 注册挑战编号 | 由平台生成并返回，保存后传入 C02。 |
| `server_time_ms` | integer | 经过认证的平台时间 | 平台可信时钟生成；全部校验通过后设置设备时钟。 |
| `expires_at_ms` | integer | 挑战到期时间 | 平台签发时间加 120 秒，到期后重新 C01。 |

```json
{
  "device_id": "KP01-AABBCCDDEEFF",
  "boot_id": "<本次启动UUID>",
  "client_nonce": "<本次请求随机数>",
  "challenge_id": "<注册挑战UUID>",
  "server_time_ms": 1789092000000,
  "expires_at_ms": 1789092120000
}
```

校验公式：`HMAC-SHA256(device_key, UTF8("TIME1\n" + payload_b64))`，其中 `\n` 表示一个 LF 换行。附件 B 要求设备核对全部回显字段、单调计时 RTT 不超过 10 秒、时间不早于固件或已保存可信时间允许的下限；通过后校时，再开始 HTTPS。

## C02 设备认证与启动登记

`POST /api/v1/device/register`

用途：认证已有设备身份并登记本次启动；重复请求不新建设备、不清空既有归属。

### 输入字段

| 字段 | 类型 | 必填 | 中文含义 | 怎么获得／填写 |
| --- | --- | --- | --- | --- |
| `challenge_id` | string（UUID） | 是 | 注册挑战 | 取 C01 验签后解码对象中的 `challenge_id`。 |
| `boot_id` | string（UUID） | 是 | 本次启动编号 | 沿用同一次 C01 的 `boot_id`。 |
| `hardware_model` | string，≤32字节 | 是 | 设备型号 | 从出厂配置读取，按真实型号填写。 |
| `hardware_revision` | string，≤16字节 | 是 | 硬件版本 | 读取出厂记录的硬件修订号。 |
| `firmware_version` | string，≤32字节 | 是 | 固件版本 | 读取设备当前实际运行的固件版本。 |
| `sdk_version` | string，≤64字节 | 是 | SDK版本 | 读取设备实际集成的 SDK 版本信息。 |

输入示例：

```json
{
  "challenge_id": "<C01挑战UUID>",
  "boot_id": "<本次启动UUID>",
  "hardware_model": "KP01",
  "hardware_revision": "A1",
  "firmware_version": "1.0.0",
  "sdk_version": "1.0.0"
}
```

### 输出字段

下表字段位于普通响应的 `data` 中。

| 字段 | 类型 | 中文含义 | 来源／设备怎么用 |
| --- | --- | --- | --- |
| `state` | object | 当前设备状态 | 平台返回已有记录的最新状态，完整字段见公共状态表。 |
| `contract_version` | string | 协议版本 | 原文规定 `ONBOARDING-1.1`；用于确认两侧接口口径。 |

输出示例：

```json
{
  "state": {
    "device_id": "KP01-AABBCCDDEEFF",
    "device_revision": 3,
    "binding_generation": 0,
    "binding_state": "UNBOUND",
    "activation_state": "NOT_STARTED",
    "state_hash": "<本版状态SHA256摘要>"
  },
  "contract_version": "ONBOARDING-1.1"
}
```

## C03 创建设置会话

`POST /api/v1/device/setup-sessions`

用途：为本次设置建立平台会话；已绑定设备可恢复上下文，但不能借此重新认领。

### 输入字段

| 字段 | 类型 | 必填 | 中文含义 | 怎么获得／填写 |
| --- | --- | --- | --- | --- |
| `boot_id` | string（UUID） | 是 | 本次启动编号 | 沿用已完成 C02 的启动编号。 |
| `local_setup_id` | string（UUID） | 是 | 本地设置编号 | 设备为本次设置流程生成；重试和 C04 沿用。 |
| `transport_profile` | string | 是 | 本地交互方式 | 按原文固定传 `LOCAL_WEB`。 |

输入示例：

```json
{
  "boot_id": "<本次启动UUID>",
  "local_setup_id": "<设备生成的本地设置UUID>",
  "transport_profile": "LOCAL_WEB"
}
```

### 输出字段

下表字段位于普通响应的 `data` 中。

| 字段 | 类型 | 中文含义 | 来源／设备怎么用 |
| --- | --- | --- | --- |
| `setup_id` | string（UUID） | 平台设置会话编号 | 平台生成，后续传 C04、C05、C11；不同于设备生成的 local_setup_id。 |
| `expires_at_ms` | integer | 设置会话到期时间 | 平台生成；默认 15 分钟，原文绝对上限 30 分钟，设备以返回期限为准。 |
| `poll_after_ms` | integer | 建议轮询间隔，毫秒 | 平台返回；绑定期间原文默认 2000。 |
| `state` | object | 当前设备状态 | 平台返回，完整字段见公共状态表。 |

输出示例：

```json
{
  "setup_id": "<平台设置会话UUID>",
  "expires_at_ms": 1789092900000,
  "poll_after_ms": 2000,
  "state": {
    "device_id": "KP01-AABBCCDDEEFF",
    "device_revision": 3,
    "binding_generation": 0,
    "binding_state": "UNBOUND",
    "activation_state": "NOT_STARTED",
    "state_hash": "<本版状态SHA256摘要>"
  }
}
```

## C04 取得一次性手机入口

`POST /api/v1/device/handoffs`

用途：设备取得 SaaS 绑定入口，并交给当前已授权的本地会话。

### 输入字段

| 字段 | 类型 | 必填 | 中文含义 | 怎么获得／填写 |
| --- | --- | --- | --- | --- |
| `setup_id` | string（UUID） | 是 | 平台设置会话编号 | 取 C03 的 `data.setup_id`。 |
| `local_setup_id` | string（UUID） | 是 | 本地设置编号 | 沿用 C03 请求中的同名字段。 |
| `code_challenge` | string | 是 | 入口校验摘要 | 设备生成32字节随机值并编码为 verifier；对 verifier 的 ASCII 字节算 SHA256，再编码为 Base64URL。 |

输入示例：

```json
{
  "setup_id": "<C03设置会话UUID>",
  "local_setup_id": "<C03本地设置UUID>",
  "code_challenge": "<32字节SHA256结果的Base64URL>"
}
```

### 输出字段

下表字段位于普通响应的 `data` 中。

| 字段 | 类型 | 中文含义 | 来源／设备怎么用 |
| --- | --- | --- | --- |
| `handoff_token` | string | 一次性入口令牌 | 平台生成32字节随机值并编码；设备把它放进入口链接。 |
| `expires_at_ms` | integer | 令牌到期时间 | 平台生成，原文有效期90秒；不能由设备自行延长。 |
| `entry_url` | string | SaaS绑定页面地址 | 由平台固定配置的 HTTPS 白名单入口。 |

输出示例：

```json
{
  "handoff_token": "<平台一次性令牌>",
  "expires_at_ms": 1789092090000,
  "entry_url": "https://saas.example/onboarding/entry"
}
```

设备自己保留 `verifier`，不是向平台多传一个字段。交给手机的完整链接为：

```text
<entry_url>#token=<handoff_token>&verifier=<设备生成的verifier>
```

## C05 查询状态和命令

`POST /api/v1/device/poll`

用途：设备查询当前状态，领取绑定确认命令或激活配置；查询本身不代表用户按键或 SDK 执行完成。

### 输入字段

| 字段 | 类型 | 必填 | 中文含义 | 怎么获得／填写 |
| --- | --- | --- | --- | --- |
| `setup_id` | string（UUID） | 是 | 平台设置会话编号 | 取 C03 返回的设置会话编号。 |
| `boot_id` | string（UUID） | 是 | 本次启动编号 | 沿用本次已经注册的启动编号。 |
| `known_revision` | integer | 是 | 设备已知状态版本 | 取最近返回的 `state.device_revision`；首次不知道时传0。按原文该字段必填。 |

输入示例：

```json
{
  "setup_id": "<C03设置会话UUID>",
  "boot_id": "<本次启动UUID>",
  "known_revision": 3
}
```

### 输出字段

下表字段位于普通响应的 `data` 中。

| 字段 | 类型 | 中文含义 | 来源／设备怎么用 |
| --- | --- | --- | --- |
| `state` | object | 当前设备状态 | 平台返回，完整字段见公共状态表。 |
| `command` | object 或 null | 当前命令 | 平台产生；没有命令时为 null，原文兼容 NONE 类型。命令子字段见下表。 |
| `poll_after_ms` | integer | 下次轮询间隔，毫秒 | 由平台返回；绑定阶段默认2秒，普通待机不保持高频轮询。 |

输出示例：

```json
{
  "state": {
    "device_id": "KP01-AABBCCDDEEFF",
    "device_revision": 3,
    "binding_generation": 0,
    "binding_state": "UNBOUND",
    "activation_state": "NOT_STARTED",
    "state_hash": "<本版状态SHA256摘要>"
  },
  "command": null,
  "poll_after_ms": 2000
}
```

### `command` 命令字段

| 字段 | 类型 | 中文含义 | 来源／怎么用 |
| --- | --- | --- | --- |
| `command_id` | string（UUID） | 命令编号 | 平台生成，设备识别重复命令；原文未规定它必须等于申请或激活任务编号。 |
| `type` | string | 命令类型 | 原文为 NONE、CONFIRM_CLAIM、APPLY_ACTIVATION、UPDATE_STATE、CLOSE_SETUP；按返回类型处理。 |
| `expires_at_ms` | integer | 命令到期时间 | 平台生成，设备按可信时间判断有效性。 |
| `payload` | object | 命令数据 | 由平台生成；下面只展开原文明确给出的两种命令内容。 |

`CONFIRM_CLAIM` 的 `payload`：

| 字段 | 类型 | 中文含义 | 来源／怎么用 |
| --- | --- | --- | --- |
| `claim_id` | string（UUID） | 绑定申请编号 | 平台产生，设备从此处获取后传 C06。 |
| `challenge` | string | 按键挑战 | 平台生成32字节随机值编码，真实按键后 C06 原样回传。 |
| `binding_digest` | string | 固定绑定内容摘要 | 平台计算64位 SHA256 小写十六进制，设备不改写，C06 原样回传。 |
| `masked_account` | string | 脱敏账号提示 | 平台生成，例如“尾号1234”，供用户确认当前申请。 |
| `expected_binding_generation` | integer | 预期绑定代数 | 平台在建立申请时确定；C06 原样回传。 |

```json
{
  "command_id": "<命令UUID>",
  "type": "CONFIRM_CLAIM",
  "expires_at_ms": 1789092120000,
  "payload": {
    "claim_id": "<绑定申请UUID>",
    "challenge": "<32字节随机值的Base64URL>",
    "binding_digest": "<固定绑定内容SHA256>",
    "masked_account": "尾号1234",
    "expected_binding_generation": 0
  }
}
```

`APPLY_ACTIVATION` 的 `payload` 按原文只列配置封装：

| 字段 | 类型 | 中文含义 | 来源／怎么用 |
| --- | --- | --- | --- |
| `config_b64` | string | 激活配置包 | 平台生成配置 JSON 并编码；设备验签后解码，下方列出解码字段。 |
| `config_mac` | string | 配置认证码 | 平台计算 `HMAC-SHA256(device_key, UTF8("CFG1\n" + config_b64))` 的十六进制值；其中 \n 表示一个 LF，设备用本机密钥验证。 |

配置包验签解码后的字段，依据附件 E.2：

| 字段 | 类型 | 中文含义 | 来源／怎么用 |
| --- | --- | --- | --- |
| `contract_version` | string | 配置协议版本 | 原文为 `ONBOARDING-1.1`。 |
| `device_id` | string | 配置所属设备 | 平台读取生产记录，设备核对与本机一致。 |
| `activation_id` | string（UUID） | 激活任务编号 | 平台创建并保留；设备从配置包中取出，后续 C08、C09、C10 使用。 |
| `config_version` | integer | 激活配置版本 | 平台生成；后续 C08、C10 使用，不自行写死。 |
| `binding_generation` | integer | 配置对应绑定代数 | 平台维护；与当前公共状态核对，防止使用旧归属配置。 |
| `expires_at_ms` | integer | 配置到期时间 | 由平台签发，设备不得用过期配置开始新的首次激活；原文未在此规定统一24小时有效期。 |
| `iot` | object | 供应商注册资料 | 平台组装，子字段如下。 |
| `iot.instance_id` | string | 供应商实例编号 | 来自平台保存的实例配置。 |
| `iot.product_key` | string | 供应商产品标识 | 来自平台保存的产品配置。 |
| `iot.product_secret` | string | 受保护的产品注册密钥 | 这是原文 E.2 明确列出的字段；设备通过受保护配置取得，供原文 SDK 注册流程使用；与当前代码方案的差异见单独说明。 |
| `iot.device_name` | string | 物理设备在供应商侧的固定名称 | 由 SaaS 首次激活前生成并永久记录，设备原样使用；不随账号、重试、重启更换。 |
| `bot_id` | string | 共享智能体编号 | 来自平台配置，设备按对应 SDK 要求使用。 |

原文要求配置仅经设备 HTTPS 下发，落地使用加密 NVS，不交给手机或写入普通日志。该表没有增加当前代码中的其他运行配置字段。

## C06 设备按键确认绑定

`POST /api/v1/device/claim-confirmations`

用途：用户真实按下设备确认键后，设备提交本次确认，平台正式建立归属关系。

### 输入字段

| 字段 | 类型 | 必填 | 中文含义 | 怎么获得／填写 |
| --- | --- | --- | --- | --- |
| `claim_id` | string（UUID） | 是 | 绑定申请编号 | 取 C05 同一确认命令的 `payload.claim_id`。 |
| `challenge` | string | 是 | 按键挑战 | 取该命令的 `payload.challenge`，原样回传。 |
| `binding_digest` | string，64位hex | 是 | 绑定内容摘要 | 取该命令同名字段，原样回传。 |
| `expected_binding_generation` | integer | 是 | 预期绑定代数 | 取该命令同名字段，不能自行加一。 |
| `press_event_id` | string（UUID） | 是 | 本次真实按键事件编号 | 设备在真实按键发生时生成并保存，网络重试沿用。 |

输入示例：

```json
{
  "claim_id": "<C05申请UUID>",
  "challenge": "<C05按键挑战>",
  "binding_digest": "<C05绑定摘要>",
  "expected_binding_generation": 0,
  "press_event_id": "<设备实际按键UUID>"
}
```

### 输出字段

下表字段位于普通响应的 `data` 中。

| 字段 | 类型 | 中文含义 | 来源／设备怎么用 |
| --- | --- | --- | --- |
| `claim_id` | string（UUID） | 已处理的绑定申请 | 平台返回，设备核对是本次申请。 |
| `state` | object | 处理后的归属及激活状态 | 平台返回；保存对应版本、代数和摘要后调用 C07。 |
| `already_applied` | boolean | 该确认是否已经提交过 | 由平台识别重复相同申请的结果；不可据此产生第二次绑定。 |

输出示例：

```json
{
  "claim_id": "<绑定申请UUID>",
  "state": {
    "device_id": "KP01-AABBCCDDEEFF",
    "device_revision": 4,
    "binding_generation": 1,
    "binding_state": "BOUND",
    "activation_state": "RESERVED",
    "state_hash": "<本版状态SHA256摘要>"
  },
  "already_applied": false
}
```

## C07 确认绑定状态已保存

`POST /api/v1/device/state-acks`

用途：报告设备已经保存平台状态，不根据此回执修改 owner。

### 输入字段

| 字段 | 类型 | 必填 | 中文含义 | 怎么获得／填写 |
| --- | --- | --- | --- | --- |
| `device_revision` | integer | 是 | 已保存状态版本 | 取同一版 `state.device_revision`。 |
| `binding_generation` | integer | 是 | 已保存绑定代数 | 取同一版 `state.binding_generation`。 |
| `local_generation` | integer | 是 | 本地保存序号 | 由设备本地保存模块产生并在保存成功后记录，不用平台版本号代替。 |
| `state_hash` | string，64位hex | 是 | 已保存状态摘要 | 取同一版 `state.state_hash` 并核对实际保存内容。 |

输入示例：

```json
{
  "device_revision": 4,
  "binding_generation": 1,
  "local_generation": 1,
  "state_hash": "<已保存状态摘要>"
}
```

### 输出字段

下表字段位于普通响应的 `data` 中。

| 字段 | 类型 | 中文含义 | 来源／设备怎么用 |
| --- | --- | --- | --- |
| `accepted_revision` | integer | 平台接受的保存版本 | 平台确认后返回，设备可记录该版已完成回执。 |
| `setup_can_close` | boolean | 是否可以收尾 | 平台根据回执和流程条件判断；设备按结果执行收尾。 |

输出示例：

```json
{
  "accepted_revision": 4,
  "setup_can_close": false
}
```

原文收尾条件：页面与设备都确认后等待3秒，或设备确认后最多30秒。这里保留原文的布尔判断，不新增等待时间或后续动作字段。

## C08 申请 SDK 执行许可

`POST /api/v1/device/activation-attempts`

用途：平台先记录本次可能执行的事实，再决定是否允许本次 SDK 调用，避免不确定结果下重复执行。

### 输入字段

| 字段 | 类型 | 必填 | 中文含义 | 怎么获得／填写 |
| --- | --- | --- | --- | --- |
| `activation_id` | string（UUID） | 是 | 激活任务编号 | 从 C05 激活配置包解码后的 `activation_id` 取得。 |
| `config_version` | integer | 是 | 本次使用的配置版本 | 从同一份已验证配置的 `config_version` 取得。 |
| `attempt_id` | string（UUID） | 是 | 一次 SDK 执行编号 | 设备为本次实际执行生成并保留；本次请求重试沿用，不重新申请第二次执行。 |

输入示例：

```json
{
  "activation_id": "<配置包中的激活任务UUID>",
  "config_version": 1,
  "attempt_id": "<设备生成的执行UUID>"
}
```

### 输出字段

下表字段位于普通响应的 `data` 中。

| 字段 | 类型 | 中文含义 | 来源／设备怎么用 |
| --- | --- | --- | --- |
| `allowed` | boolean | 是否允许本次执行 | 平台判断后返回；只有 true 才能开始此次 SDK 调用。 |
| `attempt_id` | string（UUID） | 许可对应执行编号 | 平台返回本次执行编号，后续 C09 使用。 |
| `permit_expires_at_ms` | integer | 许可到期时间 | 原文 I.1 规定许可有效期30秒；超窗重新查询，不能推断先前调用一定没有执行。 |
| `state` | object | 当前设备状态 | 平台返回，完整字段见公共状态表。 |

输出示例：

```json
{
  "allowed": true,
  "attempt_id": "<本次执行UUID>",
  "permit_expires_at_ms": 1789092030000,
  "state": {
    "device_id": "KP01-AABBCCDDEEFF",
    "device_revision": 5,
    "binding_generation": 1,
    "binding_state": "BOUND",
    "activation_state": "CONTACT_POSSIBLE",
    "state_hash": "<本版状态SHA256摘要>"
  }
}
```

## C09 上报激活执行结果

`POST /api/v1/device/activation-results`

用途：上报已获许可的实际 SDK 执行结果。超时或无法确定结果时上报 UNKNOWN，不能当作明确失败重复执行。

### 输入字段

| 字段 | 类型 | 必填 | 中文含义 | 怎么获得／填写 |
| --- | --- | --- | --- | --- |
| `activation_id` | string（UUID） | 是 | 激活任务编号 | 沿用 C08 所属任务编号。 |
| `attempt_id` | string（UUID） | 是 | 实际执行编号 | 沿用 C08 已申请并返回的执行编号，不在上报时重新生成。 |
| `stage` | string | 是 | 执行阶段 | 按原文 I.1 填 `SDK_REGISTER` 或 `CONVERSATION_TEST`，由设备依据本次实际执行操作确定。 |
| `sdk_result` | integer | 是 | SDK返回码 | 读取本次实际 SDK 调用或回调结果，不编造结果码。 |
| `outcome` | string | 是 | 本次结果分类 | 原文取值：`SUCCESS_OBSERVED` 已观察到成功、`DEFINITE_FAILURE` 明确失败、`UNKNOWN` 未知。 |

输入示例：

```json
{
  "activation_id": "<激活任务UUID>",
  "attempt_id": "<C08执行UUID>",
  "stage": "SDK_REGISTER",
  "sdk_result": 0,
  "outcome": "SUCCESS_OBSERVED"
}
```

### 输出字段

下表字段位于普通响应的 `data` 中。

| 字段 | 类型 | 中文含义 | 来源／设备怎么用 |
| --- | --- | --- | --- |
| `activation_id` | string（UUID） | 结果所属任务 | 平台返回，设备与本次任务核对。 |
| `state` | object | 处理后的设备状态 | 平台返回，判断仍在激活、待处理或已 READY。 |
| `reconcile_required` | boolean | 是否需要对账 | 平台根据本次结果判定；true 时不要自行开始第二次同类激活执行。 |

输出示例：

```json
{
  "activation_id": "<激活任务UUID>",
  "state": {
    "device_id": "KP01-AABBCCDDEEFF",
    "device_revision": 6,
    "binding_generation": 1,
    "binding_state": "BOUND",
    "activation_state": "REGISTERED_OBSERVED",
    "state_hash": "<本版状态SHA256摘要>"
  },
  "reconcile_required": false
}
```

首次通话测试时使用 `stage=CONVERSATION_TEST`。结果分类只表示这一次执行的事实，不等同于设备最终状态；服务是否可用仍读取 `state.activation_state`。

## C10 确认激活结果已保存

`POST /api/v1/device/activation-acks`

用途：设备确认激活结果已在本地保存；重复相同回执不产生新的激活副作用。

### 输入字段

| 字段 | 类型 | 必填 | 中文含义 | 怎么获得／填写 |
| --- | --- | --- | --- | --- |
| `activation_id` | string（UUID） | 是 | 已保存结果所属任务 | 沿用配置包及 C09 对应的激活任务编号。 |
| `local_generation` | integer | 是 | 本地保存序号 | 由设备保存模块在本次结果保存成功后记录，不使用配置版本代替。 |
| `config_version` | integer | 是 | 结果对应配置版本 | 沿用本次激活实际使用的配置包版本。 |

输入示例：

```json
{
  "activation_id": "<激活任务UUID>",
  "local_generation": 2,
  "config_version": 1
}
```

### 输出字段

下表字段位于普通响应的 `data` 中。

| 字段 | 类型 | 中文含义 | 来源／设备怎么用 |
| --- | --- | --- | --- |
| `accepted` | boolean | 回执是否被接受 | 由平台验证后返回。 |
| `state` | object | 当前设备状态 | 平台返回，完整字段见公共状态表。 |

输出示例：

```json
{
  "accepted": true,
  "state": {
    "device_id": "KP01-AABBCCDDEEFF",
    "device_revision": 6,
    "binding_generation": 1,
    "binding_state": "BOUND",
    "activation_state": "REGISTERED_OBSERVED",
    "state_hash": "<本版状态SHA256摘要>"
  }
}
```

## C11 设置流程收尾

`POST /api/v1/device/setup-close`

用途：请求或报告本次设置流程收尾。关闭临时入口不清空已提交的绑定或激活任务。

### 输入字段

| 字段 | 类型 | 必填 | 中文含义 | 怎么获得／填写 |
| --- | --- | --- | --- | --- |
| `setup_id` | string（UUID） | 是 | 要关闭的设置会话 | 取本次 C03 返回的 `setup_id`。 |
| `reason` | string | 是 | 关闭原因 | 设备按实际情况填 SUCCESS、TIMEOUT、CANCELLED 或 NETWORK_SWITCH。 |
| `final_revision` | integer | 是 | 关闭前最后收到的状态版本 | 取最后成功收到的 `state.device_revision`，不是设备本地保存序号。 |

输入示例：

```json
{
  "setup_id": "<C03设置会话UUID>",
  "reason": "SUCCESS",
  "final_revision": 6
}
```

### 输出字段

下表字段位于普通响应的 `data` 中。

| 字段 | 类型 | 中文含义 | 来源／设备怎么用 |
| --- | --- | --- | --- |
| `close_allowed` | boolean | 是否允许关闭 | 平台判定并返回，设备据此执行关闭。 |
| `state` | object | 当前设备状态 | 平台返回并保留正式绑定及激活事实，便于后续恢复。 |

输出示例：

```json
{
  "close_allowed": true,
  "state": {
    "device_id": "KP01-AABBCCDDEEFF",
    "device_revision": 6,
    "binding_generation": 1,
    "binding_state": "BOUND",
    "activation_state": "REGISTERED_OBSERVED",
    "state_hash": "<本版状态SHA256摘要>"
  }
}
```

## 字段从哪里取得

| 要使用的字段 | 取值来源 |
| --- | --- |
| `device_id`、`device_key`、`key_version` | 设备出厂写入的身份及凭据。 |
| `boot_id` | 设备每次启动生成。 |
| `challenge_id` | C01 验签后的校时包。 |
| `local_setup_id` | 设备为一次本地设置生成。 |
| `setup_id` | C03 平台返回。 |
| `claim_id`、`challenge`、`binding_digest`、预期绑定代数 | 同一条 C05 确认命令，不跨命令拼接。 |
| `press_event_id` | 设备真实按键时生成。 |
| `activation_id`、`config_version` | C05 激活配置包验签解码后取得。 |
| `attempt_id` | 设备为一次 SDK 执行生成，C08 申请、C09 沿用。 |
| `local_generation` | 设备保存模块记录本地保存完成的序号。 |
| `device_revision`、`binding_generation`、`state_hash` | 平台返回的同一版公共状态。 |

## 平台如何确定 C08 执行阶段

C08 不增加阶段字段。平台按任务中已确认的事实判定：尚未观察到注册成功时，许可用于 `SDK_REGISTER`；已注册且 C10 确认保存后，许可用于 `CONVERSATION_TEST`。C09 的阶段必须匹配平台为该执行编号记录的阶段。已完成 READY 的同代绑定不再发放首次激活许可。

原文未给出部分命令的完整 payload，当前实际下发 `CONFIRM_CLAIM`、`APPLY_ACTIVATION` 两种命令，其余保留枚举不作为新增接口功能。
来源：[原始流程文档](<D:/wechat/xwechat_files/wangcong3092_983b/msg/file/2026-09/AI电话_首次配网注册与激活_完整流程与详细设计(1).docx>)，重点是附件 B（认证及校时）、C（设备接口）、E（状态和配置）、I.1（逐接口输入与输出）。