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

# Banco de Horas

> Saldos, ciclos e movimentações de banco de horas conforme CLT Art. 59. Compensação, abono, prescrição e quitação em rescisão.

**Banco de Horas** é o mecanismo legal de compensação previsto na CLT
Art. 59 (Lei 13.467/2017) — horas extras realizadas em determinado dia
podem ser **compensadas** por folgas em outro, em vez de pagamento direto
em folha. Pontua suporta os 3 tipos legais: Anual, Semestral e Mensal.

## Contexto regulatório (CLT Art. 59)

<CardGroup cols={2}>
  <Card title="Anual" icon="calendar-days">
    Compensação em até **12 meses**. Exige acordo coletivo
    (sindicato). Banco mais flexível, mas regulamentação mais rigorosa.
  </Card>

  <Card title="Semestral" icon="calendar">
    Compensação em até **6 meses**. Pode ser por acordo individual escrito.
  </Card>

  <Card title="Mensal" icon="calendar-day">
    Compensação dentro do **mesmo mês** (Art. 59 §6º). Acordo individual
    suficiente. Modalidade mais simples e comum.
  </Card>

  <Card title="Quitação" icon="check-double">
    5 formas legais: **Compensação** (folga), **Abono** (paga em folha),
    **Rescisão** (na demissão), **Prescrição** (acordo expirou),
    **Caducidade** (período legal vencido).
  </Card>
</CardGroup>

<Warning>
  **Tipos não se misturam.** Um colaborador pode ter ciclos Anual e
  Semestral simultâneos, mas cada acúmulo de hora extra entra em **um
  ciclo específico** definido pelo acordo aplicável. Não somar saldos
  de ciclos diferentes para "saldo total" sem qualificar o tipo.
</Warning>

## Endpoints públicos

### Saldos e ciclos

| Método | Rota                                                   | Retorna                                        |
| ------ | ------------------------------------------------------ | ---------------------------------------------- |
| GET    | `/banco-horas/saldos`                                  | Saldos de todos os colaboradores na UN         |
| GET    | `/banco-horas/saldos/{colaboradorId}`                  | Saldo de um colaborador específico             |
| GET    | `/banco-horas/ciclos`                                  | Ciclos ativos na UN (Anual, Semestral, Mensal) |
| GET    | `/banco-horas/ciclos/{cicloId}/{colaboradorId}/resumo` | Resumo mês-a-mês de um colaborador num ciclo   |

### Movimentações

| Método | Rota                                       | Descrição                                  |
| ------ | ------------------------------------------ | ------------------------------------------ |
| GET    | `/banco-horas/movimentacoes`               | Lista movimentações (entradas e saídas)    |
| GET    | `/banco-horas/movimentacoes/{id}`          | Detalhe de uma movimentação                |
| POST   | `/banco-horas/movimentacoes`               | **Crédito/débito manual** ⚠️ (ver gotchas) |
| PATCH  | `/banco-horas/movimentacoes/cancelar/{id}` | Cancelar movimentação ⚠️                   |

Schema completo em [Referência da API](/api-reference#tag/Banco-de-Horas).

## Fluxos típicos

### Consultar saldo antes de aprovar folga

```javascript theme={null}
async function aprovarFolgaSeTemSaldo(token, colaboradorId, horasFolga) {
  const resp = await fetch(
    `https://api.pontua.com.br/banco-horas/saldos/${colaboradorId}`,
    { headers: { Authorization: `Bearer ${token}` } },
  )
  const saldo = await resp.json()

  // Saldo retornado é em formato HH:MM ou minutos — confira spec
  if (saldo.saldoMinutos < horasFolga * 60) {
    throw new Error(`Saldo insuficiente: ${saldo.saldoMinutos / 60}h disponível`)
  }

  // Aprovar folga via fluxo de Ajustes ou Turno Exceção
}
```

### Relatório de banco vencendo (prescrição)

```javascript theme={null}
async function colaboradoresComBancoVencendoEmBreve(token, diasAlerta = 30) {
  // Listar ciclos Anual (mais propensos a vencer)
  const resp = await fetch(
    `https://api.pontua.com.br/banco-horas/ciclos?tipo=ANUAL`,
    { headers: { Authorization: `Bearer ${token}` } },
  )
  const { resultados: ciclos } = await resp.json()

  const limite = new Date(Date.now() + diasAlerta * 86400000)
  return ciclos.filter((c) => new Date(c.dataFim) < limite && c.saldoTotal > 0)
}
```

## Gotchas conhecidos

<Warning title="POST /movimentacoes é OPERAÇÃO CRÍTICA">
  Crédito/débito manual altera saldo legal do colaborador. Pode afetar:

  * Folha de pagamento (dimensão financeira)
  * Litígio trabalhista (dimensão jurídica)
  * Auditoria fiscal (dimensão contábil)

  **Use apenas:**

  * Acertos pontuais com base em acordo escrito
  * Migração de saldo de outro sistema (com auditoria)
  * Correção de erro de cálculo identificado

  **Sempre documente o motivo** no payload.
</Warning>

<Warning title="Cancelamento de movimentação não reverte automaticamente cálculos">
  `PATCH /movimentacoes/cancelar/{id}` invalida a movimentação no banco
  mas **não recalcula** automaticamente saldos derivados
  (compensações posteriores que assumiam aquele saldo). Sempre verifique
  consistência após cancelamento.
</Warning>

<Warning title="Banco mensal zera no fechamento">
  Ciclos `MENSAL` quitam automaticamente no fechamento do mês —
  saldo positivo vira hora extra paga, saldo negativo vira desconto.
  Sua integração não deve esperar saldo mensal "remanescente" entre
  meses.
</Warning>

<Warning title="Prescrição vs Caducidade são diferentes legalmente">
  * **Prescrição:** o acordo coletivo/individual expirou (ex.: convenção
    sindical não foi renovada)
  * **Caducidade:** o período legal foi ultrapassado (ex.: ciclo Anual
    sem compensação em 12 meses)

  As consequências em folha podem variar — consulte jurídico antes de
  automatizar quitações nesses casos.
</Warning>

## Veja também

* [Relatório de Banco de Horas](/guias-praticas/relatorio-banco-horas) — gerar consolidado
* [Frequência](/referencia/frequencia) — origem das horas extras que alimentam o banco
* [Regras de Ponto](/referencia/regras-de-ponto) — configuração de quando hora extra vai para banco vs paga
* [Ajustes e Motivos](/referencia/ajustes-e-motivos) — fluxo formal de ajuste retroativo