Skip to content

Employer Synchronization

Objective

This guide describes how to synchronize employers (enterprises/CNPJs) of your system with Pontotel.

What's an Employer?

An employer represents a company (CNPJ) on the Pontotel platform. The entire hierarchy of employees, locations and groups is linked to an employer.

Synchronization Flow

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

Step 1: List Existing Employers

Before creating, check if the employer already exists at Pontotel using CNPJ:

Python
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
import requests

def buscar_empregador_por_cnpj(cnpj: str, headers: dict) -> dict | None:
    """Retorna empregador existente ou None"""
    response = requests.get(
        "https://apis.pontotel.com.br/pontotel/api/v4/empregadores/",
        params={"cnpj": cnpj},
        headers=headers
    )
    response.raise_for_status()
    data = response.json()

    if data["count"] > 0:
        return data["results"][0]
    return None

Step 2: Create Employer

If not, create:

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

# Payload de criação
payload = {
    "cnpj": "12.345.678/0001-99",
    "razao_social": "Example Company LTDA",
    "nome_fantasia": "Example Company",
    "is_active": True
}

empregador = criar_empregador(payload, headers)
print(f"Empregador criado: ID={empregador['id']}")

Step 3: Refresh Employer

If it already exists and data has changed:

Python
1
2
3
4
5
6
7
8
9
def atualizar_empregador(id: int, dados: dict, headers: dict) -> dict:
    """Atualização parcial (PATCH)"""
    response = requests.patch(
        f"https://apis.pontotel.com.br/pontotel/api/v4/empregadores/{id}/",
        json=dados,
        headers=headers
    )
    response.raise_for_status()
    return response.json()

Step 4: Full Sync Script

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
30
31
32
33
34
35
36
37
38
def sincronizar_empregadores(lista_cnpjs: list[dict], auth) -> dict:
    """
    Sincroniza lista de empregadores com a Pontotel.

    lista_cnpjs: [{"cnpj": "...", "razao_social": "...", ...}]
    """
    resultado = {"criados": 0, "atualizados": 0, "ignorados": 0, "erros": []}
    headers = auth.get_headers()

    for empresa in lista_cnpjs:
        try:
            cnpj = empresa["cnpj"]
            existente = buscar_empregador_por_cnpj(cnpj, headers)

            if not existente:
                criar_empregador(empresa, headers)
                resultado["criados"] += 1
                print(f"✅ Criado: {cnpj}")

            elif dados_diferentes(existente, empresa):
                atualizar_empregador(existente["id"], empresa, headers)
                resultado["atualizados"] += 1
                print(f"🔄 Atualizado: {cnpj}")

            else:
                resultado["ignorados"] += 1
                print(f"⏭ Ignorado: {cnpj}")

        except Exception as e:
            resultado["erros"].append({"cnpj": empresa.get("cnpj"), "erro": str(e)})
            print(f"❌ Erro em {empresa.get('cnpj')}: {e}")

    return resultado

def dados_diferentes(existente: dict, novo: dict) -> bool:
    """Compara campos relevantes"""
    campos = ["razao_social", "nome_fantasia", "is_active"]
    return any(existente.get(c) != novo.get(c) for c in campos)

Business Rules

Important Rules

  • O CNPJ is unique inside the Pontatel platform
  • An employer inactive does not accept new employees
  • A social reason must match the CNPJ registered in the IRS

Next Steps