API de Ingestão | Flumio - API Documentation

A API de Ingestão permite-te enviar dados dos teus sensores para o Flumio. Precisas de uma conta de Administrador e dos nomes exatos dos sensores registados no sistema.

Propriedade	Valor
URL base	`https://api.flumio.app`
Autenticação	Cookies (definidos automaticamente no login)
Formato dos dados	JSON (`application/json`)

Autenticação

`POST /auth/login`

Content-Type: application/x-www-form-urlencoded

Utiliza este endpoint para te autenticares no Flumio:

Campo	Tipo	Descrição
`username`	string	O teu e-mail (não um nome de utilizador)
`password`	string	A tua palavra-passe

A resposta define automaticamente cookies de sessão. O token de acesso expira após 15 minutos — para renovar, envia POST /auth/refresh (válido por 7 dias).

Envio de dados

`POST /ingestion/ingest_time_series`

Utiliza este endpoint para enviares medições para o Flumio:

{
  "entries": [
    {
      "sensor": "CAUDAL_ZMC_01",
      "timestamp": "2025-01-15T10:00:00+00:00",
      "value": 12.5
    },
    {
      "sensor": "PRESSAO_NO_42",
      "timestamp": "2025-01-15T10:00:00+00:00",
      "value": 3.2
    }
  ]
}

Campo	Tipo	Descrição
`entries[].sensor`	string	Nome exato do sensor (case-sensitive)
`entries[].timestamp`	string	ISO 8601 com offset de timezone
`entries[].value`	float ou string	Valor numérico da medição

Os valores são convertidos automaticamente para unidades SI.

Formato do timestamp

O timestamp deve incluir o offset de timezone:

YYYY-MM-DDTHH:MM:SS+HH:MM

2025-01-15T10:30:00+00:00       # UTC
2025-01-15T10:30:00+01:00       # Europe/Lisbon (inverno)

Formato	Aceite?	Problema
`2025-01-15T10:30:00+00:00`	Sim	—
`2025-01-15T10:30:00Z`	Não	Sufixo `Z` não é aceite — utiliza `+00:00`
`2025-01-15 10:30:00+00:00`	Não	Espaço em vez de `T`
`2025-01-15T10:30:00`	Não	Falta o offset

Validação

Cada registo (timestamp e respetivo valor) é validado individualmente. Registos inválidos são colocados em quarentena — os restantes continuam a ser processados.

Regra
O sensor deve existir no Flumio
O sensor deve estar Ativo
O timestamp deve seguir o formato exigido e representar uma data válida
O valor deve ser um número finito (sem `NaN` ou `Infinity`)
Sensores de tipo `Estado` apenas aceitam `0` ou `1`
Não pode haver duplicados `(sensor, timestamp)` na mesma submissão

Verificar sensores

`GET /timeseries/signal_status_table`

Consulta este endpoint para confirmares os nomes dos teus sensores e o último timestamp ingerido:

{
  "sensors": [
    {
      "sensor": "CAUDAL_ZMC_01",
      "timestamp": "2025-01-15T10:30:00+00:00",
      "value": 12.5
    },
    {
      "sensor": "PRESSAO_NO_42",
      "timestamp": null,
      "value": null
    }
  ]
}

Utiliza o campo timestamp para enviares apenas dados novos (posteriores ao último registo). Quando timestamp é null, o sensor ainda não tem dados — nesse caso, envia dados desde a data que considerares adequada.

Verificar resultados

`GET /tasks/status/{task_id}`

A ingestão é processada em segundo plano. A resposta imediata inclui um task_id — consulta o estado em GET /tasks/status/{task_id}. Quando task_state for SUCCESS, o campo task_result indica:

`job_status`	Significado
`success`	Todas as entradas processadas
`warning`	Algumas entradas em quarentena (ver `details.quarantined`)
`invalid`	Todas as entradas em quarentena

Erros

Consulta os códigos de erro e respetivas descrições:

Código	Descrição
400	Formato do pedido inválido
401	Sessão ausente ou expirada — re-autentica ou renova o token
403	Sem permissão — apenas Administradores podem ingerir
413	Payload demasiado grande — limita cada pedido a ~5 MB
429	Rate limit excedido