Glosario¶
Definiciones de los principales términos usados en la API y en la documentación Pontotel.
Entidades principales¶
Desplazamiento¶
Registro de ausencia justificada del colaborador (atestados, licencias, alejamientos previdenciarios etc.). Evita apuntamiento de faltas en la hoja durante el período de ausencia.
Ver: Desplazamientos →
Empleado¶
El registro del colaborador dentro de la Pontotel. Concentra datos de identificación, estructura organizativa (local, empleador) y parametrizaciones de rutina (escala/jornada/regras de cálculo). Es la entidad central del dominio de RH.
Diferencia clave: empleado es quien trabaja; usuario Es quien accede al sistema.
Ver: Empleados →
Empleador¶
Representa a la empresa empleadora (persona jurídica o física) identificada por CNPJ o CPF. Es la entidad raíz — todos los lugares, empleados y grupos pertenecen a un empleador.
Ver: Empleadores →
Escala¶
Estructura que define la secuencia de días trabajados y descansos a lo largo de un ciclo (p. ej.: 6x1, 12x36, 5x2). Para cada día de la escala es atribuida una jornada. Depende de jornadas registradas previamente.
Ver: Escalas →
Vacaciones¶
Registro del período de descanso remunerado del colaborador. Sincronizar vacaciones con Pontotel evita inconsistencias en hoja e informes.
Ver: Vacaciones →
Grupo¶
Mecanismo de agrupación para organizar locales de trabajo (y/o usuarios) en "pastas" operacionales. Facilita la selección masiva para informes y filtros de hoja.
Ver: Grupos →
Jornada¶
Define los horarios dentro de un día de trabajo: entrada, salida, intervalos y si hay trabajo previsto. Puede ser "con trabajo" o "sin trabajo" (folga/descanso). Debe ser cadastrada antes de la escala.
Ver: Jornadas →
Lugar de trabajo¶
Unidad organizacional donde el colaborador está alocado. No necesita ser un lugar físico, puede representar departamentos, equipos o filiales. Define la región y la zona horaria que impactan los días festivos y timestamps de marcaciones.
Ver: Lugares de trabajo →
Marcación de punto¶
Registro de entrada o salida de un empleado en un momento determinado. Siempre asociada a un empleado y con timestamp obligatoriamente con zona horaria (ISO 8601).
Ver: Marcaciones →
Usuario¶
La identidad de acceso al sistema Puntotel (login). Puede ser un administrador, administrador de RH o colaborador. Cuando representa un colaborador, debe ser vinculado al empleado para garantizar la consistencia de los datos (nombre, correo electrónico etc.).
Diferencia clave: usuario es quien accede; empleado Es quien trabaja.
Ver: Usuarios →
Términos técnicos¶
Bearer Token¶
Método de autenticación usado en la API. El token JWT se obtiene vía POST /login/ y enviado en el header Authorization: Bearer {token} en todas las requisiciones posteriores. Válido por 1 hora.
Business Key¶
Identificador con significado funcional usado para integración entre sistemas: CNPJ (empregador), CPF (empregado), matrícula (empregado). Preferible al ID interno para mapear registros entre sistemas.
CPF¶
Cadastro de Persona Física — documento de identificación único de persona física en Brasil. Usado como clave de negocio para empleados.
CNPJ¶
Cadastro Nacional de Persona Jurídica — identificador único de empresas en Brasil. Usado como clave de negocio para empleadores.
Dirty Reload¶
Estrategia del servidor de desarrollo MkDocs (--dirtyreload) que re-renderiza solo las páginas modificadas. No detecta cambios en mkdocs.yml — en estas situaciones es necesario reiniciar el servidor.
ERP¶
Enterprise Resource Planning — sistema de gestión empresarial (por ejemplo: SAP, TOTVS Protheus). En integraciones, el ERP suele ser el "sistema master" para datos de registro de colaboradores.
Zona horaria¶
Offset UTC aplicado a equiposstamps de marcaciones. Esencialmente para consistencia en empresas con operaciones en múltiples regiones de Brasil (o internacionales). Establece el lugar de trabajo.
ISO 8601¶
Estándar internacional de representación de fechas y horas. Formato usado en la API: 2025-01-31T08:05:00-03:00. Siempre incluya el offset de la zona horaria.
Idempotencia¶
Propiedad de una operación que puede ejecutarse múltiples veces sin efecto colateral adicional además de la primera ejecución. Importante en integraciones para garantizar que los reactivos no dupliquen datos.
JWT¶
JSON Web Token — formato del token de autenticación utilizado por la API Pontotel.
Matrícula¶
Identificador interno del colaborador dentro de la empresa. Cuando estandarizado como clave de integración, permite mapeo estable entre el sistema de RH y la Pontotel.
Paginación¶
Mecanismo de división de grandes listas de páginas. La API retorna count, next, previous y results. Use page y page_size como query parameters.
Rate Limit¶
Límite de requisiciones por unidad de tiempo. Producción: 500 req/hora, 50 req/minuto. Sandbox: 1000 req/hora, 100 req/minuto. Headers X-RateLimit-* informan el consumo actual.
Sandbox¶
Ambiente de pruebas aisladas en sandbox-apis.pontotel.com.br. Los datos no afectan la producción. Usá para el desarrollo y validación de integraciones antes de ir al aire.
Sincronización incremental¶
Estrategia de sincronización que transfiere solamente registros modificados desde la última ejecución exitosa. Más eficiente que la sincronización completa para uso regular.