Ocorrências Disciplinares

Os endpoints de ocorrências disciplinares permitem registrar, consultar e gerenciar incidentes disciplinares de alunos. Cada ocorrência é vinculada a um aluno de uma escola do seu cliente e inclui informações sobre a gravidade do incidente, notificação de responsáveis, assinatura, suspensão e tarefas pedagógicas.

Permissões

O acesso aos endpoints depende de permissões atribuídas ao usuário autenticado.

Permissão	Professor	Coordenador	Diretor
`view disciplinary occurrence`	—	✓	✓
`create disciplinary occurrence`	—	✓	✓
`edit disciplinary occurrence`	—	✓	✓
`delete disciplinary occurrence`	—	—	✓
`restore disciplinary occurrence`	—	—	✓

Gravidade da ocorrência

# Níveis de gravidade

1  →  Leve
2  →  Moderada
3  →  Grave
4  →  Muito Grave
5  →  Crítica

O modelo ocorrência disciplinar

Representa um incidente disciplinar registrado para um aluno de uma escola.

id string (uuid)

Identificador único da ocorrência.

student_id string (uuid)

Identificador do aluno.

registered_by string (uuid)

Identificador do usuário que registrou a ocorrência.

classroom_id string (uuid) | null

Identificador da turma, se aplicável.

occurred_at date

Data em que a ocorrência aconteceu (Y-m-d).

gravidade integer (1–5)

Nível de gravidade: 1=Leve, 2=Moderada, 3=Grave, 4=Muito Grave, 5=Crítica.

gravidade_label string

Descrição textual da gravidade.

description string

Descrição da ocorrência.

exige_responsavel boolean

Indica se a ocorrência exige notificação do responsável.

responsavel_notificado_at datetime | null

Data e hora em que o responsável foi notificado.

exige_assinatura boolean

Indica se a ocorrência exige assinatura.

assinatura_coletada_at datetime | null

Data e hora em que a assinatura foi coletada.

gera_suspensao boolean

Indica se a ocorrência gera suspensão.

dias_suspensao integer | null

Quantidade de dias de suspensão.

suspensao_inicio date | null

Data de início da suspensão (Y-m-d).

suspensao_fim date | null

Data de fim da suspensão (Y-m-d).

gera_tarefa_pedagogica boolean

Indica se a ocorrência gera tarefa pedagógica.

tarefa_pedagogica string | null

Descrição da tarefa pedagógica.

confidencial boolean

Indica se a ocorrência é confidencial.

exige_evidencia boolean

Indica se a ocorrência exige evidência documental.

created_at datetime

Data e hora de criação.

updated_at datetime

Data e hora da última atualização.

deleted_at datetime | null

Data e hora de exclusão (soft delete).

Modelo ocorrência disciplinar

{
  "id": "a1b2c3d4-e5f6-7890-ab12-cd34ef567890",
  "student_id": "b2c3d4e5-f6a7-8901-bc23-de45fa678901",
  "registered_by": "c3d4e5f6-a7b8-9012-cd34-ef56ab789012",
  "classroom_id": null,
  "occurred_at": "2026-05-15",
  "gravidade": 3,
  "gravidade_label": "Grave",
  "description": "Aluno agrediu verbalmente um colega.",
  "exige_responsavel": true,
  "responsavel_notificado_at": null,
  "exige_assinatura": false,
  "assinatura_coletada_at": null,
  "gera_suspensao": false,
  "dias_suspensao": null,
  "suspensao_inicio": null,
  "suspensao_fim": null,
  "gera_tarefa_pedagogica": false,
  "tarefa_pedagogica": null,
  "confidencial": false,
  "exige_evidencia": false,
  "created_at": "2026-05-15T10:30:00+00:00",
  "updated_at": "2026-05-15T10:30:00+00:00",
  "deleted_at": null
}

GET /v1/partners/school/{cnpj}/disciplinary-occurrences/all

Listar ocorrências disciplinares

Retorna as ocorrências disciplinares da escola identificada pelo CNPJ, paginadas de 50 em 50, ordenadas pela data da ocorrência (mais recentes primeiro). Requer permissão view disciplinary occurrence.

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.

404

Escola não encontrada.

Requisição GET

GET /v1/partners/school/{cnpj}/disciplinary-occurrences/all

curl https://toakiescola.com.br/api/v1/partners/school/26019466000122/disciplinary-occurrences/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/disciplinary-occurrences/all', [
    'headers' => [
        'X-Authorization' => '{api_token}',
        'X-Partner'       => '{partner_token}',
        'X-Client'        => '{client_slug}',
    ],
]);
$occurrences = json_decode($response->getBody(), true);

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

Resposta

[
  {
    "id": "a1b2c3d4-...",
    "student_id": "b2c3d4e5-...",
    "gravidade": 3,
    // ...
  }
]

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

{
  "message": "Escola não encontrada."
}

