Integrar o Akeneo com o Magento é enviar do Akeneo PIM para o catálogo do Magento as categorias, os atributos e os produtos, de forma repetível e sem edição manual na loja. Existe um conector da Akeneo para Magento 2, publicado como módulo, que faz esta transferência através de chamadas à API. Também é possível construir a ligação à medida, com a API REST do Magento.
Para a empresa, o ponto crítico não é ligar os sistemas, é manter o catálogo fiável depois de ligados. Um erro de mapeamento ou uma atualização feita no ambiente errado afeta de uma vez milhares de fichas. Na Avafa abordamos estes projetos dentro da nossa área de integração de PIM com ecommerce, e este guia centra-se no que deve ficar definido antes da primeira importação.
Cobre o que o conector faz, as versões a ter em conta, como separar ambientes de testes e produção, o papel da API assíncrona do Magento e uma lista de verificação.
O que faz o conector da Akeneo para Magento
O conector exporta dados do Akeneo PIM para o Magento Open Source ou para o Adobe Commerce. Segundo a descrição do pacote, importa categorias, famílias, atributos, opções, modelos de produto, variantes de família e produtos.
Há dois limites importantes a conhecer. O primeiro é que a versão comunitária do conector trabalha com a Akeneo PIM Community Edition, e a descrição indica que as funcionalidades da Enterprise Edition não estão incluídas. O segundo é que o conector exige uma base de dados com codificação UTF-8 e uma versão do Akeneo PIM 3.2 ou superior.
Se a sua loja é Adobe Commerce com arquitetura composable, a decisão muda de figura e convém ler também o guia sobre Akeneo com Adobe Commerce.
Que versão do conector corresponde a cada versão do Magento
A versão do conector tem de corresponder à versão do Magento, e atualizar uma sem a outra é uma das causas mais comuns de falhas. A tabela resume a correspondência indicada na página do pacote.
| Magento / Adobe Commerce | Conector | Estado |
|---|---|---|
| 2.3.7 até antes de 2.4.4 | 103.X.X | Fim de vida |
| 2.4.4 até antes de 2.4.7 | 104.X.X | Só correções |
| 2.4.7 ou superior | 105.X.X | Atual |
Se a sua loja está numa versão antiga do Magento, a integração com o PIM é também um bom momento para decidir se vale a pena atualizar a loja. Um conector em fim de vida deixa de receber melhorias, e isso pesa na decisão. Os requisitos de PHP também mudam entre versões, por isso confirme-os na documentação do pacote antes de planear o servidor.
Como separar ambientes de testes e produção
O fluxo mais seguro usa dois circuitos completos: um ambiente de testes (QA) ligado a uma cópia do Magento, e o ambiente de produção (PRD) ligado à loja real. Nunca se testa um mapeamento novo diretamente em produção.
Na prática, este é o método que aplicamos como regra de trabalho:
- Crie no Akeneo uma ligação própria para cada ambiente, com credenciais distintas.
- Aponte o ambiente de QA para uma cópia do Magento, com o mesmo código e as mesmas extensões.
- Importe primeiro estrutura (categorias, famílias, atributos) e só depois produtos.
- Compare uma amostra de fichas no Akeneo e no Magento, campo a campo.
- Só depois de aprovado, repita a sequência em produção, fora de horas de maior tráfego.
Importar a estrutura antes dos produtos não é um capricho. Os produtos dependem de famílias e atributos já existentes, e se a estrutura falha, os erros multiplicam-se em cada produto.
Como funciona o acesso à API da Akeneo
O Akeneo cria uma ligação com client ID, segredo e um utilizador de API, e a integração pede um token ao endpoint /api/oauth/v1/token. Segundo a documentação da API da Akeneo, o token de acesso dura por defeito uma hora e o token de renovação 14 dias.
Para ler produtos em volume, a mesma documentação recomenda a paginação search-after e indica um máximo de 100 itens por pedido. Um conector ou script que use paginação por página falha nos catálogos grandes, porque pedir a página 101 com 100 itens devolve um erro 422 nos produtos.
O papel da API assíncrona do Magento
Quando a integração é feita à medida, a API REST assíncrona do Magento permite enviar muitos pedidos de uma vez. Segundo a documentação do Adobe Commerce, os endpoints em lote (bulk) colocam cada entidade numa fila de mensagens e são processados de forma assíncrona. Aceitam os métodos POST, PUT, DELETE e PATCH, e não suportam GET.
Há um cuidado essencial: a resposta do lote só diz se cada pedido foi aceite na fila, não se foi processado com sucesso. Um pedido duplicado, por exemplo, pode falhar mais tarde apesar de ter sido aceite. A integração tem, portanto, de verificar o resultado depois e não presumir que “aceite” significa “gravado”.
Em instalações alojadas pelo próprio cliente ou em cloud (PaaS), é preciso configurar o RabbitMQ e os consumidores de filas. Sem isso, os pedidos ficam parados. Nas instalações Adobe Commerce as a Cloud Service (SaaS), as filas correm automaticamente e o limite de entidades por pedido é definido na configuração da loja.
Que riscos tem e como se evitam
- Mapeamento incompleto: documente cada atributo do Akeneo e o campo equivalente no Magento, incluindo os que não se enviam.
- Lista de categorias substituída: na API da Akeneo, uma lista enviada substitui a anterior; envie sempre a lista completa.
- Fila parada: monitorize os consumidores e as tarefas agendadas, para que as mensagens não fiquem retidas.
- Atualização de versão: confirme a compatibilidade do conector antes de atualizar o Magento.
- Edição manual na loja: se alguém corrige uma ficha no Magento, a próxima importação pode apagar a correção.
O último ponto é cultural e não técnico. Se a equipa continua a editar descrições na loja, o PIM perde o papel de fonte única. A regra deve ser comunicada e, idealmente, reforçada com permissões.
Lista de verificação antes de arrancar o projeto
- Confirme a versão do Magento e escolha o conector que lhe corresponde.
- Verifique se usa Akeneo Community ou Enterprise e o que isso exclui.
- Crie ligações e credenciais separadas para QA e para produção.
- Defina por escrito que campos o PIM controla e quais ficam no Magento.
- Importe estrutura primeiro, produtos depois, e valide uma amostra.
- Planeie a verificação do resultado em cada lote enviado.
- Atribua um responsável pelos alertas e pelas atualizações de versão.
Como trabalhamos na Avafa
Começamos por mapear dados e responsáveis, e só depois escolhemos entre conector, desenvolvimento à medida ou plataforma de integração. Revemos o desenho do fluxo e o contrato com o fornecedor antes de qualquer desenvolvimento. Se precisa de uma segunda opinião, veja a nossa auditoria de contratos de ERP e PIM ou a página de integração de PIM com ecommerce.
Guias relacionados do mesmo cluster
Se a plataforma de destino ainda não está decidida, estes guias comparam o mesmo PIM com outras opções:
- Integrar Akeneo com PrestaShop
- Integrar Akeneo com Adobe Commerce
- Integrar Akeneo com WooCommerce
- Integrar Akeneo com SAP Commerce Cloud
- Integrar Akeneo com BigCommerce
Perguntas frequentes
Existe um conector oficial da Akeneo para Magento?
Existe um módulo da Akeneo para Magento 2, publicado como “Akeneo Connector for Adobe Commerce”, que funciona com Magento Open Source e Adobe Commerce. A versão comunitária trabalha com o Akeneo PIM Community Edition.
O conector serve para Magento Open Source e Adobe Commerce?
Sim, a descrição do pacote indica ambos. Deve, mesmo assim, confirmar a versão exata da loja e a versão do conector correspondente.
Posso usar a API do Magento em vez do conector?
Pode, e faz sentido quando as regras são muito específicas. Em contrapartida, passa a ser responsável por paginação, renovação de tokens, filas e verificação de resultados.
Porque é que os produtos não aparecem depois de enviados em lote?
A API assíncrona só confirma que o pedido entrou na fila. Se os consumidores não estiverem ativos, ou se houver um erro no processamento, o produto não é gravado. Verifique as filas e os registos.
Quanto tempo demora um projeto destes?
Depende da qualidade dos dados de origem, do número de famílias e de idiomas e do tempo de validação em QA. O mapeamento e a limpeza de dados costumam condicionar mais o calendário do que a parte técnica.