HTTP API

业务服务端通过 TiRTC HTTP API 查询设备连接信息或提交设备唤醒请求。所有请求都应由持有应用鉴权凭证的可信业务服务端发起，不要从客户端应用或设备固件直接调用。

HTTP API 地址：

https://api-tirtc.tange365.com

TGV1-HMAC-SHA256 鉴权

请求使用 TGV1-HMAC-SHA256 鉴权。签名计算方法见 HTTP API：TGV1-HMAC-SHA256 签名。

每次请求携带以下鉴权 Header：

Header	说明
Authorization	TGV1 鉴权行
X-Tg-Algorithm	算法名
X-Tg-Date	UTC 请求时间
X-Tg-App-Id	应用 ID，必须与签名凭证中的 app_id 一致
X-Tg-Content-Sha256	请求体 SHA-256，使用十六进制小写字符串；GET 请求按空请求体计算
X-Tg-Signed-Headers	参与签名的 Header 名称列表

SecretKeyId 只用于业务服务端计算签名，不得出现在请求、客户端代码或设备固件中。以下示例中的 <...> 需要替换为签名器为当前请求生成的实际值。

接口列表

能力	接口	用途
低功耗休眠唤醒	GET /v1/device/connectivity	查询设备当前连接信息
低功耗休眠唤醒	POST /v1/device/wakeup-request	向设备提交唤醒请求

低功耗休眠唤醒

以下接口与设备端低功耗接入配合使用。调用唤醒接口前，设备主控需要先通过 TiRTC SDK 获取休眠连接参数，休眠模块再使用这些参数登录至少一个休眠服务器并持续发送心跳。完整设备端流程见接入低功耗休眠唤醒。

客户端正常连接设备时，TiRTC 会自动触发唤醒，不需要业务服务端重复提交唤醒请求。业务服务端通常只在告警、门铃或其他业务事件需要主动启动主控时调用唤醒接口。

查询设备连接信息

此接口查询设备当前连接信息，包括平台最近观察到的主控信令连接和休眠连接事件。它适合联调和辅助判断连接变化，不直接判断设备是否存活、是否已完成唤醒或当前处于哪一种业务状态。

请求

GET /v1/device/connectivity?device_id={device_id}

查询参数：

参数	必填	说明
device_id	是	TiRTC 业务设备 ID；长度为 1～255 字节，必须是有效 UTF-8；作为查询参数传递时需要进行 URL 编码

curl --get \
  'https://api-tirtc.tange365.com/v1/device/connectivity' \
  -H 'Authorization: <TGV1-Authorization>' \
  -H 'X-Tg-Algorithm: TGV1-HMAC-SHA256' \
  -H 'X-Tg-Date: <UTC-Request-Time>' \
  -H 'X-Tg-App-Id: <AppId>' \
  -H 'X-Tg-Content-Sha256: <Empty-Body-SHA256>' \
  -H 'X-Tg-Signed-Headers: <Signed-Header-Names>' \
  --data-urlencode 'device_id=example-device-id'

响应

接口使用统一响应结构：

字段	类型	说明
code	number	业务状态码；0 表示成功，非 0 表示业务错误
message	string	业务状态说明
data	object	成功时按接口定义返回设备连接信息；无数据时省略该字段

无论业务成功还是失败，HTTP 状态码均为 200 OK。调用方必须根据响应体中的 code 判断业务结果，不能只检查 HTTP 状态码。

业务成功时：

{
  "code": 0,
  "message": "ok",
  "data": {
    "device_id": "example-device-id",
    "signal": {
      "is_online": true,
      "last_login_at": 1787000000,
      "last_heartbeat_at": 1787000030,
      "last_offline_at": 1786999000
    },
    "sleep": {
      "last_login_at": 1786998000,
      "last_heartbeat_at": 1786998060,
      "last_offline_at": 1786999100
    }
  }
}

signal 和 sleep 分别对应设备上的两条连接链路：

对象	表示的设备侧状态	字段说明
signal	设备主控运行 TiRTC SDK 时，与 TiRTC 平台建立的信令连接状态	is_online 表示平台当前是否观察到主控的信令连接在线；其余字段记录该连接最近的登录、心跳和离线事件
sleep	主控休眠期间，休眠模块与休眠服务器建立的 TCP 保活连接状态	记录休眠连接最近的登录、心跳和离线事件；当前响应不提供 is_online 字段

last_login_at、last_heartbeat_at 和 last_offline_at 分别表示对应链路最近一次登录、心跳和离线事件的时间。时间字段使用 Unix 秒时间；没有对应事件时返回 null。

这两个对象是平台对两条独立连接的观测结果，不是互斥的设备状态。在主控进入休眠或从休眠恢复的切换阶段，两组时间可能同时存在。不要仅根据 signal 和 sleep 推断设备已经唤醒、仍然存活或当前处于哪一种业务状态；需要结合设备上线通知或其他业务信号判断最终状态。

