// documentação

API pública & formato de ingestão

Tudo o que a sua instância de dados aceita e serve, em duas superfícies:

1. Ingestão MQTT — seus dispositivos escrevem direto na sua instância através do broker.
2. API REST de consumo — leia o que foi escrito (métricas, dispositivos, últimos valores) para montar dashboards, alertas e integrações.

Seu arquivo de credenciais (entregue por e-mail na compra — ou gerado na hora no teste grátis) contém tudo o que é referenciado abaixo: host e porta do broker, usuário e senha MQTT, seu namespace de tópicos e sua API key.

1. Ingestão MQTT

Conexão

Tópicos

Suas credenciais são restritas por ACL ao seu namespace:

metrics/<namespace>/<device_key>   # ingestão de séries temporais
notify/<namespace>/<device_key>    # gatilho de notificação WhatsApp (addon WhatsApp)

'<device_key>' é qualquer identificador que você escolher (ex.: METRIC_01). Dispositivos se auto-registram no primeiro publish — não existe etapa de cadastro.

Payload de métricas (metrics/…)

{
  "metrics": {
    "temperature": 4.2,
    "humidity": 61,
    "door_open": 0
  },
  "timestamp": "2026-06-11T14:03:22Z"
}

Regras (mensagens que violem qualquer uma são rejeitadas, nunca aceitas parcialmente):

• +metrics: objeto com 1–100 entradas.
• +Chaves: strings não vazias, máx. 64 caracteres.
• +Valores: números finitos (booleanos como 0/1).
• +timestamp (opcional): ISO 8601; o padrão é o horário de chegada.

QoS 1 recomendado. Reenviar é seguro — a ingestão deduplica na camada de armazenamento.

Payload de notificação (notify/…, addon WhatsApp)

Uma mensagem com "mode": "NOTIFY" é casada com seus templates configurados (condições de match sobre qualquer campo do payload) e enviada via WhatsApp para os destinatários configurados para aquele dispositivo:

{
  "device": "METRIC_01",
  "mode": "NOTIFY",
  "channel": "T1",
  "event": "LOW",
  "triggered": true,
  "temperature": 4.2,
  "alarm_min": 5,
  "alarm_max": 8
}

Os campos são livres: os templates ligam qualquer campo do payload (ou metadado do dispositivo) às variáveis do template de WhatsApp. Configure templates e destinatários por dispositivo no app (Notificações) ou pela API de gerenciamento.

2. API REST de consumo

Header de autenticação em toda requisição: https://<app>/api/v1

Authorization: Bearer flx_<your api key>

Erros são sempre {"error": string, "code": string} com códigos de status convencionais (401 unauthorized, 400 invalid_query, 404 not_found).

GET /api/v1/devices

Todos os dispositivos da sua instância.

{
  "devices": [
    {
      "key": "METRIC_01",
      "name": "METRIC_01",
      "is_active": true,
      "last_seen_at": "2026-06-11T14:03:25Z",
      "created_at": "2026-06-11T10:00:00Z",
      "group_key": "t3f9a1c2e"
    }
  ]
}

GET /api/v1/metrics

Consulta de séries temporais.

{
  "device_key": "METRIC_01",
  "metric": "temperature",
  "from": "2026-06-10T14:00:00.000Z",
  "to": "2026-06-11T14:00:00.000Z",
  "count": 2,
  "points": [
    { "metric": "temperature", "value": 4.6, "timestamp": "2026-06-10T14:05:00Z" },
    { "metric": "temperature", "value": 4.2, "timestamp": "2026-06-10T14:10:00Z" }
  ]
}

Dados recentes são servidos pelo armazenamento quente; dados antigos, pelo arquivo — de forma transparente, num único endpoint.

GET /api/v1/latest

Valor atual de cada métrica por dispositivo (tiles de dashboard). Filtro opcional ?group_key=.

{
  "values": [
    {
      "group_key": "t3f9a1c2e",
      "device_key": "METRIC_01",
      "metric": "temperature",
      "value": 4.2,
      "updated_at": "2026-06-11T14:10:00Z"
    }
  ]
}

Ciclo de vida das chaves

O teste grátis passa pela mesma esteira: instância provisionada na hora, sem cartão, com o mesmo arquivo de credenciais e o mesmo ciclo de vida de chaves.

• +As chaves funcionam imediatamente após o signup (teste grátis) ou a compra; o app mostra um aviso informativo de revisão por 4 horas.
• +Rotacione ou revogue qualquer credencial pelo app. Suspensão (revisão de fraude) desativa a autenticação MQTT e a API key simultaneamente.