Pular para conteúdo

Empregadores

O que é

Empregador representa a empresa empregadora (pessoa jurídica ou física) dentro da plataforma Pontotel. É identificado por CNPJ ou CPF e funciona como a entidade raiz da hierarquia — todos os locais, grupos e empregados pertencem a um empregador.

Por que isso importa numa integração

Em cenários com múltiplos CNPJs/unidades:

  • Separa dados por empregador, refletindo a estrutura jurídica do grupo econômico
  • Facilita consistência com sistemas de folha (códigos do empregador espelhando o ERP)
  • Base para relatórios, documentos e exportações (ex.: espelho de ponto por empresa)

Chave de integração

Defina o código do empregador como chave de integração e mantenha-o estável ao longo do tempo — especialmente em clientes multi-CNPJ.

Regras de Negócio

  • O CNPJ (ou CPF) deve ser único na plataforma
  • A Razão Social é obrigatória
  • Um empregador inativo não pode receber novos empregados
  • Não troque o CNPJ/CPF de um empregador existente — crie um novo se a entidade jurídica mudar

Campos

Campo Tipo Obrigatório Descrição
id integer — ID interno (auto)
codigo string Recomendado Código de integração (use o código do ERP/folha)
cnpj string ✅ (ou CPF) CNPJ da empresa
cpf string ✅ (ou CNPJ) CPF (para MEI/empregador pessoa física)
razao_social string ✅ Razão social
nome_fantasia string — Nome fantasia
logo string — URL/base64 da logo (para documentos)
is_active boolean — Status (padrão: true)
created_at datetime — Data de criação
updated_at datetime — Última atualização

Operações Disponíveis

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

Exemplo: Criar Empregador

Requisição

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

{
  "codigo": "EMP-001",
  "cnpj": "12.345.678/0001-99",
  "razao_social": "Empresa Exemplo LTDA",
  "nome_fantasia": "Empresa Exemplo",
  "is_active": true
}

Resposta (201 Created)

JSON
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
{
  "id": 42,
  "codigo": "EMP-001",
  "cnpj": "12.345.678/0001-99",
  "razao_social": "Empresa Exemplo LTDA",
  "nome_fantasia": "Empresa Exemplo",
  "is_active": true,
  "created_at": "2025-01-31T10:00:00-03:00",
  "updated_at": "2025-01-31T10:00:00-03:00"
}

Erros Comuns

Erro Causa Solução
CNPJ duplicado Tentativa de criar dois empregadores com o mesmo CNPJ Busque pelo CNPJ antes de criar
Reutilizar código Mesmo código em empregadores distintos Garanta unicidade do codigo
Trocar CNPJ Alterar CNPJ de empregador existente Crie um novo empregador com o CNPJ correto