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.

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
Na própria API, sem credencial	https://platform.festero.com.br/v1/openapi.json

A referência interativa é gerada desse mesmo documento.

Versões em outras partes

Item	Versão
API	v1 (campo api_version nos webhooks)
Protocolo MCP	Revisão 2026-07-28. Veja Servidor MCP.

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	GET /v1/health, GET /v1/me
CRM	GET /v1/crm/opportunities, GET /v1/crm/opportunities/{id}, GET /v1/crm/pipeline-stages
Eventos	GET /v1/events, GET /v1/events/{id}
Orçamentos	GET /v1/quotes, GET /v1/quotes/{id}
Visitas	GET /v1/visits, GET /v1/visits/{id}
Financeiro	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.

Webhooks: 13 eventos assinados com HMAC-SHA256, com reentrega e verificação do endereço por um evento ping. Veja Webhooks e Eventos de webhook.

Servidor MCP: 10 ferramentas somente de leitura, autenticadas por token ou por chave MCP. Veja Servidor MCP.

Erros: formato Problem Details (RFC 9457) com códigos estáveis. Veja Erros.