To Aqui - Sandbox

O modelo funcionário

id uuid

Identificador do funcionário.

registration_number string|null

Matrícula funcional.

name / social_name string

Nome e nome social.

cpf string

CPF (somente números).

position string

Cargo.

status string

active, on_leave, vacation ou terminated.

user_id uuid|null

Usuário do funcionário na plataforma, quando tem acesso.

contract object|null

Vínculo vigente: tipo (clt / pj), admissão e carga horária semanal.

O modelo funcionário

{
  "id": "019f6967-5f7a-73fa-9b01-8c2d1b6a631f",
  "registration_number": "0001",
  "name": "Carlos Almeida",
  "social_name": null,
  "cpf": "11144477735",
  "position": "teacher",
  "position_label": "Professor(a)",
  "status": "active",
  "email": "carlos.almeida@escola.com.br",
  "phone": null,
  "mobile_phone": "(21) 97777-6666",
  "user_id": "019e6e4b-3235-727f-b423-89694ac61dea",
  "contract": {
    "type": "clt",
    "admission_date": "2024-02-01",
    "weekly_hours": 40,
    "position_description": "Professor de Matemática"
  },
  "created_at": "2024-01-20T10:00:00-03:00",
  "updated_at": "2026-07-19T09:00:00-03:00"
}

GET /v1/partners/school/{cnpj}/hr/employees/all

Listar funcionários

Funcionários vinculados à escola, em ordem alfabética. Paginado (25 por página).

Parâmetros de rota

cnpj string obrigatório

CNPJ da escola (14 dígitos, sem formatação).

Filtros (query string)

search string opcional

Parte do nome ou nome social, matrícula ou CPF.

status string opcional

active, on_leave, vacation ou terminated.

position string opcional

Cargo (ex.: teacher, coordinator, secretary, nurse, merendeira).

Códigos de resposta

200

Sucesso.

401

Credenciais inválidas (X-Partner, X-Client ou X-Authorization).

403

Cliente fora do plano Gestão Escolar (ERP_REQUIRED) ou módulo exclusivo de escolas privadas (PRIVATE_CLIENT_REQUIRED).

404

Escola ou recurso não encontrado.

422

Parâmetros inválidos — veja errors.

Requisição GET

GET /v1/partners/school/{cnpj}/hr/employees/all

curl https://toakiescola.com.br/api/v1/partners/school/{cnpj}/hr/employees/all \
  -H "X-Authorization: {api_token}" \
  -H "X-Partner: {partner_token}" \
  -H "X-Client: {client_slug}"

$response = $client->get('https://toakiescola.com.br/api/v1/partners/school/{cnpj}/hr/employees/all', [
    'headers' => $headers, // X-Authorization, X-Partner, X-Client
]);

const res = await fetch('https://toakiescola.com.br/api/v1/partners/school/{cnpj}/hr/employees/all', {
    method: 'GET',
    headers: { /* X-Authorization, X-Partner, X-Client */ 'Content-Type': 'application/json' },
});

Resposta

{
  "data": [
    {
      "id": "019f6967-5f7a-73fa-9b01-8c2d1b6a631f",
      "registration_number": "0001",
      "name": "Carlos Almeida",
      "social_name": null,
      "cpf": "11144477735",
      "position": "teacher",
      "position_label": "Professor(a)",
      "status": "active",
      "email": "carlos.almeida@escola.com.br",
      "phone": null,
      "mobile_phone": "(21) 97777-6666",
      "user_id": "019e6e4b-3235-727f-b423-89694ac61dea",
      "contract": {
        "type": "clt",
        "admission_date": "2024-02-01",
        "weekly_hours": 40,
        "position_description": "Professor de Matemática"
      },
      "created_at": "2024-01-20T10:00:00-03:00",
      "updated_at": "2026-07-19T09:00:00-03:00"
    }
  ],
  "links": { /* first, prev, next */ },
  "meta": { "current_page": 1, "per_page": 25 }
}

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

GET /v1/partners/school/{cnpj}/hr/employee/{id}

Obter funcionário

Um funcionário da escola.

Parâmetros de rota

cnpj string obrigatório

CNPJ da escola (14 dígitos, sem formatação).

id uuid obrigatório

UUID do funcionário.

Códigos de resposta

200

Sucesso.

401

Credenciais inválidas (X-Partner, X-Client ou X-Authorization).

403

