ToAqui Escola

O modelo matrícula

O modelo matrícula contém os dados de vínculo do aluno com a turma, seu número de matrícula e o status atual. Use o id para referenciar a matrícula nas operações de edição.

id uuid

Identificador único da matrícula.

number string

Número de matrícula do aluno.

status string

Status da matrícula. Valores possíveis: MATRICULADO, TRANSFERIDO, DESISTENTE, APROVADO, REPROVADO, FALECIDO, REMANEJADA, CANCELADA.

student_name string

Nome completo do aluno.

school_cnpj string

CNPJ da escola à qual a matrícula pertence.

classroom_name string

Nome da turma à qual o aluno está matriculado.

deleted_at datetime|null

Data de exclusão lógica (soft delete). Quando preenchido, a matrícula está inativa e pode ser reativada via fluxo de autorização.

has_pending_authorization boolean

Indica se existe uma autorização administrativa pendente para esta matrícula. Quando true, novas operações sensíveis são bloqueadas até a decisão da direção.

Modelo matrícula

{
  "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "number": "7.553",
  "status": "MATRICULADO",
  "student_name": "João da Silva",
  "school_cnpj": "26019466000122",
  "classroom_name": "Turma A",
  "deleted_at": null,
  "has_pending_authorization": false
}

GET /v1/partners/school/{cnpj}/enrollments/all

Listar matrículas

Retorna todas as matrículas de uma escola específica, identificada pelo CNPJ. A resposta é paginada, com os registros em data.

Parâmetros de rota

cnpj string obrigatório

CNPJ da escola (14 dígitos, sem formatação).

Códigos de resposta

200

Sucesso.

401

Autenticação inválida.

Requisição GET

GET /v1/partners/school/{cnpj}/enrollments/all

curl https://toakiescola.com.br/api/v1/partners/school/26019466000122/enrollments/all \
  -H "X-Authorization: {api_token}" \
  -H "X-Partner: {partner_token}" \
  -H "X-Client: {client_slug}"

use GuzzleHttp\Client;

$client = new Client();
$response = $client->get('https://toakiescola.com.br/api/v1/partners/school/26019466000122/enrollments/all', [
    'headers' => [
        'X-Authorization' => '{api_token}',
        'X-Partner'       => '{partner_token}',
        'X-Client'        => '{client_slug}',
    ],
]);
$enrollments = json_decode($response->getBody(), true);

const response = await fetch('https://toakiescola.com.br/api/v1/partners/school/26019466000122/enrollments/all', {
    headers: {
        'X-Authorization': '{api_token}',
        'X-Partner':       '{partner_token}',
        'X-Client':        '{client_slug}',
    },
});
const enrollments = await response.json();

Resposta

{
  "data": [
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "number": "7.553",
      "status": "MATRICULADO",
      "student_name": "João da Silva",
      // ...
    }
  ],
  "links": { /* URLs de paginação */ },
  "meta": { "current_page": 1, "per_page": 25, // ... }
}

{
  "message": "Autenticação inválida."
}

{
  "message": "Recurso não encontrado."
}

POST /v1/partners/school/{cnpj}/student/{enrollment_number}/enroll

Matricular aluno

Matricula um aluno em uma turma da escola. O aluno é identificado pelo seu número de matrícula atual e a turma pelo classroom_id no corpo da requisição.

Parâmetros de rota

cnpj string obrigatório

CNPJ da escola (14 dígitos, sem formatação).

enrollment_number string obrigatório

Número de matrícula atual do aluno.

Corpo da requisição

classroom_id uuid obrigatório

UUID da turma em que o aluno será matriculado.

Códigos de resposta

201

Criado com sucesso.

400

Dados inválidos.

401

Autenticação inválida.

404

Recurso de referência não encontrado.

Requisição POST

POST /v1/partners/school/{cnpj}/student/{enrollment_number}/enroll

curl https://toakiescola.com.br/api/v1/partners/school/26019466000122/student/7.553/enroll \
  -X POST \
  -H "X-Authorization: {api_token}" \
  -H "X-Partner: {partner_token}" \
  -H "X-Client: {client_slug}" \
  -H "Content-Type: application/json" \
  -d '{"classroom_id":"a1b2c3d4-..."}'

