# Versionamento

A versão da API vai no caminho: todas as rotas de hoje começam com `/v1`. Esta página explica o que pode mudar dentro da `/v1`, como você é avisado de uma mudança que quebra compatibilidade e quais foram as mudanças da API até agora.

## Política da `/v1`

- **Dentro da `/v1`, só mudanças aditivas.** Podem aparecer novos campos nas respostas e novas rotas, sem aviso prévio, porque não quebram quem já integrou. Escreva seu código para **ignorar campos que não conhece**.
- **Remover ou renomear** uma rota ou um campo só acontece numa versão nova, a `/v2`.
- **Convivência de 6 meses.** Quando uma `/v2` existir, a `/v1` continua funcionando lado a lado com ela por 6 meses, para você migrar com calma.
- **Avisos na própria resposta.** Durante esse período, as respostas da versão antiga trazem os cabeçalhos `Deprecation` e `Sunset`, que dizem que a versão está descontinuada e até quando ela funciona.
- **O que não muda dentro da `/v1`:** nomes de campo, nomes de rota, escopos e códigos de erro. Códigos de erro são um contrato estável: veja [Erros](https://developers.festero.com.br/errors.md).

> **Dica**: Como se proteger de mudanças aditivas
>
> Trate valores de `status` desconhecidos sem quebrar (guarde o texto e siga em frente) e não valide a resposta com um esquema que proíba campos extras.

## O contrato da API

O contrato completo, com todas as rotas, parâmetros e respostas, está no documento OpenAPI 3.1:

| Onde | Endereço |
|---|---|
| Neste portal | [`/openapi.v1.json`](https://developers.festero.com.br/openapi.v1.json) |
| Na própria API, sem credencial | `https://platform.festero.com.br/v1/openapi.json` |

A [referência interativa](https://developers.festero.com.br/referencia/) é gerada desse mesmo documento.

## Versões em outras partes

| Item | Versão |
|---|---|
| API | `v1` (campo `api_version` nos [webhooks](https://developers.festero.com.br/webhooks/eventos.md)) |
| Protocolo MCP | Revisão `2026-07-28`. Veja [Servidor MCP](https://developers.festero.com.br/mcp.md). |

## Histórico de mudanças

### Outubro de 2026: primeira versão da `/v1`

Lançamento da API do Festero.

**API de leitura** (somente `GET`), com 14 rotas:

| Grupo | Rotas |
|---|---|
| [Conta](https://developers.festero.com.br/api/conta.md) | `GET /v1/health`, `GET /v1/me` |
| [CRM](https://developers.festero.com.br/api/crm.md) | `GET /v1/crm/opportunities`, `GET /v1/crm/opportunities/{id}`, `GET /v1/crm/pipeline-stages` |
| [Eventos](https://developers.festero.com.br/api/eventos.md) | `GET /v1/events`, `GET /v1/events/{id}` |
| [Orçamentos](https://developers.festero.com.br/api/orcamentos.md) | `GET /v1/quotes`, `GET /v1/quotes/{id}` |
| [Visitas](https://developers.festero.com.br/api/visitas.md) | `GET /v1/visits`, `GET /v1/visits/{id}` |
| [Financeiro](https://developers.festero.com.br/api/financeiro.md) | `GET /v1/finance/receivables`, `GET /v1/finance/receivables/{id}`, `GET /v1/finance/sales-summary` |

**Autenticação:** client credentials com cinco escopos (`crm:read`, `visits:read`, `events:read`, `quotes:read`, `finance:read`) e tokens de 60 minutos. Veja [Autenticação](https://developers.festero.com.br/autenticacao.md).

**Webhooks:** 13 eventos assinados com HMAC-SHA256, com reentrega e verificação do endereço por um evento `ping`. Veja [Webhooks](https://developers.festero.com.br/webhooks.md) e [Eventos de webhook](https://developers.festero.com.br/webhooks/eventos.md).

**Servidor MCP:** 10 ferramentas somente de leitura, autenticadas por token ou por chave MCP. Veja [Servidor MCP](https://developers.festero.com.br/mcp.md).

**Erros:** formato Problem Details (RFC 9457) com códigos estáveis. Veja [Erros](https://developers.festero.com.br/errors.md).