Autorizações

Certas operações sensíveis sobre matrículas — como atualização de status, exclusão forçada e reativação — não são executadas diretamente. Em vez disso, geram uma autorização administrativa pendente que precisa ser aprovada ou rejeitada pela direção da escola. Estes endpoints listam, executam e rejeitam essas autorizações.

Estes são endpoints administrativos. Requerem autenticação via Bearer token Sanctum — não utilizam os cabeçalhos de parceiro (X-Authorization / X-Partner).
Todos os endpoints desta página são exclusivos para usuários com papel de Direção (DIRECTOR). Requisições de outros perfis são recusadas com 403 Forbidden.

O modelo autorização

O modelo AdminAuthorization representa uma solicitação de operação sensível aguardando decisão da direção. Inclui o tipo da operação, o status atual e o payload com os dados necessários para execução.

id uuid

Identificador único da autorização.

type string

Tipo da operação. Valores: ENROLLMENT_STATUS_UPDATE, ENROLLMENT_FORCE_DELETE, ENROLLMENT_REACTIVATION.

status string

Status da autorização. Valores: PENDING (aguardando), APPROVED (executada), REJECTED (rejeitada).

payload object

Dados específicos da operação. Contém os campos necessários para executá-la (enrollment_id, new_status, reason, etc.).

reason string

Motivo da solicitação.

target_type string

Tipo do recurso alvo. Ex: App\Models\Enrollment.

target_id uuid

ID do recurso alvo (ex: ID da matrícula).

requested_by uuid

ID do usuário que criou a solicitação.

reviewed_by uuid|null

ID do usuário que executou ou rejeitou. null enquanto estiver pendente.

created_at datetime

Data e hora em que a solicitação foi criada.

reviewed_at datetime|null

Data e hora da decisão. null enquanto estiver pendente.

enrollment object|null

Dados enriquecidos da matrícula alvo. Retornado quando o tipo é ENROLLMENT_STATUS_UPDATE, ENROLLMENT_FORCE_DELETE ou ENROLLMENT_REACTIVATION.

Tipos de autorização

Tipo Operação executada ao aprovar
ENROLLMENT_STATUS_UPDATE Atualiza o status da matrícula para o valor em payload.new_status.
ENROLLMENT_FORCE_DELETE Exclui permanentemente a matrícula do banco de dados.
ENROLLMENT_REACTIVATION Restaura uma matrícula excluída (soft delete), reativando o vínculo do aluno com a turma.
Modelo autorização 
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "ENROLLMENT_STATUS_UPDATE",
  "status": "PENDING",
  "payload": {
    "enrollment_id": "b2c3d4e5-...",
    "from_status": "MATRICULADO",
    "new_status": "TRANSFERIDO",
    "reason": "Mudança de escola"
  },
  "reason": "Mudança de escola",
  "target_type": "App\\Models\\Enrollment",
  "target_id": "b2c3d4e5-...",
  "requested_by": "c3d4e5f6-...",
  "reviewed_by": null,
  "created_at": "2026-05-20T14:30:00-03:00",
  "reviewed_at": null,
  "enrollment": {
    "id": "b2c3d4e5-...",
    "number": "7.553",
    "status": "MATRICULADO",
    "student_name": "João da Silva",
    "classroom_name": "Turma A - 1º Ano"
  }
}
GET api/admin-authorization

Listar autorizações pendentes

Retorna todas as autorizações administrativas com status PENDING pertencentes à escola do usuário autenticado. Os itens são enriquecidos com os dados da matrícula alvo quando aplicável.

Regras de negócio

  • Apenas autorizações com status = PENDING são listadas.
  • O campo enrollment é incluído automaticamente para os tipos de matrícula.
  • Apenas usuários com papel DIRECTOR podem acessar este endpoint.

Autenticação

Sessão autenticada da plataforma (cookie de sessão). Não utiliza cabeçalhos de parceiro.

Códigos de resposta

200

Lista de autorizações pendentes.

401

