Versionamento

Versão atual

O contrato público está na versão 1.0.0, declarada em info.version do OpenAPI. Não existe cabeçalho de versão na requisição: todas as chamadas falam com a versão vigente do contrato.

O que pode mudar sem aviso prévio

Mudanças aditivas, que nenhuma integração correta deveria quebrar:

• Operação nova.
• Campo novo e opcional em pedido ou resposta.
• Valor novo em enumeração aberta (por exemplo, um evento novo de webhook).
• Escopo novo.
• Erro novo com code novo.

Para isso continuar verdade do seu lado: ignore campos que não conhece, não valide enumerações como fechadas e trate code desconhecido pelo status HTTP.

O que não muda sem versão nova

Mudanças incompatíveis só entram com uma versão maior e um período de transição anunciado:

• Remover ou renomear operação, campo ou escopo.
• Mudar tipo ou significado de um campo.
• Mudar o formato do erro.
• Exigir um cabeçalho ou parâmetro que antes era opcional.
• Remover um code ou mudar o status de um code existente.

Como uma mudança incompatível acontece

1. Entrada no changelog com a data em que a versão nova fica disponível e a data em que a antiga deixa de valer.
2. Período de transição em que as duas convivem, com prazo mínimo de 90 dias.
3. Guia de migração publicado junto com o anúncio.
4. Descontinuação na data anunciada, não antes.

Descontinuação de operação

Operação descontinuada é marcada como tal na referência e no changelog, continua funcionando durante a transição e só então deixa de responder.

Prévia

Recursos em prévia não aparecem na referência pública e não têm garantia de compatibilidade. Quando uma prévia vira contrato, ela entra no changelog como adição.

Como acompanhar

• Assine as mudanças pelo changelog.
• Compare o info.version do OpenAPI na sua pipeline: versão maior nova é sinal de leitura obrigatória.