Cliente fora do plano Gestão Escolar (ERP_REQUIRED) ou módulo exclusivo de escolas privadas (PRIVATE_CLIENT_REQUIRED).

404

Escola ou recurso não encontrado.

Requisição GET

GET /v1/partners/school/{cnpj}/hr/employee/{id}

curl https://toakiescola.com.br/api/v1/partners/school/{cnpj}/hr/employee/{id} \
  -H "X-Authorization: {api_token}" \
  -H "X-Partner: {partner_token}" \
  -H "X-Client: {client_slug}"

$response = $client->get('https://toakiescola.com.br/api/v1/partners/school/{cnpj}/hr/employee/{id}', [
    'headers' => $headers, // X-Authorization, X-Partner, X-Client
]);

const res = await fetch('https://toakiescola.com.br/api/v1/partners/school/{cnpj}/hr/employee/{id}', {
    method: 'GET',
    headers: { /* X-Authorization, X-Partner, X-Client */ 'Content-Type': 'application/json' },
});

Resposta

{
  "data": {
    "id": "019f6967-5f7a-73fa-9b01-8c2d1b6a631f",
    "registration_number": "0001",
    "name": "Carlos Almeida",
    "social_name": null,
    "cpf": "11144477735",
    "position": "teacher",
    "position_label": "Professor(a)",
    "status": "active",
    "email": "carlos.almeida@escola.com.br",
    "phone": null,
    "mobile_phone": "(21) 97777-6666",
    "user_id": "019e6e4b-3235-727f-b423-89694ac61dea",
    "contract": {
      "type": "clt",
      "admission_date": "2024-02-01",
      "weekly_hours": 40,
      "position_description": "Professor de Matemática"
    },
    "created_at": "2024-01-20T10:00:00-03:00",
    "updated_at": "2026-07-19T09:00:00-03:00"
  }
}

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

POST /v1/hr/timeclock/punch/{token}

Controle de Ponto — registro de marcação

Endpoint para relógios de ponto Control iD (REP / iDFace) enviarem cada marcação em tempo real. Não usa os cabeçalhos de parceiro: cada equipamento cadastrado em RH › Controle de Ponto recebe um token próprio, informado no caminho da URL ou no cabeçalho X-Device-Token (alguns firmwares não permitem cabeçalhos personalizados). Sem limite de requisições por minuto.

O corpo pode ser um evento único, uma lista, ou um lote em access_logs, values, punches ou records. Cada marcação precisa de um horário (event_time, timestamp, date_time, datetime ou time — Unix ou data/hora) e de algo que identifique o funcionário: CPF (cpf, user_cpf), PIS/PASEP (pis, user_pis) ou o código do usuário no equipamento (user_id) igual à matrícula funcional. O NSR (nsr, event_id, log_id) evita marcações duplicadas.

Marcações que não puderem ser usadas (sem horário reconhecível ou de funcionário não encontrado) são contadas em ignored e a resposta continua 200, para que o equipamento nunca entre em repetição infinita. O espelho de ponto do dia é recalculado automaticamente.

Códigos de resposta

200

Lote processado: received marcações gravadas, ignored descartadas.

401

Token ausente, desconhecido ou de um equipamento inativo.

Requisição POST

curl https://toakiescola.com.br/api/v1/hr/timeclock/punch/{token} \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"access_logs":[{"nsr":4812,"user_cpf":"11144477735","event_time":"2026-10-02 07:58:12"}]}'

$client->post('https://toakiescola.com.br/api/v1/hr/timeclock/punch', [
    'headers' => ['X-Device-Token' => '{token}'],
    'json' => ['access_logs' => [['nsr' => 4812, 'user_cpf' => '11144477735', 'event_time' => '2026-10-02 07:58:12']]],
]);

await fetch('https://toakiescola.com.br/api/v1/hr/timeclock/punch/{token}', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ access_logs: [{ nsr: 4812, user_cpf: '11144477735', event_time: '2026-10-02 07:58:12' }] }),
});

Resposta

{
  "received": 1,
  "ignored": 0
}

{
  "message": "Equipamento não autorizado."
}

Recursos Humanos

O modelo funcionário

Listar funcionários

Parâmetros de rota

Filtros (query string)

Códigos de resposta

Obter funcionário

Parâmetros de rota

Códigos de resposta

Controle de Ponto — registro de marcação

Códigos de resposta