Endpoints de Agendamentos

Agendamentos permitem automatizar ações de ligar/desligar em horários específicos.

Regra Importante

Cada ponto de controle pode ter apenas 1 agendamento ativo. Criar um novo agendamento irá atualizar o existente (comportamento upsert).

Todos os endpoints requerem autenticação.

Authorization: Bearer <token>

---

Objeto Schedule

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "control_point_id": "cp-uuid",
  "action": "ON",
  "start_time": "2025-12-10T06:00:00Z",
  "end_time": "2025-12-10T08:00:00Z",
  "repeat_pattern": "WEEKLY",
  "days_of_week": [1, 2, 3, 4, 5],
  "is_active": true,
  "description": "Aeração matinal - Dias úteis",
  "created_at": "2025-11-21T10:30:00Z",
  "updated_at": null
}

---

Ações de Agendamento

Ação	Descrição
ON	Ligar no horário especificado
OFF	Desligar no horário especificado

Padrões de Repetição

Padrão	Descrição	Requer
ONCE	Executar apenas uma vez	start_time
DAILY	Repetir todos os dias	start_time
WEEKLY	Repetir toda semana	start_time, days_of_week
MONTHLY	Repetir todo mês	start_time
YEARLY	Repetir todo ano	start_time

Nota

Os valores de action e repeat_pattern são case-insensitive (on, ON, On são aceitos).

Tratamento de Timezone

Todos os timestamps são armazenados e retornados em UTC (formato ISO 8601 com sufixo Z). Os horários de agendamento devem ser criados em UTC. O frontend é responsável por converter os timestamps para o timezone configurado do usuário para exibição.

Dias da Semana

Para o padrão WEEKLY, os dias são representados como inteiros:

Valor	Dia
1	Segunda-feira
2	Terça-feira
3	Quarta-feira
4	Quinta-feira
5	Sexta-feira
6	Sábado
7	Domingo

Regras de Validação:

• Valores devem estar entre 1 e 7
• Valores duplicados não são permitidos

---

POST /control-points/{control_point_id}/schedules

Cria ou atualiza um agendamento para um ponto de controle.

Dica

Com a regra de 1 agendamento por ponto de controle, se já existir um agendamento, este endpoint atualiza o existente (comportamento upsert).

Parâmetros de URL

Parâmetro	Tipo	Descrição
control_point_id	UUID	ID do ponto de controle

Requisição

POST /api/v1/control-points/cp-uuid/schedules
Authorization: Bearer <token>
Content-Type: application/json

{
  "action": "ON",
  "start_time": "2025-12-10T06:00:00Z",
  "end_time": "2025-12-10T08:00:00Z",
  "repeat_pattern": "WEEKLY",
  "days_of_week": [1, 2, 3, 4, 5],
  "is_active": true,
  "description": "Aeração matinal - Dias úteis"
}

Parâmetros do Body

Campo	Tipo	Obrigatório	Padrão	Descrição
action	enum	✅	-	Ação a executar (ON ou OFF)
start_time	datetime	✅	-	Hora de início (ISO 8601)
end_time	datetime	❌	-	Hora de término (opcional)
repeat_pattern	enum	❌	ONCE	Padrão de repetição
days_of_week	array[int]	❌	-	Dias da semana (1-7) para WEEKLY
is_active	boolean	❌	true	Se o agendamento está ativo
description	string	❌	-	Descrição do agendamento

Resposta 201 Created

{
  "id": "schedule-uuid",
  "control_point_id": "cp-uuid",
  "action": "ON",
  "start_time": "2025-12-10T06:00:00Z",
  "end_time": "2025-12-10T08:00:00Z",
  "repeat_pattern": "WEEKLY",
  "days_of_week": [1, 2, 3, 4, 5],
  "is_active": true,
  "description": "Aeração matinal - Dias úteis",
  "created_at": "2025-11-21T10:30:00Z",
  "updated_at": null
}

Possíveis Erros

Status	Detalhe
404	Ponto de controle não encontrado
422	Erro de validação (days_of_week inválidos, duplicados, etc.)

---

GET /control-points/{control_point_id}/schedules

Lista os agendamentos de um ponto de controle.

Nota

Com a regra de 1 agendamento por ponto de controle, este endpoint retorna 0 ou 1 item.

Parâmetros de URL

Parâmetro	Tipo	Descrição
control_point_id	UUID	ID do ponto de controle

Requisição

GET /api/v1/control-points/cp-uuid/schedules
Authorization: Bearer <token>

Resposta 200 OK

[
  {
    "id": "schedule-uuid",
    "control_point_id": "cp-uuid",
    "action": "ON",
    "start_time": "2025-12-10T06:00:00Z",
    "end_time": "2025-12-10T08:00:00Z",
    "repeat_pattern": "WEEKLY",
    "days_of_week": [1, 2, 3, 4, 5],
    "is_active": true,
    "description": "Aeração matinal - Dias úteis"
  }
]

Possíveis Erros

Status	Detalhe
404	Ponto de controle não encontrado

---

PATCH /schedules/{schedule_id}

Atualiza um agendamento por ID (atualização parcial).

Parâmetros de URL

Parâmetro	Tipo	Descrição
schedule_id	UUID	ID do agendamento

Requisição

PATCH /api/v1/schedules/schedule-uuid
Authorization: Bearer <token>
Content-Type: application/json

{
  "action": "OFF",
  "is_active": false,
  "description": "Descrição atualizada"
}

Parâmetros do Body

Todos os campos são opcionais:

Campo	Tipo	Descrição
action	enum	Nova ação (ON / OFF)
start_time	datetime	Nova hora de início
end_time	datetime	Nova hora de término
repeat_pattern	enum	Novo padrão de repetição
days_of_week	array[int]	Novos dias da semana
is_active	boolean	Ativar/desativar agendamento
description	string	Nova descrição

Resposta 200 OK

Retorna o objeto do agendamento atualizado.

Possíveis Erros

Status	Detalhe
404	Agendamento não encontrado ou não acessível
422	Erro de validação

---

DELETE /schedules/{schedule_id}

Exclui um agendamento.

Parâmetros de URL

Parâmetro	Tipo	Descrição
schedule_id	UUID	ID do agendamento

Requisição

DELETE /api/v1/schedules/schedule-uuid
Authorization: Bearer <token>

Resposta 204 No Content

Sem corpo de resposta.

Possíveis Erros

Status	Detalhe
404	Agendamento não encontrado ou não acessível

---

Exemplos de Uso

Aeração diária pela manhã

{
  "action": "ON",
  "start_time": "2025-12-10T06:00:00Z",
  "end_time": "2025-12-10T10:00:00Z",
  "repeat_pattern": "DAILY",
  "is_active": true,
  "description": "Aeração matinal diária"
}

Aeração apenas nos fins de semana

{
  "action": "ON",
  "start_time": "2025-12-10T08:00:00Z",
  "end_time": "2025-12-10T18:00:00Z",
  "repeat_pattern": "WEEKLY",
  "days_of_week": [6, 7],
  "is_active": true,
  "description": "Aeração de fim de semana"
}

Desligar todas as noites (único)

{
  "action": "OFF",
  "start_time": "2025-12-10T23:00:00Z",
  "repeat_pattern": "ONCE",
  "is_active": true,
  "description": "Desligamento único"
}

Nota

Os agendamentos são executados automaticamente pelo sistema. Certifique-se de que o servidor de API esteja sempre em execução para que os agendamentos funcionem corretamente.