Frequências

Os endpoints de frequência permitem registrar a entrada e saída de alunos via dispositivos biométricos ou de leitura de QR Code integrados ao sistema To Aqui Escola. Use também para verificar o status atual de um aluno antes de processar o registro.

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