Este guia explica como a API Merchant lida com o controle de versões, as versões 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, Products na API Merchant, terá o próprio ciclo de vida de versão.
Formato e apresentação do controle de versões
Versões estáveis de sub-API: se uma sub-API estiver em uma versão estável, todos os métodos dela estarão em uma versão estável. Uma versão estável da sub-API é representada como vX (por exemplo, v1, v2). Essas são as versões principais prontas para produção.
Versões Alfa da sub-API: se uma sub-API estiver em Alfa, todos os métodos dela estarão em Alfa. Uma versão Alfa de 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 vida útil definida e podem ser alteradas ou desativadas com um período de aviso prévio 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 alterações interruptivas, que exigem ação do desenvolvedor. Somente as alterações interruptivas de sub-APIs estáveis terão um novo número de versão. Por exemplo, v1 para v2.
- Mudanças secundárias: as 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 que não causam falhas em 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 as versões mais antigas da sub-API Merchant. Nos comprometemos com uma janela 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 Products 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:
| Sub-API | Versões | Status |
|---|---|---|
| Contas | v1 v1alpha |
Ativo Ativo |
| Conversões | v1 | Ativo |
| Fontes de dados | v1 | Ativo |
| Inventários | v1 | Ativo |
| Resolução de problemas | v1 | Ativo |
| Parceria de feed local | v1 | Ativo |
| Notificações | v1 | Ativo |
| Rastreamento de pedidos | v1 | Ativo |
| Produtos | v1 | Ativo |
| Product Studio | v1alpha | Ativo |
| Promoções | v1 | Ativo |
| Cota | v1 | Ativo |
| Relatórios | v1 | Ativo |
| Avaliações | v1alpha | Ativo |
Práticas recomendadas
- Verifique regularmente as notas da versão e as atualizações mais recentes para saber mais sobre 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 sempre a versão mais recente.
- Projete seu aplicativo para lidar de forma adequada com vários erros de sub-API, incluindo problemas de rede, limites de taxa e os novos códigos do erro ou mensagens que podem ser introduzidos com versões mais recentes da sub-API.
- Não espere até que uma versão de 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 saber como entrar em contato com a Equipe de API Merchant para receber suporte técnico, consulte Receber ajuda com a API Merchant.