Skip to content

Employees

What is it?

Employee is the employee register within Pontotel — concentrates all the necessary data for point, sheet, organization and routine parameterizations (journada/scale).

It's usually the central entity HR domain in integrations.

Why It Matters In Integration

  • Register Synchronization: admission, changes and shutdown reflect the ERP/sheet
  • Basis for other links: users, journeys, scales, holidays and departures depend on the employee
  • Integration key: o codigo (sign) ensures mapping between systems over time

Set integration key before start

Choose a stable field as key (e.g.: codigo or cpf) and maintain this pattern throughout integration. Avoid duplicates and facilitate traceability.

Business Rules

  • CPF should be unique per employer
  • Registration (codigo) must be unique per employer (when informed)
  • The employee can only be linked to an active employer
  • Shutdown must be done via is_active: false + data_demissao, did not see DELETE
  • Inactive employee cannot register new point markings

Relationships

graph TD
    EMP["👤 Empregado"]
    EMP --> B["🏢 Empregador"]
    EMP --> C["📍 Local de Trabalho"]
    EMP --> D["📅 Escala"]
    EMP --> E["🔑 Usuário associado"]
    EMP --> F["🕐 Marcações de Ponto"]
    EMP --> G["🏖️ Férias"]
    EMP --> H["🏥 Afastamentos"]

Available Operations

Method Endpoint Description
GET /empregados/ List employees
POST /empregados/ Create Employee
GET /empregados/{id}/ Get Employee
PUT /empregados/{id}/ Update (complete)
PATCH /empregados/{id}/ Update (partial)

Fields

Field Type Required Description
id integer — Internal ID
empregador_id integer Employer ID
local_trabalho_id integer Recommended Place of allocation
cpf string Employee's number
codigo string Recommended Registration / integration code (use ERP code)
nome string Full name
email string Recommended Email (used to create user automatically)
data_admissao date Date of admission
data_demissao date — Date of resignation
escala_id integer — Workscale
is_active boolean — Status (default: true)
created_at datetime — Date of creation
updated_at datetime — Last updated

Example: Create Employee

Request

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

{
  "empregador_id": 42,
  "local_trabalho_id": 10,
  "cpf": "123.456.789-00",
  "codigo": "EMP-001",
  "nome": "John Smith",
  "email": "joao.silva@empresa.com",
  "data_admissao": "2025-01-15",
  "escala_id": 200
}

Response (201 Created)

JSON
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
{
  "id": 500,
  "empregador_id": 42,
  "local_trabalho_id": 10,
  "cpf": "123.456.789-00",
  "codigo": "EMP-001",
  "nome": "John Smith",
  "email": "joao.silva@empresa.com",
  "data_admissao": "2025-01-15",
  "data_demissao": null,
  "is_active": true,
  "created_at": "2025-01-31T10:00:00-03:00"
}

Example: Disconnect Employee

HTTP
1
2
3
4
5
6
7
8
PATCH /pontotel/api/v4/empregados/500/
Authorization: Bearer {token}
Content-Type: application/json

{
  "is_active": false,
  "data_demissao": "2025-12-31"
}

Available Filters

HTTP
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
# Por empregador
GET /empregados/?empregador_id=42

# Apenas ativos
GET /empregados/?is_active=true

# Por CPF (sem pontuação)
GET /empregados/?cpf=12345678900

# Por código de integração
GET /empregados/?codigo=EMP-001

# Admitidos em 2025
GET /empregados/?data_admissao_gte=2025-01-01&data_admissao_lte=2025-12-31

Common Errors

Error Cause Solution
Duplicate CPF Create two employees with the same number in the same employer Search for CPF before creating
Duplicate employee Missing stable single key Set and use codigo as integration key
Timeless Scale Update Scale reference unregistered journeys Register journeys before scales
Marks denied after shutdown Inactive employee trying to register point Confirm is_active before authorising