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ão no nível da sub-API. Isso significa que componentes ou serviços individuais na API Merchant terão o próprio ciclo de vida da versão.
Formato e apresentação da versão
Versões estáveis de sub-APIs:se uma sub-API estiver na versão estável, todos os métodos dela também estarão. A versão estável da sub-API é representada como vX (por exemplo, v1, v2). Essas são versões principais prontas para produção.
Sub-APIs Alfa:se uma sub-API estiver na versão Alfa, todos os métodos dela também estarão. A versão da sub-API Alfa é representada como vXalpha (por exemplo, v1alpha, v2alpha). Essas são versões experimentais de acesso antecipado destinadas a testes e iterações rápidas. As versões Alfa não têm garantia de estabilidade nem vida útil garantida. As versões Alfa podem ser alteradas ou desativadas com um período de aviso de 30 dias.
Alterações da versão
Incrementos de versão principais (por exemplo, v1 para v2): indicam mudanças incompatíveis com versões anteriores e interruptivas, que exigem ação do desenvolvedor. Somente as alterações importantes de sub-APIs estáveis terão um novo número de versão. Por exemplo, de 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 sem interrupção 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.
Elementos desativados
Desativamos periodicamente versões mais antigas das sub-APIs do Merchant. Estamos comprometidos 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 a v1 da sub-API de produtos for descontinuada em 15 de janeiro de 2026, ela será desativada em 15 de janeiro de 2027. Após essa data, a versão anterior da sub-API não estará mais disponível para uso.
Status do ciclo de vida e versão da sub-API
A tabela a seguir lista as versões mais recentes de cada sub-API da API Merchant:
| Sub-API | Versões Alfa | Versões Beta | Status |
|---|---|---|---|
| Contas | Indisponível | v1 beta | A versão Beta v1 está ativa |
| Produtos | Indisponível | v1 beta | A versão Beta v1 está ativa |
| Entradas de produtos | Indisponível | v1 beta | A versão Beta v1 está ativa |
| Inventários locais | Indisponível | v1 beta | A versão Beta v1 está ativa |
| Inventários regionais | Indisponível | v1 beta | A versão Beta v1 está ativa |
| Fontes de dados | Indisponível | v1 beta | A versão Beta v1 está ativa |
| Promoções | Indisponível | v1 beta | A versão Beta v1 está ativa |
| Relatórios | Indisponível | v1 beta | A versão Beta v1 está ativa |
| Conversões | Indisponível | v1 beta | A versão Beta v1 está ativa |
| Notificações | Indisponível | v1 beta | A versão Beta v1 está ativa |
| Avaliações | Indisponível | v1 beta | A versão Beta v1 está ativa |
| Configurações de frete | Indisponível | v1 beta | A versão Beta v1 está ativa |
| Product Studio | v1 Alfa | Indisponível | A versão Alfa v1 está ativa |
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 avisos sobre lançamentos de sub-APIs e descontinuações.
- Se uma sub-API tiver duas ou mais versões estáveis, sugerimos usar a versão mais recente o tempo todo.
- Projete seu aplicativo para processar vários erros de sub-API, incluindo problemas de rede, limites de taxa e novos códigos ou mensagens de erro que podem ser introduzidos com versões mais recentes de sub-APIs.
- Não espere até que uma versão da sub-API esteja prestes a ser desativada para começar a planejar seu upgrade. Comece a avaliar e testar novas versões assim que elas estiverem disponíveis.
- Para solicitações de recursos ou dúvidas sobre o cronograma de uma sub-API, entre em contato com nossa equipe para fazer perguntas ou enviar feedback. Para saber como entrar em contato com a equipe da API Merchant para receber suporte técnico, consulte Receber ajuda com a API Merchant.