WEBHOOK

Envio HTTP da telemetria da BMS

O Webhook envia a telemetria atual do EasyMonitor para um servidor HTTP ou HTTPS. Ele e somente leitura: não recebe comandos nem altera configurações da BMS.

Método

POST JSON

Um payload completo por envio.

Intervalo

60 segundos

Apenas com Wi-Fi e BMS online.

Sucesso

Qualquer HTTP 2xx

Resposta em até 3 segundos.

Configuração e pre-requisitos

Em Gerenciar dispositivo > Webhook, informe uma URL iniciada por http:// ou https:// e um token. Para aplicar a configuração, o EasyMonitor reinicia. O envio acontece somente quando o recurso está habilitado, a URL e o token existem, o Wi-Fi está conectado e a BMS tem telemetria válida.

Sem fila persistente: o firmware não armazena entregas. Se a rede ou o servidor falhar, aquele pacote é perdido e uma nova tentativa ocorrerá somente no próximo ciclo de 60 segundos.

Contrato HTTP

Item	Valor
Método	`POST`
Content-Type	`application/json`
Autorizacao	`Authorization: Bearer <token>`
Timeout	3 segundos para conexão e resposta.
Código de sucesso	Qualquer código de `200` a `299`.
Tamanho máximo	Payload JSON menor que 6144 bytes.

POST /integrations/easymonitor HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: Bearer seu-token-secreto

{ ...payload JSON... }

Payload enviado

O corpo segue a mesma estrutura de telemetria completa da API. Campos numéricos usam unidades do Sistema Internacional: tensão em V, corrente em A, potência em W, capacidade em Ah, temperatura em C e tempos em segundos.

{
  "success": true,
  "data": {
    "device": {
      "id": "EASYM_68F29C",
      "hostname": "EasyMonitor",
      "software": "TechLabsOS Smart BMS",
      "version": "0.0.1"
    },
    "network": { "mode": "STA", "ip": "192.168.1.20", "mac": "88:13:BF:68:F2:9C" },
    "bms": {
      "online": true,
      "name": "EasyMonitor2",
      "model": "JK-BD6A24S10PD",
      "transport": "uart",
      "transportLabel": "Serial RS485",
      "protocol": "JK BMS RS485 Modbus V1.0",
      "soc": 96,
      "capacityAh": 8,
      "remainingCapacityAh": 7.642,
      "cycles": 0,
      "pack": { "voltage": 28.926, "current": 0, "power": 0 },
      "cellsSummary": { "minVoltage": 4.127, "minCell": 7, "maxVoltage": 4.134, "maxCell": 1, "delta": 0.007 },
      "temperatures": { "mosfet": 32.8, "battery1": 30.5, "battery2": 30.3 },
      "operations": { "chargeMos": true, "dischargeMos": true, "balanceEnabled": true },
      "alarmCode": 0,
      "alarmsHex": "0x00000000",
      "alarms": [],
      "cells": [{ "number": 1, "voltage": 4.134, "wireResistanceMilliOhm": 346 }]
    }
  }
}

Campos principais

Campo	Descrição
`data.device`	Identidade, software e versão do EasyMonitor.
`data.network`	Modo, IP e MAC da rede ativa.
`data.bms.transport`	`uart` para Serial RS485 ou `ble` para Bluetooth JK02.
`data.bms.pack`	Tensão, corrente e potência do pack.
`data.bms.cellsSummary`	Menor, maior e diferença de tensão entre células.
`data.bms.cells`	Array com número, tensão e resistência do fio de cada célula.
`data.bms.temperatures`	Temperaturas do MOSFET e dos sensores da bateria.
`data.bms.operations`	Estados de carga, descarga, balanceamento e controles operacionais.
`data.bms.alarmCode` e `alarms`	Bitmask bruto e lista traduzida dos alarmes ativos.

Como implementar o receptor

1. Exponha uma rota que aceite POST JSON.
2. Valide o header Bearer antes de processar o corpo.
3. Leia data.device.id para identificar a unidade.
4. Aceite campos novos para manter compatibilidade futura.
5. Responda 204 ou outro 2xx em menos de 3 segundos.

Diagnóstico

Resposta HTTP: o servidor respondeu fora da faixa 2xx.

Falha de conexão: DNS, rota, certificado, servidor indisponível ou timeout.

Payload inválido: a telemetria não coube no buffer interno.

Nenhum envio: valide Wi-Fi, BMS online, URL, token e a chave de habilitação.

Segurança HTTPS

O firmware aceita URLs HTTPS e protege o trafego durante o transporte, mas a versão atual não válida o certificado nem o hostname do servidor. Use uma rede confiável, tokens longos e exclusivos e prefira um endpoint privado. Não envie tokens ou dados sensiveis para servidores que voce não controla.