Documentação da API EcoMonitor

A API do EcoMonitor permite gerenciar dispositivos IoT para monitoramento sustentável de recursos hídricos e energéticos. Construída com Node.js, Express e MySQL, ela oferece endpoints RESTful para integração com sistemas externos.

Requisitos Básicos

  • Todas as requisições devem usar HTTPS
  • Todas as respostas são em formato JSON
  • Autenticação via API Key no header

URLs Base

Produção

https://api.ecomonitor.dev/v1

Sandbox

https://api.sandbox.ecomonitor.dev/v1
Nota Importante
Esta documentação está em constante evolução. Recomendamos verificar regularmente por atualizações. Assine nossa newsletter para receber notificações sobre mudanças na API.

Autenticação

Todas as requisições à API EcoMonitor requerem autenticação via API Key. Sua chave de API deve ser incluída em todos os cabeçalhos de requisição.

POST /auth/login

Obtenha um token de acesso usando suas credenciais de desenvolvedor.

Como autenticar

Inclua sua API Key no cabeçalho Authorization de todas as requisições:

Cabeçalho de Autorização
Authorization: Bearer <sua-api-key>
Segurança
Nunca compartilhe sua API Key ou a inclua em código do lado do cliente. Todas as requisições devem ser feitas do lado do servidor para manter sua chave segura.

Níveis de Acesso

Free

  • 100 requisições/dia
  • Acesso somente leitura

Silver

  • 1,000 requisições/dia
  • Acesso completo

Gold

  • Requisições ilimitadas
  • Suporte prioritário

Limites de Taxa

Para garantir a estabilidade do serviço, a API EcoMonitor implementa limites de taxa (rate limiting) baseados no seu plano de assinatura.

Headers de Resposta

Todas as respostas incluem cabeçalhos que mostram seu status atual de limites de taxa:

Cabeçalhos de Limite de Taxa
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 987
X-RateLimit-Reset: 3600
Header Descrição
X-RateLimit-Limit Número total de requisições permitidas no período
X-RateLimit-Remaining Número de requisições restantes no período atual
X-RateLimit-Reset Tempo em segundos até o próximo reset do contador
Excedendo o Limite
Se você exceder seu limite de taxa, receberá uma resposta 429 Too Many Requests. Recomendamos implementar retry com backoff exponencial em seu código para lidar com esses casos.

Listar Dispositivos

Recupera uma lista paginada de todos os dispositivos IoT registrados no sistema. Os dispositivos podem ser filtrados por tipo, status ou localização.

GET /devices

Retorna uma lista de dispositivos com suporte a paginação e filtros.

Parâmetros de Query

Parâmetro Tipo Obrigatório Descrição
limit integer Não Número de dispositivos por página (padrão: 10, máximo: 100)
offset integer Não Número de dispositivos a pular (padrão: 0)
type string Não Filtrar por tipo de dispositivo (water, energy, etc.)
status string Não Filtrar por status (active, inactive, maintenance)
location string Não Filtrar por localização (busca parcial)

Exemplo de Requisição

Requisição
GET /devices?limit=5&type=water&status=active
Authorization: Bearer <sua-api-key>
Accept: application/json

Resposta

200 OK
Sucesso
{
  "status": "success",
  "data": [
    {
      "id": 1,
      "name": "Water Sensor 001",
      "type": "water",
      "location": "Main Building",
      "status": "active",
      "lastReading": "2025-04-23T10:00:00Z",
      "createdAt": "2025-01-15T08:30:00Z",
      "updatedAt": "2025-04-20T14:25:00Z"
    },
    {
      "id": 2,
      "name": "Water Sensor 002",
      "type": "water",
      "location": "Secondary Building",
      "status": "active",
      "lastReading": "2025-04-23T09:45:00Z",
      "createdAt": "2025-02-10T11:20:00Z",
      "updatedAt": "2025-04-21T10:15:00Z"
    }
  ],
  "meta": {
    "total": 12,
    "limit": 5,
    "offset": 0,
    "filter": {
      "type": "water",
      "status": "active"
    }
  }
}

