> ## 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.

# Frequência

> Agregados diários e mensais de jornada — horas trabalhadas vs esperadas, atrasos, faltas, horas extras. Fonte canônica para BI, folha e dashboards de gestão.

**Frequência** consolida os registros de ponto brutos em uma visão por
**colaborador / data** com horas trabalhadas, ausências, atrasos e
jornada esperada. É a **fonte canônica** para integrações com folha de
pagamento, BI e dashboards gerenciais — não os registros brutos.

A diferença prática:

| Camada                                           | Granularidade                   | Use quando                                |
| ------------------------------------------------ | ------------------------------- | ----------------------------------------- |
| [Registro de Ponto](/referencia/registros-ponto) | 1 linha = 1 batida              | Auditoria fina, AFD/AEJ, comprovantes     |
| **Frequência**                                   | 1 linha = 1 colaborador × 1 dia | BI, dashboards, sync com folha            |
| [Relatórios](/referencia/relatorios)             | Arquivo consolidado mensal      | Compliance, exportação para folha externa |

<Note>
  A tag `Frequency` substitui as rotas legacy `/registro-ponto/gestao/*`
  e `/registro-ponto/frequencias*`, todas marcadas como **deprecated**.
  Sua integração nova deve usar exclusivamente `/frequency/*`.
</Note>

## Como a frequência é calculada

A jornada esperada do colaborador é definida pelo **turno** que ele
está alocado. Pontua suporta 4 tipos de turno (Fixo, Flexível,
Revezamento, Ciclo) — veja [Turnos e Calendário](/referencia/turnos-e-calendario).

A cada dia, o calculador agrupa as batidas em pares entrada/saída
formando jornadas, calcula a carga horária real, compara com a
esperada e classifica:

```
Saldo = horas trabalhadas - carga horária esperada

Se saldo > 0 e dia útil:
  → Horas extras (com percentual conforme regra de ponto)

Se saldo > 0 e domingo/feriado:
  → 100% de adicional típico (CLT Art. 67)

Se saldo < 0:
  → Atraso ou falta parcial
  → Banco de horas (se houver acordo) ou desconto folha
```

### Tolerâncias

A Portaria 671 e o CLT (Art. 58 §1º) permitem **tolerância de 5 a 10
minutos** por marcação. Pontua aplica essa tolerância no cálculo —
batida 5min adiantada/atrasada não gera saldo positivo nem desconto.

A configuração exata da tolerância depende da **Regra de Ponto** vinculada
ao colaborador (RIGIDA, FLEXIVEL\_INTERVALOS, FLEXIBILIDADE\_HORARIOS) —
ver [Regras de Ponto](/referencia/regras-de-ponto).

### Status de frequência

Cada dia é classificado em um status:

| Status     | Significado                                                        |
| ---------- | ------------------------------------------------------------------ |
| `PRESENTE` | Trabalhou (com ou sem atrasos toleráveis)                          |
| `FALTA`    | Sem batidas no dia esperado de trabalho (`-1` no saldo do mês)     |
| `ATESTADO` | Ausência justificada por atestado médico (não conta como falta)    |
| `FERIAS`   | Em férias (sem expectativa de jornada)                             |
| `FOLGA`    | Folga programada (ex: domingo, feriado, banco de horas compensado) |

## Endpoints públicos

