Adobe Commerce Cloud, webhooks, GraphQL e atributos personalizados passaram a exigir uma nova rodada de atenção das equipes que mantêm integrações de carrinho, ERP, OMS, logística e devoluções. A mudança amplia as possibilidades da plataforma, mas também cria contratos de dados que precisam ser validados antes de chegar à produção.
Nas notas de novembro de 2026, o Adobe Commerce as a Cloud Service passou a aceitar atributos personalizados nos itens do carrinho pela mutação GraphQL addProductsToCart, por meio do campo CartItemInput.custom_attributes, conforme as notas de versão do Adobe Commerce as a Cloud Service. Isso permite transportar informações adicionais durante a inclusão de produtos, desde que o atributo, o consumidor da API e as etapas posteriores entendam o mesmo contrato.
A atualização também adicionou o webhook observer.rma_save_before, capaz de ler e modificar atributos de uma devolução antes do salvamento, além de um ponto de extensão para excluir itens da criação de novas remessas. Esses recursos estão descritos nas mesmas notas oficiais da plataforma e podem alcançar integrações com sistemas de atendimento, ERP, OMS, transportadoras e operações de logística reversa.
A Adobe registrou ainda, nas atualizações de documentação de novembro de 2026, a publicação das notas de produção do serviço e a ampliação dos pontos de extensão, como mostra o histórico de atualizações da documentação do Commerce. Antes de implementar qualquer recurso, confirme que o ambiente analisado é realmente o Adobe Commerce as a Cloud Service e verifique a disponibilidade no schema e na configuração daquele projeto.
Adobe Commerce Cloud: webhooks, GraphQL e atributos personalizados na prática
Um atributo personalizado no carrinho pode representar uma personalização, uma referência originada no marketplace, uma informação fiscal complementar ou outro dado necessário à operação. O desafio não termina quando a API aceita o valor: ele precisa permanecer associado ao item correto e chegar apenas aos sistemas autorizados a consumi-lo.
Nos fluxos de RMA e remessa, a atenção deve ser ainda maior. Uma decisão tomada antes do salvamento da devolução ou durante a composição de uma remessa pode alterar o que será enviado para atendimento, estoque e logística. Por isso, não habilite esses pontos diretamente em produção sem observar payloads, respostas, repetição de chamadas e tratamento de falhas.
9 testes antes de liberar as novas integrações
1. Confirme o produto e o ambiente avaliados
Não presuma que um recurso anunciado para o Adobe Commerce as a Cloud Service esteja automaticamente disponível em toda instalação Magento Open Source ou em qualquer outro modelo de hospedagem. Registre o ambiente, a data da implantação, o schema consultado e quais integrações serão alteradas.
Faça essa verificação separadamente em desenvolvimento, homologação e produção. Diferenças entre ambientes podem produzir um teste aprovado contra um schema que ainda não está disponível no destino final.
2. Consulte o schema GraphQL antes de alterar o cliente
Use as ferramentas autorizadas da equipe para confirmar a presença de custom_attributes em CartItemInput. Não publique um aplicativo móvel, front-end headless ou conector partindo apenas da documentação: a introspecção ou documentação de schema do ambiente deve fazer parte da evidência de homologação.
Se o campo não estiver disponível, interrompa o rollout e revise o ambiente. Implementar tentativas automáticas ou remover silenciosamente o campo pode esconder incompatibilidades e criar carrinhos com informações incompletas.
3. Defina o contrato de cada atributo personalizado
Documente nome, formato, tamanho esperado, obrigatoriedade, origem, destino e regra de validação de cada atributo. Diferencie dados operacionais de informações pessoais e não envie segredos, credenciais, tokens ou conteúdo de pagamento em atributos de carrinho.
Teste valores válidos, ausentes, vazios, repetidos e fora do padrão. O comportamento esperado deve ser explícito: rejeitar a operação, aceitar o item sem o atributo ou aplicar uma regra controlada. Evite conversões silenciosas que dificultem auditoria.
4. Valide o addProductsToCart sem duplicar itens
Execute o fluxo com um produto simples e avance para variações, kits ou outros tipos comercializados pela loja. Repita a solicitação de maneira controlada para descobrir como o cliente e a integração reagem a timeout, atualização de página ou reenvio.
Confirme quantidade, SKU, item do carrinho e vínculo do atributo. Se produtos já desaparecem ou são recriados durante a jornada, investigue primeiro o armazenamento de sessão com o roteiro sobre carrinho do Magento 2 que esvazia sozinho.
5. Confira totais, persistência e passagem pelo checkout
Um atributo adicional não deve alterar preço, desconto, frete ou imposto sem uma regra comercial projetada para isso. Compare os totais antes e depois da inclusão, recarregue o carrinho e verifique o comportamento após login, troca de endereço e seleção do frete.
Finalize um pedido de homologação e confirme se os dados necessários chegaram ao destino correto. Também valide o cenário em que o atributo não é enviado. O checkout não deve depender acidentalmente de uma informação considerada opcional.
6. Teste o observer.rma_save_before com dados controlados
Crie devoluções de homologação com um item, vários itens, quantidades parciais e motivos diferentes. Registre o estado recebido pelo webhook, a resposta devolvida e o resultado efetivamente salvo. Verifique também permissões e exposição de dados do cliente.
Não use a produção para descobrir se uma indisponibilidade externa impede, altera ou apenas atrasa a operação. Simule timeout, resposta inválida e serviço indisponível, observando o comportamento documentado no ambiente e definindo como a equipe recuperará uma devolução interrompida.
7. Homologue a exclusão de itens de novas remessas
Teste pedidos com remessa total, parcial, múltiplos depósitos e itens que não devem seguir no novo envio. Confirme que a exclusão não deixa quantidades incoerentes nem faz ERP, OMS e transportadora divergirem sobre o saldo pendente.
O resultado precisa ser conferido tanto no Adobe Commerce quanto nos sistemas externos. Inclua cancelamento, reprocessamento e nova tentativa para evitar que uma regra válida na primeira execução produza duplicidade posteriormente.
8. Adicione rastreabilidade sem registrar dados indevidos
Correlacione cada operação com identificadores técnicos, horário, ambiente e resultado, mas aplique mascaramento aos dados sensíveis. Métricas de latência, erro e repetição ajudam a separar falha do Adobe Commerce, indisponibilidade externa e problema de contrato.
Se a arquitetura usar mais de um tipo de evento ou integração, documente qual componente participa de cada etapa. O roteiro de testes de Webhooks e Adobe I/O Events ajuda a organizar essa fronteira e a evitar dependências desnecessárias em operações críticas.
9. Faça rollout gradual e prepare o retorno
Separe a implantação do código, a ativação da configuração e a migração dos consumidores sempre que a arquitetura permitir. Comece por um fluxo controlado, acompanhe erros e mantenha uma forma documentada de desativar a nova integração sem apagar logs.
O plano de retorno deve informar quem decide, quais sinais acionam a reversão e como tratar carrinhos, RMAs ou remessas iniciados durante a janela. Depois da liberação, monitore também o checkout; uma falha de integração pode aparecer somente no fechamento da compra. Para ampliar a validação, consulte os testes de checkout e pagamento no Adobe Commerce.
Critérios mínimos para aprovar a implantação
- O schema disponível no ambiente corresponde ao contrato usado pelo cliente GraphQL.
- Os atributos personalizados permanecem ligados ao item correto durante toda a jornada.
- Totais, estoque, frete e criação do pedido continuam consistentes.
- RMA e remessa foram testados com sucesso, timeout, repetição e resposta inválida.
- ERP, OMS, atendimento e logística interpretam o mesmo estado operacional.
- Logs permitem rastrear falhas sem expor informações sensíveis.
- Existe um plano testado para desativar a integração e tratar operações pendentes.
Perguntas frequentes
Quais ambientes suportam CartItemInput.custom_attributes?
As notas citadas apresentam o recurso para o Adobe Commerce as a Cloud Service. A equipe deve confirmar sua disponibilidade no schema GraphQL do próprio ambiente e não presumir suporte automático em outras edições ou modelos de implantação.
Como testar atributos personalizados sem duplicar itens?
Use um carrinho de homologação, registre o identificador da operação e repita chamadas sob condições controladas. Compare quantidade, SKU, item, atributo e totais antes e depois de timeout ou reenvio.
O observer.rma_save_before pode afetar uma devolução?
O ponto de extensão pode ler e modificar atributos antes do salvamento. Por isso, sua influência sobre validação e continuidade deve ser confirmada com testes de sucesso, erro, timeout e resposta inválida no ambiente da loja.
Como validar webhooks de remessa com ERP e transportadora?
Faça pedidos de teste com remessas totais e parciais, exclusão de itens e repetição da operação. Compare quantidades e estados no Adobe Commerce, ERP, OMS e sistema logístico, incluindo o tratamento de falhas.
Conclusão
Os novos recursos do Adobe Commerce Cloud para webhooks, GraphQL e atributos personalizados ampliam a capacidade de integrar carrinho, devoluções e remessas. O benefício, porém, depende de contratos claros, rastreabilidade e homologação entre todos os sistemas envolvidos.
Se sua operação precisa revisar essas integrações, vale realizar um diagnóstico técnico antes do rollout e transformar os nove testes em critérios formais de aprovação. Uma análise especializada pode reduzir mudanças improvisadas e dar mais previsibilidade à implantação.
Fontes consultadas
As informações atuais mencionadas neste artigo foram verificadas nas fontes abaixo.