Sessão não autenticada.

403

Usuário não possui papel de direção.

Requisição GET
GET /api/admin-authorization
Resposta 200 OK 
[
  {
    "id": "a1b2c3d4-...",
    "type": "ENROLLMENT_STATUS_UPDATE",
    "status": "PENDING",
    "payload": { /* ... */ },
    "enrollment": {
      "id": "b2c3d4e5-...",
      "number": "7.553",
      "status": "MATRICULADO",
      "student_name": "João da Silva",
      "classroom_name": "Turma A - 1º Ano"
    }
  }
]
PATCH api/admin-authorization/{id}/approve

Executar autorização

Aprova e executa uma autorização pendente. A operação correspondente é realizada imediatamente após a aprovação, conforme o type da autorização.

Parâmetros de rota

id uuid obrigatório

ID da autorização a ser executada.

Regras de negócio

  • Apenas usuários com papel DIRECTOR podem executar autorizações.
  • A autorização deve estar com status = PENDING.
  • Após a aprovação, o campo status muda para APPROVED e reviewed_by/reviewed_at são preenchidos.
  • A operação subjacente é executada transacionalmente: se falhar, a autorização permanece pendente.

Operações executadas por tipo

ENROLLMENT_STATUS_UPDATE

Chama EnrollmentService::updateStatus() com o novo status do payload.

ENROLLMENT_FORCE_DELETE

Chama EnrollmentService::forceDeleteEnrollment(), removendo permanentemente o registro.

ENROLLMENT_REACTIVATION

Chama EnrollmentService::reactivateEnrollment(), restaurando uma matrícula excluída.

Códigos de resposta

200

Autorização executada com sucesso.

403

Usuário não possui papel de direção.

404

Autorização não encontrada.

409

Autorização não está mais pendente.

500

Falha ao executar a operação.

Requisição PATCH
PATCH /api/admin-authorization/{id}/approve
Resposta — sucesso 200 OK 
"Autorização executada com sucesso."
Resposta — sem permissão 403 
"Apenas a direção pode realizar esta operação."
PATCH api/admin-authorization/{id}/reject

Rejeitar autorização

Rejeita uma autorização pendente sem executar a operação subjacente. O status muda para REJECTED e o campo has_pending_authorization da matrícula retorna a false.

Parâmetros de rota

id uuid obrigatório

ID da autorização a ser rejeitada.

Regras de negócio

  • Apenas usuários com papel DIRECTOR podem rejeitar autorizações.
  • A autorização deve estar com status = PENDING.
  • A rejeição não altera nenhum dado da matrícula alvo — apenas cancela a solicitação.
  • Após a rejeição, uma nova solicitação pode ser criada para a mesma matrícula.

Códigos de resposta

200

Autorização rejeitada com sucesso.

403

Usuário não possui papel de direção.

404

Autorização não encontrada.

409

Autorização não está mais pendente.

Requisição PATCH
PATCH /api/admin-authorization/{id}/reject
Resposta — sucesso 200 OK 
"Autorização rejeitada."
Resposta — sem permissão 403 
"Apenas a direção pode realizar esta operação."

Regras gerais do fluxo de autorização

1

Uma solicitação pendente por matrícula

Não é possível criar uma nova solicitação enquanto houver uma autorização com status = PENDING para a mesma matrícula. Qualquer tentativa retorna 409 Conflict.

2

Flag has_pending_authorization

Enquanto uma autorização estiver pendente para uma matrícula, o campo has_pending_authorization retornado nos endpoints de matrícula será true, impedindo novas operações conflitantes.

3

Apenas a direção decide

Somente usuários com o papel DIRECTOR podem executar (/approve) ou rejeitar (/reject) uma autorização. Secretários e coordenadores podem apenas solicitá-las.

4

Irreversibilidade após aprovação

Uma vez que uma autorização é executada (aprovada), a operação é realizada e não pode ser desfeita por este fluxo. Para reverter, é necessário criar uma nova solicitação do tipo adequado.