<AccordionGroup>
  <Accordion title="GET /frequency/daily — Frequências diárias consolidadas">
    Retorna **uma linha por colaborador por dia** dentro do período
    consultado. Para uma equipe de 50 pessoas em um mês, são \~1500
    linhas — sempre use paginação.

    **Top use case:** sync diário/noturno com sistema de folha. Cron
    pega frequências de `D-1`, alimenta folha do mês corrente.

    Filtros típicos:

    * `dataInicio` / `dataFim` — período (ISO 8601)
    * `colaboradorId` — específico
    * `departamentoId` — agregar por departamento
    * `unidadeNegocioId` — relevante se token cobre múltiplas UNs

    Schema completo no try-it.
  </Accordion>

  <Accordion title="GET /frequency/expected — Jornada esperada">
    Retorna o que era para o colaborador trabalhar naquele dia (horário
    do turno, intervalo configurado, exceções aplicáveis).

    Útil para validar **antes** de:

    * Marcar uma falta (verificar se era dia útil dele)
    * Criar uma batida ajuste (saber a janela esperada)
    * Sincronizar escala com seu sistema de gestão
  </Accordion>

  <Accordion title="GET /frequency/management — Frequência da equipe">
    Filtra automaticamente para colaboradores subordinados ao usuário
    logado, baseado em hierarquia configurada na UN.

    <Warning>
      Esse endpoint só faz sentido com **JWT de usuário gestor**, não
      com API key da unidade. Com API key (que não tem hierarquia
      associada), o filtro de subordinação não se aplica e o resultado
      pode incluir todos da UN.
    </Warning>

    Use casos: dashboard de gestor, app de aprovação de ajustes.
  </Accordion>

  <Accordion title="GET /frequency/management/punctuality — Pontualidade">
    Métricas agregadas de pontualidade da equipe:

    * % de batidas dentro da janela esperada
    * Top atrasadores
    * Distribuição de atrasos por departamento

    Para dashboard executivo. **Não confunda** com cálculo individual de
    horas extras — isso vem de `/frequency/daily` ou de [Relatórios](/referencia/relatorios).
  </Accordion>
</AccordionGroup>

## Modelo de dados (resumido)

```typescript theme={null}
{
  data: string                    // ISO 8601 date (yyyy-MM-dd)
  colaboradorId: string

  jornadaEsperada: {
    horasMinutos: string          // "08:00"
    intervalo: string             // "01:00"
    inicio?: string               // "08:00" (turnos com horário fixo)
    fim?: string                  // "17:00"
  }

  registros: Array<{
    dataHora: string
    tipo: "ENTRADA" | "SAIDA" | "INICIO_INTERVALO" | "FIM_INTERVALO"
    nsr: number
  }>

  totais: {
    horasTrabalhadas: string      // "08:15" — formato HH:MM
    horasExtras: string           // "00:15"
    horasFalta: string            // "00:00"
    horasAtraso: string           // "00:00"
  }

  status: "PRESENTE" | "FALTA" | "ATESTADO" | "FERIAS" | "FOLGA"
  ocorrencias: string[]           // ["BATIDA_DUPLICADA", "FORA_DO_CERCO", ...]
}
```

## Fluxos típicos

### Sync noturno com folha de pagamento

```javascript theme={null}
async function syncDiarioFolha(token) {
  const ontem = new Date(Date.now() - 86400000).toISOString().slice(0, 10)

  let pagina = 0
  while (true) {
    const resp = await fetch(
      `https://api.pontua.com.br/frequency/daily?` +
      `dataInicio=${ontem}&dataFim=${ontem}&pagina=${pagina}&limite=100`,
      { headers: { Authorization: `Bearer ${token}` } },
    )
    const { resultados, totalRegistros } = await resp.json()

    for (const freq of resultados) {
      await meuSistemaFolha.upsertFrequencia({
        colaborador: freq.colaboradorId,
        data: freq.data,
        horasTrabalhadas: freq.totais.horasTrabalhadas,
        horasExtras: freq.totais.horasExtras,
        status: freq.status,
      })
    }

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

### Validar jornada esperada antes de criar atestado

