Ponto Eletrônico

O módulo de RH do Lumen ERP recebe marcações de ponto em tempo real de relógios/coletores biométricos Control iD (linhas REP e iDFace). O equipamento é configurado para enviar cada marcação via webhook para um endpoint dedicado, autenticado por um token próprio do dispositivo — não pelo trio de cabeçalhos de parceiro usado no restante desta referência.

Como funciona

Diferente dos demais recursos desta referência, este endpoint não é chamado por um sistema parceiro — é o próprio equipamento de ponto quem envia os dados, em tempo real, a cada marcação.

1
Um relógio de ponto é cadastrado no módulo de RH do Lumen ERP, o que gera um token exclusivo do equipamento.
2
O token é cadastrado na configuração de webhook do próprio equipamento Control iD, que passa a enviar um POST a cada marcação (entrada, saída, ou lote de eventos pendentes).
3
O Lumen ERP identifica o funcionário pelo CPF, PIS/PASEP ou matrícula presentes na marcação, registra o ponto e recalcula o espelho de ponto do dia.
4
A resposta sempre volta com 200 e as contagens de eventos recebidos/ignorados — o equipamento não deve reenviar em loop dados que a API não conseguiu usar.

Marcações não identificadas não são um erro de protocolo. Um funcionário desconhecido, um registro sem horário legível, ou uma marcação duplicada são contabilizados em ignored e a resposta continua 200 — só a ausência ou invalidade do token retorna 401.

Como o funcionário é identificado

cpf / user_cpf / registration

Testados nesta ordem contra o CPF do funcionário (11 dígitos).

event_time / timestamp / date_time / datetime / time

Testados nesta ordem para o horário da marcação. Numérico é tratado como epoch UTC; texto é interpretado no fuso America/Sao_Paulo.

nsr / event_id / log_id / id

Testados nesta ordem como identificador externo do evento, usado para deduplicação.

Formatos de payload aceitos

O parser é tolerante a variações de firmware: um objeto único, ou um lote sob uma das chaves access_logs, values, punches ou records, ou ainda uma lista JSON simples no corpo raiz.

POST /hr/timeclock/punch/{token?}

Registrar marcação de ponto

Recebe uma ou mais marcações de um equipamento de ponto. A rota não tem prefixo de versão e fica fora do grupo de autenticação de parceiros — o próprio token do equipamento é a autenticação.

Autenticação

X-Device-Token header

Preferencial. Nem todo firmware Control iD permite configurar um cabeçalho customizado no webhook.

{token} segmento de rota

Alternativa quando o equipamento não suporta cabeçalhos customizados. Se ambos forem enviados, o cabeçalho prevalece.

O token é gerado ao cadastrar o equipamento no módulo de RH (Ponto Eletrônico → Equipamentos) e fica oculto nas respostas da API depois de criado — copie-o no momento do cadastro.

Corpo da requisição

cpf string

CPF do funcionário. Também aceito como user_cpf ou registration.

event_time string | epoch

Horário da marcação. Também aceito como timestamp, date_time, datetime ou time.

nsr string

Identificador único do evento no equipamento, usado para deduplicação. Também aceito como event_id, log_id ou id.

Códigos de resposta

200

Requisição processada — inclusive quando todos os eventos foram ignorados.

401

Token ausente, inválido ou equipamento inativo.

Requisição POST

POST /hr/timeclock/punch/{token}

curl -X POST https://lumenerp.app.br/api/hr/timeclock/punch \
  -H "X-Device-Token: {device_token}" \
  -H "Content-Type: application/json" \
  -d '{"cpf":"12345678900","event_time":"2026-09-02T08:01:12-03:00","nsr":"000482"}'

// Configurado no próprio equipamento Control iD, não chamado pelo backend do parceiro.
// Referência de payload enviado pelo dispositivo:
{
  "cpf": "12345678900",
  "event_time": "2026-09-02T08:01:12-03:00",
  "nsr": "000482"
}

// Lote de marcações pendentes (batch de firmwares AFD-style):
{
  "access_logs": [
    { "user_cpf": "12345678900", "timestamp": 1725270072, "event_id": "000482" },
    { "user_cpf": "98765432100", "timestamp": 1725270091, "event_id": "000483" }
  ]
}

Resposta

{
  "received": 1,
  "ignored": 0
}

{
  "message": "Equipamento não autorizado ou token não informado."
}