Skip to content

Employers

What is it?

Employer represents the employer (legal or physical person) within the Pontotel platform. It is identified by CNPJ or CPF and works as the root entity the hierarchy — all places, groups and employees belong to an employer.

Why It Matters In Integration

In scenarios with multiple CNPJs/units:

  • Separates data by employer, reflecting the legal structure of the economic group
  • Facilitates consistency with leaf systems (employer codes mirroring ERP)
  • Base for reports, documents and exports (e.g. point mirror per company)

Integration key

Set employer code as integration key and keep it stable over time — especially in multi-CNPJ customers.

Business Rules

  • The CNPJ (or CPF) shall be unique on the platform
  • Social Reason Is Mandatory
  • An inactive employer cannot receive new employees
  • Do not exchange CNPJ/CPF from an existing employer — create a new one if the legal entity changes

Fields

Field Type Required Description
id integer — Internal ID (auto)
codigo string Recommended Integration code (use ERP/sheet code)
cnpj string (or CPF) Company CNPJ
cpf string (or CNPJ) CPF (for MEI/person employee)
razao_social string Social Reason
nome_fantasia string — Invented name
logo string — Logo URL/base64 (for documents)
is_active boolean — Status (default: true)
created_at datetime — Date of creation
updated_at datetime — Last updated

Available Operations

Method Endpoint Description
GET /empregadores/ List Employers
POST /empregadores/ Create Employer
GET /empregadores/{id}/ Get Employer
PUT /empregadores/{id}/ Update (complete)
PATCH /empregadores/{id}/ Update (partial)

Example: Create Employer

Request

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": "Example Company LTDA",
  "nome_fantasia": "Example Company",
  "is_active": true
}

Response (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": "Example Company LTDA",
  "nome_fantasia": "Example Company",
  "is_active": true,
  "created_at": "2025-01-31T10:00:00-03:00",
  "updated_at": "2025-01-31T10:00:00-03:00"
}

Common Errors

Error Cause Solution
Duplicate CNPJ Attempt to create two employers with the same CNPJ Search for CNPJ before creating
Reuse code Same code in different employers Ensure uniqueness of codigo
Swap CNPJ Change existing employer CNPJ Create a new employer with the right CNPJ