Saltar a contenido

Sincronización de empleados

Objetivo

Esta guía describe cómo sincronizar empleados (funcionarios) de su sistema de RH con Pontotel.

Prerrequisito

Antes de sincronizar empleados, debes tener Empleadores ya registrados. Vea: Sincronización de empleados →

Flujo de sincronización

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]

Paso 1: Buscar Empleado por CPF o 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

Paso 2: Crear empleado

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": "Juan Pérez",
    "data_admissao": "2025-01-15",
    "email": "joao.silva@empresa.com",
    "is_active": True
}

Paso 3: Sincronización incremental

En la sincronización incremental, solo enviamos los registros que han sido modificados desde la última sincronización:

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

Tratamiento de Desconectamientos

Cuando un funcionario está desconectado, no delete el empleado — lo desaté:

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()

No delete empleados

Deletar a un empleado borra históricas de punto y vacaciones. Usá siempre is_active: false Para desactivar.

Reglas de negocio

Regla Descripción
CPF único por empleador Dos empleados no pueden tener el mismo CPF en el mismo empleador
Matrícula opcional Si no se informa, la API generará automáticamente
Empleador obligatorio empregador_id Es obligatorio en la creación
Fecha de admisión Debe ser una fecha válida en el pasado o presente

Campos Obligatorios en la Creación

Campo Tipo Descripción
empregador_id Integer ID del empleador
cpf string CPF del funcionario
nome string Nombre completo
data_admissao date Fecha de admisión

Siguientes pasos