Medições de energia

Antes de existir oferta, ordem ou pagamento, o medidor precisa enviar uma medição assinada. No fluxo atual, o device envia os dados a cada 15 minutos. A plataforma aceita o formato MVP em kWh e o formato da dissertação em Wh.

Visão geral

A avaliação de mercado é assíncrona (Celery Beat). O POST de medição apenas persiste; o matching corre no ciclo periódico do Market Service.

Headers obrigatórios

Header	Uso
`X-Sensor-Id`	UUID do sensor ou `deviceId`, por exemplo `es-sms-01`
`X-Sensor-Signature`	HMAC SHA-256 do JSON enviado

O HMAC usa o segredo public_key guardado no Meters Service. O Gateway serializa o JSON com chaves ordenadas e separadores compactos antes de validar a assinatura.

Formato MVP

{
  "sensor_id": "7ae3dd7e-e7b9-4ad9-bd4a-b031040790a3",
  "produced_kwh": 3.5,
  "consumed_kwh": 2.1,
  "net_kwh": 1.4,
  "measured_at_utc": "2026-07-10T02:30:00+00:00"
}

Regras:

produced_kwh e consumed_kwh não podem ser negativos;
net_kwh deve corresponder a produced_kwh - consumed_kwh, arredondado para 4 casas;
measured_at_utc aceita ISO 8601 e é normalizado para UTC;
o sensor do header precisa coincidir com sensor_id.

Campos opcionais:

reactive_inductive_varh
reactive_capacitive_varh

Formato da dissertação

{
  "deviceId": "es-sms-01",
  "activeImport": 1458300,
  "activeExport": 4274200,
  "reactiveInductive": 0,
  "reactiveCapacitive": 0,
  "timestamp": "2026-07-08T17:28:34.595467+00:00"
}

Regras:

activeImport é consumo em Wh;
activeExport é produção em Wh;
os dois campos são obrigatórios e não podem ser negativos;
o Gateway converte Wh para kWh e calcula net_kwh;
deviceId precisa coincidir com X-Sensor-Id.

Não misture os dois formatos no mesmo payload. Se houver campos MVP e dissertação juntos, a API retorna AMBIGUOUS_MEASUREMENT_FORMAT.

Persistência no Meters

O Meters Service valida e grava a medição no InfluxDB. Regras principais:

a cadência esperada é uma medição a cada 15 minutos por sensor;
a medição não pode estar mais de 15 minutos no futuro;
não pode existir outra medição do mesmo sensor no mesmo timestamp;
o sensor precisa existir;
last_communication_at é atualizado quando a medição gravada é mais recente.

As consultas internas por janela aceitam no máximo 60 minutos por chamada e respeitam o limite configurado em MEASUREMENTS_WINDOW_MAX.

Resposta ao device

Depois de gravar a medição, o Gateway consulta pagamentos pendentes no Transactions Service e devolve:

{
  "sensor_id": "7ae3dd7e-e7b9-4ad9-bd4a-b031040790a3",
  "produced_kwh": 3.5,
  "consumed_kwh": 2.1,
  "net_kwh": 1.4,
  "measured_at_utc": "2026-07-10T02:30:00+00:00",
  "pending_payments": []
}

Se houver pagamentos, o device comprador grava a transação sem assinatura na fila local e o worker de pagamentos processa depois.

Motivos comuns de rejeição

Código	Quando acontece
`MISSING_SENSOR_HEADERS`	Faltou `X-Sensor-Id` ou `X-Sensor-Signature`
`SENSOR_HEADER_MISMATCH`	Header e payload apontam para sensores diferentes
`INVALID_SENSOR_SIGNATURE`	HMAC não bate com o payload
`SENSOR_NOT_ACTIVE`	Sensor está `blocked`
`SENSOR_MISSING_PUBLIC_KEY`	Sensor não tem segredo HMAC
`INVALID_NET_KWH`	`net_kwh` não corresponde à diferença entre produção e consumo
`DUPLICATE_MEASUREMENT_TIMESTAMP`	Já existe medição para o mesmo sensor e timestamp

Comercialização

Como a medição vira oferta, ordem ou trade

BrightCity Chain

Contratos

Plataforma energética

Visão geral

Headers obrigatórios

Formato MVP

Formato da dissertação

Persistência no Meters

Resposta ao device

Motivos comuns de rejeição

Comercialização

​Visão geral

​Headers obrigatórios

​Formato MVP

​Formato da dissertação

​Persistência no Meters

​Resposta ao device

​Motivos comuns de rejeição

Comercialização

Visão geral

Headers obrigatórios

Formato MVP

Formato da dissertação

Persistência no Meters

Resposta ao device

Motivos comuns de rejeição