GET /v1/partners/school/{cnpj}/disciplinary-occurrence/{id}

Consultar ocorrência disciplinar

Retorna os detalhes de uma ocorrência disciplinar pelo seu identificador. Requer permissão view disciplinary occurrence.

Parâmetros de rota

cnpj string obrigatório

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

id string (uuid) obrigatório

Identificador da ocorrência disciplinar.

Códigos de resposta

200

Sucesso.

401

Autenticação inválida.

404

Escola ou ocorrência não encontrada.

Requisição GET

GET /v1/partners/school/{cnpj}/disciplinary-occurrence/{id}

curl https://toakiescola.com.br/api/v1/partners/school/26019466000122/disciplinary-occurrence/a1b2c3d4-e5f6-7890-ab12-cd34ef567890 \
  -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/disciplinary-occurrence/{id}', [
    'headers' => [
        'X-Authorization' => '{api_token}',
        'X-Partner'       => '{partner_token}',
        'X-Client'        => '{client_slug}',
    ],
]);
$occurrence = json_decode($response->getBody(), true);

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

Resposta

{
  "id": "a1b2c3d4-...",
  "student_id": "b2c3d4e5-...",
  "gravidade": 3,
  // ...
}

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

{
  "message": "Escola ou ocorrência não encontrada."
}

POST /v1/partners/school/{cnpj}/disciplinary-occurrence

Criar ocorrência disciplinar

Registra uma nova ocorrência disciplinar para um aluno da escola. Requer permissão create disciplinary occurrence.

Corpo da requisição

student_id string (uuid) obrigatório

UUID do aluno.

registered_by string (uuid) obrigatório

UUID do usuário que está registrando a ocorrência.

occurred_at date (Y-m-d) obrigatório

Data em que a ocorrência aconteceu.

gravidade integer (1–5) obrigatório

Nível de gravidade da ocorrência.

description string obrigatório

Descrição detalhada da ocorrência.

classroom_id string (uuid) opcional

UUID da turma, se aplicável.

exige_responsavel boolean opcional

Se exige notificação do responsável. Padrão: false.

exige_assinatura boolean opcional

Se exige assinatura. Padrão: false.

gera_suspensao boolean opcional

Se gera suspensão. Padrão: false.

dias_suspensao integer opcional

Quantidade de dias de suspensão (obrigatório se gera_suspensao=true).

suspensao_inicio date (Y-m-d) opcional

Início da suspensão (obrigatório se gera_suspensao=true).

suspensao_fim date (Y-m-d) opcional

Fim da suspensão (obrigatório se gera_suspensao=true).

gera_tarefa_pedagogica boolean opcional

Se gera tarefa pedagógica. Padrão: false.

tarefa_pedagogica string opcional

Descrição da tarefa pedagógica.

confidencial boolean opcional

Se a ocorrência é confidencial. Padrão: false.

exige_evidencia boolean opcional

Se exige evidência documental. Padrão: false.

Códigos de resposta

200

Ocorrência criada com sucesso.

400

Dados inválidos.

401

Autenticação inválida.

404

Escola ou aluno não encontrado.

Requisição POST

POST /v1/partners/school/{cnpj}/disciplinary-occurrence

curl -X POST https://toakiescola.com.br/api/v1/partners/school/26019466000122/disciplinary-occurrence \
  -H "X-Authorization: {api_token}" \
  -H "X-Partner: {partner_token}" \
  -H "X-Client: {client_slug}" \
  -H "Content-Type: application/json" \
  -d '{"student_id":"b2c3...","registered_by":"c3d4...","occurred_at":"2026-05-15","gravidade":3,"description":"..."}'

use GuzzleHttp\Client;

$client = new Client();
$response = $client->post('https://toakiescola.com.br/api/v1/partners/school/26019466000122/disciplinary-occurrence', [
    'headers' => [
        'X-Authorization' => '{api_token}',
        'X-Partner'       => '{partner_token}',
        'X-Client'        => '{client_slug}',
    ],
    'json' => [
        'student_id'    => 'b2c3d4e5-...',
        'registered_by' => 'c3d4e5f6-...',
        'occurred_at'   => '2026-05-15',
        'gravidade'     => 3,
        'description'   => 'Aluno agrediu verbalmente um colega.',
    ],
]);
$occurrence = json_decode($response->getBody(), true);

const response = await fetch('https://toakiescola.com.br/api/v1/partners/school/26019466000122/disciplinary-occurrence', {
    method: 'POST',
    headers: {
        'X-Authorization': '{api_token}',
        'X-Partner':       '{partner_token}',
        'X-Client':        '{client_slug}',
        'Content-Type':    'application/json',
    },
    body: JSON.stringify({
        student_id:    'b2c3d4e5-...',
        registered_by: 'c3d4e5f6-...',
        occurred_at:   '2026-05-15',
        gravidade:     3,
        description:   'Aluno agrediu verbalmente um colega.',
    }),
});
const occurrence = await response.json();

