> ## Documentation Index
> Fetch the complete documentation index at: https://developers.pontua.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Registros de Ponto

> Marcações de jornada de trabalho — registro via API, importação AFD (Portaria 671), consulta histórica, geração de comprovantes e auditoria com NSR sequencial.

**Registro de ponto** é o evento de marcação de jornada de um colaborador
— entrada, saída, intervalos. É a fonte primária para todo cálculo de
frequência, horas extras, banco de horas e folha de pagamento da
plataforma.

A API permite que sistemas externos (REPs customizados homologados,
apps próprios, integradores de jornada) registrem batidas, importem
arquivos AFD pré-existentes e consultem históricos.

## Contexto regulatório

A Pontua atua como **REP-P (Registrador Eletrônico de Ponto via Programa)**
homologado pelo INPI sob a Portaria MTP 671/2021 e Portaria 1.486/2022.
Isso traz obrigações **inegociáveis** para qualquer integração que
manipula registros:

<CardGroup cols={2}>
  <Card title="NSR — Número Sequencial de Registro" icon="hashtag">
    Cada batida recebe um NSR sequencial **gerado pelo Pontua**, nunca
    pelo cliente. Esse número entra no AFD/AEJ e nos comprovantes
    assinados. Sequência inválida (gaps, duplicatas) configura
    irregularidade.
  </Card>

  <Card title="Comprovante de registro" icon="file-signature">
    Para cada batida registrada, o colaborador tem direito a um
    comprovante assinado digitalmente (PAdES embed). O comprovante
    contém o NSR + hash SHA-256 + metadata INPI.
  </Card>

  <Card title="AFD e AEJ assinados" icon="file-shield">
    Arquivos exportados (AFD, AEJ) recebem assinatura digital CAdES
    detached (.p7s). Os arquivos têm encoding ISO 8859-1 e estrutura
    fixa por tipo (1 cabeçalho, 3 marcações, 99 trailer no AFD).
  </Card>

  <Card title="Soft-delete obrigatório" icon="recycle">
    Registros nunca podem ser fisicamente removidos. Correções via API
    geram novo registro com flag de ajuste + motivo + auditoria. O
    histórico original é preservado por 5 anos (Art. 98).
  </Card>
</CardGroup>

## Origens de registro

Cada registro carrega o campo `origem` indicando como foi capturado.
A integração de cliente externo tipicamente registra apenas `API`
ou `AFD`:

| Origem   | Significado                        | Acessível via API?                         |
| -------- | ---------------------------------- | ------------------------------------------ |
| `APP`    | Mobile app oficial Pontua          | Não (interno)                              |
| `WEB`    | Portal de marcação web Pontua      | Não (interno)                              |
| `REP`    | Relógio de ponto físico homologado | Limitado ao token de integração específico |
| `API`    | Integração externa via REST        | ✅ `POST /registro-ponto`                   |
| `AFD`    | Importação de arquivo AFD          | ✅ `POST /registro-ponto/afd`               |
| `AJUSTE` | Ajuste manual aprovado             | Via fluxo de Ajustes (não direto)          |

## Endpoints públicos

### Registrar batidas

<Tabs>
  <Tab title="Batida individual">
    `POST /registro-ponto` — Registra uma batida pontual.

    **Quando usar:**

    * REP customizado próprio (cliente que tem hardware homologado)
    * App de RH/onboarding que precisa registrar entrada manualmente
    * Sistema de portaria/controle de acesso integrado

    **Quando NÃO usar:**

    * Sincronizar batidas históricas de outro sistema (use AFD em vez)
    * Importar grandes lotes de uma só vez (use AFD)
    * Eventos do app Pontua oficial (já passa por outra rota interna)

    A jornada esperada do colaborador (turno) é validada no momento.
    Batidas fora da janela de tolerância podem cair em status `PENDENTE`
    aguardando aprovação de gestor. Veja [Frequência](/referencia/frequencia).
  </Tab>

  <Tab title="Importação AFD">
    `POST /registro-ponto/afd` — Importa arquivo AFD em conformidade
    com Portaria 671.

    **Quando usar:**

    * Migrar histórico de outro sistema homologado
    * Importar batidas do REP-C físico que não roda Pontua
    * Onboarding de cliente vindo de outro REP

    O arquivo deve seguir o layout exato da Portaria 671:

    * Encoding `ISO 8859-1`
    * Linhas tipo 1 (cabeçalho) + tipo 3 (marcações) + tipo 99 (trailer)
    * NSR sequencial sem gaps no arquivo

    A API valida o arquivo, gera novos NSRs do lado Pontua e devolve
    contadores `totalRegistros`, `totalImportados`, `totalRejeitados`
    com motivo de rejeição linha-a-linha.
  </Tab>

  <Tab title="Comprovante PDF">
    `POST /registro-ponto/recibo` — Gera comprovantes assinados em PDF
    para um colaborador num período.

    O PDF contém todas as batidas do período com NSR, hash, e assinatura
    PAdES embed (verificável em qualquer leitor PDF). Útil para:

    * Anexar em folha de pagamento mensal
    * Atender solicitação do colaborador (Art. 79)
    * Auditoria interna ou fiscalização
  </Tab>
