# Versionamento

## Versões

A versão da API fica no caminho: `/api/v1`. Uma mudança incompatível cria uma nova versão (`/api/v2`), e a anterior continua funcionando durante o prazo de descontinuação.

## Mudanças compatíveis

Acontecem sem aviso prévio, na mesma versão. O seu sistema deve aceitá-las:

- Novos endpoints, ferramentas MCP e tipos de evento de webhook.
- Novos campos nas respostas e novos parâmetros opcionais.
- Novos códigos de erro (`code`) e novos valores em listas abertas, como `status` e `rejection_codes`.
- Mudanças nos textos (`title`, `message`). Use `code`, não o texto.

## Mudanças incompatíveis

Remover ou renomear um campo, endpoint ou ferramenta, mudar um tipo, tornar obrigatório um parâmetro opcional, ou mudar o significado de um valor.

Exceção: mudanças exigidas pela Sefin Nacional ou pela legislação seguem o prazo do governo, que pode ser menor.

## Descontinuação

1. Aviso por e-mail aos proprietários das contas e nesta documentação, pelo menos 6 meses antes do fim.
2. As respostas do recurso descontinuado trazem os cabeçalhos `Deprecation` (RFC 9745) e `Sunset` (RFC 8594), com um `Link` para a página da mudança.
3. Depois da data em `Sunset`, o recurso responde `410 Gone`.

Hoje nenhum recurso está descontinuado.