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 (FOE) da turma, como nota máxima, recuperação paralela e casas decimais permitidas. Quando a FOE usa tipo de nota conceitual, a API também resolve e valida o conceito correspondente ao valor de score — veja o aviso abaixo.

Plano Gestão Escolar (ERP): os endpoints desta página respondem somente para clientes do plano Gestão Escolar (ERP), como no sistema web. Para clientes do plano simplificado, a resposta é 403 com "code": "ERP_REQUIRED".

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, sempre numérico independentemente do tipo de nota da FOE. Nulo quando a célula existe mas ainda não foi preenchida.

concept string | null

Conceito (ex: "A", "B") resolvido automaticamente a partir de score e dos concepts[] da FOE. Presente apenas quando a FOE da turma usa tipo de nota conceitual; ausente para FOEs numéricas.

created_at datetime

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

Tipo de nota conforme a FOE: o campo score é sempre um número decimal, respeitando os limites (min_score/max_score) e as casas decimais (decimal_places) definidos na Forma de Avaliação da turma. Quando a FOE usa tipo de nota conceitual, a API resolve automaticamente o conceito correspondente (ex: "A", "B") a partir dos intervalos (score_start/score_end) configurados em concepts[] e o retorna no campo concept — tanto ao listar quanto ao salvar uma nota. Ao salvar (POST /score), se a nota informada não corresponder a nenhum conceito configurado, a API rejeita com 422. Para consultar os conceitos configurados na FOE, veja Obter forma de avaliação.

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,
  "concept": "A",
  "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://lumenerp.app.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://lumenerp.app.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://lumenerp.app.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,
      "concept": "A"
    }
  ],
  "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).

Restrição de período: quando a escola utiliza o gerenciamento de períodos, só é possível lançar notas no período que estiver aberto. Tentativas de salvar notas em um período fechado ou não iniciado retornam 422. O período aberto é configurado pela gestão escolar e apenas um período pode estar aberto por vez.

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 (sempre numérico, mesmo em FOEs conceituais). 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

201

Avaliação criada com sucesso.

200

Avaliação atualizada com sucesso (já existia um registro com os mesmos critérios).

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, nota fora de qualquer conceito configurado) ou período fechado/não iniciado.

Requisição POST

curl https://lumenerp.app.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://lumenerp.app.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://lumenerp.app.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,
    "concept": "A"
  }
}

{
  "success": false,
  "message": "A nota informada não corresponde a nenhum conceito configurado na forma de avaliação."
}

{
  "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://lumenerp.app.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://lumenerp.app.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://lumenerp.app.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."
}