Medidores IoT: cómo registrar un dispositivo y cómo firma sus lecturas

Dispositivos IoT: registre un AMI o un punto final IoT, copie su secreto (que se muestra una vez), cámbielo con un nuevo secreto y vea cómo el dispositivo firma cada solicitud a /api/public/utilities/iot/reads, con un ejemplo de solicitud, los límites y todas las respuestas que puede obtener.

Un medidor AMI o IoT envía sus lecturas a TRANXACT a través de HTTPS. Cada dispositivo tiene una clave generada por el servidor (utd_ seguida de 24 letras y dígitos) y un secreto. El dispositivo verifica su identidad en cada solicitud, por lo que nadie más puede enviar lecturas de ese medidor.

Registro de un dispositivo

Abra CRM › Servicios públicos › Medidores y lecturas de servicios públicos › Dispositivos IoT y pulse Nuevo.
Introduzca una etiqueta, seleccione el medidor que lee y elija Firmar con: hmac (una firma HMAC-SHA256 de cada solicitud —recomendado), portador (la clave y el secreto enviados como un token) o ambos.
Configure el número máximo de lecturas por minuto para este dispositivo y el firmware, si lo conoce.
Guardar. La respuesta muestra la clave y el secreto: “Copia el secreto ahora; no se mostrará de nuevo”. Introduce ambos en la configuración del dispositivo.

El secreto se muestra una sola vez. No vuelve a aparecer en la lista, ni siquiera para un administrador; la lista solo muestra sus últimos cuatro caracteres (Fin del secreto). Si se pierde, genere uno nuevo.

Girando el secreto

En la fila del dispositivo, pulse «Nueva clave secreta» y confirme. La nueva clave se mostrará una sola vez y la anterior dejará de funcionar en ese momento, así que introduzca la nueva clave inmediatamente. Establezca el estado en «Deshabilitado» para detener un dispositivo sin rotación, o en «Retirado» cuando se retire del servicio.

Cómo un dispositivo registra una lectura

Construye el cuerpo JSON: una lista de lecturas, cada una con read_at (hora ISO 8601) y lectura. La batería, la señal, el firmware y las alarmas son opcionales.
Toma la hora Unix actual en segundos como marca de tiempo.
Calcula el HMAC-SHA256, bajo la clave secreta del dispositivo, de la marca de tiempo, un punto y los bytes exactos del cuerpo: “<marca de tiempo>.<cuerpo>”. Escríbelo como 64 caracteres hexadecimales en minúscula.
POST el cuerpo a /api/public/utilities/iot/reads con los encabezados X-Utility-Device (la clave), X-Utility-Timestamp y X-Utility-Signature (el hexadecimal, opcionalmente con el prefijo 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>"}]}

La misma firma funciona en un shell, para probar un dispositivo antes de su instalación:

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"

Firma exactamente los bytes que envíes. Si reformateas el JSON después de firmarlo o lo envías con un final de línea diferente, los bytes cambian y la firma deja de coincidir.

Un dispositivo configurado como portador (o ambos) puede enviar Authorization: Bearer <utd_DEVICE_KEY>.<DEVICE_SECRET> y no incluir encabezados de firma. HMAC es la opción más segura: el secreto nunca se transmite y una solicitud capturada no se puede reproducir.

Límites

La marca de tiempo debe tener una diferencia máxima de 5 minutos con respecto a la hora del servidor: mantenga la hora del dispositivo sincronizada mediante NTP.
La misma solicitud firmada dos veces se rechaza como una repetición. Una lectura que ya está en el archivo se considera duplicada y se almacena una sola vez.
Como máximo 64 KB y 500 lecturas por solicitud, el propio dispositivo Lecturas por minuto como máximo, y 600 solicitudes por minuto desde una dirección.
El dispositivo debe estar activo y conectado a un medidor.

Lo que el dispositivo recibe de vuelta

Respuesta	Significado
201 o 200 con aceptados, duplicados, excepciones, rechazados, alarmas y problemas	La solicitud fue procesada. Cada lectura se contabiliza; los problemas identifican cualquier lectura que no sea válida mediante su índice.
401 device_auth	Clave desconocida o inactiva, modo incorrecto o firma que no coincide. El contador de intentos rechazados del dispositivo aumenta.
401 marca de tiempo obsoleta	La marca de tiempo tiene un desfase de más de 5 minutos.
Repetición 409	Esta solicitud firmada ya ha sido recibida.
413 lecturas demasiado_manchas	Más de 500 lecturas en una sola solicitud.
422 sin medidor	El dispositivo no está conectado a un medidor.
429 tasa_limitada	El envío supera el límite. Espere y vuelva a enviar.
400 bad_json	El cuerpo no es JSON.
403 utilidades_desactivadas	Los servicios públicos de la empresa están cortados.

Salud y alarmas

Cada solicitud actualiza la última conexión, el porcentaje de batería y la señal en dBm del dispositivo. Una batería con menos del 15 % activa una alarma de batería baja.
Tipos de alarma que puede enviar un dispositivo: batería baja, manipulación, fuga, flujo inverso, sin flujo, fuera de línea y otras. Una alarma activa de cada tipo por dispositivo.
La función Alarmas de dispositivo las muestra; Borrar cierra una con una nota. Una fuga genera automáticamente una orden de servicio de investigación de fugas de alta prioridad; una alarma de manipulación o de flujo inverso también genera una orden de servicio.
La cifra de informes de medidores IoT (24 h) del panel de control contabiliza los dispositivos activos de los que se ha tenido señal en el último día.