Integrar o Akeneo com o PrestaShop é fazer do Akeneo PIM a fonte única dos dados de produto e enviá-los para o catálogo da loja PrestaShop através das APIs dos dois sistemas. A Akeneo expõe uma API REST protegida por OAuth e o PrestaShop expõe o seu Webservice. A ligação entre ambos faz-se com um módulo ou com uma camada intermédia que traduz atributos, famílias, categorias e imagens.
Para o negócio, a diferença está na manutenção do catálogo. Com centenas ou milhares de referências, atualizar fichas diretamente na loja leva a descrições diferentes por idioma, atributos em falta e erros que chegam aos clientes e aos canais de venda. Na Avafa tratamos este tipo de projeto dentro da nossa área de integração de PIM com ecommerce, e este guia resume o que decidir antes de arrancar.
Vamos ver quando compensa, como se preparam os dois acessos, que dados seguem em cada sentido, que riscos aparecem e como escolher entre módulo, script próprio ou plataforma de integração.
Quando compensa ligar o Akeneo ao PrestaShop?
Compensa quando o catálogo é grande, tem muitos atributos ou é vendido em mais do que um canal. Se tem poucas dezenas de produtos e uma só loja, o PrestaShop sozinho costuma bastar e o PIM acrescenta custo sem retorno claro.
Há três sinais de que o PIM já faz falta:
- a mesma informação de produto é mantida em folhas de cálculo, no ERP e na loja ao mesmo tempo;
- cada novo idioma ou canal obriga a repetir trabalho manual;
- os erros de dados só são detetados depois de publicados, e não antes.
Se o seu caso é mais um problema de estrutura de dados do que de ferramenta, vale a pena começar pelo guia sobre como integrar o Akeneo com WooCommerce, que mostra a mesma lógica noutra plataforma e ajuda a comparar esforços.
Como se prepara o acesso à API da Akeneo
O acesso à API da Akeneo faz-se criando uma ligação (connection) no próprio PIM. Segundo a documentação da API da Akeneo, o PIM gera um identificador de cliente (client ID), um segredo, e um utilizador e palavra-passe de API para essa ligação. A palavra-passe só é mostrada uma vez, embora possa ser regenerada.
Com estes dados, o sistema de integração pede um token ao endpoint /api/oauth/v1/token, usando o tipo de concessão por palavra-passe. Por defeito, o token de acesso dura uma hora e o token de renovação 14 dias, segundo a mesma documentação. Por isso a integração tem de renovar tokens sozinha e tratar o caso em que o token de renovação já expirou.
Para ler produtos em volume, a documentação recomenda a paginação search-after em vez da paginação por página. O limite máximo é de 100 itens por pedido e, com a paginação por página, pedir a página 101 com 100 itens devolve um erro 422 nos produtos. Uma integração desenhada com paginação por página falha precisamente nos catálogos grandes.
Como se prepara o Webservice do PrestaShop
O Webservice do PrestaShop tem de ser ativado no back office, em Parâmetros avançados, na página Webservice, com a opção de ativar o Webservice do PrestaShop. Depois cria-se uma chave de acesso nessa mesma página, que pode ser gerada pelo sistema ou definida com 32 caracteres.
As permissões definem-se por recurso, e a documentação para programadores do PrestaShop avisa para não dar todos os direitos de todos os recursos a nenhuma chave. Na prática, a chave da integração deve poder escrever apenas no que a integração altera, como produtos e categorias, e ler o que precisa de consultar. Cada chave pode ser desativada a qualquer momento, o que dá uma saída rápida se algo correr mal.
Se a loja usa vários contextos de loja (multiloja), a chave também se associa à loja correta. Convém confirmar isto antes do primeiro envio, para não publicar dados na loja errada.
Que dados vão do Akeneo para o PrestaShop
O sentido normal é do Akeneo para o PrestaShop: o PIM manda nos dados descritivos e a loja recebe-os. Preços, stock e dados de encomenda dependem do ERP e não devem ser inventados pelo PIM. A tabela resume uma divisão típica, que deve ser confirmada em cada projeto.
| Dado | Origem | Destino na loja | Cuidado |
|---|---|---|---|
| Descrições e atributos | Akeneo | Ficha de produto e características | Mapear por família |
| Variantes de produto | Akeneo | Combinações | Definir eixos antes |
| Categorias | Akeneo | Árvore de categorias | Uma árvore de referência |
| Imagens e ficheiros | Akeneo | Galeria do produto | Ordem e formato |
| Preço e stock | ERP | Ficha de produto | Fora do PIM |
| Encomendas | PrestaShop | ERP | Sentido inverso |
A regra que evita mais problemas é simples: cada campo tem uma só origem. Se o preço pode ser editado no PIM e no ERP, mais cedo ou mais tarde um deles apaga o outro. A separação entre ambiente de testes e produção, que detalhamos no guia sobre Akeneo com Magento, aplica-se também aqui.
Que riscos tem esta integração e como se evitam
Os riscos mais comuns vêm do comportamento da API e do desenho do fluxo, não da ligação em si. A documentação da Akeneo explica que uma atualização parcial (PATCH) só altera as chaves enviadas, mas que valores que não são objetos substituem o valor anterior. Assim, enviar uma lista de categorias substitui a lista inteira, e enviar um valor nulo apaga o dado nesse idioma e canal.
- Substituição de listas: envie sempre a lista completa de categorias de um produto, nunca só a nova.
- Valores nulos: distinga “campo vazio no PIM” de “campo que não deve ser enviado”.
- Tokens expirados: trate a renovação do token e repita o pedido uma vez antes de dar erro.
- Permissões largas: use uma chave de Webservice com direitos mínimos por recurso.
- Envios sem teste: valide primeiro num ambiente de testes com uma cópia do catálogo.
Um erro típico é testar com 20 produtos e descobrir em produção, com 20 000, que a paginação ou os tempos de resposta não aguentam. Por isso o ensaio deve usar o volume real, ou perto disso.
Módulo, script próprio ou plataforma de integração
A escolha depende do volume, da equipa técnica e de quanto o fluxo vai mudar. Qualquer que seja a opção, deve confirmar quem a mantém, que versões do PrestaShop e da Akeneo suporta e o que acontece quando uma delas é atualizada.
| Opção | Quando serve | Principal risco |
|---|---|---|
| Módulo de terceiros | Fluxo simples e padrão | Manutenção e versões |
| Script à medida | Regras específicas | Depende de quem o escreveu |
| Plataforma de integração | Vários sistemas ligados | Custo e curva de aprendizagem |
Para lojas com um só PIM e uma só loja, um módulo bem mantido costuma bastar. Quando entram ERP, vários idiomas e regras por canal, uma camada intermédia dá mais controlo, mas pede um responsável técnico. Em todos os casos, peça por escrito o que está incluído. Se a arquitetura da loja for composable, veja também o guia sobre Akeneo com Adobe Commerce.
Lista de verificação antes de arrancar o projeto
- Defina, campo a campo, qual é o sistema que manda: PIM, ERP ou loja.
- Crie a ligação na Akeneo e guarde o segredo e a palavra-passe de API num local seguro.
- Ative o Webservice do PrestaShop e crie uma chave com permissões mínimas.
- Mapeie famílias e atributos do Akeneo para características e combinações.
- Escolha a paginação search-after para a leitura de produtos.
- Teste a renovação de tokens e o comportamento com erros 422.
- Ensaie com uma cópia do catálogo e com o volume real.
- Defina quem recebe os alertas quando um envio falha.
Como trabalhamos na Avafa
Começamos por mapear dados e responsáveis, só depois escolhemos a forma de ligação. Revemos o desenho do fluxo e o contrato com o fornecedor antes de qualquer desenvolvimento, para que o projeto não arranque com dois sistemas a escrever o mesmo campo. Se quiser uma segunda opinião antes de assinar, 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 Adobe Commerce
- Integrar Akeneo com WooCommerce
- Integrar Akeneo com SAP Commerce Cloud
- Integrar Akeneo com BigCommerce
- Integrar Akeneo com Salesforce Commerce Cloud
Perguntas frequentes
O que é preciso para ligar o Akeneo ao PrestaShop?
São precisos um acesso à API da Akeneo (ligação com client ID, segredo e utilizador de API), um Webservice ativo no PrestaShop com uma chave, e um módulo ou camada intermédia que faça o mapeamento e o envio.
A ligação é em tempo real?
Depende do desenho. É comum correr em lotes agendados, porque simplifica o controlo de erros e evita sobrecarregar a loja. O tempo real só se justifica quando os dados mudam várias vezes por hora e isso tem impacto na venda.
Posso enviar também preços e stock a partir do PIM?
Pode, mas não é recomendável. Preços e stock costumam vir do ERP, e ter duas origens para o mesmo campo cria conflitos. O PIM deve ficar com os dados descritivos.
O que acontece se o token de acesso expirar?
Por defeito, o token de acesso da Akeneo dura uma hora. A integração deve usar o token de renovação para obter um novo e repetir o pedido, sem intervenção humana.
Quanto tempo demora um projeto destes?
Não há um prazo único. Depende do número de famílias de produto, de idiomas, de imagens e da qualidade dos dados de origem. A fase de mapeamento é a que mais condiciona o calendário.