</Tabs>

### Consultar registros

<Tabs>
  <Tab title="Listagem">
    `GET /registro-ponto` — Lista registros com filtros.

    Filtros típicos: `colaboradorId`, `dataInicio`, `dataFim`, `status`,
    `origem`, `departamentoId`. Use paginação `pagina` + `limite` para
    iterar grandes volumes — ver [Paginação](/conceitos/paginacao).

    Para sync incremental com seu sistema, salve um **cursor de
    timestamp** e filtre por data crescente — ver [Webhooks (polling)](/conceitos/webhooks).
  </Tab>

  <Tab title="Últimos registros">
    `GET /registro-ponto/ultimos` — Retorna as últimas batidas de um
    colaborador (limite default 10).

    Útil para:

    * Dashboard "quem bateu agora?"
    * Validar última marcação antes de novo registro
    * Detectar batida duplicada do lado do cliente
  </Tab>

  <Tab title="Localização e fotos">
    | Endpoint                           | Retorna                                     |
    | ---------------------------------- | ------------------------------------------- |
    | `GET /registro-ponto/localizacoes` | Coordenadas GPS das batidas de uma jornada  |
    | `GET /registro-ponto/fotos`        | URLs S3 (com expiração) das fotos de batida |

    <Warning>
      **Dados sensíveis sob LGPD.** Localização e foto são dados pessoais.
      Sua integração deve:

      * Acessar apenas com base legal documentada
      * Não armazenar fora do Pontua se não for necessário
      * Tratar URLs como temporárias (expirar em curto prazo)
      * Coletar apenas se o colaborador autorizou (configurado por UN)

      Endpoints retornam vazio quando não há dados disponíveis ou
      quando a UN não coleta GPS/foto.
    </Warning>
  </Tab>
</Tabs>

## Modelo de dados (campos chave)

```typescript theme={null}
{
  id: string                          // UUID Pontua
  nsr: number                         // Número Sequencial de Registro (Portaria 671)
  colaboradorId: string
  dataHora: string                    // ISO 8601 com timezone (BRT padrão)
  origem: "APP" | "REP" | "WEB" | "API" | "AFD" | "AJUSTE"
  status: "VALIDO" | "PENDENTE" | "REJEITADO"
  hash: string                        // SHA-256 do registro (verifiable)
  // ... demais campos no spec OpenAPI
}
```

| Campo      | Significado                                                                                                                           |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `nsr`      | Sequencial **gerado pelo Pontua** ao gravar. Único e crescente por UN. Aparece no AFD/AEJ/comprovantes.                               |
| `dataHora` | Momento exato da batida em ISO 8601. **Use timezone BRT** (`-03:00`) — registros sem timezone são interpretados como BRT por default. |
| `origem`   | Como o registro entrou no sistema. Sua API key registra como `API`.                                                                   |
| `status`   | `VALIDO` é o caso normal. `PENDENTE` aguarda aprovação. `REJEITADO` quando há violação clara (ex: batida fora do cerco geográfico).   |
| `hash`     | SHA-256 do conteúdo, cacheado no servidor e expresso no comprovante. Permite verificação offline de integridade.                      |

## Fluxos típicos

### Registrar batida em REP customizado

```javascript theme={null}
// Hardware próprio detectou marcação biométrica → envia para Pontua
async function registrarBatidaRep(token, dadosBatida) {
  const resp = await fetch('https://api.pontua.com.br/registro-ponto', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      colaboradorId: dadosBatida.colaboradorId,
      dataHora: dadosBatida.timestamp,  // já com timezone
      // demais campos opcionais (localização, etc) conforme spec
    }),
  })

  if (!resp.ok) {
    const erro = await resp.json()
    throw new Error(`${erro.service}: ${erro.message}`)
  }

  const registro = await resp.json()
  console.log(`NSR ${registro.nsr} gerado para ${dadosBatida.colaboradorId}`)
  return registro
}
```

