Integrar o Pimcore com o Adobe Commerce é separar duas funções: o Pimcore gere o catálogo e o conteúdo, e o Adobe Commerce vende, calcula preços e processa encomendas. Entre os dois, a informação circula por API. É o desenho típico de uma arquitetura composable, em que cada sistema faz aquilo para que foi pensado.
Para a empresa, a vantagem é poder mudar a loja ou acrescentar canais sem refazer o catálogo. A desvantagem é haver mais peças a manter. Por isso, esta integração justifica-se em projetos com catálogo extenso, vários canais ou várias lojas, e é uma das decisões centrais de qualquer integração de PIM com ecommerce.
Este artigo explica como a ligação funciona segundo a documentação oficial, como tratar o envio assíncrono de produtos, que dados seguem em cada sentido e que verificações fazer antes de arrancar.
Quando faz sentido usar Pimcore com Adobe Commerce
Faz sentido quando o catálogo é complexo e a loja é apenas um dos destinos. Se o Adobe Commerce fosse o único canal e o catálogo fosse simples, o próprio painel da loja bastaria.
- há várias lojas ou vistas de loja com idiomas, moedas ou sortidos diferentes
- o mesmo catálogo alimenta marketplace, B2B e loja própria
- a equipa de conteúdo precisa de fluxos de aprovação que a loja não oferece
- o catálogo tem muitos atributos e ativos que mudam com frequência
Se o catálogo é pequeno e estável, é mais económico manter os dados na própria loja. Pode ver a mesma lógica aplicada a outro PIM em Akeneo com Adobe Commerce.
Como se liga o Pimcore ao Adobe Commerce por API
A ligação usa o Datahub do Pimcore como origem e a API REST do Adobe Commerce como destino. Segundo a documentação do Pimcore, o Datahub inclui por defeito uma API GraphQL, com um esquema gerado para cada endpoint e a possibilidade de limitar os dados expostos por área de trabalho. As consultas leem dados e as mutações alteram-nos.
Do lado do Adobe Commerce, a documentação para programadores descreve endpoints REST de produtos e, para volumes maiores, endpoints em massa. Num ambiente PaaS, o endereço tem o formato /rest/ seguido do código da vista de loja e de /async/bulk/V1/products. O pedido é uma lista de produtos e cada um é colocado numa fila de mensagens como mensagem separada.
Este detalhe muda a forma de trabalhar. A resposta do endpoint em massa devolve um identificador do lote, uma lista de itens e o estado de cada um, por exemplo aceite. Segundo a documentação, essa resposta indica apenas que o pedido entrou na fila, e não que a operação teve êxito. É preciso consultar depois o estado da operação com o identificador do lote.
Segundo a mesma documentação, o RabbitMQ é o gestor de mensagens por defeito e o consumidor async.operations.all trata as mensagens assíncronas e em massa. Num ambiente PaaS, as tarefas agendadas são o mecanismo habitual para arrancar os consumidores. Se os consumidores não estiverem a correr, os produtos ficam na fila e nada chega à loja.
Produtos configuráveis e variantes
Os produtos configuráveis exigem cuidado, porque o Pimcore e o Adobe Commerce modelam variantes de forma diferente. No tutorial oficial de criação em massa, o produto configurável e os produtos simples seguem no mesmo pedido, com tipos distintos e visibilidade diferente: o configurável é visível no catálogo e os simples não.
Na prática, o conector deve montar a estrutura de cada família de variantes antes de a enviar. Um produto simples enviado sem o configurável correspondente aparece isolado na loja, e um configurável sem filhos fica sem opções de compra.
Convém também decidir quem é o dono do identificador do produto. Se o código de artigo do Pimcore for a referência única na loja, qualquer reenvio atualiza o mesmo produto em vez de criar outro. Esta escolha parece pequena, mas evita a maior parte dos duplicados que depois falham na fila.
Que dados vão em cada sentido
| Dado | Sistema mestre | Sentido |
|---|---|---|
| Atributos e descrições | Pimcore | Pimcore para loja |
| Imagens e ativos | Pimcore | Pimcore para loja |
| Famílias de variantes | Pimcore | Pimcore para loja |
| Preços por cliente | ERP ou loja | Origem para loja |
| Stock | ERP | ERP para loja |
| Encomendas | Adobe Commerce | Loja para ERP |
Convém fixar este quadro por escrito antes de começar. Quando dois sistemas podem alterar o mesmo campo, a próxima sincronização apaga em silêncio a alteração do outro.
Plano de integração em passos
- Definir as vistas de loja e os idiomas que recebem catálogo.
- Fechar o mapeamento entre atributos do Pimcore e atributos do Adobe Commerce.
- Configurar o endpoint do Datahub com esquema e área de trabalho mínimos.
- Garantir que a fila de mensagens e os consumidores estão ativos no ambiente.
- Enviar um lote de ensaio e verificar o estado de cada item.
- Fazer a carga completa por lotes e rever os itens com erro.
- Passar a sincronização incremental e definir alertas.
Um ponto importante é o âmbito de cada vista de loja. Segundo a documentação, uma atualização sem código de loja altera apenas os valores da vista por defeito, e o código especial all aplica o valor a todas as vistas. Quem ignorar isto acaba com descrições atualizadas numa vista e antigas nas restantes.
Riscos mais comuns
| Risco | Sinal | Prevenção |
|---|---|---|
| Fila parada | Produtos aceites mas não aparecem | Monitorizar os consumidores |
| Duplicados | Erros ao processar a fila | Chave única por produto |
| Âmbito errado | Texto diferente por vista | Definir o código de loja |
| Variantes soltas | Simples visíveis sem configurável | Enviar a família completa |
| Esquema aberto demais | Dados internos expostos | Área de trabalho limitada |
Segundo a documentação, os duplicados não são rejeitados à entrada: o pedido é aceite na fila e só falha quando é processado. Isto significa que um conector que não leia o estado final dá a ideia de que correu tudo bem.
Lista de verificação antes de arrancar
- a fila de mensagens e os consumidores estão ativos e monitorizados
- o conector lê o estado do lote e não só a resposta inicial
- o mapeamento indica o código de loja de cada atributo
- as famílias de variantes são enviadas completas
- há um ambiente de ensaio com cópia do catálogo
- os endereços e títulos otimizados já indexados não são alterados
- o esquema do Datahub expõe apenas o necessário
Se a plataforma for a versão em nuvem como serviço da Adobe, os endereços e a gestão das filas são diferentes dos descritos acima. Confirme na documentação o tipo de instalação antes de desenhar o conector.
Outras ligações do mesmo catálogo
O mesmo Pimcore pode alimentar outras lojas. Veja Pimcore com Magento, Pimcore com SAP Commerce Cloud ou Pimcore com BigCommerce. Para ligar o ERP à loja, consulte SAP S/4HANA com Adobe Commerce.
Como trabalhamos na Avafa
Fechamos primeiro o mapeamento e os sistemas mestre, depois testamos o fluxo assíncrono com um lote pequeno e só então avançamos para a carga completa. Documentamos o que cada fila faz e quem a vigia. Conheça a nossa agência SEO para Magento e Adobe Commerce, que acompanha o impacto no catálogo indexado.
Perguntas frequentes
Preciso de RabbitMQ para usar os endpoints em massa?
Segundo a documentação do Adobe Commerce, o RabbitMQ é o gestor de mensagens por defeito e deve estar instalado e configurado antes de usar a API em massa. Em ambiente de serviço gerido, as filas são tratadas pela plataforma.
A resposta do endpoint em massa confirma que o produto foi criado?
Não. Indica que o pedido entrou na fila. O resultado final consulta-se depois, com o identificador do lote.
Posso usar a API GraphQL do Pimcore para escrever na loja?
Não. A API GraphQL do Pimcore serve para consultar e alterar dados no próprio Pimcore. A escrita na loja faz-se pela API do Adobe Commerce.
O que acontece se o mesmo produto for enviado duas vezes?
Segundo a documentação, o duplicado entra na fila e falha no processamento. Por isso, o conector deve usar chaves únicas e rever os itens com erro.
Esta integração serve para um catálogo pequeno?
Normalmente não compensa. Com poucas referências e poucos canais, o custo de manter duas plataformas supera o ganho, e uma importação bem preparada resolve o mesmo problema com menos peças para manter.