Controle de versões

Este guia explica como a API Merchant lida com controle de versões, lançamentos e o ciclo de vida das diferentes versões.

Esquema de controle de versão

A API Merchant usa uma estratégia de controle de versão no nível da sub-API. Isso significa que cada API, por exemplo, Produtos na API Merchant, terá seu próprio ciclo de vida de versão.

Formato e apresentação do controle de versão

• Versões estáveis de sub-APIs:se uma sub-API estiver em uma versão estável, todos os métodos dela também estarão. Uma versão secundária estável da API é representada como vX (por exemplo, v1, v2). Essas são as principais versões prontas para produção.

• Versões Alfa de sub-APIs:se uma sub-API estiver em uma versão Alfa, todos os métodos dela também estarão. Uma versão alfa da sub-API é representada como vXalpha (por exemplo, v1alpha, v2alpha). Eles contêm recursos experimentais de acesso antecipado destinados a testes e iteração rápida. As versões Alfa não têm garantia de estabilidade, não têm ciclo de vida definido e podem ser alteradas ou desativadas com um aviso de 30 dias.

Alterações da versão

• Incrementos de versão principal (por exemplo, v1 para v2): sinalizam mudanças incompatíveis com versões anteriores e significativas, que exigem ação do desenvolvedor. Somente mudanças incompatíveis de sub-APIs estáveis terão um novo número de versão. Por exemplo, v1 para v2.

• Mudanças secundárias:adições ou correções compatíveis com versões anteriores são apresentadas como mudanças na versão principal atual. Essas mudanças serão detalhadas nas notas da versão principal. As adições não destrutivas a uma sub-API serão lançadas no canal Alfa da versão estável mais recente ou diretamente na versão estável mais recente.

Política de desativação

Desativamos periodicamente versões mais antigas das sub-APIs Merchant. Temos um período de descontinuação de 12 meses para versões principais estáveis (vX), começando com o anúncio oficial de descontinuação.

Por exemplo, se descontinuarmos a v1 da sub-API Products em 15 de janeiro de 2026, ela será desativada em 15 de janeiro de 2027 ou depois. Depois dessa data, a versão anterior da sub-API não estará mais disponível para uso.

Versão da sub-API e status do ciclo de vida

A tabela a seguir lista as versões mais recentes de cada sub-API da API Merchant:

Práticas recomendadas

• Verifique regularmente as notas da versão e as atualizações mais recentes para conferir novas versões, atualizações importantes, melhorias e anúncios sobre lançamentos e descontinuações de sub-APIs.
• Se uma sub-API tiver duas ou mais versões estáveis, recomendamos usar sempre a mais recente.
• Projete seu aplicativo para processar normalmente vários erros de sub-API, incluindo problemas de rede, limites de taxa e os novos códigos ou mensagens de erro que podem ser introduzidos com versões mais recentes da sub-API.
• Não espere até que uma versão secundária da API esteja prestes a ser desativada para começar a planejar o upgrade. Comece a avaliar e testar novas versões assim que elas estiverem disponíveis.
• Para solicitações de recursos ou dúvidas sobre um roteiro de sub-API, entre em contato com perguntas ou feedback. Para informações sobre como entrar em contato com a equipe da API Merchant para suporte técnico, consulte Receber ajuda com a API Merchant.