物联网电表：设备注册及其读数签名方式

IoT 设备：注册 AMI 或 IoT 端点，复制其密钥（显示一次），用新密钥轮换它，以及设备如何对每个发送到 /api/public/utilities/iot/reads 的请求进行签名 — 附带示例请求、限制以及它可以获得的每个答案。

AMI 或物联网电表通过 HTTPS 将自身读数发布到TRANXACT。每个设备都有一个由服务器生成的密钥（utd_ 后跟 24 位字母和数字）和一个秘密信息。设备在每次请求中都会验证自身身份，因此其他人无法获取该电表的读数。

注册设备

打开 CRM › 实用程序 › 公用事业计量和读数 › 物联网设备，然后按“新建”。
输入标签，选择它读取的计量器，然后选择签名方式：hmac（每个请求的 HMAC-SHA256 签名 - 推荐），bearer（作为令牌发送的密钥和秘密）或两者。
设置此设备的每分钟读取次数上限，以及固件版本（如果您知道的话）。
保存。答案会显示密钥和密文：“立即复制密文——它不会再次显示。” 将密钥和密文都输入到设备的配置中。

密钥只会显示一次。之后不会再列出，即使是对管理员也不会；列表中只会显示密钥的最后四个字符（密钥结束）。如果密钥丢失，请重新生成一个。

旋转秘密

在设备的相应行中，按下“新密钥”并确认。新密钥会显示一次，旧密钥随即失效，因此请立即将新密钥提供给设备。将“状态”设置为“禁用”可使设备停止运行而不进行轮换，或设置为“退役”则表示设备已停止使用。

设备如何记录读数

构建 JSON 数据主体：一个读取记录列表，每个记录包含 read_at（ISO 8601 时间戳）和读取状态。电池、信号、固件和报警信息为可选信息。
以当前 Unix 时间（以秒为单位）作为时间戳。
使用设备密钥，计算时间戳、句点和正文的完整字节序列的 HMAC-SHA256 值：“<timestamp>.<body>”。将其写成 64 个小写十六进制字符。
将请求体 POST 到 /api/public/utilities/iot/reads，请求头为 X-Utility-Device（密钥）、X-Utility-Timestamp 和 X-Utility-Signature（十六进制签名，可选前缀为 sha256=）。

POST https://<your-tranxact-host>/api/public/utilities/iot/reads
Content-Type: application/json
X-Utility-Device: <utd_DEVICE_KEY>
X-Utility-Timestamp: <1792252800>
X-Utility-Signature: sha256=<64 hex characters>

{"reads":[{"read_at":"<2026-10-17T09:30:00Z>","reading":<48213.4>}],
 "battery_pct":<87>,"signal_dbm":<-71>,"firmware":"<2.4.1>",
 "alarms":[{"type":"<leak>","detail":"<continuous flow 6 h>"}]}

同样的签名也适用于 shell，用于在安装设备之前对其进行测试：

BODY='{"reads":[{"read_at":"<2026-10-17T09:30:00Z>","reading":<48213.4>}]}'
TS=$(date +%s)
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "<DEVICE_SECRET>" | sed 's/^.* //')
curl -X POST "https://<your-tranxact-host>/api/public/utilities/iot/reads" \
  -H "Content-Type: application/json" \
  -H "X-Utility-Device: <utd_DEVICE_KEY>" \
  -H "X-Utility-Timestamp: $TS" \
  -H "X-Utility-Signature: sha256=$SIG" \
  --data-binary "$BODY"

请对您发送的确切字节进行签名。签名后重新格式化 JSON 或使用不同的换行符发送，都会改变字节内容，导致签名不再匹配。

设置为承载模式（或同时设置为承载模式和设备模式）的设备可以发送 Authorization: Bearer <utd_DEVICE_KEY>.<DEVICE_SECRET> 请求头，而不包含签名头。HMAC 是更安全的选择：密钥永远不会传输，捕获的请求无法重放。

限制

时间戳必须在服务器时钟的 5 分钟以内：保持设备时钟由 NTP 设置。
同一个签名请求重复执行两次会被拒绝，视为重放请求。读取已存在于文件中的数据会被计为重复操作，仅存储一次。
每次请求最多 64 KB 和 500 次读取，设备每分钟最多读取 64 KB，并且每分钟从单个地址发出 600 次请求。
该设备必须处于激活状态并连接到电表。

设备接收到的信息

回答	意义
201 或 200，包含已接受、重复、异常、已拒绝、警报和问题。	请求已执行。每次读取都会被计数；问题列表会列出所有索引无效的读取操作。
401 设备认证	密钥未知或无效、模式错误或签名不匹配。设备的“拒绝次数”增加。
401 过时时间戳	时间戳相差超过5分钟。
409 重播	这份已签署的申请已收到。
413 读取次数过多	一次请求读取超过 500 次。
422 无表	该设备未连接到仪表。
429 速率限制	发送速度超过限制，请稍等片刻后重发。
400 bad_json	响应体不是 JSON 格式。
403 实用程序关闭	公司公用设施已关闭。

健康与警报

每次请求都会更新设备的最后上线时间、电池电量百分比和信号强度（dBm）。电池电量低于 15% 时会发出低电量警报。
设备可发送的报警类型包括：电池电量低、防拆、漏电、反向流动、无流量、离线和其他。每个设备每种报警类型只能发送一个。
设备警报会列出所有警报；清除警报会关闭警报并添加备注。泄漏警报会自动触发高优先级泄漏调查服务单；篡改警报或逆流警报也会触发服务单。
仪表盘上的物联网计量表报告（24 小时）数字统计了过去一天内检测到的活跃设备数量。