Ano Letivo
O ano letivo representa o período acadêmico de uma escola e governa turmas, matrículas e formas de avaliação. Utilize estes endpoints para criar, editar, excluir e controlar o ciclo de vida do ano letivo (abertura, fechamento e pré-matrícula), bem como gerenciar as formas de avaliação vinculadas a ele.
Todos os endpoints exigem os cabeçalhos X-Authorization,
X-Partner e
X-Client. As regras de
negócio são idênticas às aplicadas no painel administrativo da escola.
O modelo ano letivo
Cada ano letivo pertence a uma escola e possui um ciclo de vida controlado pelos campos
opened_at,
closed_at,
is_current e
is_preenrollment_open.
id
string (uuid)
Identificador único do ano letivo.
name
string
Nome do ano letivo (ex.: "2026").
year
integer
Ano de calendário (ex.: 2026). 4 dígitos.
school_days
integer
Número de dias letivos previstos (default: 200).
is_current
boolean
Indica se é o ano letivo corrente.
is_preenrollment_open
boolean
Indica se a pré-matrícula está aberta.
opened_at
string|null (date)
Data de abertura do ano letivo (Y-m-d) ou null se nunca aberto.
closed_at
string|null (date)
Data de fechamento (Y-m-d) ou null se ainda aberto.
{ "id": "a1b2c3d4-0000-0000-0000-000000000001", "name": "2026", "year": 2026, "school_days": 200, "is_current": true, "is_preenrollment_open": false, "opened_at": "2026-02-01", "closed_at": null }
/v1/partners/school/{cnpj}/school-year/{id}
Obter ano letivo
Retorna os dados de um ano letivo específico, escopado pelo cnpj
da escola e pelo id do ano letivo.
Parâmetros de rota
cnpj
string
obrigatório
CNPJ da escola (14 dígitos, sem formatação).
id
string (uuid)
obrigatório
Identificador do ano letivo.
Códigos de resposta
200— Ano letivo retornado.404— Ano letivo não encontrado.
-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/school-year/{id}', [ 'headers' => [ 'X-Authorization' => '{api_token}', 'X-Partner' => '{partner_token}', 'X-Client' => '{client_slug}', ], ]); $schoolYear = json_decode($response->getBody(), true);
const response = await fetch('https://toakiescola.com.br/api/v1/partners/school/26019466000122/school-year/{id}', { headers: { 'X-Authorization': '{api_token}', 'X-Partner': '{partner_token}', 'X-Client': '{client_slug}', }, }); const schoolYear = await response.json();
{ "data": { "id": "a1b2c3d4-0000-0000-0000-000000000001", "name": "2026", "year": 2026, "school_days": 200, "is_current": true, "is_preenrollment_open": false, "opened_at": "2026-02-01", "closed_at": null } }
{ "message": "Autenticação inválida." }
{ "message": "Recurso não encontrado." }
/v1/partners/school/{cnpj}/school-year
Criar ano letivo
Cria um ano letivo para a escola identificada pelo cnpj.
O ano letivo é criado em estado fechado (não corrente, sem datas de abertura/fechamento) e
não inicia a pré-matrícula automaticamente.
Parâmetros de rota
cnpj
string
obrigatório
CNPJ da escola (14 dígitos, sem formatação).
Parâmetros do corpo
name
string · obrigatório
Nome do ano letivo.
year
integer · obrigatório
Ano de calendário com 4 dígitos (1000–9999).
school_days
integer · opcional
Quantidade de dias letivos (1–365). Default: 200.
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.
-X POST \
-H "X-Authorization: {api_token}" \
-H "X-Partner: {partner_token}" \
-H "X-Client: {client_slug}" \
-H "Content-Type: application/json" \
-d '{"name":"2026","year":2026,"school_days":200}'
use GuzzleHttp\Client; $client = new Client(); $response = $client->post('https://toakiescola.com.br/api/v1/partners/school/26019466000122/school-year', [ 'headers' => [ 'X-Authorization' => '{api_token}', 'X-Partner' => '{partner_token}', 'X-Client' => '{client_slug}', ], 'json' => [ 'name' => '2026', 'year' => 2026, 'school_days' => 200, ], ]); $schoolYear = json_decode($response->getBody(), true);
const response = await fetch('https://toakiescola.com.br/api/v1/partners/school/26019466000122/school-year', { method: 'POST', headers: { 'X-Authorization': '{api_token}', 'X-Partner': '{partner_token}', 'X-Client': '{client_slug}', 'Content-Type': 'application/json', }, body: JSON.stringify({ name: '2026', year: 2026, school_days: 200, }), }); const schoolYear = await response.json();
{ "data": { "id": "a1b2c3d4-0000-0000-0000-000000000001", "name": "2026", "year": 2026, "school_days": 200, "is_current": false, "is_preenrollment_open": false, "opened_at": null, "closed_at": null } }
{ "message": "Autenticação inválida." }
{ "message": "Recurso não encontrado." }
/v1/partners/school/{cnpj}/school-year/{id}
Editar ano letivo
Atualiza o nome e/ou a quantidade de dias letivos. O campo year
não pode ser alterado após a criação.
Parâmetros de rota
cnpj
string
obrigatório
CNPJ da escola (14 dígitos, sem formatação).
id
string (uuid)
obrigatório
Identificador do ano letivo.
Parâmetros do corpo
name
string · obrigatório
Novo nome do ano letivo.
school_days
integer · opcional
Quantidade de dias letivos (1–365).
Códigos de resposta
200
Sucesso.
400
Dados inválidos.
401
Autenticação inválida.
404
Recurso não encontrado.
-X PUT \
-H "X-Authorization: {api_token}" \
-H "X-Partner: {partner_token}" \
-H "X-Client: {client_slug}" \
-H "Content-Type: application/json" \
-d '{"name":"2026 - Revisado","school_days":205}'
use GuzzleHttp\Client; $client = new Client(); $response = $client->put('https://toakiescola.com.br/api/v1/partners/school/26019466000122/school-year/{id}', [ 'headers' => [ 'X-Authorization' => '{api_token}', 'X-Partner' => '{partner_token}', 'X-Client' => '{client_slug}', ], 'json' => [ 'name' => '2026 - Revisado', 'school_days' => 205, ], ]);
const response = await fetch('https://toakiescola.com.br/api/v1/partners/school/26019466000122/school-year/{id}', { method: 'PUT', headers: { 'X-Authorization': '{api_token}', 'X-Partner': '{partner_token}', 'X-Client': '{client_slug}', 'Content-Type': 'application/json', }, body: JSON.stringify({ name: '2026 - Revisado', school_days: 205, }), });
{ "data": { "id": "a1b2c3d4-0000-0000-0000-000000000001", "name": "2026 - Revisado", "school_days": 205 } }
{ "message": "Autenticação inválida." }
{ "message": "Recurso não encontrado." }
/v1/partners/school/{cnpj}/school-year/{id}
Excluir ano letivo
Remove um ano letivo. Só é permitido excluir um ano letivo que nunca foi aberto e
não é o corrente (campos opened_at,
closed_at nulos e
is_current = false).
Parâmetros de rota
cnpj
string
obrigatório
CNPJ da escola (14 dígitos, sem formatação).
id
string (uuid)
obrigatório
Identificador do ano letivo.
Códigos de resposta
200— Ano letivo excluído.404— Ano letivo não encontrado.422— Não é possível excluir o ano letivo corrente ou ano letivo já aberto/fechado.
-X DELETE \
-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/school-year/{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/school-year/{id}', { method: 'DELETE', headers: { 'X-Authorization': '{api_token}', 'X-Partner': '{partner_token}', 'X-Client': '{client_slug}', }, });
{ "success": true }
{ "message": "Autenticação inválida." }
{ "message": "Recurso não encontrado." }
/v1/partners/school/{cnpj}/school-year/{id}/open
Abrir ano letivo
Marca o ano letivo como corrente (is_current = true),
define opened_at
como hoje e limpa closed_at.
Não é permitido abrir um novo ano letivo se já houver outro aberto na mesma escola;
feche-o primeiro.
Parâmetros de rota
cnpj
string
obrigatório
CNPJ da escola (14 dígitos, sem formatação).
id
string (uuid)
obrigatório
Identificador do ano letivo.
Códigos de resposta
200— Ano letivo aberto. Retorna o recurso atualizado.404— Ano letivo não encontrado.422— Já existe um ano letivo aberto.
-X PATCH \
-H "X-Authorization: {api_token}" \
-H "X-Partner: {partner_token}" \
-H "X-Client: {client_slug}"
use GuzzleHttp\Client; $client = new Client(); $response = $client->patch('https://toakiescola.com.br/api/v1/partners/school/26019466000122/school-year/{id}/open', [ '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/school-year/{id}/open', { method: 'PATCH', headers: { 'X-Authorization': '{api_token}', 'X-Partner': '{partner_token}', 'X-Client': '{client_slug}', }, });
{ "data": { "id": "a1b2c3d4-0000-0000-0000-000000000001", "name": "2026", "is_current": true, "opened_at": "2026-02-01", "closed_at": null } }
{ "message": "Autenticação inválida." }
{ "message": "Recurso não encontrado." }
/v1/partners/school/{cnpj}/school-year/{id}/close
Fechar ano letivo
Encerra o ano letivo. Marca is_current = false
e define closed_at
como a data atual. Após fechado, o ano letivo não pode ser reaberto pela API
(use o painel administrativo, se necessário).
Parâmetros de rota
cnpj
string
obrigatório
CNPJ da escola (14 dígitos, sem formatação).
id
string (uuid)
obrigatório
Identificador do ano letivo.
Códigos de resposta
200
Sucesso.
400
Dados inválidos.
401
Autenticação inválida.
404
Recurso não encontrado.
-X PATCH \
-H "X-Authorization: {api_token}" \
-H "X-Partner: {partner_token}" \
-H "X-Client: {client_slug}"
use GuzzleHttp\Client; $client = new Client(); $response = $client->patch('https://toakiescola.com.br/api/v1/partners/school/26019466000122/school-year/{id}/close', [ '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/school-year/{id}/close', { method: 'PATCH', headers: { 'X-Authorization': '{api_token}', 'X-Partner': '{partner_token}', 'X-Client': '{client_slug}', }, });
{ "data": { "id": "a1b2c3d4-0000-0000-0000-000000000001", "is_current": false, "closed_at": "2026-12-20" } }
{ "message": "Autenticação inválida." }
{ "message": "Recurso não encontrado." }
/v1/partners/school/{cnpj}/school-year/{id}/preenrollment/toggle
Alternar pré-matrícula
Alterna o estado de pré-matrícula do ano letivo. Se estava aberta, fecha; se estava fechada,
abre. O novo estado é retornado em status
("OPENED" ou
"CLOSED").
Parâmetros de rota
cnpj
string
obrigatório
CNPJ da escola (14 dígitos, sem formatação).
id
string (uuid)
obrigatório
Identificador do ano letivo.
Códigos de resposta
200
Sucesso.
400
Dados inválidos.
401
Autenticação inválida.
404
Recurso não encontrado.
-X PATCH \
-H "X-Authorization: {api_token}" \
-H "X-Partner: {partner_token}" \
-H "X-Client: {client_slug}"
use GuzzleHttp\Client; $client = new Client(); $response = $client->patch('https://toakiescola.com.br/api/v1/partners/school/26019466000122/school-year/{id}/preenrollment/toggle', [ '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/school-year/{id}/preenrollment/toggle', { method: 'PATCH', headers: { 'X-Authorization': '{api_token}', 'X-Partner': '{partner_token}', 'X-Client': '{client_slug}', }, });
{ "success": true, "status": "OPENED", "school_year": { "id": "a1b2c3d4-0000-0000-0000-000000000001", "is_preenrollment_open": true } }
{ "message": "Autenticação inválida." }
{ "message": "Recurso não encontrado." }
O modelo forma de avaliação
Forma de avaliação configura como turmas de um ano letivo são avaliadas: tipo de nota (numérica/conceitual), tipo de média, periodicidade e regras de aprovação/recuperação.
id
string (uuid)
Identificador único.
school_year_id
string (uuid)
Ano letivo ao qual pertence.
name
string
Nome da forma de avaliação (máx. 100).
periodicity_id
string (uuid)
Periodicidade (bimestral, trimestral, etc.).
score_type_id
string (uuid)
Tipo de nota (numérica, conceitual).
average_type_id
string (uuid)
Tipo de cálculo de média.
decimal_places
integer|null
Casas decimais permitidas (0 ou 1).
attendance_cut_percent
numeric|null
Percentual de corte por frequência (0–100).
passing_grade
numeric|null
Nota mínima de aprovação.
max_score
numeric|null
Nota máxima.
min_score
numeric|null
Nota mínima.
auto_fail
boolean
Reprovação automática quando aplicável.
max_dependencies
integer|null
Máx. de dependências permitidas (0–255).
recovery_passing_grade
numeric|null
Nota mínima de aprovação na recuperação.
recovery_max_score
numeric|null
Nota máxima na recuperação.
parallel_recovery
boolean
Indica recuperação paralela.
concepts[]
array (opcional)
Conceitos quando o tipo de nota é conceitual.
assessments[]
array (opcional)
Avaliações configuradas (nome, peso).
{ "id": "f0e0d0c0-1111-2222-3333-444444444444", "school_year_id": "a1b2c3d4-0000-0000-0000-000000000001", "name": "Padrão Bimestral", "periodicity_id": "...", "score_type_id": "...", "average_type_id": "...", "decimal_places": 1, "attendance_cut_percent": 75, "passing_grade": 6, "max_score": 10, "min_score": 0, "auto_fail": false, "max_dependencies": 3, "recovery_passing_grade": 6, "recovery_max_score": 10, "parallel_recovery": true }
{ "message": "Autenticação inválida." }
{ "message": "Recurso não encontrado." }
/v1/partners/school/{cnpj}/form-of-evaluation/{id}
Obter forma de avaliação
Retorna os dados completos de uma FOE, incluindo conceitos e avaliações vinculadas.
Parâmetros de rota
cnpj
string
obrigatório
CNPJ da escola (14 dígitos, sem formatação).
id
string (uuid)
obrigatório
Identificador da forma de avaliação.
Códigos de resposta
200— Forma de avaliação retornada.404— Forma de avaliação não encontrada.
-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/form-of-evaluation/{id}', [ 'headers' => [ 'X-Authorization' => '{api_token}', 'X-Partner' => '{partner_token}', 'X-Client' => '{client_slug}', ], ]); $foe = json_decode($response->getBody(), true);
const response = await fetch('https://toakiescola.com.br/api/v1/partners/school/26019466000122/form-of-evaluation/{id}', { headers: { 'X-Authorization': '{api_token}', 'X-Partner': '{partner_token}', 'X-Client': '{client_slug}', }, }); const foe = await response.json();
{ "data": { "id": "f0e0d0c0-1111-2222-3333-444444444444", "school_year_id": "a1b2c3d4-0000-0000-0000-000000000001", "name": "Padrão Bimestral", "decimal_places": 1, "passing_grade": 6, "max_score": 10, "concepts": [], "assessments": [ { "name": "Prova", "weight": 7 }, { "name": "Trabalho", "weight": 3 } ] } }
{ "message": "Autenticação inválida." }
{ "message": "Recurso não encontrado." }
/v1/partners/school/{cnpj}/school-year/{school_year_id}/form-of-evaluation
Criar forma de avaliação
Cria uma forma de avaliação vinculada ao ano letivo identificado por school_year_id.
Os IDs de periodicity_id,
score_type_id e
average_type_id devem
existir no catálogo da plataforma.
Parâmetros de rota
cnpj
string
obrigatório
CNPJ da escola (14 dígitos, sem formatação).
school_year_id
string (uuid)
obrigatório
Identificador do ano letivo.
Regras
- Quando
auto_fail = true, os campos de recuperação são ignorados (forçados a null/false). concepts[]só são salvos quando o tipo de nota for conceitual.decimal_placesdeve ser 0 ou 1.
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.
-X POST \
-H "X-Authorization: {api_token}" \
-H "X-Partner: {partner_token}" \
-H "X-Client: {client_slug}" \
-H "Content-Type: application/json" \
-d '{"name":"Padrão Bimestral","periodicity_id":"...","score_type_id":"...","average_type_id":"...","decimal_places":1,"attendance_cut_percent":75,"passing_grade":6,"max_score":10,"min_score":0,"auto_fail":false,"recovery_passing_grade":6,"recovery_max_score":10,"parallel_recovery":true,"assessments":[{"name":"Prova","weight":7},{"name":"Trabalho","weight":3}]}'
use GuzzleHttp\Client; $client = new Client(); $response = $client->post('https://toakiescola.com.br/api/v1/partners/school/26019466000122/school-year/{school_year_id}/form-of-evaluation', [ 'headers' => [ 'X-Authorization' => '{api_token}', 'X-Partner' => '{partner_token}', 'X-Client' => '{client_slug}', ], 'json' => [ 'name' => 'Padrão Bimestral', 'periodicity_id' => '{periodicity_id}', 'score_type_id' => '{score_type_id}', 'average_type_id' => '{average_type_id}', 'decimal_places' => 1, 'attendance_cut_percent' => 75, 'passing_grade' => 6, 'max_score' => 10, 'min_score' => 0, 'auto_fail' => false, 'recovery_passing_grade' => 6, 'recovery_max_score' => 10, 'parallel_recovery' => true, 'assessments' => [ ['name' => 'Prova', 'weight' => 7], ['name' => 'Trabalho', 'weight' => 3], ], ], ]);
const response = await fetch('https://toakiescola.com.br/api/v1/partners/school/26019466000122/school-year/{school_year_id}/form-of-evaluation', { method: 'POST', headers: { 'X-Authorization': '{api_token}', 'X-Partner': '{partner_token}', 'X-Client': '{client_slug}', 'Content-Type': 'application/json', }, body: JSON.stringify({ name: 'Padrão Bimestral', periodicity_id: '{periodicity_id}', score_type_id: '{score_type_id}', average_type_id: '{average_type_id}', decimal_places: 1, attendance_cut_percent: 75, passing_grade: 6, max_score: 10, min_score: 0, auto_fail: false, recovery_passing_grade: 6, recovery_max_score: 10, parallel_recovery: true, assessments: [ { name: 'Prova', weight: 7 }, { name: 'Trabalho', weight: 3 }, ], }), });
{ "data": { "id": "f0e0d0c0-1111-2222-3333-444444444444", "school_year_id": "a1b2c3d4-0000-0000-0000-000000000001", "name": "Padrão Bimestral" } }
{ "message": "Autenticação inválida." }
{ "message": "Recurso não encontrado." }
/v1/partners/school/{cnpj}/form-of-evaluation/{id}
Editar forma de avaliação
Atualiza uma forma de avaliação existente. O corpo aceita os mesmos campos da criação. O
school_year_id da forma de avaliação
não é alterado pela API; o vínculo do ano letivo é mantido.
Parâmetros de rota
cnpj
string
obrigatório
CNPJ da escola (14 dígitos, sem formatação).
id
string (uuid)
obrigatório
Identificador da forma de avaliação.
As mesmas regras de validação e dependências da criação se aplicam.
Códigos de resposta
200
Sucesso.
400
Dados inválidos.
401
Autenticação inválida.
404
Recurso não encontrado.
-X PUT \
-H "X-Authorization: {api_token}" \
-H "X-Partner: {partner_token}" \
-H "X-Client: {client_slug}" \
-H "Content-Type: application/json" \
-d '{"name":"Padrão Bimestral - v2","periodicity_id":"...","score_type_id":"...","average_type_id":"...","auto_fail":false,"parallel_recovery":true}'
use GuzzleHttp\Client; $client = new Client(); $response = $client->put('https://toakiescola.com.br/api/v1/partners/school/26019466000122/form-of-evaluation/{id}', [ 'headers' => [ 'X-Authorization' => '{api_token}', 'X-Partner' => '{partner_token}', 'X-Client' => '{client_slug}', ], 'json' => [ 'name' => 'Padrão Bimestral - v2', 'periodicity_id' => '{periodicity_id}', 'score_type_id' => '{score_type_id}', 'average_type_id' => '{average_type_id}', 'auto_fail' => false, 'parallel_recovery' => true, ], ]);
const response = await fetch('https://toakiescola.com.br/api/v1/partners/school/26019466000122/form-of-evaluation/{id}', { method: 'PUT', headers: { 'X-Authorization': '{api_token}', 'X-Partner': '{partner_token}', 'X-Client': '{client_slug}', 'Content-Type': 'application/json', }, body: JSON.stringify({ name: 'Padrão Bimestral - v2', periodicity_id: '{periodicity_id}', score_type_id: '{score_type_id}', average_type_id: '{average_type_id}', auto_fail: false, parallel_recovery: true, }), });
{ "data": { "id": "f0e0d0c0-1111-2222-3333-444444444444", "name": "Padrão Bimestral - v2" } }
{ "message": "Autenticação inválida." }
{ "message": "Recurso não encontrado." }
/v1/partners/school/{cnpj}/form-of-evaluation/{id}
Excluir forma de avaliação
Remove uma forma de avaliação. Conceitos e avaliações vinculadas são excluídos em cascata. As turmas que
usavam esta forma de avaliação têm o vínculo removido (campo
form_of_evaluation_id
passa a ficar null),
mas as turmas em si não são afetadas.
Parâmetros de rota
cnpj
string
obrigatório
CNPJ da escola (14 dígitos, sem formatação).
id
string (uuid)
obrigatório
Identificador da forma de avaliação.
Códigos de resposta
200— Forma de avaliação excluída.404— Forma de avaliação não encontrada.
-X DELETE \
-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/form-of-evaluation/{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/form-of-evaluation/{id}', { method: 'DELETE', headers: { 'X-Authorization': '{api_token}', 'X-Partner': '{partner_token}', 'X-Client': '{client_slug}', }, });
{ "success": true }
{ "message": "Autenticação inválida." }
{ "message": "Recurso não encontrado." }