Frequências

Os endpoints de frequência permitem consultar e registrar a frequência dos alunos em cada aula de uma turma. A entrada e a saída na portaria são registradas pelos equipamentos faciais Control iD conectados diretamente ao Lumen; para acompanhá-las, assine os webhooks attendance.check_in e attendance.check_out.

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".

Lançamento de Frequência por Aula

Endpoints para consultar e registrar a frequência de alunos em aulas individuais de uma turma, seguindo o fluxo: calendário → aulas do dia → dados da aula → salvar.

GET /v1/partners/school/{cnpj}/classroom/{classroom_id}/attendance/calendar

Calendário da turma

Retorna todos os dias do ano letivo ativo da turma com o status agregado das aulas de cada dia. Use este endpoint como ponto de entrada para exibir uma visão mensal ou anual da frequência.

Parâmetros de URL

cnpj string obrigatório

CNPJ da escola (apenas dígitos).

classroom_id uuid obrigatório

UUID da turma.

Códigos de resposta

200

Sucesso.

401

Autenticação inválida.

404

Turma não encontrada.

Requisição GET

curl "https://lumenerp.app.br/api/v1/partners/school/26019466000122/classroom/{classroom_id}/attendance/calendar" \
  -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/{classroom_id}/attendance/calendar',
    ['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/{classroom_id}/attendance/calendar',
    { headers: {
        'X-Authorization': '{api_token}',
        'X-Partner':       '{partner_token}',
        'X-Client':        '{client_slug}',
    } }
);
const data = await response.json();

Resposta

{
  "school_year_id": "uuid",
  "days": [
    {
      "date": "2025-04-07",
      "type": "SCHOOL_DAY",
      "name": null,
      "attendance_status": "done",
      "lessons": {
        "total": 4,
        "done": 4,
        "pending": 0,
        "denied": 0
      }
    }
  ]
}

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

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

O campo attendance_status pode ser done, partial, pending, denied ou none.

GET /v1/partners/school/{cnpj}/classroom/{classroom_id}/attendance/day

Aulas do dia

Retorna a lista de aulas de uma data específica para a turma, cada uma com seu respectivo status de frequência. Use após selecionar um dia no calendário.

Parâmetro de query

date string obrigatório

Data no formato Y-m-d (ex: 2025-04-07).

Códigos de resposta

200

Sucesso.

401

Autenticação inválida.

404

Turma não encontrada.

422

Data inválida ou ausente.

Requisição GET

curl "https://lumenerp.app.br/api/v1/partners/school/26019466000122/classroom/{classroom_id}/attendance/day?date=2025-04-07" \
  -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/{classroom_id}/attendance/day',
    [
        'headers' => [
            'X-Authorization' => '{api_token}',
            'X-Partner'       => '{partner_token}',
            'X-Client'        => '{client_slug}',
        ],
        'query' => ['date' => '2025-04-07'],
    ]
);

const response = await fetch(
    'https://lumenerp.app.br/api/v1/partners/school/26019466000122/classroom/{classroom_id}/attendance/day?date=2025-04-07',
    { headers: {
        'X-Authorization': '{api_token}',
        'X-Partner':       '{partner_token}',
        'X-Client':        '{client_slug}',
    } }
);
const data = await response.json();

Resposta

{
  "date": "2025-04-07",
  "day_type": "SCHOOL_DAY",
  "is_past": true,
  "lessons": [
    {
      "id": "uuid",
      "position": 0,
      "start_time": "07:30",
      "subject_name": "Matemática",
      "teacher_name": "João Silva",
      "status": "DONE",
      "attendance_status": "done"
    }
  ]
}

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

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

{
  "message": "Data inválida ou ausente."
}

GET /v1/partners/school/{cnpj}/classroom/{classroom_id}/attendance/lesson/{lesson_id}

Dados da aula

Retorna o formulário de frequência para uma aula específica: lista de alunos matriculados na turma com os valores já registrados (se houver), além de metadados como se a aula está no passado e se há uma solicitação de aprovação pendente.

Parâmetros de URL

lesson_id uuid obrigatório

UUID da aula, obtido via endpoint de aulas do dia.

Códigos de resposta

200

Sucesso.

401

Autenticação inválida.

404

Turma ou aula não encontrada.

Requisição GET

