ToAqui Escola

O modelo frequência

O modelo frequência representa um registro de presença de um aluno. Cada registro contém os dados da escola, do aluno e o timestamp do evento.

status string

Status do registro. Pode ser: OK, STUDENT_NOT_FOUND, ALREADY_CHECKED_IN, PAST_DATE_NOT_ALLOWED ou SERVICE_UNAVAILABLE.

school_cnpj string

CNPJ da escola onde o registro foi realizado.

enrollment_number string

Número de matrícula do aluno.

checked_in_at datetime

Data e hora da entrada no formato Y-m-d H:i:s.

checked_out_at datetime

Data e hora da saída no formato Y-m-d H:i:s.

Resposta de check-in

{
  "status": "OK",
  "school_cnpj": "26019466000122",
  "enrollment_number": "7.553",
  "checked_in_at": "2026-04-29 08:30:00"
}

GET /v1/attendance/student/verify

Verificar aluno

Consulta o status de acesso de um aluno antes de registrar uma frequência. Retorna se o aluno pode sair livremente (block: false) ou se precisa de verificação dupla (block: true).

Atributos obrigatórios (query string)

enrollment_number string obrigatório

Número de matrícula do aluno.

school_cnpj string obrigatório

CNPJ da escola (14 dígitos).

Códigos de resposta

200

Sucesso.

401

Autenticação inválida.

404

Recurso não encontrado.

Requisição GET

curl "https://toakiescola.com.br/api/v1/attendance/student/verify?enrollment_number=7.553&school_cnpj=26019466000122" \
  -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/attendance/student/verify', [
    'headers' => [
        'X-Authorization' => '{api_token}',
        'X-Partner'       => '{partner_token}',
        'X-Client'        => '{client_slug}',
    ],
    'query' => [
        'enrollment_number' => '7.553',
        'school_cnpj'       => '26019466000122',
    ],
]);
$data = json_decode($response->getBody(), true);

const params = new URLSearchParams({
    enrollment_number: '7.553',
    school_cnpj:       '26019466000122',
});
const response = await fetch(`https://toakiescola.com.br/api/v1/attendance/student/verify?${params}`, {
    headers: {
        'X-Authorization': '{api_token}',
        'X-Partner':       '{partner_token}',
        'X-Client':        '{client_slug}',
    },
});
const data = await response.json();

Resposta

{
  "success": true,
  "block": true,
  "message": "O aluno não está liberado para sair sem responsável."
}

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

{
  "message": "Recurso não encontrado."
}

Resposta

{
  "success": true,
  "block": false,
  "message": "O aluno está liberado para sair sem responsável."
}

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

{
  "message": "Recurso não encontrado."
}

POST /v1/attendance/student/biometric/check/in

Registrar entrada

Registra a entrada de um aluno na escola via dispositivo biométrico. O timestamp da entrada deve ser enviado no body da requisição.

Atributos obrigatórios (body JSON)

school_cnpj string obrigatório

CNPJ da escola (deve existir no sistema).

enrollment_number string obrigatório

Número de matrícula do aluno.

checked_in_at datetime obrigatório

Data e hora da entrada no formato Y-m-d H:i:s.

Códigos de resposta

200

Sucesso.

401

Autenticação inválida.

404

Recurso de referência não encontrado.

400

STUDENT_NOT_FOUND — Aluno não encontrado.

400

PAST_DATE_NOT_ALLOWED — Data retroativa não permitida.

400

ALREADY_CHECKED_IN — Aluno já registrou entrada hoje.

Requisição POST

curl https://toakiescola.com.br/api/v1/attendance/student/biometric/check/in \
  -H "Content-Type: application/json" \
  -H "X-Authorization: {api_token}" \
  -H "X-Partner: {partner_token}" \
  -H "X-Client: {client_slug}" \
  -d '{"school_cnpj": "26019466000122", "enrollment_number": "7.553", "checked_in_at": "2026-04-29 08:30:00"}'

use GuzzleHttp\Client;

$client = new Client();
$response = $client->post('https://toakiescola.com.br/api/v1/attendance/student/biometric/check/in', [
    'headers' => [
        'X-Authorization' => '{api_token}',
        'X-Partner'       => '{partner_token}',
        'X-Client'        => '{client_slug}',
    ],
    'json' => [
        'school_cnpj'       => '26019466000122',
        'enrollment_number' => '7.553',
        'checked_in_at'     => '2026-04-29 08:30:00',
    ],
]);

const response = await fetch('https://toakiescola.com.br/api/v1/attendance/student/biometric/check/in', {
    method: 'POST',
    headers: {
        'Content-Type':    'application/json',
        'X-Authorization': '{api_token}',
        'X-Partner':       '{partner_token}',
        'X-Client':        '{client_slug}',
    },
    body: JSON.stringify({
        school_cnpj:       '26019466000122',
        enrollment_number: '7.553',
        checked_in_at:     '2026-04-29 08:30:00',
    }),
});