Possíveis Erros

401 Unauthorized - Chave de API ausente ou inválida
403 Forbidden - Permissões insuficientes para acessar este recurso
429 Too Many Requests - Limite de taxa excedido
500 Internal Server Error - Erro interno do servidor
Dica de Performance
Para listas grandes de dispositivos, sempre use os parâmetros limit e offset para implementar paginação no seu aplicativo. Isso melhora significativamente o tempo de resposta.

Criar Dispositivo

Registra um novo dispositivo IoT no sistema EcoMonitor. Requer permissões de escrita.

POST /devices

Cria um novo dispositivo com os parâmetros especificados.

Corpo da Requisição

Parâmetro Tipo Obrigatório Descrição
name string Sim Nome amigável do dispositivo (3-50 caracteres)
type string Sim Tipo do dispositivo (water, energy, temperature, etc.)
location string Sim Localização física do dispositivo
status string Não Status inicial (active, inactive, maintenance - padrão: active)
metadata object Não Dados adicionais sobre o dispositivo
Exemplo de Corpo
{
    "name": "Water Sensor 003",
    "type": "water",
    "location": "Main Building - Floor 2",
    "status": "active",
    "metadata": {
    "model": "WS-2023",
    "installationDate": "2025-04-20"
    }
}

Exemplo de Requisição

Requisição
POST /devices
Authorization: Bearer 
Content-Type: application/json
Accept: application/json

{
    "name": "Water Sensor 003",
    "type": "water",
    "location": "Main Building - Floor 2",
    "status": "active",
    "metadata": {
    "model": "WS-2023",
    "installationDate": "2025-04-20"
    }
}

Resposta

201 Created
Sucesso
{
    "status": "success",
    "data": {
    "id": 3,
    "name": "Water Sensor 003",
    "type": "water",
    "location": "Main Building - Floor 2",
    "status": "active",
    "metadata": {
        "model": "WS-2023",
        "installationDate": "2025-04-20"
    },
    "createdAt": "2025-04-23T12:00:00Z",
    "updatedAt": "2025-04-23T12:00:00Z"
    }
}

Possíveis Erros

400 Bad Request - Parâmetros inválidos ou ausentes
401 Unauthorized - Chave de API ausente ou inválida
403 Forbidden - Permissões insuficientes para criar dispositivos
429 Too Many Requests - Limite de taxa excedido
500 Internal Server Error - Erro interno do servidor
Dica de Implementação
Valide os dados do dispositivo no lado do cliente antes de enviar a requisição para evitar erros 400 Bad Request. Certifique-se de que o campo type corresponde a um dos tipos suportados pela API.

Exemplo de Requisição

Requisição Completa
POST /devices
Authorization: Bearer <sua-api-key>
Content-Type: application/json
Accept: application/json

{
    "name": "Water Sensor 003",
    "type": "water",
    "location": "Warehouse A",
    "status": "active",
    "metadata": {
    "manufacturer": "EcoTech",
    "model": "WS-2025",
    "installationDate": "2025-04-01"
    }
}

Resposta

201 Created
Dispositivo criado
{
    "status": "success",
    "data": {
        "id": 15,
        "name": "Water Sensor 003",
        "type": "water",
        "location": "Warehouse A",
        "status": "active",
        "metadata": {
            "manufacturer": "EcoTech",
            "model": "WS-2025",
            "installationDate": "2025-04-01"
        },
        "createdAt": "2025-04-23T11:30:00Z",
        "updatedAt": "2025-04-23T11:30:00Z"
    }
}

Obter Dispositivo

Recupera os detalhes completos de um dispositivo específico pelo seu ID.

GET /devices/{id}

Retorna todos os detalhes de um dispositivo específico, incluindo seu histórico de configurações.

Parâmetros de URL

Parâmetro Tipo Obrigatório Descrição
id integer Sim ID do dispositivo a ser recuperado