use GuzzleHttp\Client;

$client = new Client();
$response = $client->post('https://toakiescola.com.br/api/v1/partners/school/26019466000122/student/7.553/enroll', [
    'headers' => [
        'X-Authorization' => '{api_token}',
        'X-Partner'       => '{partner_token}',
        'X-Client'        => '{client_slug}',
    ],
    'json' => [
        'classroom_id' => '{classroom_id}',
    ],
]);
$enrollment = json_decode($response->getBody(), true);

const response = await fetch('https://toakiescola.com.br/api/v1/partners/school/26019466000122/student/7.553/enroll', {
    method: 'POST',
    headers: {
        'X-Authorization': '{api_token}',
        'X-Partner':       '{partner_token}',
        'X-Client':        '{client_slug}',
        'Content-Type':    'application/json',
    },
    body: JSON.stringify({ classroom_id: '{classroom_id}' }),
});
const enrollment = await response.json();

Resposta

{
  "data": {
    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "number": "7.553",
    "status": "MATRICULADO",
    "student_name": "João da Silva",
    "school_cnpj": "26019466000122",
    "classroom_name": "Turma A"
  }
}

{
  "success": false,
  "errors": ["O campo classroom_id é obrigatório."]
}

{
  "message": "Autenticação inválida."
}

{
  "message": "Recurso não encontrado."
}

PATCH /v1/partners/school/{cnpj}/enrollment/{enrollment_id}/number

Editar número de matrícula

Atualiza o número de matrícula de uma matrícula existente. Útil quando o sistema de gestão do parceiro precisa sincronizar ou corrigir o número de matrícula de um aluno.

Parâmetros de rota

cnpj string obrigatório

CNPJ da escola (14 dígitos, sem formatação).

enrollment_id string obrigatório

UUID da matrícula.

Corpo da requisição

number string obrigatório

Novo número de matrícula do aluno (máx. 50 caracteres).

Códigos de resposta

200

Sucesso.

400

Dados inválidos.

401

Autenticação inválida.

404

Recurso não encontrado.

Requisição PATCH

PATCH /v1/partners/school/{cnpj}/enrollment/{enrollment_id}/number

curl https://toakiescola.com.br/api/v1/partners/school/26019466000122/enrollment/b2c3d4e5-.../number \
  -X PATCH \
  -H "X-Authorization: {api_token}" \
  -H "X-Partner: {partner_token}" \
  -H "X-Client: {client_slug}" \
  -H "Content-Type: application/json" \
  -d '{"number":"8.001"}'

use GuzzleHttp\Client;

$client = new Client();
$response = $client->patch('https://toakiescola.com.br/api/v1/partners/school/26019466000122/enrollment/{id}/number', [
    'headers' => [
        'X-Authorization' => '{api_token}',
        'X-Partner'       => '{partner_token}',
        'X-Client'        => '{client_slug}',
    ],
    'json' => ['number' => '8.001'],
]);

const response = await fetch('https://toakiescola.com.br/api/v1/partners/school/26019466000122/enrollment/{id}/number', {
    method: 'PATCH',
    headers: {
        'X-Authorization': '{api_token}',
        'X-Partner':       '{partner_token}',
        'X-Client':        '{client_slug}',
        'Content-Type':    'application/json',
    },
    body: JSON.stringify({ number: '8.001' }),
});

Resposta

{
  "data": {
    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "number": "8.001",
    "status": "MATRICULADO",
    // ...
  }
}

{
  "success": false,
  "errors": ["O campo number é obrigatório."]
}

{
  "message": "Autenticação inválida."
}

{
  "message": "Recurso não encontrado."
}

POST api/enrollment/transfer/internal

Transferência interna

Move o aluno de uma turma para outra dentro da mesma escola. A operação é executada imediatamente (sem fluxo de autorização), desde que a turma de destino tenha vagas e não haja autorização pendente para a matrícula.

Corpo da requisição

enrollment_id uuid obrigatório

UUID da matrícula do aluno.

destination_classroom_id uuid obrigatório

UUID da turma de destino.

reason string obrigatório

Motivo da transferência (máx. 1000 caracteres).

observations string opcional

Observações adicionais (máx. 2000 caracteres).

Regras de negócio