curl "https://lumenerp.app.br/api/v1/partners/school/{cnpj}/classroom/{classroom_id}/attendance/lesson/{lesson_id}" \
  -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/{cnpj}/classroom/{classroom_id}/attendance/lesson/{lesson_id}',
    ['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/{cnpj}/classroom/{classroom_id}/attendance/lesson/{lesson_id}',
    { headers: {
        'X-Authorization': '{api_token}',
        'X-Partner':       '{partner_token}',
        'X-Client':        '{client_slug}',
    } }
);
const data = await response.json();

Resposta

{
  "lesson": {
    "id": "uuid",
    "date": "2025-04-07",
    "position": 0,
    "start_time": "07:30",
    "subject_name": "Matemática",
    "teacher_name": "João Silva",
    "status": "DONE"
  },
  "students": [
    {
      "id": "uuid",
      "name": "Ana Lima",
      "attendance": true,
      "behavior": "LIKE",
      "behavior_description": null
    }
  ],
  "has_done_attendance": true,
  "is_past": true,
  "pending_authorization": null,
  "last_denied_attempt": null
}

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

{
  "message": "Turma ou aula não encontrada."
}

O campo behavior aceita LIKE (bom desempenho), DISLIKE (baixo desempenho) ou null. Quando is_past é verdadeiro, o envio da frequência cria uma solicitação de aprovação em vez de salvar diretamente.

POST /v1/partners/school/{cnpj}/classroom/{classroom_id}/attendance/lesson/{lesson_id}

Salvar frequência

Registra a frequência dos alunos para uma aula. Se a aula for do dia atual ou futura, a frequência é salva imediatamente. Se a aula já passou, o lançamento é enviado para aprovação da direção — neste caso a resposta indica authorization_requested e inclui o authorization_id.

Atributos do body JSON

request_reason string opcional

Justificativa enviada à direção quando a aula é do passado.

students array obrigatório

Lista com a frequência de cada aluno. Deve incluir todos os alunos da turma.

students[].student_id uuid obrigatório

UUID do aluno.

students[].attendance boolean obrigatório

true = presente, false = ausente.

students[].behavior string | null opcional

Desempenho: LIKE, DISLIKE ou null.

students[].behavior_description string | null opcional

Obrigatório quando behavior é DISLIKE.

Códigos de resposta

200

Frequência salva ou solicitação de aprovação criada.

401

Autenticação inválida.

404

Turma ou aula não encontrada.

422

Dados inválidos (ex: behavior_description ausente para baixo desempenho).

Requisição POST

curl https://lumenerp.app.br/api/v1/partners/school/{cnpj}/classroom/{classroom_id}/attendance/lesson/{lesson_id} \
  -H "Content-Type: application/json" \
  -H "X-Authorization: {api_token}" \
  -H "X-Partner: {partner_token}" \
  -H "X-Client: {client_slug}" \
  -d '{"students": [{"student_id": "uuid", "attendance": true, "behavior": "LIKE", "behavior_description": null}]}'

use GuzzleHttp\Client;

$client = new Client();
$response = $client->post(
    'https://lumenerp.app.br/api/v1/partners/school/{cnpj}/classroom/{classroom_id}/attendance/lesson/{lesson_id}',
    [
        'headers' => [
            'X-Authorization' => '{api_token}',
            'X-Partner'       => '{partner_token}',
            'X-Client'        => '{client_slug}',
        ],
        'json' => [
            'students' => [[
                'student_id'           => 'uuid',
                'attendance'           => true,
                'behavior'             => 'LIKE',
                'behavior_description' => null,
            ]],
        ],
    ]
);

const response = await fetch(
    'https://lumenerp.app.br/api/v1/partners/school/{cnpj}/classroom/{classroom_id}/attendance/lesson/{lesson_id}',
    {
        method: 'POST',
        headers: {
            'Content-Type':    'application/json',
            'X-Authorization': '{api_token}',
            'X-Partner':       '{partner_token}',
            'X-Client':        '{client_slug}',
        },
        body: JSON.stringify({
            students: [{
                student_id:           'uuid',
                attendance:           true,
                behavior:             'LIKE',
                behavior_description: null,
            }],
        }),
    }
);

Resposta

{
  "mode": "saved",
  "message": "Frequência registrada com sucesso."
}

{
  "mode": "authorization_requested",
  "message": "Lançamento enviado para aprovação da direção.",
  "authorization_id": "uuid"
}

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

{
  "message": "Turma ou aula não encontrada."
}

{
  "message": "Dados inválidos ou aula futura."
}