Versionamento da API

O DVS utiliza versionamento baseado em path com um prefixo /v1/ em cada endpoint. Isso garante compatibilidade retroativa enquanto uma determinada versão major estiver em uso.

Regras

Mudanças aditivas não incrementam a versão

Adicionar campos opcionais a request/response bodies, novos códigos de erro, novos tipos de evento, novos query parameters — tudo retrocompatível. Essas mudanças entram em v1 sem quebrar a integração.

Breaking changes vão para um novo path

Renomear ou remover campos, alterar tipos de campo, mudar a semântica de um código de erro existente, tornar obrigatório um campo antes opcional — essas mudanças vão para /v2/.

Versões antigas coexistem por 6 meses

Quando /v2/ for lançado, /v1/ continua funcionando por pelo menos 6 meses. Todos os providers são notificados previamente por support@osigu.com e há publicação no Changelog.

Sinais de depreciação via response headers

Durante a janela de sunset, responses depreciados incluem os headers padrão Deprecation e Sunset (RFC 8594). Monitore-os nos logs da aplicação para saber quando migrar.

Versão de path vs versão de evento

São independentes:

• /v1/ na URL versiona o contrato da API (formatos de request/response).
• event_version: 1 no payload do webhook versiona o schema do evento.

Um endpoint /v1/ pode emitir eventos com event_version: 2 caso o schema do evento tenha evoluído sem alterar a API em si. A versão atual do evento sempre está presente no header X-DVS-Event-Version — verifique-o antes de fazer o parsing.

Detectando a depreciação programaticamente

HTTP/1.1 200 OK
Deprecation: Sun, 01 Jun 2027 00:00:00 GMT
Sunset: Wed, 01 Dec 2027 00:00:00 GMT
Link: <https://docs.osigu.com/changelog>; rel="deprecation"

Se o cliente receber um header Deprecation, registre-o no log e notifique a equipe. Planeje a migração antes da data de Sunset.