Magento REST API 2.4.9, imagens e store view precisam ser avaliados em conjunto quando ERP, PIM, marketplace ou integração própria atualiza o catálogo. Uma diferença no conteúdo de media_gallery_entries pode determinar se a visão de loja mantém a galeria global ou recebe valores específicos para imagens, vídeos, rótulos e posições.
No Adobe Commerce 2.4.9, uma atualização de produto no escopo de store view passa a preservar a herança da galeria padrão quando media_gallery_entries é omitido ou enviado como NULL, conforme as notas oficiais do Adobe Commerce 2.4.9. Para quem automatiza milhares de atualizações, essa alteração exige revisão dos payloads e testes antes do deploy.
O que mudou na herança de imagens pela REST API?
Em um catálogo com múltiplas store views, a galeria pode aproveitar os dados definidos no escopo padrão ou manter personalizações em uma visão específica. O problema surge quando uma integração destinada a atualizar preço, nome, descrição ou outro atributo também envia informações de mídia sem necessidade.
No comportamento documentado para o Adobe Commerce 2.4.9, omitir media_gallery_entries ou atribuir NULL ao campo durante uma atualização no escopo de store view mantém a herança da galeria global. A mudança evita que uma atualização sem dados de mídia seja interpretada como uma personalização local da galeria, como detalha a documentação da versão 2.4.9.
A mesma documentação informa que atributos específicos de uma entrada da galeria, incluindo label, position, disabled e campos relacionados a vídeo, podem voltar a herdar os valores do escopo padrão quando são definidos como NULL dentro de media_gallery_entries. Isso permite restaurar a herança de uma propriedade sem necessariamente tratar toda a galeria como um único bloco.
Qual é o impacto para lojas brasileiras?
Integrações de catálogo frequentemente combinam informações provenientes de diferentes sistemas. O ERP pode controlar dados comerciais, enquanto um PIM mantém descrições e imagens. Marketplaces, hubs e rotinas internas também podem atualizar o mesmo SKU em escopos distintos.
Após a atualização, um payload antigo pode continuar retornando sucesso HTTP e, ainda assim, produzir um resultado diferente do esperado na store view. Os efeitos possíveis incluem:
- rótulos locais permanecendo quando deveriam voltar a herdar o padrão;
- ordem de imagens diferente entre store views;
- uma imagem marcada como desabilitada somente em determinado escopo;
- vídeos mantendo metadados específicos da visão de loja;
- integrações enviando a galeria inteira sem que a operação precise alterá-la.
A versão 2.4.9 do Adobe Commerce foi publicada em 12 de maio de 2026 e possui suporte regular previsto até 31 de maio de 2029, segundo a página oficial de versões lançadas. Como se trata de uma linha com ciclo próprio de manutenção, a validação das integrações deve fazer parte do projeto de atualização, e não ser deixada para depois da entrada em produção.
Como revisar o payload de media_gallery_entries
1. Identifique quem atualiza produtos por store view
Faça um inventário de todos os processos que chamam endpoints de produto. Procure jobs do ERP, sincronizações do PIM, conectores de marketplace, importadores e scripts internos. Registre o store code utilizado, os atributos enviados e a frequência das atualizações.
Não limite a análise ao sistema responsável pelas imagens. Uma integração de preço pode usar um objeto completo de produto e reenviar media_gallery_entries apenas porque esse campo veio em uma consulta anterior.
2. Diferencie campo omitido, NULL e array vazio
Esses três formatos não devem ser considerados equivalentes sem homologação:
- Campo omitido:
media_gallery_entriesnão faz parte do objeto enviado. - Valor NULL: o campo é enviado explicitamente como
null. - Array vazio: o campo é enviado como
[].
As notas da versão confirmam o comportamento de herança para omissão e NULL. Elas não devem ser usadas para presumir o resultado de um array vazio em todas as combinações de módulos, plugins e customizações. Teste [] separadamente e, se a integração não modifica mídia, prefira não enviar a galeria.
3. Não transforme respostas de consulta em payloads de gravação
Um antipadrão comum é consultar o produto, alterar um único atributo e devolver praticamente todo o objeto à API. Além de aumentar o payload, isso pode reenviar IDs, posições, rótulos e flags de mídia que deveriam permanecer sob controle de outro sistema.
Monte payloads mínimos, contendo somente os atributos que a integração realmente domina. Por exemplo, uma rotina dedicada à descrição da store view não precisa incluir a galeria:
{
"product": {
"sku": "SKU-EXEMPLO",
"custom_attributes": [
{
"attribute_code": "description",
"value": "Descrição específica da visão de loja"
}
]
}
}Quando o objetivo for restaurar a herança de propriedades de uma entrada existente, um payload ilustrativo pode usar valores nulos:
{
"product": {
"sku": "SKU-EXEMPLO",
"media_gallery_entries": [
{
"id": 123,
"label": null,
"position": null,
"disabled": null
}
]
}
}A estrutura final deve respeitar o contrato aceito pela instalação, os campos obrigatórios e eventuais plugins. Não copie o exemplo diretamente para produção sem consultar a entrada atual e testar a operação em homologação.
Como testar Magento REST API 2.4.9, imagens e store view
Crie um SKU controlado com pelo menos duas imagens e duas store views. Defina no escopo padrão um rótulo, uma posição e o status de exibição. Em uma store view secundária, configure valores diferentes para que a origem de cada dado fique visível.
Antes de cada atualização, consulte o produto no escopo correspondente e salve a resposta. Um comando defensivo, com o token mantido em variável de ambiente, pode ser usado assim:
curl --fail --silent
-H "Authorization: Bearer $TOKEN"
"https://loja.exemplo/rest/pt_br/V1/products/SKU-EXEMPLO"
| jq '.media_gallery_entries'Execute uma matriz de testes em homologação:
- Atualize somente um atributo textual, omitindo
media_gallery_entries. - Repita a operação enviando
media_gallery_entriescomonull. - Teste um array vazio separadamente e documente o resultado.
- Defina como
nullsomentelabel,positionoudisabledde uma entrada conhecida. - Consulte novamente o produto nos escopos padrão e secundário.
- Confira a galeria na página do produto, no painel e nas APIs consumidas pelo frontend.
Compare também o comportamento dos módulos instalados. Plugins em repositórios de produto, observers e extensões de mídia podem alterar o payload ou executar processamento adicional. Se o projeto também utiliza PWA ou checkout desacoplado, aproveite a homologação para revisar as mudanças de GraphQL do Magento 2.4.9.
Checklist antes de liberar a atualização
- Mapeie integrações que escrevem produtos por store code.
- Remova campos de mídia de rotinas que não controlam a galeria.
- Registre payload, resposta, SKU, escopo e horário de cada teste.
- Valide imagens, vídeos, rótulos, posições e flags de desativação.
- Teste produtos simples, configuráveis e itens com mídia específica por store view.
- Verifique se filas ou jobs assíncronos recriam personalizações depois do teste.
- Prepare rollback do código da integração e preserve evidências do catálogo.
- Evite correções diretas nas tabelas do banco de dados.
A análise não deve ficar restrita à API. O upgrade também pode expor incompatibilidades em extensões e código próprio; por isso, use um checklist de compatibilidade de módulos com Magento 2.4.9 durante a preparação do ambiente.
Perguntas frequentes
O que acontece se media_gallery_entries for omitido no Adobe Commerce 2.4.9?
Em uma atualização de produto no escopo de store view, a omissão preserva a herança da galeria definida no escopo padrão, conforme as notas da versão 2.4.9.
Enviar NULL é igual a enviar um array vazio?
Não presuma que sejam equivalentes. O comportamento de herança está documentado para campo omitido ou enviado como NULL. Um array vazio deve ser tratado como cenário separado e validado em homologação.
É possível restaurar apenas o rótulo ou a posição herdada?
Sim. A versão permite definir como NULL propriedades específicas da entrada, como label, position e disabled, para restaurar a herança do escopo padrão. A entrada e o contrato da API devem ser validados antes da gravação.
Como evitar que o ERP altere imagens sem querer?
Use payloads mínimos e remova media_gallery_entries das operações que não administram mídia. Também registre requisições em homologação e confirme qual store code é utilizado por cada rotina.
Conclusão
A mudança da Magento REST API 2.4.9 para imagens em store view melhora o controle sobre a herança, mas exige que cada integração expresse corretamente sua intenção. Omitir a galeria, enviar NULL ou alterar propriedades específicas são operações que precisam ser diferenciadas no código e nos testes.
Se sua loja depende de ERP, PIM ou marketplace para atualizar o catálogo, revise os payloads antes do upgrade e valide o resultado em todos os escopos. Caso precise mapear integrações, preparar a homologação ou corrigir divergências de mídia, a equipe do Suporte Magento pode auxiliar no diagnóstico técnico.
Fontes consultadas
As informações atuais mencionadas neste artigo foram verificadas nas fontes abaixo.
