{ "openapi": "3.1.0", "info": { "title": "Neemias API", "version": "1.0.0", "description": "Attendance tracking API for small teams. Backend-primary, offline-resilient, LGPD-aware.\n\nBase URL: `https://api.neemias.app`", "contact": { "name": "Neemias", "url": "https://github.com/barateza/neemias" } }, "servers": [ { "url": "https://api.neemias.app", "description": "Production (Cloudflare Workers)" }, { "url": "http://localhost:8788", "description": "Local development" } ], "paths": { "/api/v1/health": { "get": { "summary": "Health check", "tags": [ "Health" ], "security": [], "responses": { "200": { "description": "Service is healthy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GET__api_v1_health_response" } } } } }, "description": "Returns service status. No authentication required." } }, "/api/v1/license": { "get": { "summary": "License entitlements", "tags": [ "License" ], "security": [], "responses": { "200": { "description": "Entitled module ids", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GET__api_v1_license_response" } } } } }, "description": "Returns the module ids the deployment license entitles (empty when unlicensed). Public — mirrors license state for the frontend UI gate; Worker route registration remains the enforcement point." } }, "/.well-known/security.txt": { "get": { "summary": "Security contact information (RFC 9116)", "tags": [ "Health" ], "security": [], "responses": {}, "description": "Returns security.txt with contact information for vulnerability disclosure." } }, "/api/v1/auth/login": { "post": { "summary": "Authenticate user", "tags": [ "Auth" ], "security": [], "responses": { "200": { "description": "Authentication successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/POST__api_v1_auth_login_response" } } } }, "401": { "description": "Unauthorized — missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Email + password login. Returns JWT access token, refresh token, and user info.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/POST__api_v1_auth_login_request" }, "example": { "email": "admin@neemias.local", "password": "senha123" } } } } } }, "/api/v1/auth/refresh": { "post": { "summary": "Refresh access token", "tags": [ "Auth" ], "security": [], "responses": { "401": { "description": "Unauthorized — missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Rotates the refresh token and returns a new access/refresh pair.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/POST__api_v1_auth_refresh_request" }, "example": { "refreshToken": "uuid-refresh-token-value" } } } } } }, "/api/v1/auth/revoke": { "post": { "summary": "Revoke session", "tags": [ "Auth" ], "security": [ { "BearerToken": [] } ], "responses": { "401": { "description": "Unauthorized — missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Revokes the current session's refresh token.\n\nRequires a valid JWT access token (any authenticated user)." } }, "/api/v1/session/validate": { "post": { "summary": "Validate session", "tags": [ "Auth" ], "security": [ { "BearerToken": [] } ], "responses": { "200": { "description": "Session is active", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/POST__api_v1_session_validate_response" } } } }, "401": { "description": "Unauthorized — missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Checks if the current session is still active and not expired.\n\nRequires a valid JWT access token (any authenticated user).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/POST__api_v1_session_validate_request" }, "example": { "sessionId": "5f2bc645-5f8f-4e4f-a7cb-f1ca01cc91e9", "clientTime": "2026-04-10T12:00:00Z" } } } } } }, "/api/v1/students": { "get": { "summary": "List students", "tags": [ "Students" ], "security": [ { "BearerToken": [] } ], "responses": { "200": { "description": "List of students", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GET__api_v1_students_response" } } } }, "401": { "description": "Unauthorized — missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Paginated student list with optional search and status filter.\n\nRequires a valid JWT access token (any authenticated user)." }, "post": { "summary": "Create student", "tags": [ "Students" ], "security": [ { "BearerToken": [] } ], "responses": { "201": { "description": "Student created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/POST__api_v1_students_response" } } } }, "400": { "description": "Validation error — invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized — missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — insufficient role permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Creates a new student. Idempotent.\n\nRequires ADMIN or CADASTRO role.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/POST__api_v1_students_request" }, "example": { "displayName": "João Silva", "photoRef": "photo:student:uuid", "guardianName": "Maria Silva", "phones": [ { "number": "11999999999", "qualifier": "Celular" } ], "classId": "uuid-da-turma" } } } } } }, "/api/v1/students/{studentId}": { "patch": { "summary": "Update student", "tags": [ "Students" ], "security": [ { "BearerToken": [] } ], "responses": { "200": { "description": "Student updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PATCH__api_v1_students__studentId_response" } } } }, "400": { "description": "Validation error — invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized — missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — insufficient role permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Updates an existing student.\n\nRequires ADMIN or CADASTRO role.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PATCH__api_v1_students__studentId_request" }, "example": { "displayName": "João Silva Atualizado", "guardianName": "Mario Silva" } } } }, "parameters": [ { "name": "studentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The studentId ID" } ] } }, "/api/v1/students/{studentId}/delete": { "post": { "summary": "Delete student (soft)", "tags": [ "Students" ], "security": [ { "BearerToken": [] } ], "responses": { "200": { "description": "Student deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/POST__api_v1_students__studentId_delete_response" } } } }, "400": { "description": "Validation error — invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized — missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — insufficient role permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Soft-deletes a student. Justification (10–500 chars) is required.\n\nRequires ADMIN role.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/POST__api_v1_students__studentId_delete_request" }, "example": { "justification": "Estudante transferiu para outra instituição." } } } }, "parameters": [ { "name": "studentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The studentId ID" } ] } }, "/api/v1/check-in": { "post": { "summary": "Register child check-in", "tags": [ "Check-in" ], "security": [ { "BearerToken": [] } ], "responses": { "201": { "description": "Check-in registered with daily code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/POST__api_v1_check_in_response" } } } }, "400": { "description": "Validation error — invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized — missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — insufficient role permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict — operation cannot be completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Records a child's arrival for a specific session. Returns a deterministic daily code for label printing. Quick registration supported for walk-in visitors.\n\nRequires ADMIN or CHAMADOR role.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/POST__api_v1_check_in_request" }, "example": { "studentId": "a1cc3a6a-8501-4fa8-9ea4-0afc7bb8d2f1", "sessionId": "b2dd4b6b-9602-5fb9-0fb5-1b0d8cc9e3f2" } } } } } }, "/api/v1/check-out": { "post": { "summary": "Check out child with daily code", "tags": [ "Check-in" ], "security": [ { "BearerToken": [] } ], "responses": { "200": { "description": "Check-out result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/POST__api_v1_check_out_response" } } } }, "400": { "description": "Validation error — invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized — missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — insufficient role permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict — operation cannot be completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "423": { "description": "HTTP 423", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Validates the 6-char daily code against the active check-in. On match: creates CHECK_OUT event. On mismatch: creates CHECKOUT_ATTEMPT. After N failed attempts: locked (423).\n\nRequires ADMIN or CHAMADOR role.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/POST__api_v1_check_out_request" }, "example": { "checkInId": "a1cc3a6a-8501-4fa8-9ea4-0afc7bb8d2f1", "code": "ABC123", "pickupPerson": "Maria Silva", "pickupPhoneSuffix": "9999" } } } } } }, "/api/v1/check-out/emergency": { "post": { "summary": "Emergency checkout (bypass code)", "tags": [ "Check-in" ], "security": [ { "BearerToken": [] } ], "responses": { "200": { "description": "Emergency checkout result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/POST__api_v1_check_out_emergency_response" } } } }, "400": { "description": "Validation error — invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized — missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — insufficient role permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict — operation cannot be completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Bypasses code verification for emergency situations. Creates EMERGENCY_CHECKOUT event with justification. Respects emergencyCheckoutAdminOnly config.\n\nRequires ADMIN or CHAMADOR role.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/POST__api_v1_check_out_emergency_request" }, "example": { "checkInId": "a1cc3a6a-8501-4fa8-9ea4-0afc7bb8d2f1", "justification": "Responsável perdeu o comprovante de retirada.", "pickupPerson": "João Pai" } } } } } }, "/api/v1/check-in/active": { "get": { "summary": "Get active check-in", "tags": [ "Check-in" ], "security": [ { "BearerToken": [] } ], "responses": { "200": { "description": "Active check-in details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GET__api_v1_check_in_active_response" } } } }, "400": { "description": "Validation error — invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized — missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — insufficient role permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Returns the active check-in record for a student+session, with child info, check-in time, and remaining attempts.\n\nRequires ADMIN or CHAMADOR role." } }, "/api/v1/church/check-in-config": { "get": { "summary": "Get church check-in configuration", "tags": [ "Check-in" ], "security": [ { "BearerToken": [] } ], "responses": { "200": { "description": "Church check-in configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GET__api_v1_church_check_in_config_response" } } } }, "401": { "description": "Unauthorized — missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — insufficient role permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Returns the aggregate check-in configuration (pickup mode, attempt limits, emergency policy) with defaults applied. Auto-generates checkin_secret on first access.\n\nRequires ADMIN or CHAMADOR role." }, "put": { "summary": "Update church check-in configuration", "tags": [ "Check-in" ], "security": [ { "BearerToken": [] } ], "responses": { "200": { "description": "Updated configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PUT__api_v1_church_check_in_config_response" } } } }, "400": { "description": "Validation error — invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized — missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — insufficient role permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Writes individual check-in config rows. Only keys present in the body are updated (partial update).\n\nRequires ADMIN role.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PUT__api_v1_church_check_in_config_request" }, "example": { "pickupMode": "PHONE_SUFFIX", "maxCodeAttempts": 3, "emergencyCheckoutAdminOnly": false, "labelExtraFields": [ "allergies" ] } } } } } }, "/api/v1/users": { "get": { "summary": "List users", "tags": [ "Users" ], "security": [ { "BearerToken": [] } ], "responses": { "200": { "description": "List of users", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GET__api_v1_users_response" } } } }, "401": { "description": "Unauthorized — missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — insufficient role permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Lists all users.\n\nRequires ADMIN role." }, "post": { "summary": "Create user", "tags": [ "Users" ], "security": [ { "BearerToken": [] } ], "responses": { "400": { "description": "Validation error — invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized — missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — insufficient role permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Creates a new user.\n\nRequires ADMIN role.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/POST__api_v1_users_request" }, "example": { "email": "novo.usuario@email.com", "displayName": "Novo Usuário", "role": "CHAMADOR", "password": "senha123" } } } } } }, "/api/v1/users/{userId}": { "patch": { "summary": "Update user", "tags": [ "Users" ], "security": [ { "BearerToken": [] } ], "responses": { "400": { "description": "Validation error — invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized — missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — insufficient role permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Updates a user's display name and/or role.\n\nRequires ADMIN role.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PATCH__api_v1_users__userId_request" }, "example": { "displayName": "Nome Atualizado", "role": "ADMIN" } } } }, "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The userId ID" } ] } }, "/api/v1/users/{userId}/reset-password": { "post": { "summary": "Reset user password", "tags": [ "Users" ], "security": [ { "BearerToken": [] } ], "responses": { "400": { "description": "Validation error — invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized — missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — insufficient role permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Resets a user's password.\n\nRequires ADMIN role.", "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The userId ID" } ] } }, "/api/v1/users/{userId}/deactivate": { "post": { "summary": "Deactivate user", "tags": [ "Users" ], "security": [ { "BearerToken": [] } ], "responses": { "400": { "description": "Validation error — invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized — missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — insufficient role permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict — operation cannot be completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Deactivates a user. Self-deactivation and last-admin deactivation are blocked.\n\nRequires ADMIN role.", "parameters": [ { "name": "userId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The userId ID" } ] } }, "/api/v1/sync/event": { "post": { "summary": "Processa 1 evento de sync atomicamente via D1.batch()", "tags": [ "Sync" ], "security": [ { "BearerToken": [] } ], "responses": { "200": { "description": "Sync result with synced, failed, and conflict entries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/POST__api_v1_sync_event_response" } } } }, "400": { "description": "Validation error — invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized — missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict — operation cannot be completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Unprocessable entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Submits a single offline event for atomic sync via D1.batch(). Idempotent.\n\nRequires a valid JWT access token (any authenticated user).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/POST__api_v1_sync_event_request" }, "example": { "eventId": "3d9d2f89-8429-4f95-b0ad-6b849bb7e2e0", "entityType": "ATTENDANCE", "actionType": "MARK_PRESENT", "payload": { "studentId": "a1cc3a6a-8501-4fa8-9ea4-0afc7bb8d2f1" }, "timestamp": "2026-04-10T12:00:00Z" } } } } } }, "/api/v1/sync/events": { "post": { "summary": "Batch sync events", "tags": [ "Sync" ], "security": [ { "BearerToken": [] } ], "responses": { "200": { "description": "Sync result with synced, failed, and conflict entries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/POST__api_v1_sync_events_response" } } } }, "400": { "description": "Validation error — invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized — missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Unprocessable entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Submits a batch of offline events for synchronization. Max 250 events per batch. Idempotent.\n\nRequires a valid JWT access token (any authenticated user).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/POST__api_v1_sync_events_request" }, "example": { "events": [ { "eventId": "3d9d2f89-8429-4f95-b0ad-6b849bb7e2e0", "entityType": "ATTENDANCE", "actionType": "MARK_PRESENT", "payload": { "studentId": "a1cc3a6a-8501-4fa8-9ea4-0afc7bb8d2f1" }, "timestamp": "2026-04-10T12:00:00Z" } ] } } } } } }, "/api/v1/roles": { "get": { "summary": "List roles", "tags": [ "Roles" ], "security": [ { "BearerToken": [] } ], "responses": { "401": { "description": "Unauthorized — missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — insufficient role permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Lists all roles with their permissions.\n\nRequires ADMIN role." }, "post": { "summary": "Create role", "tags": [ "Roles" ], "security": [ { "BearerToken": [] } ], "responses": { "400": { "description": "Validation error — invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized — missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — insufficient role permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict — operation cannot be completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Creates a custom role with selected permissions.\n\nRequires ADMIN role." } }, "/api/v1/roles/{roleName}": { "patch": { "summary": "Update role permissions", "tags": [ "Roles" ], "security": [ { "BearerToken": [] } ], "responses": { "400": { "description": "Validation error — invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized — missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — insufficient role permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Updates the permission set of an existing role.\n\nRequires ADMIN role.", "parameters": [ { "name": "roleName", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The roleName ID" } ] }, "delete": { "summary": "Delete role", "tags": [ "Roles" ], "security": [ { "BearerToken": [] } ], "responses": { "400": { "description": "Validation error — invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized — missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — insufficient role permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Deletes a custom role. System roles and roles with active users cannot be deleted.\n\nRequires ADMIN role.", "parameters": [ { "name": "roleName", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The roleName ID" } ] } }, "/api/v1/classes": { "get": { "summary": "List classes", "tags": [ "Classes" ], "security": [ { "BearerToken": [] } ], "responses": { "200": { "description": "List of classes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GET__api_v1_classes_response" } } } }, "401": { "description": "Unauthorized — missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Lists all active classes (turmas).\n\nRequires a valid JWT access token (any authenticated user)." }, "post": { "summary": "Create class", "tags": [ "Classes" ], "security": [ { "BearerToken": [] } ], "responses": { "201": { "description": "Class created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/POST__api_v1_classes_response" } } } }, "400": { "description": "Validation error — invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized — missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — insufficient role permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Creates a new class (turma).\n\nRequires ADMIN role.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/POST__api_v1_classes_request" }, "example": { "name": "Jardim de Infância", "ageMin": 3, "ageMax": 5 } } } } } }, "/api/v1/classes/{classId}": { "patch": { "summary": "Update class", "tags": [ "Classes" ], "security": [ { "BearerToken": [] } ], "responses": { "400": { "description": "Validation error — invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized — missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — insufficient role permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Updates an existing class.\n\nRequires ADMIN role.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PATCH__api_v1_classes__classId_request" }, "example": { "name": "Jardim Atualizado", "ageMax": 6 } } } }, "parameters": [ { "name": "classId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The classId ID" } ] } }, "/api/v1/classes/{classId}/delete": { "post": { "summary": "Delete class (soft)", "tags": [ "Classes" ], "security": [ { "BearerToken": [] } ], "responses": { "401": { "description": "Unauthorized — missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — insufficient role permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Soft-deletes a class.\n\nRequires ADMIN role.", "parameters": [ { "name": "classId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The classId ID" } ] } }, "/api/v1/classes/{classId}/waiting-list": { "post": { "summary": "Join class waiting list", "tags": [ "Classes", "Waiting List" ], "security": [ { "BearerToken": [] } ], "responses": { "400": { "description": "Validation error — invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized — missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — insufficient role permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict — operation cannot be completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Adds a child to the waiting list for a full class. Requires RESPONSAVEL role. Prevents duplicate entries.", "parameters": [ { "name": "classId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The classId ID" } ] }, "get": { "summary": "List class waiting list", "tags": [ "Classes", "Waiting List" ], "security": [ { "BearerToken": [] } ], "responses": { "401": { "description": "Unauthorized — missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — insufficient role permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Lists all entries in a class's waiting list, ordered FIFO. Admin only.\n\nRequires ADMIN role.", "parameters": [ { "name": "classId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The classId ID" } ] } }, "/api/v1/classes/{classId}/waiting-list/{id}": { "delete": { "summary": "Leave class waiting list", "tags": [ "Classes", "Waiting List" ], "security": [ { "BearerToken": [] } ], "responses": { "400": { "description": "Validation error — invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized — missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — insufficient role permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Removes a waiting list entry. Users can only remove their own entries; admins can remove any.\n\nRequires a valid JWT access token (any authenticated user).", "parameters": [ { "name": "classId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The classId ID" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The id ID" } ] } }, "/api/v1/class-slots": { "get": { "summary": "List class slots", "tags": [ "Class Slots" ], "security": [ { "BearerToken": [] } ], "responses": { "401": { "description": "Unauthorized — missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Lists all class slots ordered by day of week and start time.\n\nRequires a valid JWT access token (any authenticated user)." }, "post": { "summary": "Create class slot", "tags": [ "Class Slots" ], "security": [ { "BearerToken": [] } ], "responses": { "400": { "description": "Validation error — invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized — missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — insufficient role permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Creates a new class slot (horário de encontro).\n\nRequires ADMIN or CADASTRO role." } }, "/api/v1/class-slots/{slotId}": { "patch": { "summary": "Update class slot", "tags": [ "Class Slots" ], "security": [ { "BearerToken": [] } ], "responses": { "400": { "description": "Validation error — invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized — missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — insufficient role permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Updates an existing class slot.\n\nRequires ADMIN or CADASTRO role.", "parameters": [ { "name": "slotId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The slotId ID" } ] }, "delete": { "summary": "Delete class slot (soft)", "tags": [ "Class Slots" ], "security": [ { "BearerToken": [] } ], "responses": { "401": { "description": "Unauthorized — missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — insufficient role permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Soft-deletes a class slot (sets status to INACTIVE).\n\nRequires ADMIN role.", "parameters": [ { "name": "slotId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The slotId ID" } ] } }, "/api/v1/class-sessions": { "get": { "summary": "List class sessions", "tags": [ "Class Sessions" ], "security": [ { "BearerToken": [] } ], "responses": { "401": { "description": "Unauthorized — missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Lists class sessions. Optional filters: slotId, sessionDate.\n\nRequires a valid JWT access token (any authenticated user)." }, "post": { "summary": "Create class session", "tags": [ "Class Sessions" ], "security": [ { "BearerToken": [] } ], "responses": { "400": { "description": "Validation error — invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized — missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — insufficient role permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Creates a new class session (aula em data específica).\n\nRequires ADMIN or CADASTRO role." } }, "/api/v1/onboarding/{hash}": { "get": { "summary": "Validar link de onboarding", "tags": [ "Onboarding" ], "security": [], "responses": { "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "410": { "description": "HTTP 410", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "HTTP 429", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Carrega dados do formulário público a partir do hash do link. Valida expiração e limite de usos.", "parameters": [ { "name": "hash", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The hash ID" } ] } }, "/api/v1/onboarding/{hash}/request-otp": { "post": { "summary": "Solicitar código OTP", "tags": [ "Onboarding" ], "security": [], "responses": { "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "410": { "description": "HTTP 410", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Gera e retorna OTP de 6 dígitos (dev mode) para verificação do responsável. Rate limit: 3/min.", "parameters": [ { "name": "hash", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The hash ID" } ] } }, "/api/v1/onboarding/{hash}/verify-otp": { "post": { "summary": "Verificar código OTP", "tags": [ "Onboarding" ], "security": [], "responses": { "400": { "description": "Validation error — invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized — missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "410": { "description": "HTTP 410", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "HTTP 429", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Valida o código OTP informado. Max 3 tentativas, expira em 10min.", "parameters": [ { "name": "hash", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The hash ID" } ] } }, "/api/v1/onboarding/{hash}/submit": { "post": { "summary": "Submeter dados do aluno", "tags": [ "Onboarding" ], "security": [], "responses": { "400": { "description": "Validation error — invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized — missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict — operation cannot be completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "410": { "description": "HTTP 410", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Cria rascunho de onboarding com dados do aluno. Requer OTP verificado previamente.", "parameters": [ { "name": "hash", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The hash ID" } ] } }, "/api/v1/onboarding/links": { "post": { "summary": "Gerar link de onboarding", "tags": [ "Onboarding" ], "security": [ { "BearerToken": [] } ], "responses": { "400": { "description": "Validation error — invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized — missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — insufficient role permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Cria um novo link de onboarding para uma turma. Requer admin.\n\nRequires ADMIN or CADASTRO role." } }, "/api/v1/onboarding/drafts": { "get": { "summary": "Listar rascunhos pendentes", "tags": [ "Onboarding" ], "security": [ { "BearerToken": [] } ], "responses": { "401": { "description": "Unauthorized — missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — insufficient role permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Lista todos os rascunhos de onboarding. Requer admin.\n\nRequires ADMIN or CADASTRO role." } }, "/api/v1/onboarding/drafts/{id}": { "get": { "summary": "Ver detalhes do rascunho", "tags": [ "Onboarding" ], "security": [ { "BearerToken": [] } ], "responses": { "401": { "description": "Unauthorized — missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — insufficient role permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Retorna dados do rascunho com detecção de duplicidade. Requer admin.\n\nRequires ADMIN or CADASTRO role.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The id ID" } ] } }, "/api/v1/onboarding/drafts/{id}/approve": { "post": { "summary": "Aprovar rascunho", "tags": [ "Onboarding" ], "security": [ { "BearerToken": [] } ], "responses": { "400": { "description": "Validation error — invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized — missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — insufficient role permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict — operation cannot be completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Aprova rascunho e cria registro de aluno. Requer admin.\n\nRequires ADMIN or CADASTRO role.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The id ID" } ] } }, "/api/v1/onboarding/drafts/{id}/reject": { "post": { "summary": "Rejeitar rascunho", "tags": [ "Onboarding" ], "security": [ { "BearerToken": [] } ], "responses": { "400": { "description": "Validation error — invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized — missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — insufficient role permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict — operation cannot be completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Rejeita rascunho com justificativa. Requer admin.\n\nRequires ADMIN or CADASTRO role.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The id ID" } ] } }, "/api/v1/notifications": { "post": { "summary": "Create notification (alert for TV screen)", "tags": [ "Notifications" ], "security": [ { "BearerToken": [] } ], "responses": { "400": { "description": "Validation error — invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized — missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — insufficient role permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "HTTP 429", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Creates a notification for the TV screen feed. Shows child name, age, and message on the church display.\n\nRequires ADMIN or CADASTRO role." } }, "/api/v1/notifications/feed": { "get": { "summary": "SSE feed for TV screen", "tags": [ "Notifications" ], "security": [], "responses": { "401": { "description": "Unauthorized — missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Server-Sent Events endpoint. Polls D1 every 3s for new notifications. Requires ?churchId and ?token query params." } }, "/api/v1/notifications/history": { "get": { "summary": "Today's notification history", "tags": [ "Notifications" ], "security": [ { "BearerToken": [] } ], "responses": { "401": { "description": "Unauthorized — missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — insufficient role permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Returns notifications from the last 24h. Optional ?unreadOnly=true filter.\n\nRequires ADMIN or CADASTRO role." } }, "/api/v1/notifications/{id}/read": { "post": { "summary": "Mark notification as read", "tags": [ "Notifications" ], "security": [ { "BearerToken": [] } ], "responses": { "401": { "description": "Unauthorized — missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — insufficient role permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Sets read_at timestamp on a notification.\n\nRequires ADMIN or CADASTRO role.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The id ID" } ] } }, "/api/v1/capacity/snapshot": { "get": { "summary": "Capacity snapshot JSON", "tags": [ "Capacity" ], "security": [], "responses": {}, "description": "Returns a plain JSON snapshot of all slot capacities. Used by class list badge." } }, "/api/v1/capacity/feed": { "get": { "summary": "Live capacity dashboard feed (SSE)", "tags": [ "Capacity" ], "security": [], "responses": {}, "description": "Server-Sent Events endpoint for live classroom capacity data. Public, no auth required. Polls every 5s." } }, "/api/v1/class-slots/{id}": { "patch": { "summary": "Update slot capacity", "tags": [ "Capacity" ], "security": [ { "BearerToken": [] } ], "responses": { "401": { "description": "Unauthorized — missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — insufficient role permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Updates the capacity for a class slot. ADMIN/COORD only.\n\nRequires ADMIN role.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The id ID" } ] } }, "/api/v1/attendance/feed": { "get": { "summary": "Live attendance event feed (SSE)", "tags": [ "Attendance" ], "security": [], "responses": {}, "description": "Server-Sent Events endpoint for real-time attendance changes. Public, no auth required." } }, "/api/v1/events": { "get": { "summary": "List public events", "tags": [ "Events" ], "security": [], "responses": {}, "description": "Lists open events with optional churchId filter." }, "post": { "summary": "Create event", "tags": [ "Events" ], "security": [ { "BearerToken": [] } ], "responses": { "400": { "description": "Validation error — invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized — missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — insufficient role permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Creates a new event. Requires cadastro role.\n\nRequires ADMIN or CADASTRO role.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/POST__api_v1_events_request" } } } } } }, "/api/v1/events/{eventId}": { "get": { "summary": "Get event details", "tags": [ "Events" ], "security": [], "responses": { "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Returns a single event by ID.", "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The eventId ID" } ] }, "put": { "summary": "Update event", "tags": [ "Events" ], "security": [ { "BearerToken": [] } ], "responses": { "400": { "description": "Validation error — invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized — missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — insufficient role permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Updates an existing event. Requires cadastro role.\n\nRequires ADMIN or CADASTRO role.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PUT__api_v1_events__eventId_request" } } } }, "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The eventId ID" } ] }, "delete": { "summary": "Delete event", "tags": [ "Events" ], "security": [ { "BearerToken": [] } ], "responses": { "401": { "description": "Unauthorized — missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — insufficient role permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Soft-deletes an event. Requires admin role.\n\nRequires ADMIN role.", "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The eventId ID" } ] } }, "/api/v1/events/{eventId}/register": { "post": { "summary": "Register for event", "tags": [ "Events" ], "security": [], "responses": { "400": { "description": "Validation error — invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Submits a registration for a public event. Rate-limited: 5/min.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/POST__api_v1_events__eventId_register_request" }, "example": { "guardianName": "Maria Silva", "guardianPhone": "11999999999", "participantName": "João Silva", "participantAge": 8 } } } }, "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The eventId ID" } ] } }, "/api/v1/events/{eventId}/register/{regId}": { "get": { "summary": "Get registration status", "tags": [ "Events" ], "security": [], "responses": { "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Returns the details of a specific registration.", "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The eventId ID" }, { "name": "regId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The regId ID" } ] } }, "/api/v1/events/{eventId}/proof": { "post": { "summary": "Upload payment proof", "tags": [ "Events" ], "security": [], "responses": { "400": { "description": "Validation error — invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Uploads a payment proof file (JPEG/PNG/WebP/PDF, max 5MB). Rate-limited: 3/min.", "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The eventId ID" } ] } }, "/api/v1/events/{eventId}/clone": { "post": { "summary": "Clone event", "tags": [ "Events" ], "security": [ { "BearerToken": [] } ], "responses": { "401": { "description": "Unauthorized — missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — insufficient role permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Clones an event. Requires cadastro role.\n\nRequires ADMIN or CADASTRO role.", "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The eventId ID" } ] } }, "/api/v1/events/{eventId}/registrations": { "get": { "summary": "List registrations", "tags": [ "Events" ], "security": [ { "BearerToken": [] } ], "responses": { "401": { "description": "Unauthorized — missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — insufficient role permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Lists all registrations for an event. Requires cadastro role.\n\nRequires ADMIN or CADASTRO role.", "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The eventId ID" } ] } }, "/api/v1/events/{eventId}/registrations/{regId}/approve": { "post": { "summary": "Approve registration", "tags": [ "Events" ], "security": [ { "BearerToken": [] } ], "responses": { "401": { "description": "Unauthorized — missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — insufficient role permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Approves a pending registration. Requires admin role.\n\nRequires ADMIN role.", "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The eventId ID" }, { "name": "regId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The regId ID" } ] } }, "/api/v1/events/{eventId}/registrations/{regId}/reject": { "post": { "summary": "Reject registration", "tags": [ "Events" ], "security": [ { "BearerToken": [] } ], "responses": { "401": { "description": "Unauthorized — missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — insufficient role permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Rejects a pending registration. Requires admin role.\n\nRequires ADMIN role.", "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The eventId ID" }, { "name": "regId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The regId ID" } ] } }, "/api/v1/storage/proxy": { "post": { "summary": "Proxy SQL to D1", "tags": [ "Storage" ], "security": [ { "BearerToken": [] } ], "responses": { "400": { "description": "Validation error — invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized — missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — insufficient role permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "HTTP 429", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Executes a SQL query against D1. Only SELECT/INSERT/UPDATE/DELETE on known tables. DDL rejected. Auth required.\n\nRequires a valid JWT access token (any authenticated user)." } }, "/api/v1/credentials": { "get": { "summary": "Get active credential for a student", "tags": [ "Credentials" ], "security": [ { "BearerToken": [] } ], "responses": { "400": { "description": "Validation error — invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized — missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Returns the active (non-revoked) credential for a student, or null if none exists. Requires ?studentId query param.\n\nRequires ADMIN or CHAMADOR role." }, "post": { "summary": "Issue a credential for a student", "tags": [ "Credentials" ], "security": [ { "BearerToken": [] } ], "responses": { "400": { "description": "Validation error — invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized — missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — insufficient role permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Creates a new permanent credential for a student. If an active credential exists, it is auto-revoked. Requires ?studentId query param.\n\nRequires ADMIN or CADASTRO role." } }, "/api/v1/credentials/lookup": { "post": { "summary": "Lookup student by credential value", "tags": [ "Credentials" ], "security": [ { "BearerToken": [] } ], "responses": { "400": { "description": "Validation error — invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized — missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Looks up a student by their credential value (QR/barcode scan result). Returns student ID and display name for check-in pre-fill.\n\nRequires ADMIN or CHAMADOR role." } }, "/api/v1/church/daily-secret": { "get": { "summary": "Get today's daily check-in secret", "tags": [ "Check-in" ], "security": [ { "BearerToken": [] } ], "responses": { "401": { "description": "Unauthorized — missing or invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden — insufficient role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Returns today's daily secret derived from the master checkin key via HMAC. Client caches this for offline check-in code derivation. Secret changes daily for forward security.\n\nRequires ADMIN or CHAMADOR role." } }, "/api/v1/classes/alternatives": { "get": { "summary": "Find alternative classes with available capacity", "tags": [ "Classes", "Capacity" ], "security": [ { "BearerToken": [] } ], "responses": { "400": { "description": "Validation error — invalid request body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized — missing or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "description": "Returns age-compatible classes that still have room, excluding the current slot. Requires childId and slotId query params.\n\nRequires a valid JWT access token (any authenticated user)." } } }, "components": { "schemas": { "GET__api_v1_health_response": {}, "GET__api_v1_license_response": {}, "POST__api_v1_auth_login_request": {}, "POST__api_v1_auth_login_response": {}, "POST__api_v1_auth_refresh_request": {}, "POST__api_v1_session_validate_request": {}, "POST__api_v1_session_validate_response": {}, "GET__api_v1_students_response": {}, "POST__api_v1_students_request": {}, "POST__api_v1_students_response": {}, "PATCH__api_v1_students__studentId_request": {}, "PATCH__api_v1_students__studentId_response": {}, "POST__api_v1_students__studentId_delete_request": {}, "POST__api_v1_students__studentId_delete_response": {}, "POST__api_v1_check_in_request": {}, "POST__api_v1_check_in_response": {}, "POST__api_v1_check_out_request": {}, "POST__api_v1_check_out_response": {}, "POST__api_v1_check_out_emergency_request": {}, "POST__api_v1_check_out_emergency_response": {}, "GET__api_v1_check_in_active_response": {}, "GET__api_v1_church_check_in_config_response": {}, "PUT__api_v1_church_check_in_config_request": {}, "PUT__api_v1_church_check_in_config_response": {}, "GET__api_v1_users_response": {}, "POST__api_v1_users_request": {}, "PATCH__api_v1_users__userId_request": {}, "POST__api_v1_sync_event_request": {}, "POST__api_v1_sync_event_response": {}, "POST__api_v1_sync_events_request": {}, "POST__api_v1_sync_events_response": {}, "GET__api_v1_classes_response": {}, "POST__api_v1_classes_request": {}, "POST__api_v1_classes_response": {}, "PATCH__api_v1_classes__classId_request": {}, "POST__api_v1_events__eventId_register_request": {}, "POST__api_v1_events_request": {}, "PUT__api_v1_events__eventId_request": {}, "ErrorEnvelope": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Machine-readable error code" }, "message": { "type": "string", "description": "Human-readable error message" }, "correlationId": { "type": "string", "format": "uuid", "description": "Correlation ID for tracing" }, "details": { "type": "object", "description": "Additional error details" } } } } } }, "securitySchemes": { "BearerToken": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT access token from POST /auth/login" } } } }