Resposta

{
  "id": "a1b2c3d4-...",
  "student_id": "b2c3d4e5-...",
  "gravidade": 3,
  // ...
}

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

{
  "message": "Escola ou aluno não encontrado nesta escola."
}

PUT /v1/partners/school/{cnpj}/disciplinary-occurrence/{id}

Atualizar ocorrência disciplinar

Atualiza os dados de uma ocorrência disciplinar existente. Todos os campos são opcionais — apenas os campos enviados serão atualizados. Requer permissão edit disciplinary occurrence.

Parâmetros de rota

cnpj string obrigatório

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

id string (uuid) obrigatório

Identificador da ocorrência disciplinar.

Campos atualizáveis

occurred_at date (Y-m-d) opcional

Data em que a ocorrência aconteceu.

gravidade integer (1–5) opcional

Nível de gravidade da ocorrência.

description string opcional

Descrição detalhada da ocorrência.

classroom_id string | null opcional

UUID da turma, ou null para remover.

exige_responsavel boolean opcional

Se exige notificação do responsável.

exige_assinatura boolean opcional

Se exige assinatura.

gera_suspensao boolean opcional

Se gera suspensão.

dias_suspensao integer | null opcional

Quantidade de dias de suspensão.

suspensao_inicio date | null opcional

Início da suspensão.

suspensao_fim date | null opcional

Fim da suspensão.

gera_tarefa_pedagogica boolean opcional

Se gera tarefa pedagógica.

tarefa_pedagogica string | null opcional

Descrição da tarefa pedagógica.

confidencial boolean opcional

Se a ocorrência é confidencial.

exige_evidencia boolean opcional

Se exige evidência documental.

Códigos de resposta

200

Ocorrência atualizada com sucesso.

400

Dados inválidos.

401

Autenticação inválida.

404

Escola ou ocorrência não encontrada.

Requisição PUT

PUT /v1/partners/school/{cnpj}/disciplinary-occurrence/{id}

curl -X PUT https://toakiescola.com.br/api/v1/partners/school/26019466000122/disciplinary-occurrence/a1b2c3d4-e5f6-7890-ab12-cd34ef567890 \
  -H "X-Authorization: {api_token}" \
  -H "X-Partner: {partner_token}" \
  -H "X-Client: {client_slug}" \
  -H "Content-Type: application/json" \
  -d '{"gravidade":4,"exige_responsavel":true}'

use GuzzleHttp\Client;

$client = new Client();
$response = $client->put('https://toakiescola.com.br/api/v1/partners/school/26019466000122/disciplinary-occurrence/{id}', [
    'headers' => [
        'X-Authorization' => '{api_token}',
        'X-Partner'       => '{partner_token}',
        'X-Client'        => '{client_slug}',
    ],
    'json' => [
        'gravidade'         => 4,
        'exige_responsavel' => true,
    ],
]);
$occurrence = json_decode($response->getBody(), true);

const response = await fetch('https://toakiescola.com.br/api/v1/partners/school/26019466000122/disciplinary-occurrence/{id}', {
    method: 'PUT',
    headers: {
        'X-Authorization': '{api_token}',
        'X-Partner':       '{partner_token}',
        'X-Client':        '{client_slug}',
        'Content-Type':    'application/json',
    },
    body: JSON.stringify({
        gravidade:         4,
        exige_responsavel: true,
    }),
});
const occurrence = await response.json();

Resposta

{
  "id": "a1b2c3d4-...",
  "gravidade": 4,
  // ...
}

{
  "success": false,
  "errors": [...]
}

{
  "message": "Escola ou ocorrência não encontrada."
}

DELETE /v1/partners/school/{cnpj}/disciplinary-occurrence/{id}

Excluir ocorrência disciplinar

Remove (soft delete) uma ocorrência disciplinar. A ocorrência pode ser restaurada posteriormente pela aplicação. Requer permissão delete disciplinary occurrence.

Parâmetros de rota

cnpj string obrigatório

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

id string (uuid) obrigatório

Identificador da ocorrência disciplinar.

Códigos de resposta

200

Ocorrência excluída com sucesso.

401

Autenticação inválida.

404

Escola ou ocorrência não encontrada.

Requisição DELETE

DELETE /v1/partners/school/{cnpj}/disciplinary-occurrence/{id}

curl -X DELETE https://toakiescola.com.br/api/v1/partners/school/26019466000122/disciplinary-occurrence/a1b2c3d4-e5f6-7890-ab12-cd34ef567890 \
  -H "X-Authorization: {api_token}" \
  -H "X-Partner: {partner_token}" \
  -H "X-Client: {client_slug}"

use GuzzleHttp\Client;

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

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

Resposta

{
  "success": true
}

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

{
  "message": "Escola ou ocorrência não encontrada."
}