Marcações de Ponto¶

O que é¶

Uma marcação de ponto é o registro de entrada ou saída de um empregado em um determinado momento. É o dado central do sistema de controle de frequência — tudo na Pontotel gira em torno de garantir que as marcações sejam precisas e completas.

Por que isso importa numa integração¶

Em integrações com dispositivos de ponto (relógios, totens, apps), os registros chegam via API
Em sincronizações com sistemas de folha, marcações históricas podem ser importadas
O fuso horário correto é obrigatório — marcações sem offset UTC geram inconsistências nos cálculos

Regras de Negócio¶

Cada marcação tem um tipo: entrada ou saida
O data_hora deve obrigatoriamente incluir o offset de fuso horário (ISO 8601)
Empregados inativos não podem registrar novas marcações
Marcações incorretas não devem ser deletadas — devem ser ajustadas com justificativa para auditoria
A ordem cronológica (entrada → saída → entrada → saída) deve ser respeitada

Fuso horário é obrigatório

Sempre envie data_hora com offset explícito.
✅ "2025-01-31T08:05:00-03:00"
❌ "2025-01-31T08:05:00" (sem offset — ambíguo)

Operações Disponíveis¶

Método	Endpoint	Descrição
GET	`/marcacoes/`	Listar marcações
POST	`/marcacoes/`	Registrar marcação
GET	`/marcacoes/{id}/`	Obter marcação
PATCH	`/marcacoes/{id}/`	Ajustar (requer justificativa)

Campos¶

Campo	Tipo	Obrigatório	Descrição
`id`	integer	—	ID interno
`empregado_id`	integer	✅	ID do empregado
`data_hora`	datetime	✅	Data e hora com offset (ISO 8601)
`tipo`	string	✅	`entrada` ou `saida`
`origem`	string	—	`app` \| `web` \| `dispositivo` \| `api`
`justificativa`	string	—	Motivo do ajuste (para PATCH)

Exemplo: Registrar Marcação¶

Requisição¶

HTTP
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"
}

Resposta (201 Created)¶

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

Exemplo: Listar Marcações por Período¶

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}`

Exemplo: Ajustar Marcação Incorreta¶

HTTP
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"
}

Erros Comuns¶

Erro	Causa	Solução
Timestamp sem offset	`data_hora` sem fuso horário	Sempre inclua offset: `2025-01-31T08:00:00-03:00`
Empregado inativo	Tentar registrar para colaborador demitido	Verifique `is_active` antes de enviar
Ordem invertida	Saída registrada antes de entrada	Garanta ordem cronológica correta