### Sync incremental de batidas para BI

```javascript theme={null}
async function syncIncrementalBatidas(token, desde) {
  let pagina = 0
  const resultados = []

  while (true) {
    const params = new URLSearchParams({
      pagina: String(pagina),
      limite: '100',
      dataInicio: desde,  // ISO 8601 — cursor incremental
    })

    const resp = await fetch(
      `https://api.pontua.com.br/registro-ponto?${params}`,
      { headers: { Authorization: `Bearer ${token}` } },
    )
    const { resultados: lote, totalRegistros } = await resp.json()
    resultados.push(...lote)

    if ((pagina + 1) * 100 >= totalRegistros) break
    pagina++
  }

  // Salvar cursor para próxima execução
  if (resultados.length > 0) {
    const ultimaBatida = resultados[resultados.length - 1]
    await storage.set('pontua.ultimo_sync_batidas', ultimaBatida.dataHora)
  }

  return resultados
}
```

### Gerar comprovantes mensais

```javascript theme={null}
async function gerarComprovantesMes(token, colaboradorId, mes) {
  const resp = await fetch(
    'https://api.pontua.com.br/registro-ponto/recibo',
    {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${token}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        colaboradorId,
        dataInicio: `${mes}-01`,
        dataFim: `${mes}-31`,  // ou último dia do mês exato
      }),
    },
  )

  // Resposta inclui URL S3 do PDF assinado (PAdES)
  const { url } = await resp.json()
  return url
}
```

## Gotchas conhecidos

<Warning title="NSR é gerado pelo Pontua, NUNCA pelo cliente">
  Não tente enviar `nsr` no payload de `POST /registro-ponto` — é
  ignorado ou rejeitado. O backend gera sequencial conforme Art. 80 da
  Portaria 671. Misturar fontes de NSR é violação regulatória.
</Warning>

<Warning title="Timezone obrigatório em ISO 8601">
  Sempre envie `dataHora` com offset explícito (ex: `2026-04-26T08:30:00-03:00`).
  Strings sem timezone são interpretadas como BRT, mas isso pode falhar
  em horário de verão (ainda que abolido em 2019, alguns ambientes legados
  têm problemas). Para máxima portabilidade: **sempre com offset**.
</Warning>

<Warning title="Fechamento bloqueia ajustes">
  Se o período da `dataHora` está em fechamento concluído, o registro
  é **rejeitado** ou cai em fluxo de ajuste com aprovação. Verifique
  o status do fechamento antes de bulk-import histórico — ver
  [Fechamento](/referencia/fechamento).
</Warning>

<Warning title="Geolocalização e fotos têm peso LGPD alto">
  São dados pessoais sensíveis. Sua integração deve:

  * Tratar com base legal explícita (consentimento ou execução de contrato)
  * Não trafegar fora do Brasil sem AIPD (Avaliação de Impacto)
  * Implementar política de retenção curta (URLs S3 com TTL no seu lado também)
</Warning>

<Warning title="Endpoints deprecated migraram para Frequência">
  `GET /registro-ponto/gestao/dashboard`, `GET /registro-ponto/gestao/minha-equipe`,
  `GET /registro-ponto/frequencias` e variantes estão **deprecated**.
  Use a tag `Frequency` para agregados — ver [Frequência](/referencia/frequencia).
</Warning>

## Endpoints expostos publicamente

| Método | Rota                           | Descrição                           |
| ------ | ------------------------------ | ----------------------------------- |
| GET    | `/registro-ponto`              | Lista com filtros                   |
| GET    | `/registro-ponto/ultimos`      | Últimas batidas de um colaborador   |
| GET    | `/registro-ponto/localizacoes` | Coordenadas GPS dos registros       |
| GET    | `/registro-ponto/fotos`        | URLs S3 das fotos (com expiração)   |
| POST   | `/registro-ponto`              | Registrar batida individual via API |
| POST   | `/registro-ponto/afd`          | Importar arquivo AFD em massa       |
| POST   | `/registro-ponto/recibo`       | Gerar comprovantes PDF assinados    |

Schema completo + try-it em [Referência da API](/api-reference#tag/Registro-de-Ponto).

## Veja também

* [Frequência](/referencia/frequencia) — agregados diários consolidados
* [Relatórios](/referencia/relatorios) — gerar AFD/AEJ/Espelho de Ponto oficiais
* [Fechamento](/referencia/fechamento) — verificar antes de bulk-import
* [Idempotência](/conceitos/idempotencia) — evitar batidas duplicadas em retry