Avaliações

Os endpoints de avaliações permitem listar, registrar e excluir notas de alunos em turmas. As notas são salvas por aluno, disciplina, bimestre/período e avaliação (prova, trabalho etc.). A API respeita as configurações da Forma de Avaliação da turma, como nota máxima, recuperação paralela e casas decimais permitidas.

O modelo avaliação

O modelo avaliação representa a nota de um aluno em uma disciplina para um período específico.

id string (uuid)

Identificador único da avaliação.

classroom_id string (uuid)

Identificador da turma à qual pertence a avaliação.

subject_id string (uuid)

Identificador da disciplina avaliada.

subject_name string | null

Nome da disciplina (incluso quando carregado).

student_id string (uuid)

Identificador do aluno.

student_name string | null

Nome do aluno (incluso quando carregado).

enrollment_number string | null

Número de matrícula do aluno.

period integer

Número do período (bimestre, trimestre etc.). Começa em 1.

evaluation_assessment_id string | null

Identificador da avaliação dentro da Forma de Avaliação (ex: Prova, Trabalho). Nulo para formas sem instrumentos.

is_recovery boolean

Indica se a nota é de recuperação paralela.

score decimal | null

Valor da nota. Nulo quando a célula existe mas ainda não foi preenchida.

created_at datetime

Data e hora de criação no formato Y-m-d H:i:s.

Modelo avaliação

{
  "id": "a1b2c3d4-e5f6-7890-ab12-cd34ef567890",
  "classroom_id": "b2c3d4e5-f6a7-8901-bc23-de45fa678901",
  "subject_id": "c3d4e5f6-a7b8-9012-cd34-ef56ab789012",
  "subject_name": "Matemática",
  "student_id": "d4e5f6a7-b8c9-0123-de45-fa67bc890123",
  "student_name": "João Silva",
  "enrollment_number": "7.553",
  "period": 1,
  "evaluation_assessment_id": "e5f6a7b8-c9d0-1234-ef56-ab78cd901234",
  "is_recovery": false,
  "score": 8.5,
  "created_at": "2026-03-10 09:15:00"
}

GET /v1/partners/school/{cnpj}/classroom/{classroom_id}/scores

Listar avaliações da turma

Retorna todas as notas registradas para a turma informada. Os resultados podem ser filtrados por disciplina e/ou número de matrícula do aluno através de query strings. O resultado é paginado.

Parâmetros de rota

cnpj string obrigatório

CNPJ da escola (14 dígitos).

classroom_id string (uuid) obrigatório

Identificador único da turma.

Filtros (query string, opcionais)

subject_id string (uuid)

Filtra por disciplina.

enrollment_number string

Filtra pelo número de matrícula do aluno.

Códigos de resposta

200

Sucesso.

401

Autenticação inválida.

404

Escola ou turma não encontrada.

Requisição GET

curl https://toakiescola.com.br/api/v1/partners/school/26019466000122/classroom/b2c3d4e5-f6a7-8901-bc23-de45fa678901/scores \
  -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/classroom/b2c3d4e5-.../scores', [
    '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/classroom/b2c3d4e5-.../scores', {
    headers: {
        'X-Authorization': '{api_token}',
        'X-Partner':       '{partner_token}',
        'X-Client':        '{client_slug}',
    },
});

Resposta

{
  "data": [
    {
      "id": "a1b2c3d4-...",
      "subject_name": "Matemática",
      "enrollment_number": "7.553",
      "period": 1,
      "is_recovery": false,
      "score": 8.5
    }
  ],
  "links": { ... },
  "meta": { ... }
}

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

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

POST /v1/partners/school/{cnpj}/classroom/{classroom_id}/score

Salvar avaliação

Cria ou atualiza (upsert) a nota de um aluno para um determinado período e disciplina. A operação é idempotente: se já existir uma nota com os mesmos critérios (turma, disciplina, aluno, período, instrumento e tipo regular/recuperação), ela será atualizada. Regras da Forma de Avaliação são aplicadas automaticamente (nota máxima, casas decimais, recuperação paralela).

Parâmetros de rota

cnpj string obrigatório