Resposta 200

{
  "status": "OK",
  // dados do aluno
}

Resposta 400

{
  "status": "STUDENT_NOT_FOUND",
  "message": "Aluno não encontrado."
}

Resposta 400

{
  "status": "PAST_DATE_NOT_ALLOWED",
  "message": "Não é permitido registrar entrada com data retroativa."
}

Resposta 400

{
  "status": "ALREADY_CHECKED_IN",
  "message": "O aluno já efetivou sua entrada."
}

Resposta 401 Unauthorized

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

POST /v1/attendance/student/biometric/check/out

Registrar saída

Registra a saída de um aluno da escola via dispositivo biométrico.

Atributos obrigatórios (body JSON)

school_cnpj string obrigatório

CNPJ da escola.

enrollment_number string obrigatório

Número de matrícula do aluno.

checked_out_at datetime obrigatório

Data e hora da saída no formato Y-m-d H:i:s.

Códigos de resposta

200

Sucesso.

401

Autenticação inválida.

404

Recurso de referência não encontrado.

400

STUDENT_NOT_FOUND — Aluno não encontrado.

400

NOT_CHECKED_IN — Aluno ainda não registrou entrada hoje.

400

NO_RESPONSIBLE_WAITING — Nenhum responsável aguardando para buscar o aluno.

400

PAST_DATE_NOT_ALLOWED — Data retroativa não permitida.

400

ALREADY_CHECKED_OUT — Aluno já registrou saída hoje.

Requisição POST

curl https://toakiescola.com.br/api/v1/attendance/student/biometric/check/out \
  -H "Content-Type: application/json" \
  -H "X-Authorization: {api_token}" \
  -H "X-Partner: {partner_token}" \
  -H "X-Client: {client_slug}" \
  -d '{"school_cnpj": "26019466000122", "enrollment_number": "7.553", "checked_out_at": "2026-04-29 17:45:00"}'

use GuzzleHttp\Client;

$client = new Client();
$response = $client->post('https://toakiescola.com.br/api/v1/attendance/student/biometric/check/out', [
    'headers' => [
        'X-Authorization' => '{api_token}',
        'X-Partner'       => '{partner_token}',
        'X-Client'        => '{client_slug}',
    ],
    'json' => [
        'school_cnpj'       => '26019466000122',
        'enrollment_number' => '7.553',
        'checked_out_at'    => '2026-04-29 17:45:00',
    ],
]);

const response = await fetch('https://toakiescola.com.br/api/v1/attendance/student/biometric/check/out', {
    method: 'POST',
    headers: {
        'Content-Type':    'application/json',
        'X-Authorization': '{api_token}',
        'X-Partner':       '{partner_token}',
        'X-Client':        '{client_slug}',
    },
    body: JSON.stringify({
        school_cnpj:       '26019466000122',
        enrollment_number: '7.553',
        checked_out_at:    '2026-04-29 17:45:00',
    }),
});

Resposta 200

{
  "status": "OK",
  // dados do aluno
}

Resposta 400

{
  "status": "STUDENT_NOT_FOUND",
  "message": "Aluno não encontrado."
}

Resposta 400

{
  "status": "NOT_CHECKED_IN",
  "message": "O aluno ainda não entrou na escola."
}

Resposta 400

{
  "status": "NO_RESPONSIBLE_WAITING",
  "message": "O responsável do aluno ainda não está presente."
}

Resposta 400

{
  "status": "PAST_DATE_NOT_ALLOWED",
  "message": "Não é permitido registrar saída com data retroativa."
}

Resposta 400

{
  "status": "ALREADY_CHECKED_OUT",
  "message": "O aluno já efetivou sua saída."
}

Resposta 401 Unauthorized

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

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://toakiescola.com.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://toakiescola.com.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://toakiescola.com.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://toakiescola.com.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://toakiescola.com.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://toakiescola.com.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://toakiescola.com.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://toakiescola.com.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://toakiescola.com.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://toakiescola.com.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://toakiescola.com.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://toakiescola.com.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."
}

Frequências

O modelo frequência

Verificar aluno

Atributos obrigatórios (query string)

Códigos de resposta

Registrar entrada

Atributos obrigatórios (body JSON)

Códigos de resposta

Registrar saída

Atributos obrigatórios (body JSON)

Códigos de resposta

Lançamento de Frequência por Aula

Calendário da turma

Parâmetros de URL

Códigos de resposta

Aulas do dia

Parâmetro de query

Códigos de resposta

Dados da aula

Parâmetros de URL

Códigos de resposta

Salvar frequência

Atributos do body JSON

Códigos de resposta