A turma de destino deve ser diferente da atual; caso contrário retorna 400 com mensagem SAME_CLASSROOM.
A turma de destino deve ter pelo menos uma vaga disponível (vacancies > 0); caso contrário retorna 400.
Se houver uma autorização pendente para a matrícula, retorna 409 Conflict.

Códigos de resposta

200

Transferência realizada com sucesso.

400

Turma de destino inválida, igual à atual, ou sem vagas disponíveis.

409

Autorização pendente existente para esta matrícula.

422

Dados inválidos.

Requisição POST

POST /api/enrollment/transfer/internal

{
  "enrollment_id": "b2c3d4e5-...",
  "destination_classroom_id": "c3d4e5f6-...",
  "reason": "Redistribuição de turmas",
  "observations": null
}

Resposta

"Transferência interna realizada."

"A turma de destino não possui vagas."

"A turma de destino deve ser diferente da atual."

"Esta matrícula possui uma autorização administrativa pendente. Aguarde a decisão da direção."

{
  "message": "The enrollment id field is required.",
  "errors": {
    "enrollment_id": ["The enrollment id field is required."]
  }
}

POST api/enrollment/transfer/external

Transferência externa

Registra a saída do aluno da escola por transferência para outra instituição. A matrícula é marcada com status TRANSFERIDO e o nome da escola de destino é armazenado.

Corpo da requisição

enrollment_id uuid obrigatório

UUID da matrícula do aluno.

destination_school_name string obrigatório

Nome da escola de destino (máx. 255 caracteres).

reason string obrigatório

Motivo da transferência (máx. 1000 caracteres).

observations string opcional

Observações adicionais (máx. 2000 caracteres).

partial_transcript boolean opcional

Indica se foi emitido histórico parcial. Padrão: false.

Regras de negócio

Se houver uma autorização pendente para a matrícula, retorna 409 Conflict.
A operação é executada imediatamente, sem fluxo de autorização.

Códigos de resposta

200

Transferência registrada com sucesso.

409

Autorização pendente existente para esta matrícula.

422

Dados inválidos.

Requisição POST

POST /api/enrollment/transfer/external

{
  "enrollment_id": "b2c3d4e5-...",
  "destination_school_name": "Colégio São João",
  "reason": "Mudança de bairro",
  "observations": null,
  "partial_transcript": false
}

Resposta

"Transferência externa registrada."

"Esta matrícula possui uma autorização administrativa pendente. Aguarde a decisão da direção."

{
  "message": "The enrollment id field is required.",
  "errors": {
    "enrollment_id": ["The enrollment id field is required."]
  }
}

POST api/enrollment/status/request

Solicitar atualização de status

Cria uma solicitação de alteração de status da matrícula, pendente de aprovação da direção. Não altera o status diretamente — gera uma autorização do tipo ENROLLMENT_STATUS_UPDATE.

Corpo da requisição

enrollment_id uuid obrigatório

UUID da matrícula.

new_status string obrigatório

Novo status desejado. Valores: MATRICULADO, TRANSFERIDO, DESISTENTE, APROVADO, REPROVADO, REMANEJADA, CANCELADA, FALECIDO.

reason string obrigatório

Motivo da alteração (máx. 1000 caracteres).

observations string opcional

Observações adicionais (máx. 2000 caracteres).

Regras de negócio

Se já existir uma autorização pendente para a matrícula, retorna 409.
O status atual da matrícula não é alterado até a direção aprovar a solicitação.

Códigos de resposta

200

Solicitação criada com sucesso.

409

Já existe uma autorização pendente para esta matrícula.

422

Dados inválidos ou status não permitido.

Requisição POST

POST /api/enrollment/status/request

{
  "enrollment_id": "b2c3d4e5-...",
  "new_status": "TRANSFERIDO",
  "reason": "Aluno solicitou transferência",
  "observations": null
}

Resposta

"Solicitação enviada para autorização da direção."

"Esta matrícula já possui uma solicitação de autorização pendente. Aguarde a decisão da direção."

{
  "message": "The enrollment id field is required.",
  "errors": {
    "enrollment_id": ["The enrollment id field is required."]
  }
}

POST api/enrollment/reactivation/request

Solicitar reativação de matrícula

