Versionamento da API

Versão: 1.0
Owner: Engenharia SOFIA
Última revisão: 2026
Aplicável a: Dev Integradores, Arquitetura

Esta página define como a SOFIA versiona:

• Endpoints HTTP
• Contratos de evento
• SDK (quando aplicável)

1. Versão Atual

Base pública:

https://api.v1sofia.com/api

A versão atual é v1 (implícita).

Não há prefixo /v1 na URL. Mudanças breaking resultarão em nova base/versionamento explícito.

2. Níveis de Versionamento

A SOFIA opera com três níveis independentes.

2.1 API HTTP

Regras:

• Versão atual: v1 (implícita)
• Breaking change → nova base (ex.: /v2)
• Mudanças aditivas → mantidas dentro da mesma versão

Mudanças aditivas incluem:

• novos campos opcionais
• novos endpoints
• novos filtros
• novos tipos de evento

2.2 Contratos de Evento

Webhook

Header opcional:

x-sofia-version: 1

Se enviado, deve ser 1.

postMessage

Envelope contém:

{
  "version": "1.0"
}

Mudanças breaking exigem nova versão explícita.

2.3 SDK (Futuro)

Quando existir SDK oficial:

• major → breaking change
• minor → novos recursos compatíveis
• patch → correções internas

SDK será versionado independentemente da API.

3. Política de Depreciação

Objetivo: permitir evolução sem ruptura abrupta.

Regras:

• Mudanças aditivas são preferidas.
• Breaking changes exigem nova versão.
• Versões antigas podem coexistir por período de transição.
• Período de convivência será comunicado previamente.

4. O Que É Considerado Breaking Change

Uma mudança é breaking quando exige ajuste obrigatório no código do parceiro.

Exemplos:

• Remover campo obrigatório
• Alterar tipo de campo
• Alterar semântica de campo
• Mudar autenticação de endpoint
• Alterar formato de assinatura HMAC
• Alterar contrato de envelope

5. Compatibilidade Retroativa

Compatibilidade é padrão desejado.

Compromisso da SOFIA

• Nunca remover campo sem nova versão.
• Nunca alterar assinatura sem nova versão.
• Manter contratos de segurança estáveis.
• Adicionar campos apenas como opcionais.

Responsabilidade do Parceiro

Para manter compatibilidade:

• Ignorar campos desconhecidos.
• Não validar payload com whitelist rígida.
• Tratar campos opcionais como opcionais.
• Implementar idempotência.
• Não assumir ordenação implícita de eventos.

6. Recomendações Arquiteturais

Integrações maduras devem:

• Tratar versão como metadado, não como lógica rígida.
• Validar por presença de campo (capability-based), não apenas por número de versão.
• Isolar integração em camada dedicada (client/service).

7. Princípio Central

Se uma mudança obriga você a alterar código para continuar funcionando, ela é breaking.

Se a mudança apenas adiciona capacidade, ela é compatível.