Compteurs IoT : enregistrement d’un appareil et signature de ses relevés

Appareils IoT : enregistrez une AMI ou un point de terminaison IoT, copiez son secret (affiché une seule fois), faites-le tourner avec un nouveau secret, et découvrez comment l’appareil signe chaque requête à /api/public/utilities/iot/reads — avec un exemple de requête, les limites et toutes les réponses possibles.

Un compteur AMI ou IoT transmet ses relevés à TRANXACT via HTTPS. Chaque appareil possède une clé générée par le serveur (utd_ suivi de 24 caractères alphanumériques) et un secret. L'appareil s'authentifie à chaque requête, empêchant ainsi toute autre personne de publier des relevés le concernant.

Enregistrement d'un appareil

Ouvrez CRM › Services publics › Compteurs et relevés de services publics › Appareils IoT et appuyez sur Nouveau.
Saisissez une étiquette, choisissez le compteur qu'elle lit et choisissez Signer avec : hmac (une signature HMAC-SHA256 de chaque requête — recommandé), bearer (la clé et le secret envoyés comme jeton) ou les deux.
Définissez le nombre maximal de lectures par minute pour cet appareil, et pour le micrologiciel si vous le connaissez.
Enregistrez. La réponse affiche la clé et le secret : « Copiez le secret maintenant — il ne sera plus affiché. » Saisissez les deux dans la configuration de l’appareil.

Le secret n'est révélé qu'une seule fois. Il n'est plus jamais communiqué par la suite, même à un administrateur ; la liste n'affiche que ses quatre derniers caractères (« Fin du secret »). En cas de perte, un nouveau secret doit être émis.

Faire tourner le secret

Sur la ligne de l'appareil, appuyez sur « Nouveau code secret » et confirmez. Le nouveau code secret s'affiche une seule fois et l'ancien cesse de fonctionner. Saisissez donc le nouveau code secret immédiatement. Définissez l'état sur « Désactivé » pour arrêter un appareil sans rotation, ou sur « Retiré » lorsqu'il est mis hors service.

Comment un appareil signe une lecture

Constituez le corps JSON : une liste de lectures, chacune avec read_at (heure ISO 8601) et reading. Les informations relatives à la batterie, au signal, au firmware et aux alarmes sont facultatives.
Prenez l'heure Unix actuelle en secondes comme horodatage.
Calculez le hachage HMAC-SHA256, sous le secret du périphérique, de l'horodatage, d'un point et des octets exacts du corps : « <horodatage>.<corps> ». Écrivez-le sous la forme de 64 caractères hexadécimaux minuscules.
Envoyez le corps de la requête à /api/public/utilities/iot/reads avec les en-têtes X-Utility-Device (la clé), X-Utility-Timestamp et X-Utility-Signature (l'hexadécimal, éventuellement préfixé par 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 même signature a été utilisée dans un shell pour tester un périphérique avant son installation :

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"

Signez les octets exacts que vous envoyez. Tout reformatage du JSON après signature, ou tout envoi avec une fin de ligne différente, modifie les octets et la signature n'est plus valide.

Un périphérique configuré en mode porteur (ou les deux) peut envoyer l'en-tête Authorization: Bearer <utd_DEVICE_KEY>.<DEVICE_SECRET> sans signature. HMAC est l'option la plus sûre : le secret n'est jamais transmis et une requête interceptée ne peut pas être réutilisée.

Limites

L’horodatage doit être à moins de 5 minutes de l’horloge du serveur : assurez-vous que l’horloge de l’appareil est réglée par NTP.
Une même requête signée deux fois est refusée car il s'agit d'une redite. Une donnée déjà enregistrée est considérée comme un doublon et n'est conservée qu'une seule fois.
Au maximum 64 Ko et 500 lectures par requête, le nombre maximal de lectures par minute de l'appareil et 600 requêtes par minute à partir d'une adresse.
L'appareil doit être actif et connecté à un compteur.

Ce que l'appareil récupère en retour

Répondre	Signification
201 ou 200 avec acceptés, doublons, exceptions, rejetés, alarmes et problèmes	La requête a été prise en compte. Chaque lecture est comptabilisée ; les problèmes signalent toute lecture invalide par son index.
401 authentification de l'appareil	Clé inconnue ou inactive, mode incorrect ou signature non conforme. Le nombre de tentatives refusées par l'appareil augmente.
401 horodatage obsolète	L'horodatage est erroné de plus de 5 minutes.
409 replay	Cette demande signée a déjà été reçue.
413 trop_de_lectures	Plus de 500 lectures en une seule requête.
422 no_meter	L'appareil n'est pas relié à un compteur.
429 débit limité	Envoi plus rapide que la limite. Veuillez patienter et réessayer.
400 bad_json	Le corps du message n'est pas au format JSON.
403 services publics désactivés	Les services publics sont coupés pour l'entreprise.

Santé et alarmes

Chaque requête met à jour la dernière position connue de l'appareil, le pourcentage de batterie et le niveau de signal (dBm). Une batterie inférieure à 15 % déclenche une alarme de batterie faible.
Types d'alarmes qu'un appareil peut envoyer : batterie faible, sabotage, fuite, flux inversé, absence de flux, hors ligne et autres. Une seule alarme de chaque type est active par appareil.
La section Alarmes des appareils les répertorie ; la fonction Effacer en ferme une avec une note. Une fuite déclenche automatiquement une intervention prioritaire ; une alarme de sabotage ou de reflux déclenche également une intervention.
Le chiffre des compteurs IoT du tableau de bord (24h) comptabilise les appareils actifs ayant reçu des informations au cours de la dernière journée.