{ "openapi": "3.0.0", "info": { "title": "Explicador API", "description": "Documentação inicial da API v1 de autenticação, verificação e sessões.", "version": "1.0.0" }, "paths": { "/api/v1/admin/articles": { "get": { "tags": [ "Admin" ], "summary": "Lista artigos editoriais para gestao administrativa.", "operationId": "adminListArticles", "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "category", "in": "query", "schema": { "type": "string" } }, { "name": "state", "in": "query", "description": "Filtra por estado de publicacao derivado.", "schema": { "type": "string", "enum": [ "published", "scheduled", "draft" ] } }, { "name": "page", "in": "query", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Lista paginada de artigos." } }, "security": [ { "sanctum": [] } ] }, "post": { "tags": [ "Admin" ], "summary": "Cria um novo artigo.", "operationId": "adminCreateArticle", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "201": { "description": "Artigo criado." }, "422": { "description": "Erro de validacao.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/admin/articles/{id}": { "get": { "tags": [ "Admin" ], "summary": "Detalhe de um artigo (incluindo HTML).", "operationId": "adminShowArticle", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Artigo." } }, "security": [ { "sanctum": [] } ] }, "delete": { "tags": [ "Admin" ], "summary": "Remove um artigo.", "operationId": "adminDeleteArticle", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Artigo removido." } }, "security": [ { "sanctum": [] } ] }, "patch": { "tags": [ "Admin" ], "summary": "Actualiza um artigo.", "operationId": "adminUpdateArticle", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Artigo actualizado." } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/admin/articles/{id}/publish": { "post": { "tags": [ "Admin" ], "summary": "Publica um artigo (imediato ou agendado).", "operationId": "adminPublishArticle", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "published_at": { "description": "Data futura para agendar; ausente publica imediatamente.", "type": "string", "format": "date-time", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Artigo publicado/agendado." } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/admin/articles/{id}/unpublish": { "post": { "tags": [ "Admin" ], "summary": "Despublica um artigo (volta a rascunho).", "operationId": "adminUnpublishArticle", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Artigo despublicado." } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/admin/contents": { "get": { "tags": [ "Admin" ], "summary": "Lista conteudos da plataforma para gestao administrativa.", "operationId": "adminListContents", "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "draft", "published", "archived" ] } }, { "name": "content_type_id", "in": "query", "schema": { "type": "integer" } }, { "name": "is_featured", "in": "query", "schema": { "type": "boolean" } }, { "name": "page", "in": "query", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Lista paginada." } }, "security": [ { "sanctum": [] } ] }, "post": { "tags": [ "Admin" ], "summary": "Cria um conteudo.", "operationId": "adminCreateContent", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "201": { "description": "Conteudo criado." }, "422": { "description": "Erro de validacao.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/admin/contents/{id}": { "get": { "tags": [ "Admin" ], "summary": "Detalhe administrativo de um conteudo.", "operationId": "adminShowContent", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Conteudo." } }, "security": [ { "sanctum": [] } ] }, "delete": { "tags": [ "Admin" ], "summary": "Remove (soft delete) um conteudo.", "operationId": "adminDeleteContent", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Conteudo removido." } }, "security": [ { "sanctum": [] } ] }, "patch": { "tags": [ "Admin" ], "summary": "Actualiza um conteudo.", "operationId": "adminUpdateContent", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Conteudo actualizado." } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/admin/contents/{id}/publish": { "post": { "tags": [ "Admin" ], "summary": "Publica um conteudo.", "operationId": "adminPublishContent", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "published_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Conteudo publicado." } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/admin/contents/{id}/archive": { "post": { "tags": [ "Admin" ], "summary": "Arquiva um conteudo.", "operationId": "adminArchiveContent", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Conteudo arquivado." } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/admin/dashboard": { "get": { "tags": [ "Admin" ], "summary": "Resumo executivo da plataforma com métricas, séries temporais e actividade recente.", "operationId": "adminDashboardOverview", "parameters": [ { "name": "range", "in": "query", "description": "Janela em dias para séries temporais e contagens \"new_in_range\".", "schema": { "type": "integer", "default": 30, "enum": [ 7, 14, 30, 60, 90 ] } }, { "name": "recent_limit", "in": "query", "description": "Número de itens em cada lista de actividade recente.", "schema": { "type": "integer", "default": 5, "maximum": 20, "minimum": 1 } } ], "responses": { "200": { "description": "Painel administrativo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminDashboardResponse" } } } }, "401": { "description": "Não autenticado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthenticatedResponse" } } } }, "403": { "description": "Sem permissão." } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/admin/users/{email}/kyc/approve": { "post": { "tags": [ "Admin" ], "summary": "Aprova a verificacao KYC de um utilizador.", "operationId": "adminApproveUserKyc", "parameters": [ { "name": "email", "in": "path", "required": true, "schema": { "type": "string", "format": "email" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "review_notes": { "type": "string", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "KYC aprovado." }, "401": { "description": "Não autenticado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthenticatedResponse" } } } }, "403": { "description": "Sem permissao." }, "404": { "description": "Utilizador ou verificacao não encontrada." }, "422": { "description": "Erro de validacao.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/admin/users/{email}/kyc/reject": { "post": { "tags": [ "Admin" ], "summary": "Rejeita a verificacao KYC de um utilizador.", "operationId": "adminRejectUserKyc", "parameters": [ { "name": "email", "in": "path", "required": true, "schema": { "type": "string", "format": "email" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "rejection_reason" ], "properties": { "rejection_reason": { "type": "string", "maxLength": 1000 }, "review_notes": { "type": "string", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "KYC rejeitado." }, "422": { "description": "Erro de validacao.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/admin/users/{email}/kyc/request-action": { "post": { "tags": [ "Admin" ], "summary": "Pede accao adicional ao utilizador antes de aprovar a verificacao KYC.", "operationId": "adminRequestUserKycAction", "parameters": [ { "name": "email", "in": "path", "required": true, "schema": { "type": "string", "format": "email" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "action_required_reason" ], "properties": { "action_required_reason": { "type": "string", "maxLength": 1000 }, "review_notes": { "type": "string", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Pedido de accao registado." }, "422": { "description": "Erro de validacao.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/admin/users/{email}/kyc/under-review": { "post": { "tags": [ "Admin" ], "summary": "Marca a verificacao KYC como em analise pelo administrador.", "operationId": "adminMarkUserKycUnderReview", "parameters": [ { "name": "email", "in": "path", "required": true, "schema": { "type": "string", "format": "email" } } ], "responses": { "200": { "description": "KYC marcado em analise." } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/admin/opportunities": { "get": { "tags": [ "Admin" ], "summary": "Lista solicitações para revisão administrativa.", "operationId": "adminListOpportunities", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "to_review", "published", "closed", "cancelled" ] } }, { "name": "discipline", "in": "query", "schema": { "type": "string" } }, { "name": "page", "in": "query", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Lista paginada administrativa.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminOpportunityListResponse" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/admin/opportunities/{id}": { "get": { "tags": [ "Admin" ], "summary": "Retorna o detalhe administrativo de uma solicitação.", "operationId": "adminShowOpportunity", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Detalhe administrativo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminOpportunityItem" } } } } }, "security": [ { "sanctum": [] } ] }, "patch": { "tags": [ "Admin" ], "summary": "Edita administrativamente uma solicitação antes ou depois da publicação.", "operationId": "adminUpdateOpportunity", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminOpportunityUpdateRequest" } } } }, "responses": { "200": { "description": "Solicitação actualizada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminOpportunityUpdateResponse" } } } }, "422": { "description": "Erro de validação.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/admin/opportunities/{id}/interests": { "get": { "tags": [ "Admin" ], "summary": "Lista as candidaturas privadas de uma solicitação.", "operationId": "adminListOpportunityInterests", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Lista de candidaturas.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminOpportunityInterestsResponse" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/admin/access-control/matrix": { "get": { "tags": [ "Admin" ], "summary": "Retorna a matriz CRUD de permissoes da plataforma.", "operationId": "adminAccessControlMatrix", "responses": { "200": { "description": "Matriz de permissoes por recurso e accao CRUD." }, "401": { "description": "Não autenticado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthenticatedResponse" } } } }, "403": { "description": "Sem permissao." } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/admin/access-control/endpoints": { "get": { "tags": [ "Admin" ], "summary": "Lista os endpoints administrativos e a permissao exigida por cada um.", "operationId": "adminAccessControlEndpoints", "responses": { "200": { "description": "Catalogo de endpoints administrativos." }, "401": { "description": "Não autenticado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthenticatedResponse" } } } }, "403": { "description": "Sem permissao." } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/admin/permissions": { "get": { "tags": [ "Admin" ], "summary": "Lista permissoes Spatie.", "operationId": "adminListPermissions", "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "page", "in": "query", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Lista paginada de permissoes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminPermissionListResponse" } } } }, "401": { "description": "Não autenticado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthenticatedResponse" } } } }, "403": { "description": "Sem permissao." } }, "security": [ { "sanctum": [] } ] }, "post": { "tags": [ "Admin" ], "summary": "Cria uma permissao Spatie.", "operationId": "adminCreatePermission", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminPermissionCreateRequest" } } } }, "responses": { "201": { "description": "Permissão criada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminPermissionMutationResponse" } } } }, "401": { "description": "Não autenticado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthenticatedResponse" } } } }, "403": { "description": "Sem permissao." }, "422": { "description": "Erro de validacao.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/admin/permissions/{permission}": { "delete": { "tags": [ "Admin" ], "summary": "Remove uma permissao.", "operationId": "adminDeletePermission", "parameters": [ { "name": "permission", "in": "path", "description": "ID ou nome da permissao.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Permissão removida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimpleSuccessResponse" } } } }, "401": { "description": "Não autenticado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthenticatedResponse" } } } }, "403": { "description": "Sem permissao." } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/admin/audit-logs": { "get": { "tags": [ "Admin" ], "summary": "Lista global do registo de auditoria com filtros por actor, accao, alvo e data.", "operationId": "adminListAuditLogs", "parameters": [ { "name": "actor_id", "in": "query", "description": "Filtra por ID do administrador que executou a accao.", "schema": { "type": "integer" } }, { "name": "actor_email", "in": "query", "description": "Filtra por email do administrador.", "schema": { "type": "string" } }, { "name": "action", "in": "query", "description": "Filtra por nome da accao (ex: user.updated).", "schema": { "type": "string" } }, { "name": "action_prefix", "in": "query", "description": "Filtra por prefixo (ex: kyc, tutor, article).", "schema": { "type": "string" } }, { "name": "target_type", "in": "query", "description": "Filtra por classe alvo (ex: App\\\\Models\\\\User).", "schema": { "type": "string" } }, { "name": "target_id", "in": "query", "schema": { "type": "integer" } }, { "name": "from", "in": "query", "description": "Data inicial (inclusive).", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "description": "Data final (inclusive).", "schema": { "type": "string", "format": "date-time" } }, { "name": "page", "in": "query", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Pagina do registo de auditoria." } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/admin/profile-types": { "get": { "tags": [ "Admin" ], "summary": "Lista o catalogo de tipos de perfil de utilizador.", "description": "Devolve todos os tipos de perfil registados (activos e inactivos), ordenados por sort_order. O slug e imutavel; restantes campos sao editaveis.", "operationId": "adminListProfileTypes", "responses": { "200": { "description": "Catalogo de tipos de perfil.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminProfileTypeListResponse" } } } }, "401": { "description": "Não autenticado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthenticatedResponse" } } } }, "403": { "description": "Sem permissao." } }, "security": [ { "sanctum": [] } ] }, "post": { "tags": [ "Admin" ], "summary": "Cria um novo tipo de perfil no catalogo.", "description": "Slug e imutavel apos a criacao. Definir is_default=true desmarca o anterior automaticamente.", "operationId": "adminCreateProfileType", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "slug", "label" ], "properties": { "slug": { "description": "Identificador unico imutavel (alpha_dash).", "type": "string", "example": "researcher", "maxLength": 50 }, "label": { "type": "string", "example": "Investigador", "maxLength": 100 }, "description": { "type": "string", "nullable": true }, "is_selectable": { "type": "boolean", "example": true }, "is_default": { "type": "boolean", "example": false }, "requires_kyc": { "type": "boolean", "example": false }, "icon": { "type": "string", "nullable": true, "maxLength": 50 }, "color": { "type": "string", "nullable": true, "maxLength": 20 }, "sort_order": { "type": "integer", "example": 10, "minimum": 0 }, "is_active": { "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Tipo de perfil criado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminProfileTypeMutationResponse" } } } }, "422": { "description": "Erro de validacao (slug duplicado, campos obrigatorios).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/admin/profile-types/{slug}": { "get": { "tags": [ "Admin" ], "summary": "Detalhe de um tipo de perfil pelo slug.", "operationId": "adminShowProfileType", "parameters": [ { "name": "slug", "in": "path", "description": "Slug imutavel do perfil (ex.: tutor, student).", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Detalhe do tipo de perfil.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/AdminProfileTypeItem" } }, "type": "object" } } } }, "404": { "description": "Slug não encontrado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityNotFoundResponse" } } } } }, "security": [ { "sanctum": [] } ] }, "delete": { "tags": [ "Admin" ], "summary": "Remove um tipo de perfil do catalogo.", "description": "Bloqueado se houver utilizadores associados. Para retirar de uso sem perder historico, prefira PATCH com is_active=false.", "operationId": "adminDeleteProfileType", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Tipo de perfil removido.", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Tipo de perfil removido com sucesso." } }, "type": "object" } } } }, "404": { "description": "Slug não encontrado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityNotFoundResponse" } } } }, "422": { "description": "Tipo de perfil em uso por utilizadores.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "sanctum": [] } ] }, "patch": { "tags": [ "Admin" ], "summary": "Edita campos de um tipo de perfil existente.", "description": "O slug não pode ser alterado. Se is_default=true, o anterior padrao e desmarcado automaticamente.", "operationId": "adminUpdateProfileType", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "label": { "type": "string", "example": "Explicador Profissional", "maxLength": 100 }, "description": { "type": "string", "nullable": true }, "is_selectable": { "type": "boolean" }, "is_default": { "type": "boolean" }, "requires_kyc": { "type": "boolean" }, "icon": { "type": "string", "nullable": true, "maxLength": 50 }, "color": { "type": "string", "nullable": true, "maxLength": 20 }, "sort_order": { "type": "integer", "minimum": 0 }, "is_active": { "type": "boolean" } }, "type": "object" } } } }, "responses": { "200": { "description": "Tipo de perfil actualizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminProfileTypeMutationResponse" } } } }, "404": { "description": "Slug não encontrado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityNotFoundResponse" } } } }, "422": { "description": "Erro de validacao.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/admin/roles": { "get": { "tags": [ "Admin" ], "summary": "Lista roles Spatie.", "operationId": "adminListRoles", "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "page", "in": "query", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Lista paginada de roles.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminRoleListResponse" } } } }, "401": { "description": "Não autenticado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthenticatedResponse" } } } }, "403": { "description": "Sem permissao." } }, "security": [ { "sanctum": [] } ] }, "post": { "tags": [ "Admin" ], "summary": "Cria uma role Spatie.", "operationId": "adminCreateRole", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminRoleCreateRequest" } } } }, "responses": { "201": { "description": "Role criada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminRoleMutationResponse" } } } }, "401": { "description": "Não autenticado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthenticatedResponse" } } } }, "403": { "description": "Sem permissao." }, "422": { "description": "Erro de validacao.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/admin/roles/{role}": { "get": { "tags": [ "Admin" ], "summary": "Retorna uma role por ID ou nome.", "operationId": "adminShowRole", "parameters": [ { "name": "role", "in": "path", "description": "ID ou nome da role.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Detalhe da role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminRoleItem" } } } }, "401": { "description": "Não autenticado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthenticatedResponse" } } } }, "403": { "description": "Sem permissao." } }, "security": [ { "sanctum": [] } ] }, "delete": { "tags": [ "Admin" ], "summary": "Remove uma role.", "operationId": "adminDeleteRole", "parameters": [ { "name": "role", "in": "path", "description": "ID ou nome da role.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Role removida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimpleSuccessResponse" } } } }, "401": { "description": "Não autenticado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthenticatedResponse" } } } }, "403": { "description": "Sem permissao." } }, "security": [ { "sanctum": [] } ] }, "patch": { "tags": [ "Admin" ], "summary": "Actualiza o nome de uma role.", "operationId": "adminUpdateRole", "parameters": [ { "name": "role", "in": "path", "description": "ID ou nome da role.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminRoleUpdateRequest" } } } }, "responses": { "200": { "description": "Role actualizada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminRoleMutationResponse" } } } }, "401": { "description": "Não autenticado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthenticatedResponse" } } } }, "403": { "description": "Sem permissao." }, "422": { "description": "Erro de validacao.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/admin/roles/{role}/permissions": { "patch": { "tags": [ "Admin" ], "summary": "Substitui as permissoes de uma role.", "operationId": "adminSyncRolePermissions", "parameters": [ { "name": "role", "in": "path", "description": "ID ou nome da role.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminSyncPermissionsRequest" } } } }, "responses": { "200": { "description": "Permissões da role actualizadas.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminRoleMutationResponse" } } } }, "401": { "description": "Não autenticado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthenticatedResponse" } } } }, "403": { "description": "Sem permissao." }, "422": { "description": "Erro de validacao.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/admin/subject-requests": { "get": { "tags": [ "Admin" ], "summary": "Lista pedidos de disciplinas submetidos por explicadores.", "description": "Filtros suportados: status (pending/approved/rejected/cancelled), q (procura em proposed_name/where_taught).", "operationId": "adminListSubjectRequests", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "approved", "rejected", "cancelled" ] } }, { "name": "q", "in": "query", "description": "Pesquisa por nome ou local onde leciona.", "schema": { "type": "string" } }, { "name": "page", "in": "query", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "maximum": 100, "minimum": 1 } } ], "responses": { "200": { "description": "Lista paginada de pedidos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminSubjectRequestListResponse" } } } }, "401": { "description": "Não autenticado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthenticatedResponse" } } } }, "403": { "description": "Sem permissao." } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/admin/subject-requests/{publicId}": { "get": { "tags": [ "Admin" ], "summary": "Detalhe de um pedido de disciplina.", "operationId": "adminShowSubjectRequest", "parameters": [ { "name": "publicId", "in": "path", "description": "public_id do pedido (ex.: sreq_abc123).", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Detalhe do pedido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminSubjectRequestItem" } } } }, "404": { "description": "Pedido não encontrado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityNotFoundResponse" } } } } }, "security": [ { "sanctum": [] } ] }, "patch": { "tags": [ "Admin" ], "summary": "Edita campos de um pedido pendente antes de aprovar/rejeitar.", "description": "So pedidos com status=pending podem ser editados. Aceita correcoes ortograficas no nome e ajustes nos niveis/grades propostos.", "operationId": "adminUpdateSubjectRequest", "parameters": [ { "name": "publicId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "proposed_name": { "type": "string", "maxLength": 255 }, "proposed_levels": { "type": "array", "items": { "properties": { "level": { "type": "string", "enum": [ "primario", "secundario", "tecnico", "universitario" ] }, "grades": { "type": "array", "items": { "type": "string" } } }, "type": "object" } }, "where_taught": { "type": "string", "nullable": true, "maxLength": 1000 }, "description": { "type": "string", "nullable": true, "maxLength": 2000 } }, "type": "object" } } } }, "responses": { "200": { "description": "Pedido actualizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminSubjectRequestMutationResponse" } } } }, "422": { "description": "Pedido não esta pendente ou erro de validacao.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/admin/subject-requests/{publicId}/approve": { "post": { "tags": [ "Admin" ], "summary": "Aprova um pedido e cria a disciplina no catalogo.", "description": "Cria uma nova entrada em \"subjects\" com slug derivado do nome (ou final_name se fornecido). Por defeito, anexa a disciplina ao perfil do explicador requisitante (em rascunho/inactivo) por cada nivel proposto. So pedidos pendentes podem ser aprovados.", "operationId": "adminApproveSubjectRequest", "parameters": [ { "name": "publicId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "final_name": { "description": "Nome final da disciplina (sobrescreve proposed_name).", "type": "string", "nullable": true, "maxLength": 255 }, "review_notes": { "type": "string", "nullable": true, "maxLength": 2000 }, "auto_attach_to_requester": { "description": "Se true (default), cria entradas TutorSubject inactivas para o requerente nos niveis propostos.", "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Pedido aprovado e disciplina criada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminSubjectRequestMutationResponse" } } } }, "422": { "description": "Pedido não esta pendente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/admin/subject-requests/{publicId}/reject": { "post": { "tags": [ "Admin" ], "summary": "Rejeita um pedido pendente com nota explicativa.", "operationId": "adminRejectSubjectRequest", "parameters": [ { "name": "publicId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "review_notes": { "description": "Motivo da rejeicao (visivel ao explicador).", "type": "string", "nullable": true, "maxLength": 2000 } }, "type": "object" } } } }, "responses": { "200": { "description": "Pedido rejeitado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminSubjectRequestMutationResponse" } } } }, "422": { "description": "Pedido não esta pendente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/admin/tutors": { "get": { "tags": [ "Admin" ], "summary": "Lista explicadores para gestao administrativa.", "operationId": "adminListTutors", "parameters": [ { "name": "q", "in": "query", "description": "Pesquisa por nome, slug, disciplina, email do utilizador associado.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "approved", "rejected", "inactive" ] } }, { "name": "verified", "in": "query", "schema": { "type": "boolean" } }, { "name": "discipline", "in": "query", "schema": { "type": "string" } }, { "name": "mode", "in": "query", "schema": { "type": "string", "enum": [ "online", "presencial", "domicilio", "todos" ] } }, { "name": "page", "in": "query", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Lista paginada de explicadores." }, "401": { "description": "Não autenticado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthenticatedResponse" } } } }, "403": { "description": "Sem permissao." } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/admin/tutors/{id}": { "get": { "tags": [ "Admin" ], "summary": "Detalhe administrativo completo de um explicador.", "description": "Inclui dados pessoais, capacidades, formação, KYC com documentos e reviewer, disciplinas com preços, disponibilidade por dia, top 10 reviews, e placeholders para stats e subscription.", "operationId": "adminShowTutor", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Detalhe do explicador.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminTutorItem" } } } }, "404": { "description": "Explicador não encontrado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityNotFoundResponse" } } } } }, "security": [ { "sanctum": [] } ] }, "delete": { "tags": [ "Admin" ], "summary": "Remove um perfil de explicador.", "operationId": "adminDeleteTutor", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Explicador removido." } }, "security": [ { "sanctum": [] } ] }, "patch": { "tags": [ "Admin" ], "summary": "Edita campos editaveis do perfil de explicador.", "operationId": "adminUpdateTutor", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Explicador actualizado." }, "422": { "description": "Erro de validacao.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/admin/tutors/{id}/status": { "patch": { "tags": [ "Admin" ], "summary": "Actualiza o estado administrativo de um explicador.", "operationId": "adminUpdateTutorAdminStatus", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "pending", "approved", "rejected", "inactive" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Estado actualizado." } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/admin/tutors/{id}/verification": { "patch": { "tags": [ "Admin" ], "summary": "Marca ou desmarca um explicador como verificado.", "operationId": "adminUpdateTutorVerification", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "verified" ], "properties": { "verified": { "type": "boolean" } }, "type": "object" } } } }, "responses": { "200": { "description": "Verificação actualizada." } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/admin/tutoring-sessions": { "get": { "tags": [ "Admin" ], "summary": "Lista sessões de explicação para gestão administrativa.", "operationId": "adminListTutoringSessions", "parameters": [ { "name": "tutor_id", "in": "query", "description": "public_id do tutor para filtrar.", "schema": { "type": "string" } }, { "name": "student_user_id", "in": "query", "schema": { "type": "integer" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "scheduled", "in_progress", "completed", "cancelled", "no_show" ] } }, { "name": "confirmed", "in": "query", "description": "Filtra apenas confirmadas (true) ou ainda não confirmadas (false).", "schema": { "type": "boolean" } }, { "name": "page", "in": "query", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Lista paginada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TutoringSessionListResponse" } } } }, "403": { "description": "Sem permissão." } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/admin/tutoring-sessions/{id}": { "get": { "tags": [ "Admin" ], "summary": "Detalhe administrativo de uma sessão.", "operationId": "adminShowTutoringSession", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Detalhe.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TutoringSessionItem" } } } }, "404": { "description": "Não encontrada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityNotFoundResponse" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/admin/users": { "get": { "tags": [ "Admin" ], "summary": "Lista utilizadores com roles e permissoes.", "operationId": "adminListUsers", "parameters": [ { "name": "q", "in": "query", "description": "Pesquisa por nome, email ou telefone.", "schema": { "type": "string" } }, { "name": "user_type", "in": "query", "description": "Filtra por slug(s) de perfil. Aceita um slug (\"tutor\"), CSV (\"tutor,tutor\") ou array (user_type[]=tutor&user_type[]=tutor). Match com qualquer um (OR). Slugs validos em GET /api/v1/admin/profile-types.", "schema": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "example": "tutor,tutor" }, { "name": "status", "in": "query", "description": "Filtra pelo estado operacional da conta.", "schema": { "type": "string", "enum": [ "active", "pending", "blocked", "suspended", "inactive" ] } }, { "name": "role", "in": "query", "description": "Filtra por role Spatie.", "schema": { "type": "string" } }, { "name": "permission", "in": "query", "description": "Filtra por permissao Spatie.", "schema": { "type": "string" } }, { "name": "kyc_status", "in": "query", "description": "Filtra pelo estado de KYC. Use \"none\" para utilizadores sem verificacao iniciada.", "schema": { "type": "string", "enum": [ "draft", "submitted", "under_review", "need_action", "approved", "rejected", "expired", "none" ] } }, { "name": "page", "in": "query", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Lista paginada de utilizadores.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminUserListResponse" } } } }, "401": { "description": "Não autenticado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthenticatedResponse" } } } }, "403": { "description": "Sem permissao." } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/admin/users/{email}": { "get": { "tags": [ "Admin" ], "summary": "Retorna um utilizador com roles e permissoes.", "operationId": "adminShowUser", "parameters": [ { "name": "email", "in": "path", "description": "Email do utilizador.", "required": true, "schema": { "type": "string", "format": "email" } } ], "responses": { "200": { "description": "Detalhe do utilizador.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminUserItem" } } } }, "401": { "description": "Não autenticado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthenticatedResponse" } } } }, "403": { "description": "Sem permissao." } }, "security": [ { "sanctum": [] } ] }, "delete": { "tags": [ "Admin" ], "summary": "Remove (soft delete) um utilizador, revogando tokens e sessoes.", "operationId": "adminDeleteUser", "parameters": [ { "name": "email", "in": "path", "required": true, "schema": { "type": "string", "format": "email" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "reason": { "type": "string", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Utilizador removido." }, "422": { "description": "Tentativa de auto-eliminar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "sanctum": [] } ] }, "patch": { "tags": [ "Admin" ], "summary": "Edita os dados base de um utilizador (sem mudar password ou estado operacional).", "operationId": "adminUpdateUser", "parameters": [ { "name": "email", "in": "path", "required": true, "schema": { "type": "string", "format": "email" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "maxLength": 255 }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string", "nullable": true }, "whatsapp": { "type": "string", "nullable": true }, "gender": { "type": "string", "nullable": true }, "birth_date": { "type": "string", "format": "date", "nullable": true }, "user_type": { "description": "Slug do perfil primário. Lista de slugs em GET /api/v1/admin/profile-types.", "type": "string", "example": "tutor" }, "user_types": { "description": "Conjunto completo de perfis a atribuir (substitui os existentes).", "type": "array", "items": { "type": "string" } }, "primary_user_type": { "description": "Slug do perfil primário quando user_types e enviado.", "type": "string", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Utilizador actualizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminUserMutationResponse" } } } }, "422": { "description": "Erro de validacao.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/admin/users/{email}/audit": { "get": { "tags": [ "Admin" ], "summary": "Retorna o registo de auditoria do utilizador (accoes administrativas que o tiveram como alvo).", "operationId": "adminUserAuditLog", "parameters": [ { "name": "email", "in": "path", "required": true, "schema": { "type": "string", "format": "email" } }, { "name": "action", "in": "query", "description": "Filtra por accao (ex: user.status_updated).", "schema": { "type": "string" } }, { "name": "page", "in": "query", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Registo de auditoria." } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/admin/users/{email}/status": { "patch": { "tags": [ "Admin" ], "summary": "Actualiza o estado operacional de uma conta.", "operationId": "adminUpdateUserStatus", "parameters": [ { "name": "email", "in": "path", "description": "Email do utilizador.", "required": true, "schema": { "type": "string", "format": "email" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminUserStatusUpdateRequest" } } } }, "responses": { "200": { "description": "Estado do utilizador actualizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminUserMutationResponse" } } } }, "401": { "description": "Não autenticado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthenticatedResponse" } } } }, "403": { "description": "Sem permissao." }, "422": { "description": "Erro de validacao.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/admin/users/{email}/roles": { "patch": { "tags": [ "Admin" ], "summary": "Substitui as roles de um utilizador.", "operationId": "adminSyncUserRoles", "parameters": [ { "name": "email", "in": "path", "description": "Email do utilizador.", "required": true, "schema": { "type": "string", "format": "email" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminSyncRolesRequest" } } } }, "responses": { "200": { "description": "Roles actualizadas.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminUserMutationResponse" } } } }, "401": { "description": "Não autenticado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthenticatedResponse" } } } }, "403": { "description": "Sem permissao." }, "422": { "description": "Erro de validacao.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/admin/users/{email}/permissions": { "patch": { "tags": [ "Admin" ], "summary": "Substitui as permissoes directas de um utilizador.", "operationId": "adminSyncUserPermissions", "parameters": [ { "name": "email", "in": "path", "description": "Email do utilizador.", "required": true, "schema": { "type": "string", "format": "email" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminSyncPermissionsRequest" } } } }, "responses": { "200": { "description": "Permissões directas actualizadas.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminUserMutationResponse" } } } }, "401": { "description": "Não autenticado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthenticatedResponse" } } } }, "403": { "description": "Sem permissao." }, "422": { "description": "Erro de validacao.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/admin/users/{email}/profile": { "get": { "tags": [ "Admin" ], "summary": "Vista 360 graus do utilizador para administracao.", "description": "Devolve agregado completo: identidade, KYC, perfil de tutor, sessoes, e listas de actividade (oportunidades criadas, interesses, favoritos, inscricoes, conteudos publicados, contactos a tutores, pedidos publicos). Cada lista limitada por history_limit; totais separados em \"totals\".", "operationId": "adminUserProfile", "parameters": [ { "name": "email", "in": "path", "required": true, "schema": { "type": "string", "format": "email" } }, { "name": "history_limit", "in": "query", "description": "Limite de itens em historicos e listas de actividade.", "schema": { "type": "integer", "default": 10, "maximum": 50, "minimum": 1 } } ], "responses": { "200": { "description": "Perfil completo do utilizador.", "content": { "application/json": { "schema": { "properties": { "user": { "$ref": "#/components/schemas/AdminUserItem" }, "kyc_documents": { "type": "array", "items": { "type": "object" } }, "login_history": { "type": "array", "items": { "type": "object" } }, "active_sessions": { "type": "array", "items": { "type": "object" } }, "tutor_profile": { "type": "object", "nullable": true }, "activity": { "properties": { "opportunities_created": { "description": "Oportunidades criadas pelo email do user.", "type": "array", "items": { "type": "object" } }, "opportunity_interests": { "description": "Interesses submetidos pelo user em oportunidades.", "type": "array", "items": { "type": "object" } }, "favorite_tutors": { "description": "Tutores marcados como favoritos.", "type": "array", "items": { "type": "object" } }, "enrollments": { "description": "Inscricoes em conteudos/eventos (polimorfico).", "type": "array", "items": { "type": "object" } }, "contents_authored": { "description": "Conteudos publicados pelo user via author_user_id.", "type": "array", "items": { "type": "object" } }, "tutor_contact_requests": { "description": "Contactos enviados pelo email do user a tutores.", "type": "array", "items": { "type": "object" } }, "find_tutor_requests": { "description": "Pedidos publicos de matching submetidos pelo email do user.", "type": "array", "items": { "type": "object" } } }, "type": "object" }, "totals": { "properties": { "login_history": { "type": "integer" }, "active_sessions": { "type": "integer" }, "opportunities_created": { "type": "integer" }, "opportunity_interests": { "type": "integer" }, "favorite_tutors": { "type": "integer" }, "enrollments": { "type": "integer" }, "contents_authored": { "type": "integer" }, "tutor_contact_requests": { "type": "integer" }, "find_tutor_requests": { "type": "integer" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Não autenticado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthenticatedResponse" } } } }, "403": { "description": "Sem permissao." }, "404": { "description": "Utilizador não encontrado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityNotFoundResponse" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/admin/users/{email}/sessions": { "delete": { "tags": [ "Admin" ], "summary": "Revoga todas as sessoes activas do utilizador.", "operationId": "adminRevokeUserSessions", "parameters": [ { "name": "email", "in": "path", "required": true, "schema": { "type": "string", "format": "email" } } ], "responses": { "200": { "description": "Sessões revogadas com sucesso." }, "401": { "description": "Não autenticado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthenticatedResponse" } } } }, "403": { "description": "Sem permissao." } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/admin/users/{email}/sessions/{session}": { "delete": { "tags": [ "Admin" ], "summary": "Revoga uma sessao especifica do utilizador.", "operationId": "adminRevokeUserSession", "parameters": [ { "name": "email", "in": "path", "required": true, "schema": { "type": "string", "format": "email" } }, { "name": "session", "in": "path", "description": "ID da sessao em user_device_sessions.", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Sessão revogada." }, "401": { "description": "Não autenticado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthenticatedResponse" } } } }, "403": { "description": "Sem permissao." }, "404": { "description": "Sessão não encontrada para este utilizador." }, "422": { "description": "Sessão ja estava revogada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/articles": { "get": { "tags": [ "Articles" ], "summary": "Lista artigos da secção editorial.", "operationId": "listArticles", "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "category", "in": "query", "schema": { "type": "string" } }, { "name": "page", "in": "query", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "name": "sort", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Lista paginada de artigos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedArticleListResponse" } } } } } } }, "/api/v1/articles/{slug}": { "get": { "tags": [ "Articles" ], "summary": "Retorna o detalhe de um artigo.", "operationId": "showArticle", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Detalhe do artigo.", "content": { "application/json": { "schema": { "properties": { "id": { "type": "string", "example": "article_123" }, "slug": { "type": "string", "example": "como-estudar-para-exames" }, "title": { "type": "string" }, "excerpt": { "type": "string" }, "cover_image_url": { "type": "string", "nullable": true }, "published_at": { "type": "string", "format": "date-time", "nullable": true }, "author_name": { "type": "string" }, "html": { "type": "string" } }, "type": "object" } } } } } } }, "/api/v1/platform/auth/register": { "post": { "tags": [ "PlatformAuth" ], "summary": "Cria conta de utilizador para a plataforma.", "operationId": "platformRegister", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformRegisterRequest" } } } }, "responses": { "201": { "description": "Conta criada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformAuthResponse" } } } }, "422": { "description": "Erro de validacao.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } } } }, "/api/v1/platform/auth/login": { "post": { "tags": [ "PlatformAuth" ], "summary": "Autentica utilizador da plataforma.", "operationId": "platformLogin", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformLoginRequest" } } } }, "responses": { "200": { "description": "Login concluído.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformAuthResponse" } } } }, "422": { "description": "Credenciais invalidas ou erro de validacao.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvalidCredentialsResponse" } } } } } } }, "/api/v1/me/contact-requests": { "get": { "tags": [ "Me" ], "summary": "Lista contactos recebidos pelo explicador autenticado.", "operationId": "listMyContactRequests", "parameters": [ { "name": "responded", "in": "query", "description": "Filtrar apenas respondidos (true) ou ainda por responder (false).", "required": false, "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Lista paginada de contactos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactRequestListResponse" } } } }, "403": { "description": "Apenas explicadores podem aceder." } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/me/contact-requests/{id}/respond": { "post": { "tags": [ "Me" ], "summary": "Marca um contacto como respondido (opcionalmente regista a mensagem de resposta).", "description": "O tutor confirma que respondeu ao solicitante (via canal externo: chamada, email, whatsapp). Time-to-response é calculado de `created_at` até este momento e usado para `avg_response_time` e `response_rate` nas stats.", "operationId": "respondToContactRequest", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "response_message": { "description": "Mensagem que o tutor enviou ao solicitante (para registo).", "type": "string", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Contacto marcado como respondido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactRequestItem" } } } }, "403": { "description": "Contacto não pertence a este tutor." }, "404": { "description": "Contacto não encontrado." }, "422": { "description": "Contacto já foi respondido." } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/contents": { "get": { "tags": [ "Public" ], "summary": "Lista publica de conteudos publicados (paginada).", "description": "Tambem usado pelas rotas alias: /courses, /videos, /exams, /books, /events, /projects (cada uma fixa o type via route default). Para tipo \"event\", eventos passados sao excluidos por defeito (use include_past=true para incluir).", "operationId": "publicListContents", "parameters": [ { "name": "type", "in": "query", "description": "Filtra pelo slug do content_type quando nao injectado por rota alias.", "schema": { "type": "string" } }, { "name": "search", "in": "query", "description": "Pesquisa em title e short_description (URL-encode caracteres acentuados).", "schema": { "type": "string" } }, { "name": "subject", "in": "query", "description": "public_id da disciplina.", "schema": { "type": "string" } }, { "name": "level", "in": "query", "description": "public_id do nivel de ensino.", "schema": { "type": "string" } }, { "name": "is_featured", "in": "query", "schema": { "type": "string", "enum": [ "true", "false", "1", "0" ] } }, { "name": "include_past", "in": "query", "description": "Apenas para tipo event.", "schema": { "type": "string", "enum": [ "true", "false", "1", "0" ] } }, { "name": "sort", "in": "query", "schema": { "type": "string", "default": "published_at", "enum": [ "published_at", "title", "view_count" ] } }, { "name": "order", "in": "query", "schema": { "type": "string", "default": "desc", "enum": [ "asc", "desc" ] } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "default": 12, "maximum": 50, "minimum": 1 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Lista paginada de conteudos.", "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "items": { "type": "object" } }, "pagination": { "properties": { "total": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" }, "last_page": { "type": "integer" } }, "type": "object" } }, "type": "object" } } } } } } }, "/api/v1/contents/featured": { "get": { "tags": [ "Public" ], "summary": "Devolve os 8 conteudos publicados marcados como destaque.", "description": "GET /contents/featured", "operationId": "publicFeaturedContents", "responses": { "200": { "description": "Lista de destaques.", "content": { "application/json": { "schema": { "properties": { "items": { "type": "array", "items": { "type": "object" } } }, "type": "object" } } } } } } }, "/api/v1/contents/{publicId}/enroll": { "post": { "tags": [ "Public" ], "summary": "Inscreve o utilizador autenticado num curso ou evento.", "description": "Apenas conteudos cujo content_type e curso ou evento aceitam inscricoes (ver supportsEnrollment). Idempotente: re-inscricao apos cancelamento reactiva.", "operationId": "enrollInContent", "parameters": [ { "name": "publicId", "in": "path", "description": "public_id do conteudo (ex.: cont_abc).", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "Inscricao criada ou reactivada." }, "404": { "description": "Conteudo não encontrado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityNotFoundResponse" } } } }, "422": { "description": "Conteudo não suporta inscricoes." } }, "security": [ { "sanctum": [] } ] }, "delete": { "tags": [ "Public" ], "summary": "Cancela a inscricao do utilizador autenticado num conteudo.", "description": "DELETE /contents/{publicId}/enroll", "operationId": "cancelEnrollment", "parameters": [ { "name": "publicId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Inscricao cancelada." }, "404": { "description": "Inscricao não encontrada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityNotFoundResponse" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/me/enrollments": { "get": { "tags": [ "Me" ], "summary": "Lista as inscricoes do utilizador autenticado.", "description": "GET /me/enrollments", "operationId": "listMyEnrollments", "responses": { "200": { "description": "Inscricoes do utilizador, com conteudo associado." } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/favorites": { "post": { "tags": [ "Favorites" ], "summary": "Adiciona ou remove um item autenticado dos favoritos.", "operationId": "toggleFavorite", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FavoriteToggleRequest" } } } }, "responses": { "201": { "description": "Item adicionado aos favoritos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FavoriteToggleResponse" } } } }, "200": { "description": "Item removido dos favoritos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FavoriteToggleResponse" } } } }, "401": { "description": "Autenticação necessária.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthenticatedResponse" } } } }, "404": { "description": "Item não encontrado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityNotFoundResponse" } } } }, "422": { "description": "Erro de validacao.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/favorites/check": { "get": { "tags": [ "Favorites" ], "summary": "Verifica se um item esta favoritado pelo utilizador autenticado.", "operationId": "checkFavorite", "parameters": [ { "name": "type", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "content", "tutor" ] } }, { "name": "id", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Estado de favorito retornado com sucesso.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FavoriteCheckResponse" } } } }, "401": { "description": "Autenticação necessária.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthenticatedResponse" } } } }, "422": { "description": "Erro de validacao.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/me/favorites": { "get": { "tags": [ "Favorites" ], "summary": "Lista os favoritos do utilizador autenticado.", "operationId": "listMyFavorites", "parameters": [ { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "content", "tutor" ] } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "example": 12 } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "example": 1 } } ], "responses": { "200": { "description": "Lista paginada de favoritos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FavoritesListResponse" } } } }, "401": { "description": "Autenticação necessária.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthenticatedResponse" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/find-tutor-requests": { "post": { "tags": [ "Matching" ], "summary": "Regista um pedido para encontrar explicador.", "operationId": "storeFindTutorRequest", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "discipline", "mode" ], "properties": { "discipline": { "type": "string", "example": "Matemática" }, "level": { "type": "string", "example": "12ª Classe", "nullable": true }, "mode": { "type": "string", "example": "online", "enum": [ "online", "presencial", "domicilio", "todos" ] }, "location": { "type": "string", "example": "Maputo", "nullable": true }, "budget_max": { "type": "integer", "example": 4500, "nullable": true }, "keyword": { "type": "string", "example": "preparação para exame", "nullable": true }, "guardian_name": { "type": "string", "example": "Ana Cumbe", "nullable": true }, "email": { "type": "string", "example": "ana@email.com", "nullable": true }, "phone": { "type": "string", "example": "+258840000000", "nullable": true }, "source": { "type": "string", "example": "find_tutor_modal", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Pedido registado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FindTutorRequestResponse" } } } }, "422": { "description": "Erro de validacao.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } } } }, "/api/v1/me": { "get": { "tags": [ "Me" ], "summary": "Retorna o utilizador autenticado.", "operationId": "platformMe", "responses": { "200": { "description": "Utilizador autenticado.", "content": { "application/json": { "schema": { "properties": { "id": { "type": "string", "example": "user_123" }, "name": { "type": "string", "example": "Jose Tembe" }, "email": { "type": "string", "example": "jose@email.com" }, "phone": { "type": "string", "example": "+258840000000", "nullable": true }, "whatsapp": { "type": "string", "example": "+258840000000", "nullable": true }, "gender": { "type": "string", "example": "male", "nullable": true }, "birth_date": { "type": "string", "format": "date", "example": "1995-10-08", "nullable": true }, "nationality": { "type": "string", "example": "Moçambicana", "nullable": true }, "languages": { "type": "array", "items": { "type": "string" }, "example": [ "Português", "Inglês" ] }, "role": { "type": "string", "example": "tutor", "enum": [ "student", "guardian", "tutor", "admin" ] }, "user_types": { "type": "array", "items": { "type": "string" }, "example": [ "tutor", "student" ] }, "is_admin": { "type": "boolean", "example": false }, "roles": { "type": "array", "items": { "type": "string" }, "example": [ "support" ] }, "permissions": { "type": "array", "items": { "type": "string" }, "example": [ "users.view", "opportunities.view" ] }, "last_login_at": { "type": "string", "format": "date-time", "nullable": true }, "last_active_at": { "type": "string", "format": "date-time", "nullable": true }, "kyc": { "description": "Estado de verificacao KYC do utilizador.", "type": "object", "nullable": true } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/me/tutor-profile": { "get": { "tags": [ "Me" ], "summary": "Retorna o perfil de explicador autenticado.", "operationId": "showMyTutorProfile", "responses": { "200": { "description": "Perfil do explicador.", "content": { "application/json": { "schema": { "properties": { "id": { "type": "string", "example": "tutor_123" }, "title": { "type": "string", "example": "Explicador de Matemática" }, "disciplines": { "type": "array", "items": { "type": "string" } }, "levels": { "type": "array", "items": { "type": "string" } }, "mode": { "type": "string", "example": "online", "enum": [ "online", "presencial", "domicilio", "todos" ] }, "location": { "type": "string", "example": "Maputo", "nullable": true }, "bio": { "type": "string", "nullable": true }, "price_monthly": { "type": "integer", "example": 4500, "nullable": true }, "availability_label": { "type": "string", "example": "Esta semana", "nullable": true }, "image_url": { "type": "string", "nullable": true } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] }, "patch": { "tags": [ "Me" ], "summary": "Actualiza o perfil do explicador autenticado.", "operationId": "updateMyTutorProfile", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "title": { "type": "string" }, "disciplines": { "type": "array", "items": { "type": "string" } }, "levels": { "type": "array", "items": { "type": "string" } }, "mode": { "type": "string", "enum": [ "online", "presencial", "domicilio", "todos" ] }, "location": { "type": "string", "nullable": true }, "bio": { "type": "string", "nullable": true }, "price_monthly": { "type": "integer", "nullable": true }, "availability_label": { "type": "string", "nullable": true }, "image_url": { "type": "string", "nullable": true }, "education_course": { "type": "string", "example": "Ensino de Matemática", "nullable": true }, "education_institution": { "type": "string", "example": "UEM", "nullable": true }, "education_level": { "type": "string", "nullable": true, "enum": [ "medio", "tecnico", "superior" ] }, "education_status": { "type": "string", "nullable": true, "enum": [ "concluido", "em_curso" ] }, "education_completion_year": { "type": "integer", "example": 2020, "nullable": true }, "education_current_year": { "type": "string", "example": "finalista", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Perfil actualizado.", "content": { "application/json": { "schema": { "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "disciplines": { "type": "array", "items": { "type": "string" } }, "levels": { "type": "array", "items": { "type": "string" } }, "mode": { "type": "string", "enum": [ "online", "presencial", "domicilio", "todos" ] }, "location": { "type": "string", "nullable": true }, "bio": { "type": "string", "nullable": true }, "price_monthly": { "type": "integer", "nullable": true }, "availability_label": { "type": "string", "nullable": true }, "image_url": { "type": "string", "nullable": true }, "education": { "$ref": "#/components/schemas/TutorEducation" } }, "type": "object" } } } }, "422": { "description": "Erro de validacao.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/me/tutor-profile/submit": { "post": { "tags": [ "Me" ], "summary": "Submete o perfil de explicador para revisao do admin.", "operationId": "submitMyTutorProfile", "responses": { "200": { "description": "Perfil submetido para revisao." }, "422": { "description": "Perfil incompleto." } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/me/tutor-profile/photo": { "post": { "tags": [ "Me" ], "summary": "Carrega a foto de capa do explicador (image_url).", "operationId": "uploadTutorProfilePhoto", "responses": { "201": { "description": "Foto carregada." }, "422": { "description": "Erro de validacao." } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/me/tutor-profile/cover": { "post": { "tags": [ "Me" ], "summary": "Carrega a imagem de fundo (cover_image_url).", "operationId": "uploadTutorProfileCover", "responses": { "201": { "description": "Capa carregada." }, "422": { "description": "Erro de validacao." } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/me/opportunity-interests": { "get": { "tags": [ "Me" ], "summary": "Lista os interesses do explicador autenticado.", "operationId": "listMyOpportunityInterests", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "to_review", "published", "closed", "cancelled" ] } }, { "name": "page", "in": "query", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Lista paginada de interesses.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MyOpportunityInterestsResponse" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/me/favorite-tutors": { "get": { "tags": [ "Me" ], "summary": "Lista explicadores favoritos do utilizador autenticado.", "operationId": "listMyFavoriteTutors", "responses": { "200": { "description": "Lista de favoritos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FavoriteTutorsResponse" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/me/opportunity-interests/{id}": { "delete": { "tags": [ "Me" ], "summary": "Cancela um interesse previamente submetido.", "operationId": "deleteMyOpportunityInterest", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Interesse cancelado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimpleSuccessResponse" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/me/opportunities/{id}/interests": { "get": { "tags": [ "Me" ], "summary": "Lista as candidaturas recebidas num pedido do solicitante autenticado.", "operationId": "listMyOpportunityInterestsAsGuardian", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Lista de candidaturas." }, "403": { "description": "Pedido não pertence ao utilizador." }, "404": { "description": "Pedido não encontrado." } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/me/opportunities/{id}/interests/{interestId}/approve": { "post": { "tags": [ "Me" ], "summary": "Solicitante aprova uma candidatura. Apenas uma candidatura pode ser aprovada por pedido; ao aprovar, o pedido transita para `closed`.", "operationId": "approveOpportunityInterest", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "interestId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Candidatura aprovada; pedido encerrado." }, "403": { "description": "Pedido não pertence ao utilizador." }, "404": { "description": "Pedido ou candidatura não encontrada." }, "422": { "description": "Pedido ja tem candidatura aprovada ou candidatura cancelada." } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/opportunities": { "get": { "tags": [ "Opportunities" ], "summary": "Lista pedidos de explicacao.", "operationId": "listOpportunities", "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "discipline", "in": "query", "schema": { "type": "string" } }, { "name": "level", "in": "query", "schema": { "type": "string" } }, { "name": "mode", "in": "query", "schema": { "type": "string", "enum": [ "online", "presencial", "domicilio", "todos" ] } }, { "name": "location", "in": "query", "schema": { "type": "string" } }, { "name": "budget_min", "in": "query", "schema": { "type": "integer" } }, { "name": "budget_max", "in": "query", "schema": { "type": "integer" } }, { "name": "frequency_min", "in": "query", "schema": { "type": "integer" } }, { "name": "frequency_max", "in": "query", "schema": { "type": "integer" } }, { "name": "urgency", "in": "query", "schema": { "type": "string", "enum": [ "normal", "alta", "urgente" ] } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "to_review", "published", "closed", "cancelled" ] } }, { "name": "page", "in": "query", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "name": "sort", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Lista paginada de pedidos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedOpportunityListResponse" } } } } } }, "post": { "tags": [ "Opportunities" ], "summary": "Cria um novo pedido de explicacao.", "operationId": "createOpportunity", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "guardian_name", "email", "phone", "discipline", "level", "mode", "frequency_per_week", "objectives", "description" ], "properties": { "guardian_name": { "type": "string" }, "student_name": { "type": "string", "nullable": true }, "email": { "type": "string" }, "phone": { "type": "string" }, "discipline": { "type": "string" }, "level": { "type": "string" }, "mode": { "type": "string", "enum": [ "online", "presencial", "domicilio", "todos" ] }, "location": { "type": "string", "nullable": true }, "budget_min": { "type": "integer", "nullable": true }, "budget_max": { "type": "integer", "nullable": true }, "frequency_per_week": { "type": "integer" }, "preferred_schedule": { "type": "string", "nullable": true }, "objectives": { "type": "array", "items": { "type": "string" } }, "description": { "type": "string" }, "urgency": { "type": "string", "nullable": true, "enum": [ "normal", "alta", "urgente" ] }, "availability_label": { "type": "string", "nullable": true }, "student_type": { "type": "string", "nullable": true }, "requirements": { "type": "array", "items": { "type": "string" } } }, "type": "object" } } } }, "responses": { "201": { "description": "Pedido criado.", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "id": { "type": "string", "example": "opp_123" } }, "type": "object" }, "message": { "type": "string", "example": "Pedido criado com sucesso." } }, "type": "object" } } } }, "422": { "description": "Erro de validacao.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } } } }, "/api/v1/opportunities/{id}": { "get": { "tags": [ "Opportunities" ], "summary": "Retorna o detalhe completo de um pedido.", "operationId": "showOpportunity", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Detalhe do pedido.", "content": { "application/json": { "schema": { "properties": { "id": { "type": "string", "example": "opp_123" }, "title": { "type": "string" }, "discipline": { "type": "string" }, "level": { "type": "string" }, "mode": { "type": "string", "enum": [ "online", "presencial", "domicilio", "todos" ] }, "location": { "type": "string", "nullable": true }, "description": { "type": "string" }, "budget_min": { "type": "integer", "nullable": true }, "budget_max": { "type": "integer", "nullable": true }, "frequency_per_week": { "type": "integer", "nullable": true }, "urgency": { "type": "string", "enum": [ "normal", "alta", "urgente" ] }, "posted_at": { "type": "string", "format": "date-time", "nullable": true }, "availability_label": { "type": "string", "nullable": true }, "student_type": { "type": "string", "nullable": true }, "preferred_schedule": { "type": "string", "nullable": true }, "objectives": { "type": "array", "items": { "type": "string" } }, "requirements": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "to_review", "published", "closed", "cancelled" ] } }, "type": "object" } } } } } } }, "/api/v1/opportunities/{id}/interests": { "post": { "tags": [ "Opportunities" ], "summary": "Permite ao explicador manifestar interesse num pedido.", "operationId": "expressInterestInOpportunity", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "email", "phone", "proposed_price", "source" ], "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "location": { "description": "Localizacao do explicador candidato.", "type": "string", "nullable": true }, "proposed_price": { "description": "Proposta de preco; deve estar dentro de [budget_min, budget_max] da opportunity.", "type": "integer" }, "tutor_id": { "type": "string", "nullable": true }, "source": { "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Candidatura registada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimpleSuccessResponse" } } } }, "403": { "description": "Apenas explicadores aprovados podem candidatar-se." }, "422": { "description": "Erro de validação (preço fora do orçamento, candidatura duplicada, ou pedido fechado).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } } } }, "/api/v1/opportunities/{id}/status": { "patch": { "tags": [ "Admin" ], "summary": "Actualiza o estado de um pedido.", "operationId": "updateOpportunityStatus", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "to_review", "published", "closed", "cancelled" ] }, "note": { "type": "string", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Estado actualizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimpleSuccessResponse" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/tutors": { "get": { "tags": [ "Tutors" ], "summary": "Lista explicadores com filtros.", "operationId": "listTutors", "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "discipline", "in": "query", "schema": { "type": "string" } }, { "name": "mode", "in": "query", "schema": { "type": "string", "enum": [ "online", "presencial", "domicilio", "todos" ] } }, { "name": "location", "in": "query", "schema": { "type": "string" } }, { "name": "price_min", "in": "query", "schema": { "type": "integer" } }, { "name": "price_max", "in": "query", "schema": { "type": "integer" } }, { "name": "experience_min", "in": "query", "schema": { "type": "integer" } }, { "name": "experience_max", "in": "query", "schema": { "type": "integer" } }, { "name": "verified", "in": "query", "schema": { "type": "boolean" } }, { "name": "page", "in": "query", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "price_asc", "price_desc", "rating_desc", "newest" ] } } ], "responses": { "200": { "description": "Lista paginada de explicadores.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedTutorListResponse" } } } } } } }, "/api/v1/tutors/{slug}": { "get": { "tags": [ "Tutors" ], "summary": "Retorna o perfil completo de um explicador.", "operationId": "showTutor", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Perfil do explicador.", "content": { "application/json": { "schema": { "properties": { "id": { "type": "string", "example": "tutor_123" }, "slug": { "type": "string", "example": "marcia-alberto" }, "hero": { "properties": { "name": { "type": "string" }, "role": { "type": "string" }, "experience_summary": { "type": "string" }, "rating": { "type": "number", "format": "float" }, "reviews_count": { "type": "integer" }, "students_count": { "type": "integer" }, "location": { "type": "string", "nullable": true }, "image_url": { "type": "string", "nullable": true }, "cover_image_url": { "type": "string", "nullable": true }, "quick_reply": { "type": "string", "nullable": true } }, "type": "object" }, "tags": { "type": "array", "items": { "type": "string" } }, "about": { "properties": { "short": { "type": "string", "nullable": true }, "extended": { "type": "string", "nullable": true } }, "type": "object" }, "education": { "$ref": "#/components/schemas/TutorEducation" }, "monthly_plan": { "properties": { "price": { "type": "integer", "nullable": true }, "price_label": { "type": "string", "nullable": true }, "availability_label": { "type": "string", "nullable": true }, "benefits": { "type": "array", "items": { "type": "string" } } }, "type": "object" }, "session_options": { "type": "array", "items": { "type": "object" } }, "quick_summary": { "type": "array", "items": { "type": "object" } }, "reviews": { "type": "array", "items": { "type": "object" } }, "related_tutors": { "type": "array", "items": { "$ref": "#/components/schemas/TutorListItem" } } }, "type": "object" } } } } } } }, "/api/v1/tutors/{id}/contact": { "post": { "tags": [ "Tutors" ], "summary": "Regista um pedido de contacto para um explicador.", "operationId": "contactTutor", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "email", "phone", "source" ], "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "message": { "type": "string", "nullable": true }, "source": { "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Pedido enviado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimpleSuccessResponse" } } } }, "422": { "description": "Erro de validacao.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } } } }, "/api/v1/tutors/{id}/reviews": { "post": { "tags": [ "Tutors" ], "summary": "Permite ao utilizador autenticado comentar um explicador.", "operationId": "storeTutorReview", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "comment" ], "properties": { "comment": { "type": "string", "example": "Explicou muito bem e ajudou na preparação para o exame." } }, "type": "object" } } } }, "responses": { "201": { "description": "Comentário criado.", "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "name": { "type": "string", "example": "Ana Cumbe" }, "avatar_url": { "type": "string", "example": "/data-assets/avatar/avatar-1.jpg", "nullable": true }, "date": { "type": "string", "format": "date", "example": "2026-04-16" }, "comment": { "type": "string", "example": "Explicou muito bem e ajudou na preparação para o exame." } }, "type": "object" }, "message": { "type": "string", "example": "Comentário submetido com sucesso." } }, "type": "object" } } } }, "401": { "description": "Não autenticado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthenticatedResponse" } } } }, "422": { "description": "Erro de validacao.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/tutors/{id}/status": { "patch": { "tags": [ "Admin" ], "summary": "Actualiza o estado de um explicador.", "operationId": "updateTutorStatus", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "status" ], "properties": { "status": { "type": "string", "example": "approved", "enum": [ "pending", "approved", "rejected", "inactive" ] }, "note": { "type": "string", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Estado actualizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimpleSuccessResponse" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/tutors/{id}/favorite": { "post": { "tags": [ "Tutors" ], "summary": "Adiciona um explicador aos favoritos do utilizador autenticado.", "operationId": "favoriteTutor", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Favorito guardado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimpleSuccessResponse" } } } }, "401": { "description": "Não autenticado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthenticatedResponse" } } } } }, "security": [ { "sanctum": [] } ] }, "delete": { "tags": [ "Tutors" ], "summary": "Remove um explicador dos favoritos do utilizador autenticado.", "operationId": "unfavoriteTutor", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Favorito removido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimpleSuccessResponse" } } } }, "401": { "description": "Não autenticado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthenticatedResponse" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/tutor-signup": { "post": { "tags": [ "Tutors" ], "summary": "Regista um novo explicador interessado na plataforma.", "operationId": "tutorSignup", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "email", "phone", "disciplines", "levels", "mode", "experience_years", "bio", "source" ], "properties": { "name": { "type": "string", "example": "Rosa Mate" }, "email": { "type": "string", "example": "rosa@email.com" }, "phone": { "type": "string", "example": "+258840000111" }, "disciplines": { "type": "array", "items": { "type": "string", "example": "Química" } }, "levels": { "type": "array", "items": { "type": "string", "example": "12ª Classe" } }, "mode": { "type": "string", "example": "presencial" }, "location": { "type": "string", "example": "Maputo", "nullable": true }, "experience_years": { "type": "integer", "example": 6 }, "bio": { "type": "string", "example": "Experiência com preparação para exames." }, "cv_url": { "type": "string", "example": "https://example.com/cv.pdf", "nullable": true }, "source": { "type": "string", "example": "landing" } }, "type": "object" } } } }, "responses": { "201": { "description": "Registo submetido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TutorSignupResponse" } } } }, "422": { "description": "Erro de validacao.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } } } }, "/api/v1/me/tutoring-sessions": { "get": { "tags": [ "Me" ], "summary": "Lista sessões de explicação do utilizador autenticado (como tutor ou como solicitante).", "description": "Por defeito lista sessões onde o utilizador é tutor (`role=tutor`) ou solicitante (`role=student`). Sem `role`, retorna sessões em qualquer um dos lados.", "operationId": "listMyTutoringSessions", "parameters": [ { "name": "role", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "tutor", "student" ] } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "scheduled", "in_progress", "completed", "cancelled", "no_show" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Lista paginada de sessões.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TutoringSessionListResponse" } } } } }, "security": [ { "sanctum": [] } ] }, "post": { "tags": [ "Me" ], "summary": "Regista uma sessão de explicação (acção do tutor).", "description": "O tutor regista que uma sessão aconteceu, opcionalmente ligando à candidatura aprovada da qual deriva. O solicitante deve depois confirmar via POST /me/tutoring-sessions/{id}/confirm.", "operationId": "createMyTutoringSession", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "student_user_id", "mode" ], "properties": { "opportunity_interest_id": { "description": "public_id da candidatura aprovada (opcional).", "type": "string", "nullable": true }, "student_user_id": { "description": "ID do utilizador aluno/solicitante.", "type": "integer" }, "scheduled_at": { "type": "string", "format": "date-time", "nullable": true }, "started_at": { "type": "string", "format": "date-time", "nullable": true }, "ended_at": { "type": "string", "format": "date-time", "nullable": true }, "duration_minutes": { "type": "integer", "example": 90, "nullable": true }, "mode": { "type": "string", "enum": [ "online", "presencial", "domicilio" ] }, "status": { "description": "Default `completed` quando o tutor regista após acontecer.", "type": "string", "enum": [ "scheduled", "in_progress", "completed" ] }, "notes": { "type": "string", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Sessão registada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TutoringSessionItem" } } } }, "403": { "description": "Apenas tutores aprovados podem registar sessões." }, "422": { "description": "Erro de validação.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/me/tutoring-sessions/{id}/confirm": { "post": { "tags": [ "Me" ], "summary": "Solicitante confirma que a sessão aconteceu (opcionalmente com rating e feedback).", "description": "Marca a sessão como confirmada. Após confirmação, a sessão conta para stats.completed_sessions do tutor. Apenas o solicitante (student_user_id) da sessão pode confirmar.", "operationId": "confirmMyTutoringSession", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "student_rating": { "type": "integer", "nullable": true, "maximum": 5, "minimum": 1 }, "student_feedback": { "type": "string", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Sessão confirmada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TutoringSessionItem" } } } }, "403": { "description": "Sessão não pertence ao utilizador autenticado." }, "404": { "description": "Sessão não encontrada." }, "422": { "description": "Sessão já confirmada ou cancelada." } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/me/tutoring-sessions/{id}/cancel": { "post": { "tags": [ "Me" ], "summary": "Cancela uma sessão (tutor ou solicitante).", "description": "Apenas o tutor (via user_id) ou o solicitante (student_user_id) podem cancelar. Sessão confirmada não pode ser cancelada.", "operationId": "cancelMyTutoringSession", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "reason": { "type": "string", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Sessão cancelada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TutoringSessionItem" } } } }, "403": { "description": "Sessão não pertence ao utilizador autenticado." }, "422": { "description": "Sessão já confirmada ou cancelada." } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/auth/register": { "post": { "tags": [ "Auth" ], "summary": "Cria uma nova conta e devolve o token inicial.", "operationId": "registerUser", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterRequest" } } } }, "responses": { "201": { "description": "Conta criada com sucesso.", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Conta criada com sucesso." }, "data": { "properties": { "token": { "type": "string", "example": "1|token-exemplo" }, "token_type": { "type": "string", "example": "Bearer" }, "user": { "$ref": "#/components/schemas/AuthUser" }, "onboarding": { "properties": { "email_verification_required": { "type": "boolean", "example": true }, "phone_verification_required": { "type": "boolean", "example": false }, "next_steps": { "type": "array", "items": { "type": "string", "example": "verify_email" } } }, "type": "object" }, "otp": { "type": "string", "example": "123456", "nullable": true } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "Erro de validacao ou captcha.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } } } }, "/api/v1/auth/login": { "post": { "tags": [ "Auth" ], "summary": "Inicia o login e cria um desafio MFA.", "operationId": "loginUser", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginRequest" } } } }, "responses": { "200": { "description": "Segundo fator requerido.", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Segundo fator requerido para concluir o login." }, "data": { "$ref": "#/components/schemas/MfaChallengePayload" } }, "type": "object" } } } }, "422": { "description": "Credenciais invalidas ou captcha rejeitado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } } } }, "/api/v1/auth/mfa/verify": { "post": { "tags": [ "Auth" ], "summary": "Valida o codigo MFA e devolve um token de acesso.", "operationId": "verifyMfaChallenge", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MfaVerifyRequest" } } } }, "responses": { "200": { "description": "Autenticação concluída.", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Autenticação realizada com sucesso." }, "data": { "$ref": "#/components/schemas/AuthPayload" } }, "type": "object" } } } }, "422": { "description": "Codigo invalido ou expirado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "429": { "description": "Limite de tentativas atingido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } } } } }, "/api/v1/auth/mfa/resend": { "post": { "tags": [ "Auth" ], "summary": "Reenvia o codigo MFA do desafio pendente.", "operationId": "resendMfaChallenge", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MfaResendRequest" } } } }, "responses": { "200": { "description": "Codigo reenviado.", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Codigo de 2FA reenviado com sucesso." }, "data": { "$ref": "#/components/schemas/MfaChallengePayload" } }, "type": "object" } } } }, "429": { "description": "Limite de reenvios atingido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "422": { "description": "Desafio invalido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } } } }, "/api/v1/auth/logout": { "post": { "tags": [ "Auth" ], "summary": "Termina a sessao atual.", "operationId": "logoutUser", "responses": { "200": { "description": "Sessão terminada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "401": { "description": "Não autenticado." } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/auth/me": { "get": { "tags": [ "Auth" ], "summary": "Devolve a identidade rica do utilizador autenticado.", "description": "Inclui perfis, roles, permissoes, kyc summary, login history (ultimas 5), active_sessions count e menus.", "operationId": "authMe", "responses": { "200": { "description": "Identidade do utilizador.", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/IdentityResource" } }, "type": "object" } } } }, "401": { "description": "Não autenticado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthenticatedResponse" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/auth/profile": { "patch": { "tags": [ "Auth" ], "summary": "Actualiza dados base do utilizador autenticado.", "description": "Mudancas em email/phone disparam re-verificacao e revogam o estado verified ate confirmacao por OTP/link.", "operationId": "authUpdateProfile", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "maxLength": 255 }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string", "nullable": true }, "whatsapp": { "type": "string", "nullable": true }, "gender": { "type": "string", "nullable": true }, "birth_date": { "type": "string", "format": "date", "nullable": true }, "nationality": { "type": "string", "example": "Moçambicana", "nullable": true }, "languages": { "type": "array", "items": { "type": "string" }, "example": [ "Português", "Inglês" ], "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Perfil actualizado com indicacao de proximos passos (verificacao se aplicavel)." }, "422": { "description": "Erro de validacao.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/auth/profile/photo": { "post": { "tags": [ "Auth" ], "summary": "Carrega a foto de perfil do utilizador autenticado.", "operationId": "authUploadProfilePhoto", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "photo" ], "properties": { "photo": { "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "200": { "description": "Foto carregada e URL devolvido." }, "422": { "description": "Ficheiro invalido (tipo/tamanho).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/auth/kyc": { "get": { "tags": [ "Auth" ], "summary": "Devolve o estado actual da verificacao KYC do utilizador autenticado.", "operationId": "showKycVerification", "responses": { "200": { "description": "Estado KYC.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/auth/kyc/draft": { "put": { "tags": [ "Auth" ], "summary": "Actualiza o draft KYC com perfil e NUIT.", "description": "Aceita slugs do catalogo de perfis cujo requires_kyc=true (consulte GET /api/v1/admin/profile-types).", "operationId": "saveKycDraft", "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "profile_type": { "description": "Slug do perfil KYC. Apenas slugs com requires_kyc=true sao validos.", "type": "string", "example": "tutor", "nullable": true }, "nuit": { "type": "string", "example": "123456789", "nullable": true, "maxLength": 50 } }, "type": "object" } } } }, "responses": { "200": { "description": "Draft actualizado.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "object" } }, "type": "object" } } } }, "422": { "description": "Slug invalido para KYC.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/auth/kyc/documents": { "post": { "tags": [ "Auth" ], "summary": "Carrega ou substitui um documento KYC.", "description": "Multipart/form-data. Ja existindo documento do mesmo tipo, e substituido (updateOrCreate). Tipos validos dependem do profile_type (ver requiredDocumentTypes).", "operationId": "uploadKycDocument", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "type", "file" ], "properties": { "type": { "description": "Tipo do documento KYC (id_document, selfie_liveness, address_proof, qualification, guardian_responsibility).", "type": "string" }, "file": { "type": "string", "format": "binary" }, "metadata": { "type": "object", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Documento carregado." }, "422": { "description": "Erro de validacao (tipo invalido, ficheiro fora dos limites).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "500": { "description": "Falha no armazenamento." } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/auth/kyc/documents/{document}/preview": { "get": { "tags": [ "Auth" ], "summary": "Devolve o ficheiro do documento KYC do utilizador autenticado para preview inline.", "description": "So o dono do documento pode aceder. Resposta com Content-Disposition inline para visualizacao em browser.", "operationId": "previewKycDocument", "parameters": [ { "name": "document", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Ficheiro do documento.", "content": { "application/octet-stream": {} } }, "404": { "description": "Documento não encontrado ou não pertence ao utilizador." } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/auth/kyc/submit": { "post": { "tags": [ "Auth" ], "summary": "Submete a verificacao KYC para revisao do admin.", "description": "Falha se: profile_type ausente, NUIT obrigatorio para tutor mas em falta, ou documentos obrigatorios em falta para o perfil.", "operationId": "submitKyc", "responses": { "200": { "description": "KYC submetido (status=submitted)." }, "422": { "description": "Falta perfil, NUIT ou documentos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/auth/password/forgot": { "post": { "tags": [ "Auth" ], "summary": "Solicita o envio do link de recuperacao de senha.", "operationId": "forgotPassword", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForgotPasswordRequest" } } } }, "responses": { "200": { "description": "Pedido recebido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "422": { "description": "Identificador invalido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } } } }, "/api/v1/auth/password/reset": { "post": { "tags": [ "Auth" ], "summary": "Redefine a senha com token de recuperacao.", "operationId": "resetPassword", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResetPasswordRequest" } } } }, "responses": { "200": { "description": "Senha redefinida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "422": { "description": "Token, email ou senha invalidos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } } } }, "/api/v1/auth/sessions": { "get": { "tags": [ "Sessions" ], "summary": "Lista as sessoes ativas do utilizador.", "operationId": "listSessions", "responses": { "200": { "description": "Lista de sessoes.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SessionResource" } } }, "type": "object" } } } }, "401": { "description": "Nao autenticado." } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/auth/sessions/{sessionId}": { "delete": { "tags": [ "Sessions" ], "summary": "Encerra uma sessao especifica do utilizador.", "operationId": "deleteSession", "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Sessao encerrada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "401": { "description": "Nao autenticado." }, "404": { "description": "Sessao nao encontrada." } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/auth/profile/user-type-options": { "get": { "tags": [ "Auth" ], "summary": "Lista os tipos de perfil seleccionaveis pelo utilizador.", "description": "Devolve perfis com is_selectable=true do catalogo (GET /api/v1/admin/profile-types).", "operationId": "tutorListUserTypeOptions", "responses": { "200": { "description": "Catalogo filtrado.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "properties": { "value": { "type": "string", "example": "tutor" }, "label": { "type": "string", "example": "Explicador" } }, "type": "object" } } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/auth/profile/type": { "patch": { "tags": [ "Auth" ], "summary": "Define ou troca o tipo de perfil primario do utilizador autenticado.", "description": "Adiciona o slug ao conjunto de perfis (mantem outros) e marca-o como primario. Para substituir o conjunto inteiro, use PUT /profile/types.", "operationId": "tutorUpdateUserType", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "user_type" ], "properties": { "user_type": { "description": "Slug do perfil (catalogo dinamico).", "type": "string", "example": "tutor" } }, "type": "object" } } } }, "responses": { "200": { "description": "Tipo actualizado.", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" }, "data": { "properties": { "user_type": { "type": "string", "example": "tutor" }, "user_type_label": { "type": "string", "example": "Explicador" }, "user_types": { "type": "array", "items": { "type": "string" } }, "menu_options": { "type": "array", "items": { "type": "object" } } }, "type": "object" } }, "type": "object" } } } }, "422": { "description": "Slug invalido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/auth/profile/types": { "put": { "tags": [ "Auth" ], "summary": "Substitui o conjunto completo de perfis do utilizador.", "description": "Operacao destrutiva: perfis nao incluidos em user_types sao removidos. Use PATCH /profile/type para apenas adicionar.", "operationId": "tutorSyncUserTypes", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "user_types" ], "properties": { "user_types": { "description": "Conjunto completo de slugs.", "type": "array", "items": { "type": "string" }, "example": [ "tutor", "guardian" ], "minItems": 1 }, "primary_user_type": { "description": "Slug que fica como primario. Deve estar incluido em user_types.", "type": "string", "example": "tutor", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Perfis sincronizados." }, "422": { "description": "Erro de validacao.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/auth/tutor/subjects": { "get": { "tags": [ "Auth" ], "summary": "Lista as disciplinas do explicador autenticado.", "operationId": "tutorListSubjects", "responses": { "200": { "description": "Disciplinas do explicador." }, "403": { "description": "Apenas explicadores podem aceder." } }, "security": [ { "sanctum": [] } ] }, "post": { "tags": [ "Auth" ], "summary": "Adiciona uma disciplina ao perfil do explicador.", "description": "Disciplina deve existir no catalogo (subject_public_id). Educacao: primario|secundario|tecnico|universitario. price_unit: session|monthly. hourly_rate e alias legado de price_amount.", "operationId": "tutorStoreSubject", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "subject_public_id", "education_level" ], "properties": { "subject_public_id": { "type": "string", "example": "subj_abc" }, "education_level": { "type": "string", "enum": [ "primario", "secundario", "tecnico", "universitario" ] }, "grades": { "type": "array", "items": { "type": "string" }, "example": [ "10ª", "11ª" ] }, "price_amount": { "type": "number", "format": "float", "example": 500, "minimum": 0 }, "price_unit": { "type": "string", "example": "session", "enum": [ "session", "monthly" ] }, "currency": { "type": "string", "example": "MZN", "maxLength": 3 }, "notes": { "type": "string", "nullable": true, "maxLength": 1000 }, "is_active": { "type": "boolean", "example": true }, "hourly_rate": { "description": "Alias legado de price_amount.", "type": "number", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Disciplina criada." }, "422": { "description": "Disciplina ja registada para este nivel ou erro de validacao.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/auth/tutor/subjects/{tutorSubject}": { "put": { "tags": [ "Auth" ], "summary": "Edita uma disciplina do perfil do explicador.", "operationId": "tutorUpdateSubject", "parameters": [ { "name": "tutorSubject", "in": "path", "description": "ID interno do registo TutorSubject.", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "subject_public_id": { "type": "string" }, "education_level": { "type": "string", "enum": [ "primario", "secundario", "tecnico", "universitario" ] }, "grades": { "type": "array", "items": { "type": "string" }, "nullable": true }, "price_amount": { "type": "number", "nullable": true }, "price_unit": { "type": "string", "enum": [ "session", "monthly" ] }, "currency": { "type": "string", "maxLength": 3 }, "notes": { "type": "string", "nullable": true }, "is_active": { "type": "boolean" }, "hourly_rate": { "description": "Alias legado.", "type": "number", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Disciplina actualizada." }, "404": { "description": "Registo nao pertence ao utilizador." }, "422": { "description": "Erro de validacao.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "sanctum": [] } ] }, "delete": { "tags": [ "Auth" ], "summary": "Remove uma disciplina do perfil do explicador.", "operationId": "tutorDestroySubject", "parameters": [ { "name": "tutorSubject", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Disciplina removida." }, "404": { "description": "Registo nao pertence ao utilizador." } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/auth/tutor/education-levels": { "get": { "tags": [ "Auth" ], "summary": "Devolve os niveis de ensino e grades aceites + opcoes de unidade de preco.", "operationId": "tutorListEducationLevels", "responses": { "200": { "description": "Catalogo educativo.", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "properties": { "value": { "type": "string", "example": "secundario" }, "label": { "type": "string", "example": "Ensino Secundario" }, "grades": { "type": "array", "items": { "type": "string" } } }, "type": "object" } }, "meta": { "properties": { "price_units": { "type": "array", "items": { "type": "object" } }, "session_average_minutes": { "type": "integer", "example": 90 }, "monthly_average_sessions": { "type": "integer", "example": 10 } }, "type": "object" } }, "type": "object" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/auth/tutor/subject-requests": { "get": { "tags": [ "Auth" ], "summary": "Lista os pedidos de disciplinas submetidos pelo explicador autenticado.", "operationId": "tutorListSubjectRequests", "responses": { "200": { "description": "Pedidos do explicador (todos os status)." }, "403": { "description": "Apenas explicadores podem aceder." } }, "security": [ { "sanctum": [] } ] }, "post": { "tags": [ "Auth" ], "summary": "Submete um pedido para criar uma nova disciplina no catalogo.", "description": "Use quando a disciplina pretendida nao esta em GET /api/v1/subjects. O admin recebe o pedido em /admin/subject-requests para aprovar.", "operationId": "tutorCreateSubjectRequest", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "proposed_name", "proposed_levels" ], "properties": { "proposed_name": { "type": "string", "example": "Programacao em Python", "maxLength": 255 }, "proposed_levels": { "type": "array", "items": { "properties": { "level": { "type": "string", "enum": [ "primario", "secundario", "tecnico", "universitario" ] }, "grades": { "type": "array", "items": { "type": "string" } } }, "type": "object" }, "minItems": 1 }, "where_taught": { "type": "string", "maxLength": 1000 }, "description": { "type": "string", "nullable": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Pedido enviado." }, "422": { "description": "Pedido pendente duplicado ou erro de validacao.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/auth/tutor/subject-requests/{subjectRequest}": { "delete": { "tags": [ "Auth" ], "summary": "Cancela um pedido de disciplina pendente.", "description": "So o autor pode cancelar e apenas pedidos com status=pending. O pedido fica marcado como cancelled.", "operationId": "tutorCancelSubjectRequest", "parameters": [ { "name": "subjectRequest", "in": "path", "description": "ID interno do pedido.", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Pedido cancelado." }, "404": { "description": "Pedido nao pertence ao utilizador." }, "422": { "description": "Pedido nao esta pendente." } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/auth/tutor/availability": { "get": { "tags": [ "Auth" ], "summary": "Lista as janelas de disponibilidade do explicador.", "operationId": "tutorListAvailabilities", "responses": { "200": { "description": "Disponibilidades agrupadas por dia da semana." }, "403": { "description": "Apenas explicadores podem aceder." } }, "security": [ { "sanctum": [] } ] }, "post": { "tags": [ "Auth" ], "summary": "Cria uma nova janela de disponibilidade.", "description": "day_of_week: 0=Domingo, 6=Sabado. Sobreposicao com janelas activas e rejeitada.", "operationId": "tutorStoreAvailability", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "day_of_week", "start_time", "end_time" ], "properties": { "day_of_week": { "type": "integer", "example": 2, "maximum": 6, "minimum": 0 }, "start_time": { "type": "string", "example": "14:00" }, "end_time": { "type": "string", "example": "16:00" }, "mode": { "type": "string", "example": "online", "enum": [ "online", "presencial", "domicilio", "todos" ] }, "timezone": { "type": "string", "example": "Africa/Maputo" }, "is_active": { "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "201": { "description": "Disponibilidade criada." }, "422": { "description": "Sobreposicao ou erro de validacao.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/auth/tutor/availability/{tutorAvailability}": { "put": { "tags": [ "Auth" ], "summary": "Edita uma janela de disponibilidade.", "operationId": "tutorUpdateAvailability", "parameters": [ { "name": "tutorAvailability", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "day_of_week": { "type": "integer", "maximum": 6, "minimum": 0 }, "start_time": { "type": "string" }, "end_time": { "type": "string" }, "mode": { "type": "string", "enum": [ "online", "presencial", "domicilio", "todos" ] }, "timezone": { "type": "string" }, "is_active": { "type": "boolean" } }, "type": "object" } } } }, "responses": { "200": { "description": "Disponibilidade actualizada." }, "422": { "description": "Sobreposicao ou erro de validacao.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "sanctum": [] } ] }, "delete": { "tags": [ "Auth" ], "summary": "Remove uma janela de disponibilidade.", "operationId": "tutorDestroyAvailability", "parameters": [ { "name": "tutorAvailability", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Disponibilidade removida." }, "404": { "description": "Janela nao pertence ao utilizador." } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/auth/email/verification-notification": { "post": { "tags": [ "Verification" ], "summary": "Reenvia o email de verificacao para o utilizador autenticado.", "operationId": "resendEmailVerification", "responses": { "200": { "description": "Email reenviado ou ja confirmado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "401": { "description": "Não autenticado." }, "422": { "description": "Utilizador sem email.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/auth/email/verify/{id}/{hash}": { "get": { "tags": [ "Verification" ], "summary": "Confirma o email a partir do link assinado.", "operationId": "verifyEmailAddress", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "hash", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Email confirmado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "403": { "description": "Assinatura invalida." }, "404": { "description": "Utilizador não encontrado." } } } }, "/api/v1/auth/phone/otp/send": { "post": { "tags": [ "Verification" ], "summary": "Envia ou reenvia o OTP de confirmacao de telefone.", "operationId": "sendPhoneOtp", "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendPhoneOtpRequest" } } } }, "responses": { "201": { "description": "OTP criado.", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "OTP enviado com sucesso." }, "data": { "properties": { "expires_at": { "type": "string", "format": "date-time" }, "otp": { "type": "string", "example": "123456", "nullable": true } }, "type": "object" } }, "type": "object" } } } }, "200": { "description": "OTP reenviado.", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "OTP reenviado com sucesso." }, "data": { "properties": { "expires_at": { "type": "string", "format": "date-time" }, "otp": { "type": "string", "example": "123456", "nullable": true } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Não autenticado." }, "422": { "description": "Numero invalido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "429": { "description": "Limite de reenvios atingido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } } }, "security": [ { "sanctum": [] } ] } }, "/api/v1/auth/phone/otp/verify": { "post": { "tags": [ "Verification" ], "summary": "Valida o OTP e confirma o telefone do utilizador.", "operationId": "verifyPhoneOtp", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyPhoneOtpRequest" } } } }, "responses": { "200": { "description": "Telefone confirmado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "401": { "description": "Não autenticado." }, "422": { "description": "Codigo invalido ou expirado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationErrorResponse" } } } }, "429": { "description": "Limite de tentativas atingido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } } }, "security": [ { "sanctum": [] } ] } } }, "components": { "schemas": { "MessageResponse": { "properties": { "message": { "type": "string", "example": "Operação concluída com sucesso." } }, "type": "object" }, "AuthUser": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Ana Paulo" }, "email": { "type": "string", "example": "ana@example.com", "nullable": true }, "phone": { "type": "string", "example": "+258841234567", "nullable": true }, "user_type": { "description": "Slug do perfil primário do utilizador. Catalogo dinamico em GET /api/v1/admin/profile-types.", "type": "string", "example": "student" }, "user_type_label": { "description": "Label legivel do perfil primário.", "type": "string", "example": "Estudante", "nullable": true }, "email_verified": { "type": "boolean", "example": false }, "phone_verified": { "type": "boolean", "example": false }, "last_login_at": { "type": "string", "format": "date-time", "nullable": true }, "last_login_ip": { "type": "string", "example": "127.0.0.1", "nullable": true }, "last_login_origin": { "type": "string", "example": "web", "nullable": true } }, "type": "object" }, "AuthPayload": { "properties": { "token": { "type": "string", "example": "1|token-exemplo" }, "token_type": { "type": "string", "example": "Bearer" }, "user": { "$ref": "#/components/schemas/AuthUser" } }, "type": "object" }, "MfaChallengePayload": { "properties": { "mfa_required": { "type": "boolean", "example": true }, "challenge_id": { "type": "string", "example": "01JXYZ123ABC456DEF789GHIJK" }, "channel": { "type": "string", "example": "email" }, "destination_masked": { "type": "string", "example": "an***@example.com" }, "expires_at": { "type": "string", "format": "date-time" }, "otp": { "type": "string", "example": "123456", "nullable": true } }, "type": "object" }, "RegisterRequest": { "required": [ "name", "password", "password_confirmation", "terms_accepted" ], "properties": { "name": { "type": "string", "example": "Ana Paulo" }, "email": { "type": "string", "example": "ana@example.com", "nullable": true }, "phone": { "type": "string", "example": "+258841234567", "nullable": true }, "password": { "type": "string", "format": "password", "example": "Senha@123" }, "password_confirmation": { "type": "string", "format": "password", "example": "Senha@123" }, "terms_accepted": { "type": "boolean", "example": true }, "user_type": { "description": "Slug do perfil pretendido. Catalogo em GET /api/v1/admin/profile-types (apenas slugs com is_selectable=true sao aceites).", "type": "string", "example": "student", "nullable": true }, "device_name": { "type": "string", "example": "Chrome Mac", "nullable": true }, "platform": { "type": "string", "example": "web", "nullable": true }, "captcha_token": { "type": "string", "example": "captcha-token", "nullable": true } }, "type": "object" }, "LoginRequest": { "required": [ "identifier", "password" ], "properties": { "identifier": { "type": "string", "example": "ana@example.com" }, "password": { "type": "string", "format": "password", "example": "Senha@123" }, "device_name": { "type": "string", "example": "Chrome Mac", "nullable": true }, "platform": { "type": "string", "example": "web", "nullable": true }, "captcha_token": { "type": "string", "example": "captcha-token", "nullable": true } }, "type": "object" }, "MfaVerifyRequest": { "required": [ "challenge_id", "code" ], "properties": { "challenge_id": { "type": "string", "example": "01JXYZ123ABC456DEF789GHIJK" }, "code": { "type": "string", "example": "123456" }, "device_name": { "type": "string", "example": "Chrome Mac", "nullable": true }, "platform": { "type": "string", "example": "web", "nullable": true } }, "type": "object" }, "MfaResendRequest": { "required": [ "challenge_id" ], "properties": { "challenge_id": { "type": "string", "example": "01JXYZ123ABC456DEF789GHIJK" } }, "type": "object" }, "ForgotPasswordRequest": { "required": [ "identifier" ], "properties": { "identifier": { "type": "string", "example": "ana@example.com" } }, "type": "object" }, "ResetPasswordRequest": { "required": [ "token", "email", "password", "password_confirmation" ], "properties": { "token": { "type": "string", "example": "reset-token" }, "email": { "type": "string", "example": "ana@example.com" }, "password": { "type": "string", "format": "password", "example": "NovaSenha@123" }, "password_confirmation": { "type": "string", "format": "password", "example": "NovaSenha@123" } }, "type": "object" }, "SendPhoneOtpRequest": { "properties": { "phone": { "type": "string", "example": "+258841234567", "nullable": true } }, "type": "object" }, "VerifyPhoneOtpRequest": { "required": [ "code" ], "properties": { "phone": { "type": "string", "example": "+258841234567", "nullable": true }, "code": { "type": "string", "example": "123456" } }, "type": "object" }, "RecentLogin": { "properties": { "ip_address": { "type": "string", "example": "127.0.0.1", "nullable": true }, "user_agent": { "type": "string", "example": "Mozilla/5.0", "nullable": true }, "platform": { "type": "string", "example": "web", "nullable": true }, "logged_in_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" }, "IdentityResource": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Ana Paulo" }, "email": { "type": "string", "example": "ana@example.com", "nullable": true }, "phone": { "type": "string", "example": "+258841234567", "nullable": true }, "user_type": { "description": "Slug do perfil primário. Catalogo em GET /api/v1/admin/profile-types.", "type": "string", "example": "student" }, "user_type_label": { "type": "string", "example": "Estudante", "nullable": true }, "user_types": { "description": "Lista de slugs de perfis atribuidos.", "type": "array", "items": { "type": "string" } }, "email_verified": { "type": "boolean", "example": true }, "phone_verified": { "type": "boolean", "example": true }, "last_login_at": { "type": "string", "format": "date-time", "nullable": true }, "last_login_ip": { "type": "string", "example": "127.0.0.1", "nullable": true }, "last_login_origin": { "type": "string", "example": "web", "nullable": true }, "active_sessions": { "type": "integer", "example": 2 }, "recent_logins": { "type": "array", "items": { "$ref": "#/components/schemas/RecentLogin" } } }, "type": "object" }, "SessionResource": { "properties": { "id": { "type": "integer", "example": 11 }, "device_name": { "type": "string", "example": "Chrome Mac", "nullable": true }, "platform": { "type": "string", "example": "web", "nullable": true }, "ip_address": { "type": "string", "example": "127.0.0.1", "nullable": true }, "user_agent": { "type": "string", "example": "Mozilla/5.0", "nullable": true }, "last_login_at": { "type": "string", "format": "date-time", "nullable": true }, "last_seen_at": { "type": "string", "format": "date-time", "nullable": true }, "is_current": { "type": "boolean", "example": true } }, "type": "object" }, "ValidationErrorResponse": { "properties": { "message": { "type": "string", "example": "The given data was invalid." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "type": "object" }, "SimpleSuccessResponse": { "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Operação concluída com sucesso." } }, "type": "object" }, "PlatformAuthUser": { "properties": { "id": { "type": "string", "example": "user_123" }, "name": { "type": "string", "example": "Jose Tembe" }, "email": { "type": "string", "example": "jose@email.com" }, "role": { "type": "string", "example": "tutor" } }, "type": "object" }, "PlatformAuthResponse": { "properties": { "token": { "type": "string", "example": "1|token-exemplo" }, "user": { "$ref": "#/components/schemas/PlatformAuthUser" } }, "type": "object" }, "PlatformRegisterRequest": { "required": [ "name", "email", "password", "role" ], "properties": { "name": { "type": "string", "example": "Jose Tembe" }, "email": { "type": "string", "example": "jose@email.com" }, "phone": { "type": "string", "example": "+258840000000", "nullable": true }, "password": { "type": "string", "format": "password", "example": "Strong@123" }, "role": { "type": "string", "example": "tutor" } }, "type": "object" }, "PlatformLoginRequest": { "required": [ "email", "password" ], "properties": { "email": { "type": "string", "example": "jose@email.com" }, "password": { "type": "string", "format": "password", "example": "Strong@123" } }, "type": "object" }, "TutorEducation": { "description": "Formação académica do explicador. Todos os campos são opcionais. Se `status === concluido`, `completion_year` deve estar preenchido; se `status === em_curso`, `current_year` deve estar preenchido.", "properties": { "course": { "type": "string", "example": "Ensino de Matemática", "nullable": true }, "institution": { "type": "string", "example": "UEM", "nullable": true }, "level": { "type": "string", "example": "superior", "nullable": true, "enum": [ "medio", "tecnico", "superior" ] }, "status": { "type": "string", "example": "concluido", "nullable": true, "enum": [ "concluido", "em_curso" ] }, "completion_year": { "type": "integer", "example": 2020, "nullable": true }, "current_year": { "description": "Valores típicos: \"1\", \"2\", \"3\", \"finalista\".", "type": "string", "example": "finalista", "nullable": true } }, "type": "object" }, "ContactRequestItem": { "description": "Contacto recebido pelo tutor (formulário de contacto). Usado para calcular response_rate e avg_response_time nas stats.", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "message": { "type": "string", "nullable": true }, "source": { "type": "string" }, "responded_at": { "type": "string", "format": "date-time", "nullable": true }, "response_message": { "type": "string", "nullable": true }, "response_time_seconds": { "description": "Tempo entre received e responded em segundos. null se ainda não respondido.", "type": "integer", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "ContactRequestListResponse": { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ContactRequestItem" } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" }, "message": { "type": "string", "nullable": true } }, "type": "object" }, "TutoringSessionItem": { "description": "Sessão de explicação. status `completed` + `confirmed_at` != null = sessão real validada pelo aluno.", "properties": { "id": { "type": "string", "example": "session_01ABC" }, "status": { "type": "string", "enum": [ "scheduled", "in_progress", "completed", "cancelled", "no_show" ] }, "mode": { "type": "string", "enum": [ "online", "presencial", "domicilio" ] }, "scheduled_at": { "type": "string", "format": "date-time", "nullable": true }, "started_at": { "type": "string", "format": "date-time", "nullable": true }, "ended_at": { "type": "string", "format": "date-time", "nullable": true }, "duration_minutes": { "type": "integer", "nullable": true }, "confirmed_at": { "type": "string", "format": "date-time", "nullable": true }, "student_rating": { "type": "integer", "nullable": true, "maximum": 5, "minimum": 1 }, "student_feedback": { "type": "string", "nullable": true }, "cancelled_at": { "type": "string", "format": "date-time", "nullable": true }, "cancellation_reason": { "type": "string", "nullable": true }, "notes": { "type": "string", "nullable": true }, "tutor": { "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "discipline": { "type": "string", "nullable": true } }, "type": "object", "nullable": true }, "student": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string", "nullable": true } }, "type": "object", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "TutoringSessionListResponse": { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/TutoringSessionItem" } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" }, "message": { "type": "string", "nullable": true } }, "type": "object" }, "AdminTutorItem": { "description": "Payload completo do explicador na view admin (`GET /admin/tutors/{id}`). Inclui dados pessoais, capacidades, formação, KYC, disciplinas, disponibilidade e reviews. Stats e subscription são placeholders até existirem os subsistemas de tracking/pagamentos.", "properties": { "id": { "type": "string", "example": "tutor_123" }, "slug": { "type": "string" }, "name": { "type": "string" }, "title": { "type": "string" }, "discipline": { "type": "string" }, "mode": { "type": "string", "enum": [ "online", "presencial", "domicilio", "todos" ] }, "location": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "pending", "approved", "rejected", "inactive" ] }, "verified": { "type": "boolean" }, "rating": { "type": "number", "format": "float" }, "price_monthly": { "type": "integer", "nullable": true }, "experience_years": { "type": "integer" }, "reviews_count": { "type": "integer" }, "contact_requests_count": { "type": "integer" }, "interests_count": { "type": "integer" }, "students_count": { "type": "integer" }, "education": { "$ref": "#/components/schemas/TutorEducation" }, "user": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "user_type": { "type": "string" }, "user_type_label": { "type": "string" }, "status": { "type": "string" } }, "type": "object", "nullable": true }, "birth_date": { "type": "string", "format": "date", "nullable": true }, "gender": { "type": "string", "nullable": true }, "nationality": { "type": "string", "example": "Moçambicana", "nullable": true }, "languages": { "type": "array", "items": { "type": "string" }, "example": [ "Português", "Inglês" ] }, "last_login_at": { "type": "string", "format": "date-time", "nullable": true }, "last_active_at": { "type": "string", "format": "date-time", "nullable": true }, "admin_notes": { "description": "Notas internas do admin (apenas visíveis ao admin).", "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "about_short": { "type": "string", "nullable": true }, "about_extended": { "type": "string", "nullable": true }, "availability_label": { "type": "string", "nullable": true }, "image_url": { "type": "string", "nullable": true }, "cover_image_url": { "type": "string", "nullable": true }, "disciplines": { "description": "Disciplinas leccionadas com níveis e preços. Derivado de TutorSubject pivot.", "type": "array", "items": { "properties": { "name": { "type": "string", "example": "Matemática" }, "levels": { "type": "array", "items": { "type": "string" }, "example": [ "10", "11", "12" ] }, "education_level": { "type": "string", "example": "secundario", "nullable": true }, "price": { "type": "number", "format": "float", "nullable": true }, "price_unit": { "type": "string", "nullable": true, "enum": [ "session", "monthly" ] }, "currency": { "type": "string", "example": "MZN", "nullable": true }, "hourly_rate": { "type": "number", "format": "float", "nullable": true }, "notes": { "type": "string", "nullable": true } }, "type": "object" } }, "levels": { "type": "array", "items": { "type": "string" }, "nullable": true }, "tags": { "type": "array", "items": { "type": "string" }, "nullable": true }, "cv_url": { "type": "string", "nullable": true }, "travel_radius_km": { "description": "Raio máximo (km) em que o explicador aceita deslocar-se.", "type": "integer", "nullable": true }, "accepts_groups": { "description": "Aceita aulas em grupo (vs. apenas individual).", "type": "boolean" }, "frequency_per_week": { "description": "Frequência semanal padrão de aulas.", "type": "integer", "nullable": true }, "availability_days": { "description": "Janelas de disponibilidade por dia da semana. Derivado de TutorAvailability pivot.", "type": "array", "items": { "properties": { "day_of_week": { "description": "0=Domingo, 1=Segunda, ..., 6=Sábado", "type": "integer", "example": 1 }, "start_time": { "type": "string", "example": "14:00" }, "end_time": { "type": "string", "example": "18:00" }, "mode": { "type": "string", "enum": [ "online", "presencial", "domicilio", "todos" ] }, "timezone": { "type": "string", "example": "Africa/Maputo" } }, "type": "object" } }, "preferred_schedule": { "description": "Resumo textual de horário preferido (campo legacy quick_reply).", "type": "string", "nullable": true }, "kyc": { "description": "Estado da verificação KYC, com documentos e identificação do reviewer.", "properties": { "status": { "type": "string", "enum": [ "draft", "submitted", "under_review", "approved", "rejected", "expired" ] }, "submitted_at": { "type": "string", "format": "date-time", "nullable": true }, "reviewed_at": { "type": "string", "format": "date-time", "nullable": true }, "reviewer": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string", "nullable": true } }, "type": "object", "nullable": true }, "documents": { "type": "array", "items": { "properties": { "id": { "type": "integer" }, "type": { "type": "string", "example": "id_front" }, "label": { "type": "string" }, "url": { "type": "string", "nullable": true }, "status": { "type": "string", "nullable": true }, "reviewed_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" } }, "rejection_reason": { "type": "string", "nullable": true }, "review_notes": { "type": "string", "nullable": true }, "expires_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object", "nullable": true }, "reviews": { "description": "Top 10 reviews mais recentes.", "type": "array", "items": { "properties": { "author": { "type": "string" }, "avatar_url": { "type": "string", "nullable": true }, "text": { "type": "string" }, "plan": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" } }, "stats": { "description": "Métricas de performance derivadas de TutoringSession, OpportunityInterest e TutorContactRequest.", "properties": { "response_rate": { "description": "responded_contacts / total_contacts. null se tutor ainda não recebeu contactos.", "type": "number", "format": "float", "nullable": true }, "completion_rate": { "description": "completed / (total - cancelled). null se denominator = 0.", "type": "number", "format": "float", "nullable": true }, "avg_response_time": { "description": "Tempo médio em formato humano. null se ainda não há respostas.", "type": "string", "example": "2h 30m", "nullable": true }, "completed_sessions": { "description": "Sessões com status=completed E confirmed_at != null.", "type": "integer", "example": 12 }, "contracted_sessions": { "description": "Candidaturas aprovadas (= contratações).", "type": "integer", "example": 3 }, "total_sessions": { "description": "Total de TutoringSession registadas (qualquer status).", "type": "integer", "example": 15 }, "cancelled_sessions": { "type": "integer", "example": 1 }, "total_contacts": { "description": "Total de contactos recebidos pelo tutor.", "type": "integer", "example": 20 }, "responded_contacts": { "description": "Contactos com responded_at != null.", "type": "integer", "example": 17 } }, "type": "object" }, "subscription": { "description": "Plano activo do explicador. Null até o sistema de planos pagos estar implementado.", "properties": { "plan": { "type": "string", "example": "pro", "nullable": true }, "plan_label": { "type": "string", "example": "Explicador Pro", "nullable": true }, "started_at": { "type": "string", "format": "date-time", "nullable": true }, "next_billing_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "TutorListItem": { "properties": { "id": { "type": "string", "example": "tutor_123" }, "slug": { "type": "string", "example": "marcia-alberto" }, "name": { "type": "string", "example": "Marcia Alberto" }, "title": { "type": "string", "example": "Explicadora de Matemática" }, "discipline": { "type": "string", "example": "Matemática" }, "mode": { "type": "string", "example": "online" }, "location": { "type": "string", "example": "Maputo, Polana Canico" }, "description": { "type": "string", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" } }, "rating": { "type": "number", "format": "float", "example": 5 }, "reviews_count": { "type": "integer", "example": 16 }, "students_count": { "type": "integer", "example": 40 }, "price_monthly": { "type": "integer", "example": 4500, "nullable": true }, "price_label": { "type": "string", "example": "4.500 MZN", "nullable": true }, "availability_label": { "type": "string", "example": "Esta semana", "nullable": true }, "experience_years": { "type": "integer", "example": 8 }, "verified": { "type": "boolean", "example": true }, "image_url": { "type": "string", "nullable": true }, "plan_items": { "type": "array", "items": { "type": "string" } } }, "type": "object" }, "OpportunityListItem": { "properties": { "id": { "type": "string", "example": "opp_123" }, "title": { "type": "string", "example": "Pedido de Matemática" }, "discipline": { "type": "string", "example": "Matemática" }, "level": { "type": "string", "example": "12a Classe" }, "mode": { "type": "string", "example": "todos" }, "location": { "type": "string", "nullable": true }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "budget_min": { "type": "integer", "nullable": true }, "budget_max": { "type": "integer", "nullable": true }, "budget_label": { "type": "string", "nullable": true }, "frequency_per_week": { "type": "integer", "nullable": true }, "urgency": { "type": "string", "example": "urgente" }, "posted_at": { "type": "string", "format": "date-time", "nullable": true }, "posted_label": { "type": "string", "nullable": true }, "availability_label": { "type": "string", "nullable": true }, "student_type": { "type": "string", "nullable": true }, "preferred_schedule": { "type": "string", "nullable": true }, "objectives": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "example": "open" } }, "type": "object" }, "AdminOpportunityItem": { "properties": { "id": { "type": "string", "example": "opp_123" }, "guardian_name": { "type": "string", "example": "Ana Cumbe" }, "student_name": { "type": "string", "example": "Paulo Cumbe", "nullable": true }, "email": { "type": "string", "example": "ana@email.com" }, "phone": { "type": "string", "example": "+258840000000" }, "title": { "type": "string", "example": "Pedido de Matemática" }, "discipline": { "type": "string", "example": "Matemática" }, "level": { "type": "string", "example": "12a Classe" }, "mode": { "type": "string", "example": "todos", "enum": [ "online", "presencial", "domicilio", "todos" ] }, "location": { "type": "string", "example": "Maputo, Sommerschield", "nullable": true }, "description": { "type": "string", "example": "Preparacao intensiva para exame final." }, "budget_min": { "type": "integer", "example": 3000, "nullable": true }, "budget_max": { "type": "integer", "example": 4500, "nullable": true }, "frequency_per_week": { "type": "integer", "example": 2, "nullable": true }, "urgency": { "type": "string", "example": "urgente", "enum": [ "normal", "alta", "urgente" ] }, "posted_at": { "type": "string", "format": "date-time", "nullable": true }, "availability_label": { "type": "string", "example": "Inicio esta semana", "nullable": true }, "student_type": { "type": "string", "example": "Aluno individual", "nullable": true }, "preferred_schedule": { "type": "string", "example": "Fim de tarde", "nullable": true }, "objectives": { "type": "array", "items": { "type": "string" } }, "requirements": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "example": "to_review", "enum": [ "to_review", "published", "closed", "cancelled" ] }, "interests_count": { "type": "integer", "example": 2 } }, "type": "object" }, "AdminOpportunityListResponse": { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AdminOpportunityItem" } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" }, "message": { "type": "string", "example": "Nenhum resultado encontrado.", "nullable": true } }, "type": "object" }, "AdminOpportunityUpdateRequest": { "properties": { "guardian_name": { "type": "string", "example": "Ana Cumbe" }, "student_name": { "type": "string", "example": "Paulo Cumbe", "nullable": true }, "email": { "type": "string", "example": "ana@email.com" }, "phone": { "type": "string", "example": "+258840000000" }, "title": { "type": "string", "example": "Pedido de Matemática" }, "discipline": { "type": "string", "example": "Matemática" }, "level": { "type": "string", "example": "12a Classe" }, "mode": { "type": "string", "example": "todos", "enum": [ "online", "presencial", "domicilio", "todos" ] }, "location": { "type": "string", "example": "Maputo, Sommerschield", "nullable": true }, "description": { "type": "string", "example": "Descricao longa do pedido." }, "budget_min": { "type": "integer", "example": 3000, "nullable": true }, "budget_max": { "type": "integer", "example": 4500, "nullable": true }, "frequency_per_week": { "type": "integer", "example": 2, "nullable": true }, "urgency": { "type": "string", "example": "alta", "enum": [ "normal", "alta", "urgente" ] }, "availability_label": { "type": "string", "example": "Inicio esta semana", "nullable": true }, "student_type": { "type": "string", "example": "Aluno individual", "nullable": true }, "preferred_schedule": { "type": "string", "example": "Fim de tarde", "nullable": true }, "objectives": { "type": "array", "items": { "type": "string" } }, "requirements": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "example": "published", "enum": [ "to_review", "published", "closed", "cancelled" ] } }, "type": "object" }, "AdminOpportunityUpdateResponse": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/AdminOpportunityItem" }, "message": { "type": "string", "example": "Solicitação actualizada com sucesso." } }, "type": "object" }, "AdminOpportunityInterestTutor": { "properties": { "id": { "type": "string", "example": "tutor_456" }, "name": { "type": "string", "example": "Jose Tembe" }, "slug": { "type": "string", "example": "jose-tembe" }, "title": { "type": "string", "example": "Explicador de Matemática", "nullable": true }, "status": { "type": "string", "example": "approved", "enum": [ "pending", "approved", "rejected", "inactive" ] } }, "type": "object" }, "AdminOpportunityInterestItem": { "properties": { "id": { "type": "string", "example": "interest_123" }, "name": { "type": "string", "example": "Jose Tembe" }, "email": { "type": "string", "example": "jose@email.com" }, "phone": { "type": "string", "example": "+258840000000" }, "message": { "type": "string", "example": "Tenho experiencia com exames da 12a classe.", "nullable": true }, "source": { "type": "string", "example": "opportunity_detail" }, "submitted_at": { "type": "string", "format": "date-time", "nullable": true }, "cancelled_at": { "type": "string", "format": "date-time", "nullable": true }, "tutor": { "$ref": "#/components/schemas/AdminOpportunityInterestTutor" } }, "type": "object" }, "AdminOpportunityInterestsResponse": { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AdminOpportunityInterestItem" } } }, "type": "object" }, "AdminPermissionSummary": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "users.view" }, "guard_name": { "type": "string", "example": "web" } }, "type": "object" }, "AdminRoleSummary": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "support-admin" }, "guard_name": { "type": "string", "example": "web" } }, "type": "object" }, "AdminPermissionItem": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "users.view" }, "guard_name": { "type": "string", "example": "web" }, "roles_count": { "type": "integer", "example": 2 }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" }, "AdminPermissionListResponse": { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AdminPermissionItem" } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" }, "message": { "type": "string", "example": "Nenhum resultado encontrado.", "nullable": true } }, "type": "object" }, "AdminPermissionCreateRequest": { "required": [ "name" ], "properties": { "name": { "type": "string", "example": "users.manage" } }, "type": "object" }, "AdminPermissionMutationResponse": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/AdminPermissionItem" }, "message": { "type": "string", "example": "Permissão criada com sucesso." } }, "type": "object" }, "AdminRoleItem": { "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "support-admin" }, "guard_name": { "type": "string", "example": "web" }, "users_count": { "type": "integer", "example": 4 }, "permissions": { "type": "array", "items": { "$ref": "#/components/schemas/AdminPermissionSummary" } }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" }, "AdminRoleListResponse": { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AdminRoleItem" } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" }, "message": { "type": "string", "example": "Nenhum resultado encontrado.", "nullable": true } }, "type": "object" }, "AdminRoleCreateRequest": { "required": [ "name" ], "properties": { "name": { "type": "string", "example": "support-admin" }, "permissions": { "type": "array", "items": { "type": "string" }, "example": [ "users.view", "users.manage" ] } }, "type": "object" }, "AdminRoleUpdateRequest": { "properties": { "name": { "type": "string", "example": "operations-admin" } }, "type": "object" }, "AdminRoleMutationResponse": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/AdminRoleItem" }, "message": { "type": "string", "example": "Role actualizada com sucesso." } }, "type": "object" }, "AdminSyncRolesRequest": { "required": [ "roles" ], "properties": { "roles": { "type": "array", "items": { "type": "string" }, "example": [ "support-admin", "content-admin" ] } }, "type": "object" }, "AdminUserStatusUpdateRequest": { "required": [ "status" ], "properties": { "status": { "type": "string", "example": "blocked", "enum": [ "active", "pending", "blocked", "suspended", "inactive" ] }, "reason": { "type": "string", "example": "Tentativas suspeitas de acesso.", "nullable": true } }, "type": "object" }, "AdminSyncPermissionsRequest": { "required": [ "permissions" ], "properties": { "permissions": { "type": "array", "items": { "type": "string" }, "example": [ "users.view", "users.manage" ] } }, "type": "object" }, "AdminUserItem": { "properties": { "id": { "type": "integer", "example": 12 }, "name": { "type": "string", "example": "Ana Paulo" }, "email": { "type": "string", "example": "ana@example.com", "nullable": true }, "phone": { "type": "string", "example": "+258841234567", "nullable": true }, "user_type": { "description": "Slug do perfil primário. Catalogo em GET /api/v1/admin/profile-types.", "type": "string", "example": "admin" }, "user_type_label": { "type": "string", "example": "Administrador", "nullable": true }, "user_types": { "description": "Lista de slugs de perfis atribuidos.", "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "example": "active", "enum": [ "active", "pending", "blocked", "suspended", "inactive" ] }, "status_reason": { "type": "string", "example": "Tentativas suspeitas de acesso.", "nullable": true }, "status_changed_at": { "type": "string", "format": "date-time", "nullable": true }, "status_changed_by": { "type": "integer", "example": 1, "nullable": true }, "email_verified_at": { "type": "string", "format": "date-time", "nullable": true }, "phone_verified_at": { "type": "string", "format": "date-time", "nullable": true }, "last_login_at": { "type": "string", "format": "date-time", "nullable": true }, "roles": { "type": "array", "items": { "$ref": "#/components/schemas/AdminRoleSummary" } }, "permissions": { "type": "array", "items": { "$ref": "#/components/schemas/AdminPermissionSummary" } }, "all_permissions": { "type": "array", "items": { "$ref": "#/components/schemas/AdminPermissionSummary" } }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" }, "AdminUserListResponse": { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AdminUserItem" } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" }, "message": { "type": "string", "example": "Nenhum resultado encontrado.", "nullable": true } }, "type": "object" }, "AdminProfileTypeItem": { "description": "Tipo de perfil de utilizador (catalogo dinamico). O slug e imutavel e usado em codigo; restantes campos sao editaveis via admin.", "properties": { "id": { "type": "integer", "example": 3 }, "slug": { "description": "Identificador imutavel usado em codigo.", "type": "string", "example": "tutor" }, "label": { "description": "Nome legivel apresentado ao utilizador.", "type": "string", "example": "Explicador" }, "description": { "type": "string", "example": "Profissional que oferece explicacoes.", "nullable": true }, "is_selectable": { "description": "Pode ser escolhido no formulario de registo.", "type": "boolean", "example": true }, "is_default": { "description": "Atribuido automáticamente quando nenhum perfil e indicado no registo.", "type": "boolean", "example": false }, "requires_kyc": { "description": "Indica se este perfil suporta verificação KYC.", "type": "boolean", "example": true }, "icon": { "type": "string", "example": "chalkboard-teacher", "nullable": true }, "color": { "type": "string", "example": "#16A34A", "nullable": true }, "sort_order": { "type": "integer", "example": 3 }, "is_active": { "type": "boolean", "example": true }, "users_count": { "description": "Numero de utilizadores actualmente associados a este perfil.", "type": "integer", "example": 42 }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" }, "AdminProfileTypeListResponse": { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AdminProfileTypeItem" } } }, "type": "object" }, "AdminProfileTypeMutationResponse": { "properties": { "message": { "type": "string", "example": "Tipo de perfil actualizado com sucesso." }, "data": { "$ref": "#/components/schemas/AdminProfileTypeItem" } }, "type": "object" }, "AdminSubjectRequestItem": { "description": "Pedido de criacao de disciplina submetido por um explicador.", "properties": { "id": { "type": "string", "example": "sreq_abc123" }, "proposed_name": { "type": "string", "example": "Programacao em Python" }, "proposed_levels": { "type": "array", "items": { "properties": { "level": { "type": "string", "example": "universitario" }, "grades": { "type": "array", "items": { "type": "string" }, "example": [ "1º ano", "2º ano" ] } }, "type": "object" } }, "where_taught": { "type": "string", "example": "Universidade Eduardo Mondlane", "nullable": true }, "description": { "type": "string", "nullable": true }, "status": { "type": "string", "example": "pending", "enum": [ "pending", "approved", "rejected", "cancelled" ] }, "reviewed_at": { "type": "string", "format": "date-time", "nullable": true }, "review_notes": { "type": "string", "nullable": true }, "requester": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string", "nullable": true } }, "type": "object", "nullable": true }, "reviewer": { "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string", "nullable": true } }, "type": "object", "nullable": true }, "result_subject": { "description": "Disciplina criada quando o pedido e aprovado.", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" } }, "type": "object", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" }, "AdminSubjectRequestListResponse": { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AdminSubjectRequestItem" } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" } }, "type": "object" }, "AdminSubjectRequestMutationResponse": { "properties": { "message": { "type": "string", "example": "Pedido aprovado e disciplina criada." }, "data": { "$ref": "#/components/schemas/AdminSubjectRequestItem" } }, "type": "object" }, "AdminDashboardCountByKey": { "properties": { "key": { "type": "string", "example": "active" }, "total": { "type": "integer", "example": 42 } }, "type": "object" }, "AdminDashboardTimeSeriesPoint": { "properties": { "date": { "type": "string", "format": "date", "example": "2026-04-01" }, "total": { "type": "integer", "example": 5 } }, "type": "object" }, "AdminDashboardResponse": { "properties": { "range": { "properties": { "days": { "type": "integer", "example": 30 }, "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" } }, "type": "object" }, "summary": { "type": "object", "additionalProperties": { "type": "object" } }, "breakdowns": { "type": "object", "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/AdminDashboardCountByKey" } } }, "time_series": { "type": "object", "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/AdminDashboardTimeSeriesPoint" } } }, "top_lists": { "properties": { "tutors_by_contact_requests": { "type": "array", "items": { "type": "object" } }, "disciplines_by_opportunities": { "type": "array", "items": { "$ref": "#/components/schemas/AdminDashboardCountByKey" } } }, "type": "object" }, "recent_activity": { "properties": { "users": { "type": "array", "items": { "type": "object" } }, "opportunities": { "type": "array", "items": { "type": "object" } }, "tutors": { "type": "array", "items": { "type": "object" } }, "opportunity_interests": { "type": "array", "items": { "type": "object" } }, "find_tutor_requests": { "type": "array", "items": { "type": "object" } }, "tutor_contact_requests": { "type": "array", "items": { "type": "object" } } }, "type": "object" }, "generated_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "AdminUserMutationResponse": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/AdminUserItem" }, "message": { "type": "string", "example": "Roles do utilizador actualizadas com sucesso." } }, "type": "object" }, "InvalidCredentialsResponse": { "properties": { "success": { "type": "boolean", "example": false }, "error": { "properties": { "code": { "type": "string", "example": "INVALID_CREDENTIALS" }, "message": { "type": "string", "example": "Credenciais invalidas." } }, "type": "object" } }, "type": "object" }, "UnauthenticatedResponse": { "properties": { "success": { "type": "boolean", "example": false }, "error": { "properties": { "code": { "type": "string", "example": "UNAUTHENTICATED" }, "message": { "type": "string", "example": "Autenticação necessária." } }, "type": "object" } }, "type": "object" }, "EntityNotFoundResponse": { "properties": { "success": { "type": "boolean", "example": false }, "error": { "properties": { "code": { "type": "string", "example": "ENTITY_NOT_FOUND" }, "message": { "type": "string", "example": "Item nao encontrado." } }, "type": "object" } }, "type": "object" }, "FindTutorRequestResponse": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "id": { "type": "string", "example": "find_123" } }, "type": "object" }, "message": { "type": "string", "example": "Pedido de matching registado com sucesso." } }, "type": "object" }, "FavoriteTutorItem": { "properties": { "id": { "type": "string", "example": "tutor_123" }, "slug": { "type": "string", "example": "marcia-alberto" }, "name": { "type": "string", "example": "Marcia Alberto" }, "title": { "type": "string", "example": "Explicadora de Matemática" }, "discipline": { "type": "string", "example": "Matemática" }, "mode": { "type": "string", "example": "online", "enum": [ "online", "presencial", "domicilio", "todos" ] }, "location": { "type": "string", "example": "Maputo", "nullable": true }, "price_monthly": { "type": "integer", "example": 4500, "nullable": true }, "favorited_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" }, "FavoriteTutorsResponse": { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/FavoriteTutorItem" } }, "message": { "type": "string", "example": "Nenhum resultado encontrado.", "nullable": true } }, "type": "object" }, "FavoriteContentItem": { "properties": { "id": { "type": "string", "example": "content_123" }, "type": { "type": "string", "example": "article", "nullable": true }, "type_name": { "type": "string", "example": "Artigo", "nullable": true }, "title": { "type": "string", "example": "Como estudar para exames" }, "slug": { "type": "string", "example": "como-estudar-para-exames" }, "short_description": { "type": "string", "example": "Guia pratico para melhorar resultados.", "nullable": true }, "cover_image_url": { "type": "string", "nullable": true }, "status": { "type": "string", "example": "published", "nullable": true }, "published_at": { "type": "string", "format": "date-time", "nullable": true }, "is_featured": { "type": "boolean", "example": false }, "view_count": { "type": "integer", "example": 120 }, "favorites_count": { "type": "integer", "example": 12 } }, "type": "object" }, "FavoriteTutorSummary": { "properties": { "id": { "type": "string", "example": "tutor_123" }, "slug": { "type": "string", "example": "marcia-alberto" }, "name": { "type": "string", "example": "Marcia Alberto" }, "title": { "type": "string", "example": "Explicadora de Matemática", "nullable": true }, "discipline": { "type": "string", "example": "Matemática", "nullable": true }, "mode": { "type": "string", "example": "online", "nullable": true, "enum": [ "online", "presencial", "domicilio", "todos" ] }, "location": { "type": "string", "example": "Maputo", "nullable": true }, "price_monthly": { "type": "integer", "example": 4500, "nullable": true }, "image_url": { "type": "string", "nullable": true } }, "type": "object" }, "FavoriteItem": { "properties": { "id": { "type": "integer", "example": 1 }, "type": { "type": "string", "example": "tutor", "enum": [ "content", "tutor" ] }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "item": { "oneOf": [ { "$ref": "#/components/schemas/FavoriteContentItem" }, { "$ref": "#/components/schemas/FavoriteTutorSummary" } ] } }, "type": "object" }, "FavoriteToggleRequest": { "required": [ "type", "id" ], "properties": { "type": { "type": "string", "example": "tutor", "enum": [ "content", "tutor" ] }, "id": { "type": "string", "example": "tutor_123" } }, "type": "object" }, "FavoriteToggleResponse": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "type": { "type": "string", "example": "tutor", "enum": [ "content", "tutor" ] }, "id": { "type": "string", "example": "tutor_123" }, "is_favorited": { "type": "boolean", "example": true } }, "type": "object" }, "message": { "type": "string", "example": "Adicionado aos favoritos." } }, "type": "object" }, "FavoriteCheckResponse": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "is_favorited": { "type": "boolean", "example": true } }, "type": "object" } }, "type": "object" }, "FavoritesListResponse": { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/FavoriteItem" } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" }, "message": { "type": "string", "example": "Nenhum resultado encontrado.", "nullable": true } }, "type": "object" }, "TutorSignupResponse": { "properties": { "success": { "type": "boolean", "example": true }, "data": { "properties": { "id": { "type": "string", "example": "tutor_123" }, "status": { "type": "string", "example": "pending", "enum": [ "pending", "approved", "rejected", "inactive" ] } }, "type": "object" }, "message": { "type": "string", "example": "Registo de explicador submetido com sucesso." } }, "type": "object" }, "PaginatedTutorListResponse": { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/TutorListItem" } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" }, "message": { "type": "string", "example": "Nenhum resultado encontrado.", "nullable": true } }, "type": "object" }, "PaginatedOpportunityListResponse": { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/OpportunityListItem" } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" }, "message": { "type": "string", "example": "Nenhum resultado encontrado.", "nullable": true } }, "type": "object" }, "PaginatedArticleListResponse": { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ArticleListItem" } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" }, "message": { "type": "string", "example": "Nenhum resultado encontrado.", "nullable": true } }, "type": "object" }, "MyOpportunityInterestsResponse": { "properties": { "items": { "type": "array", "items": { "properties": { "id": { "type": "string" }, "message": { "type": "string", "nullable": true }, "submitted_at": { "type": "string", "format": "date-time", "nullable": true }, "opportunity": { "properties": { "id": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "status": { "type": "string", "nullable": true } }, "type": "object" } }, "type": "object" } }, "pagination": { "$ref": "#/components/schemas/PaginationMeta" }, "message": { "type": "string", "example": "Nenhum resultado encontrado.", "nullable": true } }, "type": "object" }, "ArticleListItem": { "properties": { "id": { "type": "string", "example": "article_123" }, "slug": { "type": "string", "example": "como-estudar-para-exames" }, "title": { "type": "string" }, "excerpt": { "type": "string" }, "cover_image_url": { "type": "string", "nullable": true }, "published_at": { "type": "string", "format": "date-time", "nullable": true }, "author_name": { "type": "string" } }, "type": "object" }, "PaginationMeta": { "properties": { "page": { "type": "integer", "example": 1 }, "limit": { "type": "integer", "example": 12 }, "total": { "type": "integer", "example": 48 } }, "type": "object" } }, "securitySchemes": { "sanctum": { "type": "http", "description": "Use o token Sanctum no header Authorization: Bearer {token}.", "scheme": "bearer" } } }, "tags": [ { "name": "Auth", "description": "Fluxos de autenticação e recuperacao de conta." }, { "name": "Verification", "description": "Verificação de email e telefone." }, { "name": "Sessions", "description": "Identidade do utilizador e sessões ativas." }, { "name": "Tutors", "description": "Listagem, perfil e gestao de explicadores." }, { "name": "Opportunities", "description": "Pedidos de explicacao e interesses dos explicadores." }, { "name": "Matching", "description": "Pedidos de apoio para encontrar explicador." }, { "name": "Articles", "description": "Conteudo editorial da plataforma." }, { "name": "PlatformAuth", "description": "Registo e login simplificados da plataforma." }, { "name": "Me", "description": "Perfil autenticado, perfil de explicador e interesses." }, { "name": "Favorites", "description": "Favoritos autenticados e verificação de itens favoritos." }, { "name": "Admin", "description": "Operacoes administrativas da plataforma." }, { "name": "Public", "description": "Public" } ] }