Измерительные приборы IoT: регистрация устройства и способ подписи показаний.
Устройства IoT: регистрация образа AMI или конечной точки IoT, копирование ее секрета (показано один раз), замена его новым секретом и способ подписи устройством каждого запроса к /api/public/utilities/iot/reads — с примером запроса, ограничениями и всеми возможными ответами.
Счетчик AMI или IoT отправляет свои показания в TRANXACT по протоколу HTTPS. Каждое устройство имеет ключ, созданный сервером (utd_, за которым следуют 24 буквы и цифры), и секретный ключ. Устройство подтверждает свою личность при каждом запросе, поэтому никто другой не может отправлять показания с этого счетчика.
Регистрация устройства
- Откройте CRM › Утилиты › Счетчики и показания коммунальных услуг › Устройства IoT и нажмите «Создать».
- Введите метку, выберите считываемый ею счетчик и выберите «Подписывать с помощью: hmac (подпись HMAC-SHA256 для каждого запроса — рекомендуется), bearer (ключ и секрет, отправляемые в виде токена) или обоих вариантов».
- Установите максимальное количество считываний в минуту для этого устройства, а также укажите версию прошивки, если она вам известна.
- Сохраните. В ответе отображается ключ и секрет: «Скопируйте секрет сейчас — он больше не будет отображаться». Введите оба параметра в конфигурацию устройства.
Секретный ключ отображается только один раз. Он никогда не указывается в списке впоследствии, даже администратору; в списке отображаются только его последние четыре символа (конец секретного ключа). Если он потерян, выдайте новый.
Вращение секрета
На строке устройства нажмите «Новый секрет» и подтвердите. Новый секрет отобразится один раз, а старый перестанет работать в этот момент, поэтому сразу же введите устройству новый секрет. Установите статус «Отключено», чтобы остановить устройство без поворота, или «Выведено из эксплуатации», когда оно будет выведено из строя.
Как устройство отображает показания
- Сформируйте JSON-тело: список операций чтения, каждая с указанием read_at (время по стандарту ISO 8601) и даты чтения. Информация о батарее, сигнале, прошивке и будильниках является необязательной.
- В качестве метки времени используйте текущее время Unix в секундах.
- Вычислите HMAC-SHA256, используя секретный ключ устройства, для метки времени, точки и точных байтов тела запроса: «<метка времени>.<тело запроса>». Запишите это в виде 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>"}]}Та же самая сигнатура была получена в командной оболочке для проверки устройства перед установкой:
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 КБ и 500 операций чтения за запрос, максимальное количество операций чтения в минуту у самого устройства, и 600 запросов в минуту с одного адреса.
- Устройство должно быть активным и подключено к счетчику.
Что устройство получает обратно
| Отвечать | Значение |
|---|---|
| 201 или 200 с указанием принятых, дубликатов, исключений, отклоненных, предупреждений и проблем. | Запрос принят. Каждое прочтение учитывается; в разделе «Проблемы» указываются все прочтения, которые не соответствуют своему индексу. |
| 401 device_auth | Неизвестный или неактивный ключ, неправильный режим или несовпадающая подпись. Количество отказов устройства увеличивается. |
| 401 stale_timestamp | Отметка времени отличается более чем на 5 минут. |
| 409 повтор | Этот подписанный запрос уже получен. |
| 413 too_many_reads | Более 500 прочтений в одном запросе. |
| 422 no_meter | Устройство не подключено к счётчику. |
| 429 rate_limited | Отправка осуществляется со скоростью, превышающей лимит. Подождите и отправьте снова. |
| 400 bad_json | Тело запроса не в формате JSON. |
| 403 utilities_off | Коммунальные услуги компании отключены. |
Здоровье и оповещения
- Каждый запрос обновляет информацию о последнем посещении устройства, проценте заряда батареи и уровне сигнала в дБм. При уровне заряда батареи ниже 15% срабатывает сигнал тревоги battery_low.
- Типы сигналов тревоги, которые может отправлять устройство: низкий заряд батареи, несанкционированное вмешательство, утечка, обратный поток, отсутствие потока, отключение и другие. На одно устройство может быть отправлен один сигнал тревоги каждого типа.
- В разделе «Аварийные сигналы устройства» они отображаются; в разделе «Очистить» один из них закрывается с примечанием. Утечка сама по себе создает заявку на обслуживание по расследованию утечек высокого приоритета; сигнал тревоги о несанкционированном вмешательстве или обратном потоке также создает заявку на обслуживание.
- В отчете IoT-измерителей на панели управления (за 24 часа) подсчитывается количество активных устройств, от которых поступали данные за последние сутки.