Pular para conteúdo

Empregados

O que é

Empregado é o cadastro do colaborador dentro da Pontotel — concentra todos os dados necessários para gestão de ponto, folha, organização e parametrizações de rotina (jornada/escala).

É normalmente a entidade central do domínio de RH em integrações.

Por que isso importa numa integração

  • Sincronização de cadastro: admissão, alterações e desligamento refletem o ERP/folha
  • Base para outros vínculos: usuários, jornadas, escalas, férias e afastamentos dependem do empregado
  • Chave de integração: o codigo (matrícula) garante o mapeamento entre sistemas ao longo do tempo

Defina a chave de integração antes do início

Escolha um campo estável como chave (ex.: codigo ou cpf) e mantenha esse padrão durante toda a integração. Evita duplicatas e facilita rastreabilidade.

Regras de Negócio

  • CPF deve ser único por empregador
  • Matrícula (codigo) deve ser única por empregador (quando informada)
  • O empregado só pode ser vinculado a um empregador ativo
  • Desligamento deve ser feito via is_active: false + data_demissao, não via DELETE
  • Empregado inativo não pode registrar novas marcações de ponto

Relacionamentos

graph TD
    EMP["👤 Empregado"]
    EMP --> B["🏢 Empregador"]
    EMP --> C["📍 Local de Trabalho"]
    EMP --> D["📅 Escala"]
    EMP --> E["🔑 Usuário associado"]
    EMP --> F["🕐 Marcações de Ponto"]
    EMP --> G["🏖️ Férias"]
    EMP --> H["🏥 Afastamentos"]

Operações Disponíveis

Método Endpoint Descrição
GET /empregados/ Listar empregados
POST /empregados/ Criar empregado
GET /empregados/{id}/ Obter empregado
PUT /empregados/{id}/ Atualizar (completo)
PATCH /empregados/{id}/ Atualizar (parcial)

Campos

Campo Tipo Obrigatório Descrição
id integer — ID interno
empregador_id integer ✅ ID do empregador
local_trabalho_id integer Recomendado Local de alocação
cpf string ✅ CPF do colaborador
codigo string Recomendado Matrícula / código de integração (use o código do ERP)
nome string ✅ Nome completo
email string Recomendado E-mail (usado para criar usuário automaticamente)
data_admissao date ✅ Data de admissão
data_demissao date — Data de demissão
escala_id integer — Escala de trabalho
is_active boolean — Status (padrão: true)
created_at datetime — Data de criação
updated_at datetime — Última atualização

Exemplo: Criar Empregado

Requisição

HTTP
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
POST /pontotel/api/v4/empregados/
Authorization: Bearer {token}
Content-Type: application/json

{
  "empregador_id": 42,
  "local_trabalho_id": 10,
  "cpf": "123.456.789-00",
  "codigo": "EMP-001",
  "nome": "João Silva",
  "email": "joao.silva@empresa.com",
  "data_admissao": "2025-01-15",
  "escala_id": 200
}

Resposta (201 Created)

JSON
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
{
  "id": 500,
  "empregador_id": 42,
  "local_trabalho_id": 10,
  "cpf": "123.456.789-00",
  "codigo": "EMP-001",
  "nome": "João Silva",
  "email": "joao.silva@empresa.com",
  "data_admissao": "2025-01-15",
  "data_demissao": null,
  "is_active": true,
  "created_at": "2025-01-31T10:00:00-03:00"
}

Exemplo: Desligar Empregado

HTTP
1
2
3
4
5
6
7
8
PATCH /pontotel/api/v4/empregados/500/
Authorization: Bearer {token}
Content-Type: application/json

{
  "is_active": false,
  "data_demissao": "2025-12-31"
}

Filtros Disponíveis

HTTP
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
# Por empregador
GET /empregados/?empregador_id=42

# Apenas ativos
GET /empregados/?is_active=true

# Por CPF (sem pontuação)
GET /empregados/?cpf=12345678900

# Por código de integração
GET /empregados/?codigo=EMP-001

# Admitidos em 2025
GET /empregados/?data_admissao_gte=2025-01-01&data_admissao_lte=2025-12-31

Erros Comuns

Erro Causa Solução
CPF duplicado Criar dois empregados com o mesmo CPF no mesmo empregador Busque por CPF antes de criar
Empregado duplicado Falta de chave única estável Defina e use codigo como chave de integração
Atualização de escala sem jornada Escala referencia jornadas não cadastradas Cadastre jornadas antes das escalas
Marcações negadas após desligamento Empregado inativo tentando registrar ponto Confirme is_active antes de autorizar