Pular para conteúdo

Sincronização de Empregados

Objetivo

Este guia descreve como sincronizar empregados (funcionários) do seu sistema de RH com a Pontotel.

Pré-requisito

Antes de sincronizar empregados, você deve ter os Empregadores já cadastrados. Veja: Sincronização de Empregadores →

Fluxo de Sincronização

flowchart LR
    A[Seu Sistema RH] -->|Busca empregados| B[Seu Banco de Dados]
    B -->|Para cada funcionário| C{Existe na Pontotel?}
    C -->|Não| D[POST /empregados/]
    C -->|Sim| E{Dados mudaram?}
    E -->|Sim| F[PATCH /empregados/id/]
    E -->|Não| G[Ignorar]
    D --> H[Armazenar ID Pontotel]

Passo 1: Buscar Empregado por CPF ou Matrícula

Python
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
def buscar_empregado(cpf: str, empregador_id: int, headers: dict) -> dict | None:
    """Busca empregado por CPF dentro de um empregador"""
    response = requests.get(
        "https://apis.pontotel.com.br/pontotel/api/v4/empregados/",
        params={"cpf": cpf, "empregador_id": empregador_id},
        headers=headers
    )
    response.raise_for_status()
    data = response.json()
    return data["results"][0] if data["count"] > 0 else None

Passo 2: Criar Empregado

Python
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
def criar_empregado(dados: dict, headers: dict) -> dict:
    response = requests.post(
        "https://apis.pontotel.com.br/pontotel/api/v4/empregados/",
        json=dados,
        headers=headers
    )
    response.raise_for_status()
    return response.json()

# Payload completo de criação
payload = {
    "empregador_id": 5,
    "cpf": "123.456.789-00",
    "matricula": "EMP-001",
    "nome": "João Silva",
    "data_admissao": "2025-01-15",
    "email": "joao.silva@empresa.com",
    "is_active": True
}

Passo 3: Sincronização Incremental

Na sincronização incremental, enviamos apenas os registros que foram modificados desde a última sincronização:

Python
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
from datetime import datetime, timedelta

def sincronizar_incremental(data_ultima_sync: datetime, auth) -> dict:
    """Sincroniza apenas empregados modificados desde a última sync"""
    headers = auth.get_headers()
    resultado = {"criados": 0, "atualizados": 0, "erros": []}

    # 1. Buscar empregados modificados no seu sistema
    empregados_modificados = seu_sistema.buscar_modificados_desde(data_ultima_sync)

    for func in empregados_modificados:
        try:
            existente = buscar_empregado(func["cpf"], func["empregador_id"], headers)

            if not existente:
                criar_empregado(func, headers)
                resultado["criados"] += 1
            else:
                requests.patch(
                    f"https://apis.pontotel.com.br/pontotel/api/v4/empregados/{existente['id']}/",
                    json=func,
                    headers=headers
                ).raise_for_status()
                resultado["atualizados"] += 1

        except Exception as e:
            resultado["erros"].append({"cpf": func.get("cpf"), "erro": str(e)})

    return resultado

Tratamento de Desligamentos

Quando um funcionário é desligado, não delete o empregado — desative-o:

Python
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
def desligar_empregado(id: int, data_demissao: str, headers: dict):
    """Desativa empregado na Pontotel"""
    requests.patch(
        f"https://apis.pontotel.com.br/pontotel/api/v4/empregados/{id}/",
        json={
            "is_active": False,
            "data_demissao": data_demissao
        },
        headers=headers
    ).raise_for_status()

Não delete empregados

Deletar um empregado apaga históricas de ponto e férias. Use sempre is_active: false para desativação.

Regras de Negócio

Regra Descrição
CPF único por empregador Dois empregados não podem ter o mesmo CPF no mesmo empregador
Matrícula opcional Se não informada, a API gerará automaticamente
Empregador obrigatório empregador_id é obrigatório na criação
Data de admissão Deve ser uma data válida no passado ou presente

Campos Obrigatórios na Criação

Campo Tipo Descrição
empregador_id integer ID do empregador
cpf string CPF do funcionário
nome string Nome completo
data_admissao date Data de admissão

Próximos Passos