```javascript theme={null}
async function criarAtestadoComValidacao(token, colaboradorId, data) {
  // 1. Verificar se era dia esperado de trabalho
  const espResp = await fetch(
    `https://api.pontua.com.br/frequency/expected?` +
    `colaboradorId=${colaboradorId}&data=${data}`,
    { headers: { Authorization: `Bearer ${token}` } },
  )
  const { jornadaEsperada } = await espResp.json()

  if (!jornadaEsperada || jornadaEsperada.horasMinutos === '00:00') {
    console.log(`${data} não é dia útil para ${colaboradorId}, atestado dispensável`)
    return null
  }

  // 2. Era dia útil → criar atestado via fluxo de Ajustes
  // (ver Ajustes de Registro)
}
```

### Dashboard de presença em tempo real

```javascript theme={null}
async function dashboardPresenca(token, departamentoId) {
  const hoje = new Date().toISOString().slice(0, 10)
  const resp = await fetch(
    `https://api.pontua.com.br/frequency/daily?` +
    `dataInicio=${hoje}&dataFim=${hoje}&departamentoId=${departamentoId}&limite=100`,
    { headers: { Authorization: `Bearer ${token}` } },
  )
  const { resultados } = await resp.json()

  return {
    presentes: resultados.filter((f) => f.status === 'PRESENTE').length,
    faltas: resultados.filter((f) => f.status === 'FALTA').length,
    atestados: resultados.filter((f) => f.status === 'ATESTADO').length,
    ferias: resultados.filter((f) => f.status === 'FERIAS').length,
  }
}
```

## Gotchas conhecidos

<Warning title="Frequência muda com ajustes posteriores">
  Frequência é **calculada continuamente** conforme batidas e ajustes
  entram. Um valor lido hoje pode mudar amanhã se houver aprovação de
  ajuste retroativo. Para snapshot **imutável**, use o relatório oficial
  (AFD/AEJ) gerado após fechamento do período.
</Warning>

<Warning title="Cálculo depende da Regra de Ponto vigente">
  Se a regra de ponto do colaborador muda no meio do mês, dias antes da
  mudança usam regra antiga; dias depois, nova regra. Em integrações
  que reportam "horas extras totais do mês", isso pode causar
  inconsistência se a regra mudou — sempre cite a regra na hora do
  cálculo.
</Warning>

<Warning title="Tolerância CLT pode esconder atrasos">
  Atraso de 5 min ainda é atraso para o RH, mas **não gera saldo
  negativo** na frequência (tolerância CLT). Se sua integração é para
  acompanhamento disciplinar, complemente com query nos registros brutos
  via `GET /registro-ponto`.
</Warning>

<Warning title="Endpoints legacy retornam dados ligeiramente diferentes">
  As rotas deprecated em `/registro-ponto/gestao/*` foram **substituídas**,
  não simplesmente renomeadas. Há diferenças sutis em:

  * Cálculo de pontualidade (nova versão considera tolerância configurada)
  * Agrupamento por departamento (nova versão respeita hierarquia eSocial)
  * Formato de horários (HH:MM string em vez de minutos integer)

  Migre para `/frequency/*` em integração nova; para integrações
  existentes, planeje migração antes da remoção das deprecated.
</Warning>

## Endpoints expostos publicamente

| Método | Rota                                | Descrição                                                  |
| ------ | ----------------------------------- | ---------------------------------------------------------- |
| GET    | `/frequency/daily`                  | Frequências diárias consolidadas (1 linha por colab × dia) |
| GET    | `/frequency/expected`               | Jornada esperada para colaborador/data                     |
| GET    | `/frequency/management`             | Frequência filtrada por subordinação (gestor)              |
| GET    | `/frequency/management/punctuality` | Métricas de pontualidade agregadas                         |

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

## Veja também

* [Sincronizar frequência com ERP](/guias-praticas/sincronizar-frequencia-erp) — fluxo cron noturno
* [Registros de Ponto](/referencia/registros-ponto) — eventos brutos antes da agregação
* [Relatórios](/referencia/relatorios) — espelho de ponto, banco de horas, horas extras formais
* [Banco de Horas](/referencia/banco-horas) — saldos consolidados por ciclo
* [Regras de Ponto](/referencia/regras-de-ponto) — tolerâncias, percentuais, adicional noturno
* [Turnos e Calendário](/referencia/turnos-e-calendario) — jornada esperada, exceções