错误

业务失败时同样返回 200 OK，例如：

{
  "code": 40003,
  "message": "参数错误"
}

主要业务错误：

code	说明
40003	参数错误，例如 device_id 缺失、长度不在 1～255 字节范围内或不是有效 UTF-8
40301	应用凭证无权限
40302	设备与应用不匹配
40304	设备已过期
40403	设备不存在
50000	服务内部错误
50301	连接状态服务不可用
50401	查询超时

连接状态服务不可用或查询超时时，平台不会把缺失结果解释成设备离线，而是返回对应的业务错误码。

提交设备唤醒请求

此接口用于向设备提交唤醒请求，由业务事件主动唤醒设备。目标设备必须已经按照设备接入流程登录休眠服务器；如果平台没有找到对应休眠连接，请求无法表示设备可被唤醒。

请求

POST /v1/device/wakeup-request
Content-Type: application/json

可选请求头 X-Request-ID 用于指定请求标识，取值为 1～128 个可打印 ASCII 字符。省略时由服务端生成；请求头非法时返回 40003，并由服务端生成新的 request_id。最终使用的请求标识通过响应体顶层的 request_id 返回，且与响应头 X-Tg-Request-Id 一致。

请求体：

{
  "device_id": "example-device-id",
  "custom_data": "0x1234"
}

字段	必填	说明
device_id	是	TiRTC 业务设备 ID；长度为 1～255 字节，必须是有效 UTF-8
custom_data	否	两字节自定义唤醒数据；必须为字符串，格式为 0x 加四位十六进制字符，例如 0x1234；非字符串时返回 40003 和稳定提示 custom_data must be a string；仅在目标设备能够解析自定义数据时传入

custom_data 会成为八字节唤醒包的最后两字节。目标设备的休眠模块只能匹配固定报文时，必须省略 custom_data，平台随后下发默认唤醒包 98 3b 16 f8 f3 9c 00 00；如果传入自定义数据导致最后两字节发生变化，该设备可能无法被唤醒。可编程设备如何校验报文、解析自定义数据并保证唤醒幂等，见处理唤醒包。

请求示例：

curl -X POST \
  'https://api-tirtc.tange365.com/v1/device/wakeup-request' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: <TGV1-Authorization>' \
  -H 'X-Tg-Algorithm: TGV1-HMAC-SHA256' \
  -H 'X-Tg-Date: <UTC-Request-Time>' \
  -H 'X-Tg-App-Id: <AppId>' \
  -H 'X-Tg-Content-Sha256: <Request-Body-SHA256>' \
  -H 'X-Tg-Signed-Headers: <Signed-Header-Names>' \
  -H 'X-Request-ID: req-001' \
  -d '{"device_id":"example-device-id","custom_data":"0x1234"}'

响应

响应体使用统一结构，request_id、code、message 同为顶层字段；成功时按接口定义返回 data，无数据时省略 data：

字段	类型	说明
code	number	业务状态码；0 表示成功，非 0 表示业务错误
message	string	业务状态说明
request_id	string	本次请求标识；优先使用有效的 X-Request-ID，未传时由服务端生成；与响应头 X-Tg-Request-Id 一致
data	object	成功时按接口定义返回唤醒请求信息；无数据时省略该字段

平台接受请求时返回 HTTP 202 Accepted：

{
  "code": 0,
  "message": "ok",
  "request_id": "req-001",
  "data": {
    "device_id": "example-device-id",
    "status": "accepted",
    "accepted_at": "2026-08-23T10:00:00.126+08:00"
  }
}

202 Accepted 表示平台至少在一个目标节点找到了设备休眠连接，并且唤醒数据的 TCP 写入调用没有立即失败。它不表示唤醒数据已经到达设备、主控已经启动、设备已经连接 signal，或设备最终唤醒成功。

提交成功后，可以再次查询设备连接信息，或使用你的业务上线信号判断设备是否完成启动。不要把 202 Accepted 当作最终上线信号。

错误

业务错误使用相同的 code、message、request_id 结构，例如：

{
  "code": 40412,
  "message": "设备未连接",
  "request_id": "req-001"
}

主要业务错误：

code	说明
40003	参数错误，例如字段缺失、长度超限或格式不合法，或 custom_data 不是字符串
40301	应用凭证无权限
40302	设备与应用不匹配
40304	设备已过期
40403	设备不存在
40412	设备未连接
40902	不支持唤醒协议
42901	请求过载
50000	服务内部错误
50204	唤醒投递失败
50301	唤醒服务不可用
50402	投递结果未知

收到 50402 时，不能据此判断唤醒数据是否已经投递。使用 request_id 关联日志，并结合设备上线信号判断最终结果；重试时仍需保证业务操作幂等。