Guia de API

Consulte o Guia de API completo para detalhes sobre cada endpoint.

---

Resumo de Endpoints

Todas as rotas usam o prefixo /api/v1. Autenticação via Authorization: Bearer <JWT> + header X-Device-Id.

Health & Meta

Método	Rota	Roles	Descrição
GET	/api/v1/health	Público	Health check do serviço
GET	/.well-known/security.txt	Público	RFC 9116

Autenticação

Método	Rota	Roles	Descrição
POST	/api/v1/auth/login	Público	Login (email + senha) — rate limit: 5/min
POST	/api/v1/auth/refresh	Público	Renovar access token — rate limit: 10/min
POST	/api/v1/auth/revoke	Autenticado	Revogar sessão atual
POST	/api/v1/session/validate	Autenticado	Validar sessão ativa

Alunos

Método	Rota	Roles	Descrição
GET	/api/v1/students	Autenticado	Listar alunos (paginado, busca)
POST	/api/v1/students	ADMIN, CADASTRO	Criar aluno
PATCH	/api/v1/students/:studentId	ADMIN, CADASTRO	Atualizar aluno
POST	/api/v1/students/:studentId/delete	ADMIN	Soft-delete aluno (justificativa obrigatória)

Chamada

Método	Rota	Roles	Descrição
POST	/api/v1/attendance/events	CHAMADOR, ADMIN	Marcar presença de aluno

Turmas

Método	Rota	Roles	Descrição
GET	/api/v1/classes	Autenticado	Listar turmas
POST	/api/v1/classes	ADMIN	Criar turma
PATCH	/api/v1/classes/:classId	ADMIN	Atualizar turma
POST	/api/v1/classes/:classId/delete	ADMIN	Soft-delete turma

Núcleos

Método	Rota	Roles	Descrição
GET	/api/v1/nuclei	Autenticado	Listar núcleos
POST	/api/v1/nuclei	ADMIN	Criar núcleo
PATCH	/api/v1/nuclei/:nucleusId	ADMIN	Atualizar núcleo
POST	/api/v1/nuclei/:nucleusId/delete	ADMIN	Soft-delete núcleo

Usuários

Método	Rota	Roles	Descrição
GET	/api/v1/users	ADMIN	Listar usuários
POST	/api/v1/users	ADMIN	Criar usuário
PATCH	/api/v1/users/:userId	ADMIN	Atualizar usuário
POST	/api/v1/users/:userId/reset-password	ADMIN	Resetar senha
POST	/api/v1/users/:userId/deactivate	ADMIN	Desativar usuário

Roles

Método	Rota	Roles	Descrição
GET	/api/v1/roles	ADMIN	Listar roles
POST	/api/v1/roles	ADMIN	Criar role customizada
PATCH	/api/v1/roles/:roleName	ADMIN	Atualizar role
DELETE	/api/v1/roles/:roleName	ADMIN	Excluir role (não-sistema)

Sincronia

Método	Rota	Roles	Descrição
POST	/api/v1/sync/events	CHAMADOR, ADMIN, CADASTRO	Wrapper batch — processa múltiplos eventos
POST	/api/v1/sync/event	Autenticado	Processa 1 evento atomicamente via D1.batch()

Dev

Método	Rota	Roles	Descrição
POST	/_seed	—	Seed de dados demo (apenas desenvolvimento)

---

Cabeçalhos Obrigatórios (Requisições Autenticadas)

Header	Valor
Authorization	Bearer <accessToken>
X-Device-Id	UUID v4 identificando o dispositivo
Idempotency-Key	UUID v4 (todas as mutações: POST, PATCH)

Formato de Erro

Todos os erros seguem o envelope:

{
  "error": "ERROR_CODE",
  "message": "Descrição legível",
  "details": {}
}

Status	Código	Significado
400	VALIDATION_FAILED	Body inválido ou header obrigatório ausente
401	UNAUTHORIZED	Token ausente, inválido ou expirado
401	COMPROMISED_SESSION	Refresh token reutilizado (possível roubo)
403	FORBIDDEN_ROLE	Role sem permissão para o endpoint
404	NOT_FOUND	Rota inexistente
409	IDEMPOTENCY_KEY_REUSED_WITH_DIFFERENT_PAYLOAD	Chave de idempotência reutilizada com payload diferente
500	CONFIG_ERROR	Erro de configuração do servidor

---

Fonte: router.ts + workers/CONTEXT.md