Saltar a contenido

Marcaciones de punto

Qué es

Una marcado de punto es el registro de entrada o salida de un empleado en un determinado momento. Es el dato central del sistema de control de frecuencia — todo en la Pontotel gira en torno a garantizar que las marcas sean precisas y completas.

Por qué esto importa en una integración

  • En integraciones con dispositivos de punto (relogios, totens, apps), los registros llegan vía API
  • sincronizaciones con sistemas de hoja, marcas históricas pueden ser importadas
  • El Zona horaria correcto es obligatorio — marcas sin offset UTC generan inconsistencias en los cálculos

Reglas de negocio

  • Cada marca tiene un tipo: entrada o saida
  • El data_hora obligatoriamente debe incluir offset de zona horaria (ISO 8601)
  • Empleados inactivos no pueden registrar nuevas marcas
  • Las etiquetas incorrectas no deben ser deletadas — deben ser ajustados con justificación para auditoría
  • El orden cronológico (entrada → salida → entrada → salida) debe ser respetado

Fuso horario es obligatorio

Siempre envíe data_hora con offset explícito.
Gálatas "2025-01-31T08:05:00-03:00"
❌ "2025-01-31T08:05:00" (sin offset — ambiguo)

Operaciones disponibles

Método Variable Descripción
GET /marcacoes/ Listar marcas
POST /marcacoes/ Registro marcado
GET /marcacoes/{id}/ Obtener marcado
PATCH /marcacoes/{id}/ Ajustar (requier justificación)

Campos

Campo Tipo Obligatorio Descripción
id Integer — ID interno
empregado_id Integer Gálatas ID del empleado
data_hora datetime Gálatas Fecha y hora con offset (ISO 8601)
tipo string Gálatas entrada o saida
origem string — app \
justificativa string — Motivo del ajuste (para PATCH)

Ejemplo: Registrar marcador

Solicitud

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

{
  "empregado_id": 500,
  "data_hora": "2025-01-31T08:05:00-03:00",
  "tipo": "entrada",
  "origem": "api"
}

Respuesta (201 Created)

JSON
1
2
3
4
5
6
7
8
{
  "id": 9999,
  "empregado_id": 500,
  "data_hora": "2025-01-31T08:05:00-03:00",
  "tipo": "entrada",
  "origem": "api",
  "justificativa": null
}

Ejemplo: Listar marcas por periodo

HTTP
1
2
GET /pontotel/api/v4/marcacoes/?empregado_id=500&data_inicio=2025-01-01T00:00:00-03:00&data_fim=2025-01-31T23:59:59-03:00
Authorization: Bearer {token}

Ejemplo: Ajustar marcador

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

{
  "data_hora": "2025-01-31T08:00:00-03:00",
  "justificativa": "Correção de horário registrado com atraso por falha no dispositivo"
}

Errores comunes

Error Causa Solución
Timestamp sin offset data_hora sin zona horaria Siempre incluya offset: 2025-01-31T08:00:00-03:00
Empleado inactivo Intentar registrar a un colaborador despedido Compruebe is_active antes de enviar
Orden invertida Salida registrada antes de entrada Garanta orden cronológico correcta