Versionamento & Changelog

Versão da API

A versão está embutida na URL base:

https://api.selectwin.io/v1

Enquanto você usar /v1, a API mantém compatibilidade retroativa — não removemos campos nem endpoints existentes dentro da mesma versão maior.

O que é considerado uma mudança compatível (não-quebra)

Estas mudanças podem acontecer a qualquer momento dentro de /v1. Sua integração deve tolerá-las:

Novos endpoints e novos recursos.
Novos campos opcionais em requisições.
Novos campos em respostas (não remova/ignore campos que não conhece).
Novos valores em enums (ex.: novos status, novos type de webhook). Trate valores desconhecidos com um caminho padrão.
Novos tipos de evento de webhook. Ignore com segurança os que você não trata.
Reordenação de chaves em objetos JSON.

O que é uma mudança quebrável (breaking)

Mudanças quebráveis não são feitas em /v1. Quando necessárias, são lançadas em uma nova versão maior (ex.: /v2), com período de transição e comunicação prévia. Exemplos:

Remover ou renomear um campo/endpoint.
Mudar o tipo de um campo ou o significado de um valor.
Tornar obrigatório um parâmetro antes opcional.

Boas práticas para sobreviver a mudanças

Trate IDs como opacos — não dependa de comprimento/prefixo (veja Convenções).
Ignore campos desconhecidos em respostas, em vez de falhar.
Tenha um caminho padrão para status/type novos.
Assine apenas os eventos de webhook que você processa.
Use error.code (estável) para lógica, nunca a message (texto).

Quando um recurso for descontinuado, comunicaremos com antecedência pelos canais oficiais e, quando aplicável, marcaremos o recurso como deprecated na referência OpenAPI antes da remoção (que só ocorre em uma nova versão maior).

Changelog

As mudanças relevantes da API são publicadas no changelog oficial. Consulte a documentação pública para o histórico de versões e novidades. Para dúvidas sobre uma mudança específica, contate [email protected].