Solicita a reativação de uma matrícula excluída logicamente (deleted_at != null). Gera uma autorização do tipo ENROLLMENT_REACTIVATION pendente de aprovação da direção.

Corpo da requisição

enrollment_id uuid obrigatório

UUID da matrícula excluída que se deseja reativar.

reason string obrigatório

Motivo da reativação (máx. 1000 caracteres).

Regras de negócio

Se o aluno já possuir uma matrícula ativa (status MATRICULADO, APROVADO, REPROVADO ou REMANEJADA), retorna 409.
Se já existir uma autorização pendente para esta matrícula, retorna 409.
A matrícula só é efetivamente restaurada após aprovação da direção.

Códigos de resposta

200

Solicitação criada com sucesso.

409

Aluno possui matrícula ativa, ou já existe autorização pendente.

422

Dados inválidos.

Requisição POST

POST /api/enrollment/reactivation/request

{
  "enrollment_id": "b2c3d4e5-...",
  "reason": "Aluno retornou após desistência"
}

Resposta

"Solicitação de reativação enviada para autorização da direção."

"O aluno já possui uma matrícula ativa. Não é possível reativar outra enquanto houver uma matrícula em andamento."

"Esta matrícula já possui uma solicitação de autorização pendente. Aguarde a decisão da direção."

{
  "message": "The enrollment id field is required.",
  "errors": {
    "enrollment_id": ["The enrollment id field is required."]
  }
}

DELETE api/enrollment/force/{enrollment}

Exclusão forçada Direção

Remove permanentemente um registro de matrícula do banco de dados. Operação restrita ao papel DIRECTOR. Diferente do soft delete, este endpoint não pode ser desfeito.

Parâmetros de rota

enrollment uuid obrigatório

UUID da matrícula a ser excluída permanentemente.

Corpo da requisição

reason string obrigatório

Motivo da exclusão (máx. 1000 caracteres).

observations string opcional

Observações adicionais (máx. 2000 caracteres).

Códigos de resposta

200

Matrícula excluída permanentemente.

403

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

404

Matrícula não encontrada.

Requisição DELETE

DELETE /api/enrollment/force/{enrollment_id}

{
  "reason": "Matrícula criada com erro — aluno nunca frequentou",
  "observations": null
}

Resposta

"Matrícula excluída de forma definitiva."

"Apenas a direção pode realizar esta operação."

{
  "message": "No query results for model [Enrollment]."
}

GET api/enrollment/timeline/{student}

Timeline da matrícula

Retorna o histórico cronológico de eventos de matrículas de um aluno: criações, transferências, atualizações de status, autorizações e exclusões. Útil para auditoria e visualização da trajetória escolar do aluno.

Parâmetros de rota

student uuid obrigatório

UUID do aluno.

Códigos de resposta

200

Lista de eventos em ordem cronológica reversa.

404

Aluno não encontrado.

Requisição GET

GET /api/enrollment/timeline/{student_id}

Resposta

[
  {
    "type": "enrollment",
    "label": "Matriculado em Turma A",
    "date": "2026-02-01T10:00:00-03:00",
    "actor": "Maria Secretária"
  },
  {
    "type": "status_update",
    "label": "Status atualizado para TRANSFERIDO",
    "date": "2026-05-10T14:22:00-03:00",
    "actor": "João Diretor"
  }
]

{
  "message": "No query results for model [Student]."
}

Matrículas

O modelo matrícula

Listar matrículas

Parâmetros de rota

Códigos de resposta

Matricular aluno

Parâmetros de rota

Corpo da requisição

Códigos de resposta

Editar número de matrícula

Parâmetros de rota

Corpo da requisição

Códigos de resposta

Operações administrativas

Transferência interna

Corpo da requisição

Regras de negócio

Códigos de resposta

Transferência externa

Corpo da requisição

Regras de negócio

Códigos de resposta

Solicitar atualização de status

Corpo da requisição

Regras de negócio

Códigos de resposta

Solicitar reativação de matrícula

Corpo da requisição

Regras de negócio

Códigos de resposta

Exclusão forçada Direção

Parâmetros de rota

Corpo da requisição

Códigos de resposta

Timeline da matrícula

Parâmetros de rota

Códigos de resposta