CNPJ da escola (14 dígitos).

classroom_id string (uuid) obrigatório

Identificador único da turma.

Corpo da requisição

enrollment_number string obrigatório

Número de matrícula do aluno.

subject_id string (uuid) obrigatório

Identificador da disciplina.

period integer obrigatório

Número do período (1, 2, 3...).

score decimal | null opcional

Valor da nota. Envie null para apagar sem excluir o registro.

evaluation_assessment_id string | null opcional

ID do instrumento de avaliação (ex: Prova, Trabalho). Nulo para formas sem instrumentos.

is_recovery boolean opcional

Indica se é nota de recuperação paralela. Padrão: false.

Códigos de resposta

200

Avaliação salva com sucesso.

400

Dados inválidos.

401

Autenticação inválida.

404

Escola, turma ou aluno não encontrado.

422

Violação de regra da forma de avaliação (nota acima do máximo, casas decimais, recuperação não habilitada).

Requisição POST

curl https://toakiescola.com.br/api/v1/partners/school/26019466000122/classroom/b2c3d4e5-.../score \
  -X POST \
  -H "X-Authorization: {api_token}" \
  -H "X-Partner: {partner_token}" \
  -H "X-Client: {client_slug}" \
  -H "Content-Type: application/json" \
  -d '{"enrollment_number":"7.553","subject_id":"c3d4e5f6-...","period":1,"score":8.5}'

use GuzzleHttp\Client;

$client = new Client();
$response = $client->post('https://toakiescola.com.br/api/v1/partners/school/26019466000122/classroom/b2c3d4e5-.../score', [
    'headers' => [
        'X-Authorization' => '{api_token}',
        'X-Partner'       => '{partner_token}',
        'X-Client'        => '{client_slug}',
    ],
    'json' => [
        'enrollment_number' => '7.553',
        'subject_id'        => 'c3d4e5f6-...',
        'period'            => 1,
        'score'             => 8.5,
    ],
]);

const response = await fetch('https://toakiescola.com.br/api/v1/partners/school/26019466000122/classroom/b2c3d4e5-.../score', {
    method: 'POST',
    headers: {
        'X-Authorization': '{api_token}',
        'X-Partner':       '{partner_token}',
        'X-Client':        '{client_slug}',
        'Content-Type':    'application/json',
    },
    body: JSON.stringify({
        enrollment_number: '7.553',
        subject_id:        'c3d4e5f6-...',
        period:            1,
        score:             8.5,
    }),
});

Resposta

{
  "data": {
    "id": "a1b2c3d4-...",
    "subject_name": "Matemática",
    "enrollment_number": "7.553",
    "period": 1,
    "is_recovery": false,
    "score": 8.5
  }
}

{
  "success": false,
  "message": "A nota informada excede o valor máximo..."
}

{
  "success": false,
  "message": "Aluno não encontrado."
}

DELETE /v1/partners/school/{cnpj}/classroom/{classroom_id}/score/{score_id}

Excluir avaliação

Remove permanentemente uma nota pelo seu identificador. A operação é irreversível.

Parâmetros de rota

cnpj string obrigatório

CNPJ da escola (14 dígitos).

classroom_id string (uuid) obrigatório

Identificador único da turma.

score_id string (uuid) obrigatório

Identificador único da avaliação a ser excluída.

Códigos de resposta

200

Avaliação excluída.

401

Autenticação inválida.

404

Escola, turma ou avaliação não encontrada.

Requisição DELETE

curl https://toakiescola.com.br/api/v1/partners/school/26019466000122/classroom/b2c3d4e5-.../score/a1b2c3d4-... \
  -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/classroom/b2c3d4e5-.../score/a1b2c3d4-...', [
    '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/classroom/b2c3d4e5-.../score/a1b2c3d4-...', {
    method: 'DELETE',
    headers: {
        'X-Authorization': '{api_token}',
        'X-Partner':       '{partner_token}',
        'X-Client':        '{client_slug}',
    },
});

Resposta

{
  "success": true,
  "message": "Avaliação excluída."
}

{
  "success": false,
  "message": "Avaliação não encontrada."
}