Integrar o Akeneo com o Adobe Commerce é usar o Akeneo PIM como fonte dos dados de produto e enviá-los para o catálogo do Adobe Commerce através das APIs dos dois sistemas. Numa arquitetura composable, em que cada função é um componente separado ligado por APIs, o PIM trata do conteúdo do produto e o Adobe Commerce trata da venda.
Para o negócio, o que muda entre uma instalação tradicional e uma composable é o modelo de execução. O Adobe Commerce pode estar em modo PaaS (em cloud ou instalado pelo próprio cliente) ou em modo SaaS (Adobe Commerce as a Cloud Service), e as rotas, as filas e os limites da API diferem. Na Avafa tratamos estes projetos dentro da nossa área de integração de PIM com ecommerce, e este guia ajuda a perceber o que confirmar primeiro.
Vamos ver como se organiza a arquitetura, o que a API assíncrona do Adobe Commerce exige, o que o conector da Akeneo cobre e que decisões convém fechar antes do desenvolvimento.
Como se organiza uma arquitetura composable com Akeneo e Adobe Commerce
Numa arquitetura composable, o Akeneo guarda e enriquece os dados de produto, e o Adobe Commerce recebe só o que precisa para vender. Cada sistema tem uma função clara e comunica com os outros por API.
Uma divisão típica é a seguinte:
| Função | Sistema | Dados principais |
|---|---|---|
| Conteúdo de produto | Akeneo PIM | Atributos, textos, imagens |
| Venda e checkout | Adobe Commerce | Catálogo, carrinho, encomenda |
| Preço e stock | ERP | Valores e disponibilidade |
| Camada de ligação | Integração | Mapeamento e filas |
A vantagem é poder trocar um componente sem refazer os outros. O custo é que a ligação passa a ser uma peça crítica do negócio e precisa de responsável, monitorização e documentação. Se está a comparar com uma plataforma mais simples, vale a pena ler o guia sobre Akeneo com PrestaShop.
PaaS ou SaaS: o que muda na API do Adobe Commerce
Muda a rota dos endpoints assíncronos, a gestão das filas e o modo de indicar a loja. Segundo a documentação do Adobe Commerce, os endpoints em lote (bulk) agrupam vários pedidos do mesmo tipo e colocam cada entidade numa fila de mensagens.
- PaaS: a rota é do tipo /async/bulk/V1/products. É preciso instalar e configurar o RabbitMQ e manter ativo o consumidor async.operations.all, normalmente através de tarefas agendadas (cron) ou de um gestor de processos como o Supervisor.
- SaaS: a rota é do tipo /V1/async/bulk/products. As filas correm automaticamente, não é preciso gerir um broker, e o limite de entidades por pedido define-se na configuração “Maximum Entities per Bulk Request”.
- Seleção de loja: em PaaS indica-se o código da loja na rota (ou o valor “all”); em SaaS usa-se o cabeçalho Store.
Se a equipa de desenvolvimento escreve o código para uma destas variantes e a loja muda para a outra, o código tem de ser revisto. Convém, por isso, confirmar o modelo antes de orçamentar.
O que a API assíncrona não garante
A resposta de um pedido em lote confirma apenas que foi aceite na fila, não que foi processado. A documentação do Adobe Commerce é explícita: o estado devolvido nesta fase é “accepted”, e um pedido duplicado pode falhar mais tarde mesmo tendo sido aceite.
Cada pedido devolve um identificador (bulk_uuid) que serve para consultar o estado da operação mais tarde. Uma integração bem desenhada guarda esse identificador, consulta o resultado e regista os erros por produto. Sem esse passo, um catálogo pode ficar meio atualizado sem que ninguém dê por isso.
Os endpoints em lote não suportam GET e as rotas não aceitam parâmetros de entrada diretamente: o parâmetro é indicado no próprio caminho, trocando os dois pontos por “by” e pondo a primeira letra do parâmetro em maiúscula, como em bySku.
O que o conector da Akeneo cobre
O conector da Akeneo para Magento 2 está descrito como compatível com Magento Open Source e Adobe Commerce 2.3.7 ou superior. Importa categorias, famílias, atributos, opções, modelos de produto, variantes de família e produtos a partir do Akeneo PIM, e a versão comunitária não inclui as funcionalidades da Enterprise Edition.
Para versões 2.4.7 ou superiores, a página do pacote indica o conector 105.X.X como o atual. A documentação analisada não detalha se este conector cobre o modelo SaaS do Adobe Commerce, por isso essa é uma pergunta a fazer ao fornecedor antes de decidir. Se não cobrir, o caminho é uma integração à medida sobre as APIs de ambos os lados. O guia sobre Akeneo com Magento detalha as versões e os ambientes de teste.
A Akeneo documenta também uma API GraphQL, além da API REST, que pode ser uma opção de leitura quando se quer pedir apenas os campos necessários.
Que decisões fechar antes de desenvolver
- Confirme se a loja é PaaS ou SaaS e qual é a rota da API em cada caso.
- Defina, campo a campo, o sistema que manda: PIM, ERP ou Adobe Commerce.
- Escolha entre conector e desenvolvimento à medida, pedindo ao fornecedor a lista do que cobre.
- Planeie como se consulta o resultado de cada lote através do bulk_uuid.
- Defina o tamanho máximo de lote em função do limite configurado na loja.
- Separe ambientes de testes e produção, com credenciais distintas.
- Atribua um responsável pela monitorização das filas e dos alertas.
Que riscos tem esta integração
Os riscos concentram-se na fila, na identidade dos dados e na renovação de acessos. Do lado da Akeneo, o token de acesso dura por defeito uma hora e o de renovação 14 dias, segundo a documentação da API. Uma integração que não renova tokens falha sempre ao fim de uma hora de execução longa.
- Fila parada: sem consumidores ativos em PaaS, os pedidos aceites não são processados.
- Sucesso aparente: tratar “accepted” como “gravado” esconde erros reais.
- Paginação: a leitura de produtos na Akeneo deve usar search-after, com um máximo de 100 itens por pedido.
- Listas substituídas: uma lista de categorias enviada na Akeneo substitui a anterior.
- Mudança de modelo: passar de PaaS para SaaS obriga a rever rotas e filas.
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 contrato e o desenho do fluxo antes de qualquer desenvolvimento. Se quer 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 Magento
- Integrar Akeneo com PrestaShop
- Integrar Akeneo com WooCommerce
- Integrar Akeneo com SAP Commerce Cloud
- Integrar Akeneo com Salesforce Commerce Cloud
Uma regra prática ajuda a fechar o âmbito: comece por um conjunto pequeno de produtos, confirme que cada lote devolve um bulk_uuid e consulte o estado final de cada item, e só depois alargue ao catálogo completo. Em PaaS, confirme também que o consumidor async.operations.all está ativo antes de cada carga grande, porque, segundo a documentação do Adobe Commerce, uma resposta positiva indica apenas que o pedido foi aceite na fila. Do lado da Akeneo, a paginação por search-after, com o máximo de 100 itens por pedido, evita os erros 422 que a paginação por página provoca nos produtos.
Perguntas frequentes
Qual a diferença entre Adobe Commerce PaaS e SaaS para esta integração?
Muda a rota da API assíncrona, a gestão das filas de mensagens e a forma de indicar a loja. Em PaaS gere o RabbitMQ e os consumidores; em SaaS as filas correm automaticamente.
A API em lote do Adobe Commerce confirma que o produto foi gravado?
Não. Confirma apenas que o pedido foi aceite na fila. O resultado final consulta-se depois, através do identificador devolvido na resposta.
Posso usar GraphQL para ler dados do Akeneo?
Sim, a Akeneo documenta uma API GraphQL. Serve sobretudo para pedir apenas os campos necessários, mas o desenho do fluxo continua a precisar de paginação, renovação de tokens e tratamento de erros.
Preciso de um conector ou posso desenvolver à medida?
Os dois caminhos existem. O conector poupa tempo se cobrir o seu modelo e a sua versão; o desenvolvimento à medida dá controlo, mas fica sob a sua responsabilidade.
Quanto tempo demora um projeto composable?
Não há prazo único. Depende do número de sistemas envolvidos, da qualidade dos dados e do tempo de validação. A fase de definição de responsabilidades por campo é a que mais condiciona o calendário.