API — Visão Geral

A API do Neemias é servida por um Cloudflare Worker e organizada por recurso. Todas as rotas utilizam o prefixo /api/v1 e seguem um pipeline declarativo de middleware que aplica autenticação, autorização por role, rate limiting e validação de schema de forma consistente.

Autenticação e Cabeçalhos

Toda requisição autenticada deve incluir três cabeçalhos obrigatórios:

Header	Valor	Obrigatório em
Authorization	Bearer <accessToken> (JWT HS256)	Todas as rotas autenticadas
Idempotency-Key	UUID v4	Todas as mutações (POST, PATCH)

v0.53.0: X-Device-Id foi removido — não é mais obrigatório.

O Idempotency-Key garante que operações retentadas por timeout ou falha de rede não sejam processadas duplicadamente.

Resumo de Endpoints (59 rotas)

v0.54.0: O número total de rotas passou de 41 para 59, incluindo novos endpoints para eventos, temas e storage proxy. Consulte o OpenAPI spec para a lista completa.

Health & Meta

Método	Rota	Roles	Descrição
GET	/api/v1/health	Público	Health check
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 — rate limit: 5/min (PBKDF2)
POST	/api/v1/auth/refresh	Público	Renovar token — rate limit: 10/min
POST	/api/v1/auth/revoke	Autenticado	Revogar sessão
POST	/api/v1/session/validate	Autenticado	Validar sessão ativa

v0.56.0: O JWT agora retorna roles[] (array) + primaryRole, substituindo o campo role único. requireRole() usa roles.some() para any() match.

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 com justificativa

Chamada

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

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 — múltiplos eventos
POST	/api/v1/sync/event	Autenticado	Evento único atômico via D1.batch()

Dev

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

Pipeline de Middleware

O helper route() (workers/src/middleware/pipeline.ts) constrói cada endpoint como uma cadeia declarativa de middlewares que executam em sequência. O fluxo típico é:

Request → rateLimit? → requireAuth (JWT) → requireRole → Zod validation → Handler → Response

Headers de segurança (CORS, CSP, HSTS) são aplicados uniformemente pelo router. Erros seguem o envelope { error, message, details } com códigos HTTP canônicos (401 UNAUTHORIZED, 403 FORBIDDEN_ROLE, 409 IDEMPOTENCY_KEY_REUSED_WITH_DIFFERENT_PAYLOAD, etc.).

Consulte o Guia de API para o workflow completo de implementação de novas rotas e a especificação OpenAPI para o contrato detalhado de cada endpoint.

⚠️ Seção em expansão.

---

Fonte: workers/src/router.ts + workers/CONTEXT.md