Exemplo de Requisição

Requisição
GET /devices/15
Authorization: Bearer <sua-api-key>
Accept: application/json

Resposta

200 OK
Dispositivo encontrado
{
    "status": "success",
    "data": {
    "id": 15,
    "name": "Water Sensor 003",
    "type": "water",
    "location": "Warehouse A",
    "status": "active",
    "lastReading": null,
    "metadata": {
        "manufacturer": "EcoTech",
        "model": "WS-2025",
        "installationDate": "2025-04-01"
    },
    "createdAt": "2025-04-23T11:30:00Z",
    "updatedAt": "2025-04-23T11:30:00Z",
    "configHistory": []
    }
}

Atualizar Dispositivo

Atualiza as informações de um dispositivo existente. Permite alterar nome, localização, status e metadados.

PUT /devices/{id}

Atualiza parcial ou completamente um dispositivo existente.

Corpo da Requisição

Parâmetro Tipo Obrigatório Descrição
name string Não Novo nome para o dispositivo
location string Não Nova localização para o dispositivo
status string Não Novo status (active, inactive, maintenance)
metadata object Não Metadados atualizados (substitui o objeto completo)
Exemplo de Corpo
{
    "location": "Warehouse A - Sector 2",
    "status": "maintenance",
    "metadata": {
        "manufacturer": "EcoTech",
        "model": "WS-2025",
        "installationDate": "2025-04-01",
        "lastMaintenance": "2025-04-23"
    }
}

Exemplo de Requisição

Requisição Completa
PUT /devices/15
Authorization: Bearer <sua-api-key>
Content-Type: application/json
Accept: application/json

{
    "location": "Warehouse A - Sector 2",
    "status": "maintenance",
    "metadata": {
    "manufacturer": "EcoTech",
    "model": "WS-2025",
    "installationDate": "2025-04-01",
    "lastMaintenance": "2025-04-23"
    }
}

Resposta

200 OK
Dispositivo atualizado
{  
    "status": "success",
    "data": {
    "id": 15,
    "name": "Water Sensor 003",
    "type": "water",
    "location": "Warehouse A - Sector 2",
    "status": "maintenance",
    "metadata": {
        "manufacturer": "EcoTech",
        "model": "WS-2025",
        "installationDate": "2025-04-01",
        "lastMaintenance": "2025-04-23"
    },
    "createdAt": "2025-04-23T11:30:00Z",
    "updatedAt": "2025-04-23T12:45:00Z"
    }
}

Remover Dispositivo

Remove permanentemente um dispositivo do sistema. Esta ação é irreversível.

DELETE /devices/{id}

Remove um dispositivo e todos os seus dados associados.

Parâmetros de URL

Parâmetro Tipo Obrigatório Descrição
id integer Sim ID do dispositivo a ser removido

Exemplo de Requisição

Requisição
DELETE /devices/15
Authorization: Bearer <sua-api-key>
Accept: application/json

Resposta

204 No Content
Dispositivo removido
// Sem conteúdo no corpo da resposta

Possíveis Erros

401 Unauthorized - Chave de API ausente ou inválida
403 Forbidden - Permissões insuficientes para esta ação
404 Not Found - Dispositivo não encontrado
500 Internal Server Error - Erro ao remover o dispositivo
Aviso Importante
A remoção de um dispositivo é permanente e irá apagar todos os dados associados, incluindo históricos de leitura. Considere desativar o dispositivo (status=inactive) em vez de removê-lo, caso precise preservar os dados.

Obter Leituras

Recupera as leituras de um dispositivo específico ou de todos os dispositivos, com suporte a filtros por data e tipo.

GET /readings

Retorna leituras paginadas com suporte a diversos filtros.

Parâmetros de Query

