Data Model¶

Overview¶

The Pontotel API organizes your data into hierarchical and interdependent entities. Understanding this model is essential to planning consistent integration.

Entities Graph¶

graph TD
    EMPLOYER["🏢 Empregador"]
    LOCAL["📍 Local de Trabalho"]
    GRUPO["📁 Grupo"]
    JORNADA["⏰ Jornada"]
    ESCALA["📅 Escala"]
    EMP["👤 Empregado"]
    USR["🔑 Usuário"]
    FERIAS["🏖️ Férias"]
    AFASTA["🏥 Afastamento"]
    MARCA["🕐 Marcação de Ponto"]

    EMPLOYER --> LOCAL
    EMPLOYER --> GRUPO
    GRUPO --> LOCAL
    LOCAL --> EMP
    JORNADA --> ESCALA
    ESCALA --> EMP
    EMP --> USR
    EMP --> FERIAS
    EMP --> AFASTA
    EMP --> MARCA

Description of Entity¶

Employer¶

It represents the employer (CNPJ/CPF). It is the organizational root — all locations, groups and employees belong to an employer.

Roll into integration: Base to separate data into multi-CNPJ scenarios. The "employee code" shall be aligned with the ERP/sheet.

Place of Work¶

Organizational unit where the collaborator is allocated. It doesn't have to be a physical location. — may represent departments, teams or subsidiaries.

Roll into integration: Sets region/time zone which impacts holidays and timestamps of markings. It's a major filter in reports.

Group¶

Cluster mechanism for organizing workplaces (and/or users), creating operational "views" for reports and filters.

Example: "South Philials," "Sales Team SP."

Shift¶

Defines schedules within the day: entry, exit, intervals and if there is work planned.

• With work: has input/output forecast and duration.
• No job: does not foresee attendance; absence does not generate lack.

Dependency: Journeys must be registered before from the scales.

Scale¶

Set sequence of days worked and slack over time (e.g. 6×1, 12×36, 5×2). For each day, the scale points out which journey will be followed.

Roll into integration: The collaborator is associated with a scale to automate the routine. Scale changes impact sheet and compliance.

Employee¶

The employee's central register at Pontotel — concentrates identification data, organizational structure (local, employer) and routine parameterizations (scale/journage).

Roll into integration: It's the most synchronized entity. Base to link users, point records, vacations and removals.

User¶

The identity of System access (login) In practice: user is the one who accesses, Employee is the one who works.

In many scenarios the user is linked to an employee so that the employee can register point with their own data.

Types: - Management — administrative profile (HR, supervision) - Official — restricted profile for personal record - Collective — for shared devices (where applicable)

Holiday / Distances¶

Registrations of scheduled or justified absences (attested, licences). Avoid inconsistencies in the sheet and incorrect notes.

Point Marker¶

Entrance/exit registration of employee. Always associated with an employee and with timestamp in the correct time zone (ISO 8601 with offset).

Operational Dependencies¶

A registration order imposed by dependencies between entities is:

1
2
3
4
5
6
7
8

1. Empregador
   → 2. Local de Trabalho
      → (opcional) Grupo
   → 3. Jornadas
      → 4. Escalas
   → 5. Empregados
      → 6. Usuários (gestão e/ou funcionário)
      → 7. Férias / Afastamentos (conforme necessidade)

Difference: User vs. Employee¶

Difference: Journey vs. Scale¶

Consistency Checklist (for integrations)¶

• Single keys defined and stable (employee code, location and employee)
• Registered journeys before scale
• User "employee" linked to employee to avoid divergence of data
• Region and time zone of the workplace set up correctly (impact holidays and timestamps)
• Standard user email according to corporate policy (avoid collisions)

Next Steps¶

• Glossary →
• Identifiers →
• Filters and Query Parameters →