Modelo de datos¶

Visión general¶

La API Pontotel organiza sus datos en entidades jerárquicas e interdependientes. Comprender este modelo es esencial para planificar una integración consistente.

Grafo de Entidades¶

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

Descripción de las entidades¶

Empleador¶

Representa a la empresa empleadora (CNPJ/CPF). Es la raíz organizacional — todos los lugares, grupos y empleados pertenecen a un empleador.

Role en la integración: Base para separar datos en escenarios multi-CNPJ. El "código del empleador" debe alinearse al ERP/foja.

Lugar de trabajo¶

Unidad organizacional donde el colaborador es asignado. No necesita ser un lugar físico — puede representar departamentos, equipos o filiales.

Role en la integración: Define región/fuso horario que impacta feriados y timestamps de marcaciones. Es filtro principal en informes.

Grupo¶

Mecanismo de agrupación para organizar locales de trabajo (y/o usuarios), creando "views" operacionales para informes y filtros.

Ejemplo: "Filiales del Sur", "Equipe de ventas SP".

Jornada¶

Define los horarios dentro del día: entrada, salida, intervalos y si hay trabajo previsto.

Con trabajo: tiene previsión de entrada/salida y duración.
Sin trabajo: no prevé asistencia; ausencia no genera falta.

⚠️ Dependencia: Las Jornadas deben ser registradas antes De las escalas.

Escala¶

Define la secuencia de días Trabajos y descansos a lo largo del tiempo (p. ej.: 6x1, 12x36, 5x2). Para cada día, la escala apunta cual viaje será seguida.

Role en la integración: El colaborador está asociado a una escala para automatizar la rutina. Cambios de escala impactan hoja y cumplimiento.

Empleado¶

El registro central del colaborador en Pontotel — concentra datos de identificación, estructura organizativa (local, empleador) y parametrizaciones de rutina (escala/jornada).

Role en la integración: Es la entidad más sincronizada. Base para vincular usuarios, registros de punto, vacaciones y alejamientos.

Usuario¶

La identidad de acceso al sistema (login). En la práctica: usuario es quien accede, empleado es quien trabaja.

En muchos escenarios el usuario está vinculado a un empleado para que el colaborador pueda registrar punto con sus propios datos.

Tipos: - Gestión — perfil administrativo (RH, supervisión) - Funcion — perfil restringido para registro de punto personal - Colectivo — para dispositivos compartidos (cuando proceda)

Vacaciones / Alejamientos¶

Registros de ausencias programadas (férias) o justificadas (atestados, licencias). Evitan inconsistencias en la hoja y apuntamientos incorrectos.

Marcación de punto¶

Registro de entrada/salida del empleado. Siempre asociado a un empleado y con timestamp en la zona horaria correcta (ISO 8601 con offset).

Dependencias operativas¶

A orden de registro impuesta por las dependencias entre entidades es:

Text Only

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)

Atención: Jornada antes de Escala

La escala referencia jornadas al día. Si intentas crear una escala sin jornadas registradas, la operación fallará.

Diferencia: Usuario vs. Empleado¶

	Usuario	Empleado
Qué es	Identidad de acceso (login)	Cadastro del colaborador (RH)
Para qué sirve	Autenticar y operar el sistema	Gestión de punto, hoja, escalas
Obligatorio para punto	Sí (login)	Sí (datos cadastrales)
Vinculación	Puede estar vinculado a un empleado	Puede tener un usuario asociado
Variable	`/usuarios/`	`/empregados/`

Diferencia: Jornada vs. Escala¶

	Jornada	Escala
Define	Horarios del día (entrada/saída/intervalos)	Secuencia de días (trabajo/folga)
Granularidad	1 día	Ciclo repetible (p. ej.: 6x1)
Dependencia	Independiente	Depende de jornadas
Ejemplos	"08h-17h, 1h intervalo"	"6 días trabajo, 1 descanso"

Checklist de consistencia (para integraciones)¶

Claves únicas definidas y estable (código del empleador, local y empleado)
Jornadas registradas antes las escalas
Usuario "funcionario" vinculado al empleado para evitar divergencias de datos
Región y zona horaria del lugar de trabajo configurados correctamente (impacta feriados y timestamps)
Correo electrónico del usuario estandarizado conforme política corporativa (evitar colisiones)