Parâmetro Tipo Obrigatório Descrição
deviceId integer Não Filtrar por ID do dispositivo
type string Não Filtrar por tipo de leitura (water_level, energy_consumption, etc.)
startDate string Não Data de início (formato ISO 8601)
endDate string Não Data de fim (formato ISO 8601)
limit integer Não Número de leituras por página (padrão: 50, máximo: 1000)
offset integer Não Número de leituras a pular (padrão: 0)

Exemplo de Requisição

Requisição
GET /readings?deviceId=15&type=water_level&startDate=2025-04-01&endDate=2025-04-23&limit=100
Authorization: Bearer <sua-api-key>
Accept: application/json

Resposta

200 OK
Leituras encontradas
{
    "status": "success",
    "data": [
    {
        "id": 12345,
        "deviceId": 15,
        "type": "water_level",
        "value": 42.5,
        "unit": "cm",
        "timestamp": "2025-04-22T08:30:00Z",
        "metadata": {
            "sensorBattery": 85,
            "signalStrength": "good"
        }
    },
    {
        "id": 12346,
        "deviceId": 15,
        "type": "water_level",
        "value": 41.8,
        "unit": "cm",
        "timestamp": "2025-04-22T09:30:00Z",
        "metadata": {
            "sensorBattery": 84,
            "signalStrength": "good"
        }
    }
    ],
    "meta": {
        "total": 48,
        "limit": 100,
        "offset": 0,
        "filter": {
            "deviceId": 15,
            "type": "water_level",
            "dateRange": {
                "start": "2025-04-01T00:00:00Z",
                "end": "2025-04-23T23:59:59Z"
            }
        }
    }
}

Enviar Leitura

Envia uma nova leitura de dados para um dispositivo específico.

POST /readings

Registra uma nova leitura no sistema para processamento e análise.

Corpo da Requisição

Parâmetro Tipo Obrigatório Descrição
deviceId integer Sim ID do dispositivo que gerou a leitura
type string Sim Tipo de leitura (ex: water_level, energy_consumption)
value number Sim Valor numérico da leitura
unit string Sim Unidade de medida (ex: cm, kWh, °C)
timestamp string Não Data/hora da leitura (ISO 8601, padrão: agora)
metadata object Não Dados adicionais sobre a leitura
Exemplo de Corpo
{
    "deviceId": 15,
    "type": "water_level",
    "value": 43.2,
    "unit": "cm",
    "timestamp": "2025-04-23T14:30:00Z",
    "metadata": {
        "sensorBattery": 83,
        "signalStrength": "excellent",
        "accuracy": 0.5
    }
}

Exemplo de Requisição

Requisição Completa
POST /readings
Authorization: Bearer <sua-api-key>
Content-Type: application/json
Accept: application/json

{
    "deviceId": 15,
    "type": "water_level",
    "value": 43.2,
    "unit": "cm",
    "timestamp": "2025-04-23T14:30:00Z",
    "metadata": {
    "sensorBattery": 83,
    "signalStrength": "excellent",
    "accuracy": 0.5
    }
}

Resposta

201 Created
Leitura registrada
{
    "status": "success",
    "data": {
    "id": 12347,
    "deviceId": 15,
    "type": "water_level",
    "value": 43.2,
    "unit": "cm",
    "timestamp": "2025-04-23T14:30:00Z",
    "metadata": {
        "sensorBattery": 83,
        "signalStrength": "excellent",
        "accuracy": 0.5
    },
    "createdAt": "2025-04-23T14:30:05Z"
    }
}

Downloads

Recursos úteis para integrar com a API EcoMonitor.

SDKs e Bibliotecas

Postman Collection

Coleção completa de endpoints para testar a API no Postman.

Baixar Collection

Suporte

Precisa de ajuda ou tem dúvidas sobre a API? Entre em contato com nossa equipe.

Email

api-support@ecomonitor.dev

Resposta em até 24h (dias úteis)

Chat Online

Disponível no painel de desenvolvedor

Seg-Sex: 9h-18h (horário de Brasília)

Documentação

Guia do Desenvolvedor

Tutoriais e exemplos completos