REST API

A app api expõe endpoints REST via Django REST Framework para o app Flet consumir.

Autenticação

Token-based (DRF TokenAuthentication). Todo request autenticado deve incluir:

Authorization: Token <token>

O token é obtido via POST /api/auth/token/ com e-mail e senha.

Todos os endpoints retornam somente dados do usuário autenticado (escopo por owner.effective_owner). Tentar acessar dado de outro usuário retorna 403 ou 404.

Contas visualizadoras: tokens de contas visualizadoras (somente-leitura, ver PRD.md seção 6.11) autenticam normalmente e leem os dados do owner vinculado, mas todo endpoint de escrita (POST/PUT/PATCH/DELETE) retorna 403 Forbidden para essas contas (api.permissions.DenyViewerWrite).

---

Endpoints

Autenticação

Método	Rota	Descrição
POST	/api/auth/token/	Autentica por e-mail e senha; retorna o token

Body:

{ "email": "usuario@email.com", "password": "senha" }

Resposta 200:

{ "token": "abc123..." }

---

Medidores

Método	Rota	Descrição
GET	/api/meters/	Lista os medidores do usuário e seus status
GET	/api/meters/{id}/	Detalha um medidor

---

Telemetria

Método	Rota	Descrição
GET	/api/meters/{id}/readings/	Leituras do medidor (filtráveis por período)
GET	/api/meters/{id}/summary/	KPIs: potência atual (W), kWh do ciclo, custo estimado (R$)

Query params para /readings/:

Param	Tipo	Exemplo
start	date	2026-06-01
end	date	2026-06-30

---

Tarifas

Método	Rota	Descrição
GET	/api/tariffs/	Lista as tarifas do usuário
POST	/api/tariffs/	Cria uma tarifa
PUT	/api/tariffs/{id}/	Atualiza uma tarifa
DELETE	/api/tariffs/{id}/	Remove uma tarifa (204 No Content)

Tarifa branca (postos horários — Sprint 16): quando is_white: true, o corpo da requisição deve incluir rate_source, rate_source_date e o campo extra time_slots (lista de exatamente 3 postos — não faz parte dos campos do model, tratado à parte na view):

{
  "name": "Tarifa Branca CELESC",
  "price_per_kwh": "1.0000",
  "flag_color": "green",
  "flag_extra_cost": "0",
  "taxes_percent": "0",
  "is_active": true,
  "is_white": true,
  "rate_source": "Resolução Homologatória ANEEL nº 1234/2026",
  "rate_source_date": "2026-01-01",
  "time_slots": [
    { "period_type": "peak", "start_time": "18:00:00", "end_time": "21:00:00", "price_per_kwh": "2.0000" },
    { "period_type": "intermediate", "start_time": "21:00:00", "end_time": "22:30:00", "price_per_kwh": "1.5000" },
    { "period_type": "off_peak", "start_time": "22:30:00", "end_time": "18:00:00", "price_per_kwh": "0.5000" }
  ]
}

A resposta (e o GET /api/tariffs/) sempre inclui time_slots (lista, vazia para tarifas não-brancas) com id, period_type, period_type_display, start_time, end_time, price_per_kwh.

---

Analytics (IA)

Método	Rota	Descrição
GET	/api/meters/{id}/forecast/	Previsão de fatura: kWh estimado, custo em R$ e confiança (404 se não houver previsão gerada ainda)
POST	/api/meters/{id}/forecast/	Gera uma nova previsão de fatura sob demanda (201 Created)
GET	/api/meters/{id}/disaggregation/	Composição de consumo por aparelho (NILM)
GET	/api/meters/{id}/usage-suggestions/	Recomendação de horário de uso (Sprint 17) — melhor posto por aparelho conhecido, com base na tarifa branca ativa. Lista vazia sem tarifa branca ativa ou sem aparelhos conhecidos.

Resposta de /usage-suggestions/:

[
  {
    "appliance_id": 3,
    "appliance_name": "Chuveiro Elétrico",
    "recommended_period_type": "off_peak",
    "recommended_period_display": "Fora de Ponta",
    "recommended_start": "22:30:00",
    "recommended_end": "18:00:00",
    "worst_period_display": "Ponta",
    "usage_hours": 1.0,
    "kwh_per_use": 5.0,
    "cost_at_recommended": 2.5,
    "cost_at_worst": 10.0,
    "estimated_savings": 7.5
  }
]

---

Códigos de resposta

Código	Situação
200	OK
201	Criado
400	Dados inválidos
401	Sem autenticação ou token inválido
403 / 404	Recurso de outro usuário