Este guia explica como a API Merchant lida com 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 usa uma estratégia de controle de versões no nível da sub-API. Isso significa que cada API Merchant, por exemplo, produtos na API Merchant, terá um ciclo de vida de versão próprio.
Formato e apresentação do controle de versões
Versões secundárias estáveis da API: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 um 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 interruptivas, que exigem ação do desenvolvedor. Somente mudanças interruptivas 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 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
Periodicamente, desativamos 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:
| Sub-API | Versões | Status |
|---|---|---|
| Contas | v1 v1alpha v1beta |
Ativo Ativo Desativado em 28 de fevereiro de 2026 |
| Conversões | v1 v1beta |
Ativo Desativado em 28 de fevereiro de 2026 |
| Fontes de dados | v1 v1beta |
Ativo Desativado em 28 de fevereiro de 2026 |
| Inventários | v1 v1beta |
Ativo Desativado em 28 de fevereiro de 2026 |
| Resolução de problemas | v1 v1beta |
Ativo Desativado em 28 de fevereiro de 2026 |
| Parceria de feeds locais | v1 v1beta |
Ativo Desativado em 28 de fevereiro de 2026 |
| Notificações | v1 v1beta |
Ativo Desativado em 28 de fevereiro de 2026 |
| Rastreamento de pedidos | v1 v1beta |
Ativo Desativado em 28 de fevereiro de 2026 |
| Produtos | v1 v1beta |
Ativo Desativado em 28 de fevereiro de 2026 |
| Product Studio | v1alpha | Ativo |
| Promoções | v1 v1beta |
Ativo Desativado em 28 de fevereiro de 2026 |
| Cota | v1 v1beta |
Ativo Desativado em 28 de fevereiro de 2026 |
| Relatórios | v1 v1beta |
Ativo Desativado em 28 de fevereiro de 2026 |
| Avaliações | v1alpha v1beta |
Ativo Desativado em 28 de fevereiro de 2026 |
Práticas recomendadas
- Consulte 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 a mais recente sempre.
- 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 forem disponibilizadas.
- Para solicitações de recursos ou dúvidas sobre um roteiro de sub-API, entre em contato com nossa equipe para enviar 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.