# 设备相关外部接口表
范围仅包含设备终端以 HMAC 身份直接调用的 `/device/v2/*` 外部接口；不包含家庭/运营 Web API、内部工具和供应商回调。基于 `openapi/openapi.yaml`（OpenAPI 3.1，版本 0.70.0）生成，并与 `internal/httpapi/router.go` 的实际路由逐项核对。当前共 **16** 个已注册且纳入 OpenAPI 契约的接口。
说明：`*` 表示必填字段；`body` 表示请求体；响应栏只展开成功响应。全部接口都要求设备 HMAC 请求头：`X-Device-Id`、`X-Device-Timestamp`、`X-Device-Nonce`、`X-Device-Content-SHA256`、`X-Device-Signature`，表内不重复。通用错误响应为 `ErrorResponse`。
## 设备端 v2
| 接口名字 | 方法与路径 | 接口描述 | 输入参数 | 输出参数 |
|---|---|---|---|---|
| `getDeviceBootstrap` | `GET /device/v2/bootstrap` | 返回可信设备状态、服务器时间、绑定和最低安全版本 | query `firmware_version*`: string
query `board_rev`: string
query `rtc_sdk_version`: string
query `codec`: string
query `sample_rate`: integer
query `device_time*`: string(date-time)
query `network`: string | 200 DeviceBootstrapResponse{data*:DeviceBootstrapData{clock_skew_ms*:integer(int64), device*:DeviceBootstrap, server_time*:string(date-time)}, request_id*:string} — 返回可信设备状态、服务器时间、绑定和最低安全版本 |
| `pullDeviceCommands` | `GET /device/v2/commands` | 返回未过期的待执行命令并记录投递次数 | query `limit`: integer | 200 DeviceCommandDeliveryListResponse{data*:object{items*:array}, request_id*:string} — 返回未过期的待执行命令并记录投递次数 |
| `acknowledgeDeviceCommand` | `POST /device/v2/commands/{id}/ack` | 回执已保存 | path `id*`: string(uuid)
body* `application/json` DeviceCommandAckRequest{result_summary*:object, status*:string[ACKNOWLEDGED/SUCCEEDED/FAILED]} | 200 DeviceCommandDeliveryResponse{data*:DeviceCommandDelivery{created_at*:string(date-time), delivery_attempts*:integer, expires_at*:string(date-time), id*:string(uuid), payload*:object, status*:DeviceCommandStatus, type*:string[apply_config/reboot/diagnostics/firmware_update]}, request_id*:string} — 回执已保存 |
| `getDeviceConfig` | `GET /device/v2/config` | 返回设备期望配置及当前绑定 | header `If-None-Match`: string | 200 DeviceConfigResponse{data*:DeviceConfiguration{binding*:DeviceBinding, desired_config*:object, device_id*:string(uuid), reported_revision:integer(int64), revision*:integer(int64)}, request_id*:string}；headers{ETag:string} — 返回设备期望配置及当前绑定
304 无响应体 — 配置未变化 |
| `createDeviceConversation` | `POST /device/v2/conversations` | 分配房间和短期入房凭证；此步骤不启动语音智能体。 | header `Idempotency-Key*`: string
body* `application/json` CreateConversationRequest{capabilities*:DeviceCapabilities{audio_tracks*:array, rtc*:boolean, rtc_credential_renewal:boolean, upload_resume*:boolean}, device_time*:string(date-time), monotonic_ms:integer(int64), network*:DeviceNetwork{rssi:integer, type*:string}, requested_goal*:string} | 201 CreateConversationResponse{data*:CreatedConversation{conversation_id*:string(uuid), privacy*:ConversationPrivacy, rtc*:RTCGrant, session*:ConversationSession, status*:string}, request_id*:string}；headers{Idempotency-Replayed:string[true]} — 房间资料已分配；重复请求返回相同通话和相同确定性短期Token |
| `getDeviceConversationState` | `GET /device/v2/conversations/{id}` | 设备确认入房后读取云端权威通话状态和下一步动作；供应商永久拒绝启动或异步启动失败时返回稳定failure_code及leave_room，响应不包含供应商原始错误。 | path `id*`: string(uuid) | 200 DeviceConversationStateResponse{data*:DeviceConversationState{action*:string[wait/continue/leave_room], conversation_id*:string(uuid), failure_code:string, status*:ConversationStatus}, request_id*:string} — 返回当前设备所属通话的权威状态和设备动作 |
| `activateDeviceConversation` | `POST /device/v2/conversations/{id}/activate` | 设备确认已进入指定RTC房间后，投递固定供应商语音任务。 | path `id*`: string(uuid)
header `Idempotency-Key*`: string
body* `application/json` ActivateConversationRequest{config_revision*:integer(int64), connection_reference:string, joined_at*:string(date-time), room_id*:string, rtc_join_result*:string, rtc_user_id*:string} | 202 ActivateConversationResponse{data*:ActivatedConversation{accepted_at*:string(date-time), conversation_id*:string(uuid), status*:string[STARTING_AGENT/ACTIVE]}, request_id*:string} — 入房确认已接受；语音智能体正在启动或已经启动 |
| `heartbeatDeviceConversation` | `POST /device/v2/conversations/{id}/heartbeat` | 按严格递增序号刷新设备在线状态和通话短期租约；重复或乱序心跳不会延长租约。 | path `id*`: string(uuid)
body* `application/json` HeartbeatConversationRequest{command_results*:array