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

# Versionamento

> Como a API Pontua evolui sem quebrar integrações existentes — política de mudanças e endpoints deprecated atuais.

A API Pontua é tratada como **contrato público** com seus integradores.
Quebrar sem aviso é caro para todo mundo, então temos política explícita
de comunicação de mudanças.

## O que é considerado mudança quebrante

Mudanças que **podem quebrar** sua integração existente:

* Remover um endpoint
* Renomear ou remover campos de **request** obrigatórios
* Renomear ou remover campos de **response** que sua integração consome
* Mudar tipos (ex.: `number` → `string`)
* Mudar regras de validação que ficam mais estritas

Tudo o resto é **não-quebrante**:

* Adicionar novos endpoints
* Adicionar novos campos opcionais em request
* Adicionar novos campos em response (sua integração deve **ignorar campos desconhecidos**)
* Adicionar novos valores em enums (sua integração deve ter **fallback** para valores não reconhecidos)

## Comunicação de mudanças

Mudanças relevantes são comunicadas via:

* **Notas de versão** publicadas no portal
* **E-mail** para o contato técnico cadastrado da sua conta

## Endpoints deprecated atualmente

Existem **26 endpoints marcados como `deprecated: true`** no spec OpenAPI
em produção, mantidos por compatibilidade com versões antigas do
dashboard. Padrões observados:

### PUT → PATCH (5 endpoints)

Edição parcial migrou de `PUT` para `PATCH`:

* `PUT /regras-de-ponto/{id}/ativar` → `PATCH /regras-de-ponto/{id}/ativar`
* `PUT /cargos/{id}` → `PATCH /cargos/{id}`
* `PUT /automacoes/{id}` → `PATCH /automacoes/{id}`
* `PUT /centro-custo/{id}` → `PATCH /centro-custo/{id}`
* `PUT /local-trabalho/{id}` → `PATCH /local-trabalho/{id}`

### Subperfis Colaborador (14 endpoints)

Antigamente cada aspecto do colaborador (acesso, alocação, complemento,
dados, definições, foto, preferência) tinha seu próprio par GET + PATCH.
Foram unificados em:

* `PATCH /colaborador/{id}` recebe payload parcial com qualquer combinação de campos
* `GET /colaborador/{id}` retorna o colaborador completo

### Frequência (rotas /registro-ponto/gestao/\*)

Endpoints `/registro-ponto/gestao/*` e `/registro-ponto/frequencias*`
foram migrados para a tag `Frequency`:

* `/registro-ponto/gestao/dashboard` → `/frequency/management`
* `/registro-ponto/frequencias` → `/frequency/daily`
* `/registro-ponto/frequencias/jornada-esperada` → `/frequency/expected`

## Como identificar endpoints deprecated

Na [Referência da API](/api-reference), endpoints deprecated têm um
marcador visual. No spec OpenAPI são marcados com `deprecated: true`.

Sua integração nova deve **evitar usar endpoints deprecated** — embora
eles continuem funcionando hoje, podem ser removidos no futuro.

## Veja também

* [Notas de versão](/changelog) — mudanças anunciadas
* [Erros](/conceitos/erros) — comportamento padrão de respostas