Documentação técnica

API REST

Referência da API HTTP disponível no TechLabsOS mais novo para consulta de telemetria, estado do equipamento e acionamento do relé.

Esta documentação reflete a organização atual do Plus v3 no TechLabsOS mais novo, com autenticação Bearer, respostas JSON e suporte a CORS.

Visão geral

A API expõe dois endpoints principais: GET /api para leitura completa do dispositivo e POST /api/relay para controle do relé quando o modo manual estiver habilitado.

Autenticação

Bearer token obrigatório nas rotas de consulta e comando.

Formato

Respostas em application/json com blocos success, message e data.

CORS

As rotas aceitam OPTIONS e liberam origem *.

Autenticação

Inclua o token no cabeçalho Authorization em todas as chamadas protegidas.

Authorization: Bearer SEU_TOKEN_AQUI

Se o token for inválido ou ausente, a requisição é interrompida pela validação interna antes da montagem da resposta da API.

Endpoint de leitura

Consulta consolidada de sistema, rede, monitoramento e conectividade.

GET /api

Exemplo

curl -X GET "http://IP_DO_EQUIPAMENTO/api" \
  -H "Authorization: Bearer SEU_TOKEN_AQUI"

Campos retornados

system

Informações como uptime, hostname, nome do software, versão, build e revisão da placa.

network

Tipo de rede, MAC, IP local, gateway, máscara, DNS e status do cabo.

monitoring

Temperatura, tensões DC, nomes dos canais, entradas digitais e estado lógico do relé.

connectivity

Status das integrações, incluindo SNMP, API habilitada e comunidade configurada.

Resposta exemplo

{
  "success": true,
  "data": {
    "system": {
      "uptime": 12854,
      "hostname": "plus-v3",
      "softwareName": "TechLabsOS",
      "softwareVersion": "0.6.1",
      "softwareBuild": "2026-07",
      "boardVersion": "Plus v3"
    },
    "network": {
      "networkType": "ethernet",
      "macAddress": "AA:BB:CC:DD:EE:FF",
      "localIP": "192.168.94.4",
      "gatewayIP": "192.168.94.1",
      "subnetMask": "255.255.255.0",
      "dnsIP1": "8.8.8.8",
      "dnsIP2": "1.1.1.1",
      "cable": true
    },
    "monitoring": {
      "tempName0": "Temperatura interna",
      "temp0": 31.4,
      "voltageDCName0": "Fonte A",
      "voltageDCName1": "Fonte B",
      "voltageDCName2": "Banco",
      "voltageDC0": 12.9,
      "voltageDC1": 12.7,
      "voltageDC2": 13.1,
      "sensorInputName0": "Porta",
      "sensorInputName1": "Alarme",
      "sensorInputValue0": 0,
      "sensorInputValue1": 1,
      "relay0Name": "Relé 1",
      "relay0Value": 1
    },
    "connectivity": {
      "snmp": true,
      "api": true,
      "community": "public"
    }
  }
}

Endpoint de comando do relé

Aciona ou desliga o relé via comando textual ou booleano normalizado pela API.

POST /api/relay

Parâmetros aceitos

Campo	Obrigatório	Descrição
`cmd`	Não*	Aceita `on`, `off`, `true`, `false`, `1` ou `0`.
`state`	Não*	Alternativa ao campo `cmd` com a mesma interpretação.

* Pelo menos um dos dois campos deve ser enviado no corpo da requisição.

Exemplo

curl -X POST "http://IP_DO_EQUIPAMENTO/api/relay" \
  -H "Authorization: Bearer SEU_TOKEN_AQUI" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "cmd=on"

Resposta de sucesso

{
  "success": true,
  "message": "Relay updated successfully.",
  "data": {
    "relay0Name": "Relé 1",
    "relay0Value": 1,
    "relay0State": "on",
    "relay0Config": 1
  }
}

Códigos de retorno esperados

200

Consulta concluída ou relé atualizado com sucesso.

400

Comando inválido para o relé. Use on/off, true/false ou 1/0.

409

Controle bloqueado porque o relé não está configurado em modo manual.

As rotas também respondem a OPTIONS para pré-validação CORS, com liberação dos métodos GET, POST e OPTIONS conforme cada endpoint.