Documentacao

REST API

Use a API REST da IoTsys para consultar dispositivos, ler estado, acompanhar historico e enviar comandos a partir de sistemas externos.

Autenticação

Gere um token em REST API no painel da sua conta e envie em todas as chamadas no header Authorization.

Authorization: Bearer iotsys_live_SEU_TOKEN
Content-Type: application/json

Listar dispositivos

Retorna dispositivos ativos da conta associada ao token. Use page e per_page para navegar; per_page aceita de 10 a 100 registros.

curl -H "Authorization: Bearer iotsys_live_SEU_TOKEN" \\
  "https://api.iotsys.com.br/api/v1/devices?page=1&per_page=25"

{
  "data": [],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total_count": 0,
    "total_pages": 1
  }
}

Consultar um dispositivo

Retorna detalhes, disponibilidade, estado atual e eventos recentes do dispositivo. Use events_page e events_per_page para paginar o histórico retornado.

curl -H "Authorization: Bearer iotsys_live_SEU_TOKEN" \\
  "https://api.iotsys.com.br/api/v1/devices/1?events_page=1&events_per_page=25"

{
  "data": {
    "id": 1,
    "name": "Ventilador",
    "kind": "switch",
    "availability_status": "online",
    "last_seen_at": "2026-05-03T20:18:42-03:00",
    "state": {
      "power_state": "ON",
      "brightness": null,
      "reported_at": "2026-05-03T20:18:42-03:00"
    },
    "events": [],
    "events_meta": {
      "page": 1,
      "per_page": 25,
      "total_count": 0,
      "total_pages": 1
    }
  }
}

Enviar comando

Publica um comando para o dispositivo. O hardware precisa estar conectado ao MQTT para receber e executar.

curl -X POST https://api.iotsys.com.br/api/v1/devices/1/command \\
  -H "Authorization: Bearer iotsys_live_SEU_TOKEN" \\
  -H "Content-Type: application/json" \\
  -d '{"command":{"type":"power","value":"ON"}}'

{
  "data": {
    "accepted": true,
    "command": {
      "type": "power",
      "value": "ON",
      "source": "rest_api"
    }
  }
}

Status HTTP

Status	Quando ocorre
200	Consulta realizada com sucesso.
202	Comando aceito para envio ao dispositivo.
400	Payload inválido ou campo obrigatório ausente.
401	Token ausente, inválido ou revogado.
404	Dispositivo não encontrado para a conta autenticada.
429	Limite de acessos por hora excedido para o plano atual.
422	O comando não pôde ser publicado.

Limites do plano

O super admin define dois controles por plano: retenção de dados em meses e acessos REST API por hora. Quando o limite por hora é excedido, a API responde 429 com metadados de limite, uso, restante e reset.