98 lines
6.0 KiB
YAML
98 lines
6.0 KiB
YAML
|
openapi: 3.1.0
|
|||
|
|
info:
|
|||
|
|
title: 蓝牙配网与账号绑定
|
|||
|
|
version: 1.1.1
|
|||
|
|
description: 蓝牙只传 Wi-Fi 与一次性绑定令牌，账号身份从登录态获取。实际响应统一使用 ok/code/request_id/server_time_ms/data 信封。
|
|||
|
|
paths:
|
|||
|
|
/api/v1/web/ble-bind-tokens:
|
|||
|
|
post:
|
|||
|
|
summary: 为已登录账号签发5分钟一次性设备绑定令牌
|
|||
|
|
security:
|
|||
|
|
- Bearer: []
|
|||
|
|
- AccountCookie: []
|
|||
|
|
description: Cookie 请求必须同源并携带 X-CSRF-Token。省略 expected_binding_id 时设备必须未添加；省略 elder_id 时仅添加到账号。更换已绑定设备的使用老人必须同时提交 elder_id 和当前 expected_binding_id，账号需有原家庭及目标家庭设备管理权限。申请不改变原归属，设备实体确认后才原子完成转移；届时再次检查权限、归属版本、通话及升级。仅替换本人对该设备的未完成令牌。
|
|||
|
|
requestBody:
|
|||
|
|
required: true
|
|||
|
|
content:
|
|||
|
|
application/json:
|
|||
|
|
schema:
|
|||
|
|
type: object
|
|||
|
|
additionalProperties: false
|
|||
|
|
required: [device_id]
|
|||
|
|
properties:
|
|||
|
|
device_id: {type: string, pattern: '^KP01-[0-9A-F]{12}$'}
|
|||
|
|
elder_id: {type: string, format: uuid, description: 可省略；省略表示先添加到账号，之后在设备管理中绑定老人。不会发送到蓝牙设备}
|
|||
|
|
expected_binding_id: {type: string, format: uuid, description: 更换使用老人时必填，为 binding-impact 返回的当前绑定 UUID。配网及普通添加不得携带。}
|
|||
|
|
responses:
|
|||
|
|
'200': {description: 'data: {bind_token: 43字符Base64URL令牌}'}
|
|||
|
|
'400': {description: 'DEVICE_ID_INVALID：设备编号格式错误；ELDER_ID_INVALID：老人编号格式错误；PROFILE_REQUIRED：显式选择的使用者不可管理'}
|
|||
|
|
'403': {description: '按具体原因返回账号、组织、设备状态或归属权限错误；与 mini/ble-device-state 一致，message 为可直接展示的中文原因，不再合并提示'}
|
|||
|
|
'404': {description: 'DEVICE_NOT_REGISTERED：平台没有该设备的注册记录'}
|
|||
|
|
'409': {description: 'DEVICE_NOT_RELEASED / DEVICE_ENROLLMENT_UNSUPPORTED / DEVICE_BINDING_STALE / ALREADY_BOUND；message 给出相应处理方式'}
|
|||
|
|
default: {description: 权限不足、设备已绑定、使用者未选择或服务暂不可用}
|
|||
|
|
/api/v1/web/ble-bind-status:
|
|||
|
|
post:
|
|||
|
|
summary: 由签发账号查询平台绑定结果
|
|||
|
|
security:
|
|||
|
|
- Bearer: []
|
|||
|
|
- AccountCookie: []
|
|||
|
|
description: 同源和CSRF要求同签发接口。平台成功不代表设备已经保存Wi-Fi；蓝牙断开后可用此接口确认云端结果。
|
|||
|
|
requestBody:
|
|||
|
|
$ref: '#/components/requestBodies/Token'
|
|||
|
|
responses:
|
|||
|
|
'200': {description: 'data.status 为 pending/success/failed，可附 message'}
|
|||
|
|
default: {description: 不属于当前账号的令牌不可查询}
|
|||
|
|
/api/v1/device/ble-bind:
|
|||
|
|
post:
|
|||
|
|
summary: 设备绑定并同步取得火山连接配置
|
|||
|
|
security:
|
|||
|
|
- DeviceRequest: []
|
|||
|
|
description: HTTPS，DEVREQ1九行HMAC签名；X-Device-ID、X-Key-Version、X-Timestamp-Ms、X-Nonce、X-Request-ID 必填。每次重试刷新nonce，保留实体确认事件的request ID。已提交令牌的重试返回同一有效绑定；不会抢占已有设备归属。
|
|||
|
|
requestBody:
|
|||
|
|
$ref: '#/components/requestBodies/Token'
|
|||
|
|
responses:
|
|||
|
|
'200':
|
|||
|
|
description: data直接带status及5个火山字段，无voice_status/voice。平台取齐才成功，设备保存配置与Wi-Fi后才报告蓝牙success；凭据不转发小程序。设备超时设45秒，平台取参等待上限35秒。
|
|||
|
|
content:
|
|||
|
|
application/json:
|
|||
|
|
schema:
|
|||
|
|
type: object
|
|||
|
|
required: [ok, data]
|
|||
|
|
properties:
|
|||
|
|
ok: {const: true}
|
|||
|
|
code: {type: string}
|
|||
|
|
request_id: {type: string}
|
|||
|
|
server_time_ms: {type: integer}
|
|||
|
|
data:
|
|||
|
|
type: object
|
|||
|
|
additionalProperties: false
|
|||
|
|
required: [status, instance_id, product_key, device_name, device_secret, RTCAppID]
|
|||
|
|
properties:
|
|||
|
|
status: {const: success}
|
|||
|
|
instance_id: {type: string, minLength: 1}
|
|||
|
|
product_key: {type: string, minLength: 1}
|
|||
|
|
device_name: {type: string, minLength: 1}
|
|||
|
|
device_secret: {type: string, minLength: 16, maxLength: 256}
|
|||
|
|
RTCAppID: {type: string, minLength: 1, maxLength: 128}
|
|||
|
|
'409': {description: 'BINDING_CHANGED：等待期间解绑/归属变化；VOICE_MIGRATION_REQUIRED：需补交旧设备凭据。另有原令牌错误。'}
|
|||
|
|
'502': {description: 'VOICE_REGISTRATION_FAILED / VOICE_CONFIG_INVALID：未取得完整配置，已完成绑定保留。注册结果不确定由平台核对，不重复注册。'}
|
|||
|
|
'503': {description: 'VOICE_REGISTRATION_PAUSED：语音暂停，已完成绑定保留；也可能是绑定暂停。'}
|
|||
|
|
'504': {description: 'VOICE_REGISTRATION_TIMEOUT：取参超时，保留原令牌重试；已完成绑定保留。'}
|
|||
|
|
default: {description: 令牌无效、过期、归属变化或服务暂不可用；网络超时/5xx不应视为绑定失败}
|
|||
|
|
components:
|
|||
|
|
securitySchemes:
|
|||
|
|
Bearer: {type: http, scheme: bearer}
|
|||
|
|
AccountCookie: {type: apiKey, in: cookie, name: __Host-platform-onboarding}
|
|||
|
|
DeviceRequest: {type: apiKey, in: header, name: Authorization, description: 'Device-HMAC-SHA256 后接64字符小写十六进制MAC'}
|
|||
|
|
requestBodies:
|
|||
|
|
Token:
|
|||
|
|
required: true
|
|||
|
|
content:
|
|||
|
|
application/json:
|
|||
|
|
schema:
|
|||
|
|
type: object
|
|||
|
|
additionalProperties: false
|
|||
|
|
required: [bind_token]
|
|||
|
|
properties:
|
|||
|
|
bind_token: {type: string, pattern: '^[A-Za-z0-9_-]{43}$'}
|