Controle de versões

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

Esquema de controle de versão

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

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

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

• Versões Alfa da sub-API: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). Elas 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 vida útil definida e podem ser alteradas ou descontinuadas com um aviso prévio de 30 dias.

Alterações da versão

• Incrementos de versão principal (por exemplo, v1 para v2): indicam mudanças incompatíveis com versões anteriores e que exigem ação do desenvolvedor. Somente mudanças significativas 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 de lançamento dessa versão principal. As adições não significativas 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 da sub-API Merchant. Nos comprometemos com um período de descontinuação de 12 meses para versões principais estáveis (vX), a partir do anúncio oficial de descontinuação.

Por exemplo, se descontinuarmos a v1 da sub-API Produtos em 15 de janeiro de 2026, ela será desativada em 15 de janeiro de 2027 ou depois. Após essa 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

• Consulte regularmente as notas de lançamento e as atualizações mais recentes para 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, sugerimos usar a versão 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 da sub-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 conosco com perguntas ou feedback. Para informações sobre como entrar em contato com a equipe da API Merchant para receber suporte técnico, consulte Receber ajuda com a API Merchant.