Medidores IoT: registrando um dispositivo e como ele assina suas leituras.

Dispositivos IoT: registre uma AMI ou um endpoint IoT, copie seu segredo (mostrado uma vez), alterne-o com um novo segredo e veja como o dispositivo assina cada solicitação para /api/public/utilities/iot/reads — com um exemplo de solicitação, os limites e todas as respostas que ele pode obter.

Um medidor AMI ou IoT envia suas próprias leituras para TRANXACT via HTTPS. Cada dispositivo possui uma chave gerada pelo servidor (utd_ seguido por 24 letras e dígitos) e um segredo. O dispositivo comprova sua identidade a cada requisição, impedindo que outros dispositivos enviem leituras para aquele medidor.

Registrando um dispositivo

Abra o CRM › Serviços Públicos › Medidores e Leituras de Serviços Públicos › Dispositivos IoT e clique em Novo.
Insira um rótulo, escolha o medidor que ele lê e selecione Assinar com: hmac (uma assinatura HMAC-SHA256 de cada solicitação — recomendado), portador (a chave e o segredo enviados como um token) ou ambos.
Defina o número máximo de leituras por minuto para este dispositivo e, se souber, a versão do firmware.
Salve. A resposta mostra a chave e o segredo: “Copie o segredo agora — ele não será exibido novamente.” Insira ambos na configuração do dispositivo.

O segredo é exibido apenas uma vez. Ele nunca mais é listado, nem mesmo para um administrador; a lista mostra apenas seus quatro últimos caracteres (Fim do Segredo). Se for perdido, emita um novo.

Girando o segredo

Na linha do dispositivo, pressione "Nova senha" e confirme. A nova senha será exibida apenas uma vez e a antiga deixará de funcionar nesse momento; portanto, insira a nova senha no dispositivo imediatamente. Defina o status como "Desativado" para interromper um dispositivo sem precisar girá-lo ou como "Retirado de serviço" quando ele for desativado.

Como um dispositivo registra uma leitura

Construa o corpo JSON: uma lista de leituras, cada uma com read_at (tempo ISO 8601) e reading. Battery, signal, firmware e alarms são opcionais.
Utilize o tempo Unix atual em segundos como o registro de data e hora.
Calcule o HMAC-SHA256, sob o segredo do dispositivo, do carimbo de data/hora, um ponto final e os bytes exatos do corpo da mensagem: “<carimbo de data/hora>.<corpo>”. Escreva-o como 64 caracteres hexadecimais em minúsculas.
Envie o corpo da requisição POST para /api/public/utilities/iot/reads com os cabeçalhos X-Utility-Device (a chave), X-Utility-Timestamp e X-Utility-Signature (o valor hexadecimal, opcionalmente prefixado com 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>"}]}

A mesma assinatura funcionou em um shell, para testar um dispositivo antes de sua instalação:

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"

Assine os bytes exatos que você enviar. Reformatar o JSON após a assinatura, ou enviá-lo com uma quebra de linha diferente, altera os bytes e a assinatura deixa de corresponder.

Um dispositivo configurado como portador (ou ambos) pode, em vez disso, enviar Authorization: Bearer <utd_DEVICE_KEY>.<DEVICE_SECRET> sem cabeçalhos de assinatura. O HMAC é a opção mais segura: o segredo nunca é transmitido e uma solicitação capturada não pode ser reproduzida.

Limites

O registro de data e hora deve estar dentro de uma margem de 5 minutos do relógio do servidor: mantenha o relógio do dispositivo sincronizado com o NTP.
A mesma solicitação assinada duas vezes é recusada como uma repetição. Uma leitura já existente no arquivo é considerada duplicada e armazenada apenas uma vez.
No máximo 64 KB e 500 leituras por solicitação, o dispositivo tem um limite máximo de leituras por minuto e 600 solicitações por minuto de um mesmo endereço.
O dispositivo deve estar ativo e conectado a um medidor.

O que o dispositivo recebe de volta

Responder	Significado
201 ou 200 com aceitos, duplicados, exceções, rejeitados, alarmes e problemas	A solicitação foi processada. Cada leitura é contabilizada; o campo "problemas" identifica qualquer leitura que não seja válida de acordo com seu índice.
401 autenticação de dispositivo	Chave desconhecida ou inativa, modo incorreto ou assinatura incompatível. A contagem de rejeições do dispositivo aumenta.
401 timestamp obsoleto	O registro de data e hora está atrasado em mais de 5 minutos.
409 repetição	Este pedido assinado já foi recebido.
413 muitas_leituras	Mais de 500 leituras em uma única solicitação.
422 sem medidor	O dispositivo não está conectado a um medidor.
429 taxa_limitada	Envio acima do limite. Aguarde e tente novamente.
400 json inválido	O corpo da mensagem não está em formato JSON.
403 utilitários_desligados	Os serviços públicos foram desligados para a empresa.

Saúde e alarmes

Cada solicitação atualiza a última visualização do dispositivo, a porcentagem da bateria e o sinal em dBm. Uma bateria com menos de 15% de carga aciona um alarme de bateria fraca.
Tipos de alarmes que um dispositivo pode enviar: bateria fraca, violação, vazamento, fluxo reverso, ausência de fluxo, offline e outros. Um alarme aberto de cada tipo por dispositivo.
A opção Alarmes do Dispositivo lista os alarmes; Limpar fecha um alarme com uma anotação. Um vazamento gera automaticamente uma ordem de serviço de investigação de vazamento de alta prioridade; um alarme de violação ou fluxo reverso também gera uma ordem de serviço.
O indicador de medidores de IoT (24h) do painel de controle contabiliza os dispositivos ativos que detectaram atividade no último dia.