Integrar o Akeneo com o WooCommerce é usar o Akeneo PIM como origem dos dados de produto e enviá-los para a loja WooCommerce através da API REST de cada sistema. O Akeneo guarda e enriquece o catálogo; o WooCommerce recebe produtos, variações e categorias prontos a publicar.
Para a empresa, o ganho é deixar de editar fichas à mão na loja. O WooCommerce é flexível, mas não foi pensado para gerir centenas de atributos por produto em vários idiomas. Na Avafa tratamos esta ligação dentro da nossa área de integração de PIM com ecommerce, e este guia explica o que preparar em cada lado e onde costumam surgir os problemas.
Cobre quando compensa, a autenticação das duas APIs, o tratamento de variações, os envios em lote, os riscos e uma lista de verificação para o arranque.
Quando compensa ligar o Akeneo ao WooCommerce
Compensa quando o catálogo tem muitos produtos com variações, vários idiomas ou mais de um canal de venda. Para um catálogo pequeno e estável, um PIM raramente se paga e o próprio WooCommerce chega.
Os sinais de que está na altura de avançar são claros:
- os mesmos dados são mantidos em folhas de cálculo e na loja ao mesmo tempo;
- cada produto com tamanhos ou cores obriga a repetir edições;
- as correções de uma ficha não chegam a todos os canais.
Se ainda está a escolher a plataforma de destino, compare com o guia sobre Akeneo com PrestaShop, que mostra uma preparação semelhante noutra loja.
Como se autentica a API do WooCommerce
A API REST do WooCommerce usa uma chave de consumidor (consumer key) e um segredo (consumer secret), que se geram em WooCommerce, Definições, Avançadas, API REST. Segundo a documentação oficial, cada chave pode ter permissão de leitura, escrita ou ambas, e segue as permissões do utilizador do WordPress escolhido.
Em HTTPS, a autenticação é feita por HTTP Basic, com a chave como utilizador e o segredo como palavra-passe. Em HTTP, usa-se OAuth 1.0a de uma só perna, e os pedidos com carimbo de data fora de uma janela de 15 minutos são rejeitados. Para uma integração de catálogo, só HTTPS faz sentido, porque evita expor as credenciais.
Há ainda dois requisitos que costumam falhar: a documentação indica que são precisos permalinks personalizados (“pretty permalinks”), porque os permalinks por defeito não funcionam, e que a API v3 exige o WooCommerce 3.5 ou superior e o WordPress 4.4 ou superior. Crie a chave com um utilizador próprio da integração e permissões mínimas, e não com a conta de um administrador.
Como se autentica a API do Akeneo
No Akeneo, cria-se uma ligação no PIM, que gera um client ID, um segredo e um utilizador e palavra-passe de API. A integração pede o token ao endpoint /api/oauth/v1/token. Por defeito, o token de acesso dura uma hora e o de renovação 14 dias, segundo a documentação da API da Akeneo.
Para ler produtos em volume, use a paginação search-after. O máximo é de 100 itens por pedido, e a paginação por página falha nos produtos a partir da página 101 com um erro 422. É um detalhe técnico, mas é a causa de muitas integrações que funcionam no teste e falham em produção.
Que dados vão do Akeneo para o WooCommerce
O Akeneo manda nos dados descritivos; o preço e o stock costumam vir do ERP. A tabela mostra uma divisão de partida, a ajustar a cada projeto.
| Dado | Origem | Destino | Cuidado |
|---|---|---|---|
| Título e descrição | Akeneo | Produto | Por idioma |
| Atributos | Akeneo | Atributos do produto | Mapear por família |
| Variantes | Akeneo | Variações | Definir eixos antes |
| Categorias | Akeneo | Categorias | Uma árvore única |
| Preço e stock | ERP | Produto | Fora do PIM |
Os modelos de produto e as variantes do Akeneo correspondem, em regra, a um produto variável e às suas variações no WooCommerce. A documentação da API do WooCommerce lista operações próprias para variações, incluindo atualização em lote. O desenho dos eixos (cor, tamanho) tem de ser decidido antes de enviar o primeiro produto, porque alterá-los depois obriga a recriar fichas.
Envios em lote e atualizações parciais
A API do WooCommerce tem uma operação de atualização em lote de produtos, que reduz o número de pedidos e acelera cargas grandes. A documentação consultada não indica o número máximo de objetos por pedido, por isso esse limite deve ser testado na sua instalação e respeitado pela integração.
Do lado da Akeneo, uma atualização parcial (PATCH) só altera as chaves enviadas. As listas, porém, são substituídas por inteiro: enviar uma categoria nova sem as anteriores apaga as que lá estavam. O envio de um valor nulo apaga o dado nesse idioma e canal. Estes dois detalhes, previstos na documentação da Akeneo, explicam a maioria dos “desaparecimentos” de dados em integrações recentes.
Que riscos tem esta integração e como se evitam
- Chaves com demasiadas permissões: crie chaves só com as permissões necessárias e revogue as que não usa.
- Alterações manuais na loja: se se edita na loja, a próxima carga pode apagar essa edição.
- Variações mal definidas: fixe os eixos de variação antes da primeira importação.
- Cargas pesadas em horas de pico: agende os lotes para horários de baixa procura.
- Plugins de terceiros sem manutenção: avalie quem mantém o módulo e que versões do WooCommerce e do Akeneo suporta.
Um exemplo típico: uma loja com um plugin de importação instalado há anos, que deixa de funcionar quando o WooCommerce é atualizado. Se não houver quem o mantenha, o catálogo volta à gestão manual. Por isso, a escolha do módulo é uma decisão de manutenção, não só de funcionalidade.
Lista de verificação antes de arrancar o projeto
- Atualize o WooCommerce e o WordPress para versões compatíveis com a API v3.
- Ative permalinks personalizados e confirme que o site responde em HTTPS.
- Crie uma chave de API do WooCommerce com um utilizador próprio e permissões mínimas.
- Crie a ligação no Akeneo e guarde o segredo e a palavra-passe de API em local seguro.
- Mapeie famílias, atributos e eixos de variação, e documente o que não se envia.
- Teste os lotes e descubra o limite prático de objetos por pedido.
- Ensaie com uma cópia da loja e com o volume real de produtos.
- Defina quem recebe os alertas quando um envio falha.
Como trabalhamos na Avafa
Começamos por mapear dados e responsáveis, e só depois escolhemos entre módulo, desenvolvimento à medida ou plataforma de integração. Revemos o desenho do fluxo e o contrato 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 PrestaShop
- Integrar Akeneo com Magento
- Integrar Akeneo com Adobe Commerce
- Integrar Akeneo com BigCommerce
- Integrar Akeneo com Salesforce Commerce Cloud
Antes de ligar o catálogo completo, convém validar o circuito com um grupo reduzido de produtos. Confirme que a chave de consumidor do WooCommerce tem apenas as permissões necessárias, que os permalinks personalizados estão ativos e que a versão do WooCommerce é a 3.5 ou superior, exigida pela API v3. Do lado da Akeneo, use a paginação search-after, com o máximo de 100 itens por pedido, e planeie a renovação do token, que por defeito expira ao fim de uma hora. Este teste curto evita descobrir os problemas só depois de enviar milhares de produtos.
Perguntas frequentes
Posso usar a API do WooCommerce sem HTTPS?
Pode, com OAuth 1.0a, mas não é aconselhável para uma integração de catálogo. Com HTTPS, a autenticação é mais simples e as credenciais não circulam em claro.
Como se enviam as variações de um produto?
A API do WooCommerce tem operações próprias para variações, incluindo atualização em lote. No Akeneo, os modelos de produto e as variantes são o ponto de partida do mapeamento.
Qual o limite de produtos por pedido em lote?
A documentação consultada não o indica. Teste na sua instalação, com o seu servidor, e configure a integração para respeitar o valor encontrado.
O que acontece se o token do Akeneo expirar durante uma carga?
O token de acesso dura por defeito uma hora. A integração deve usar o token de renovação para obter um novo e retomar o pedido sem intervenção.
Posso enviar também o stock a partir do PIM?
Pode, mas não é recomendável. O stock costuma vir do ERP, e duas origens para o mesmo campo geram conflitos. Deixe ao PIM os dados descritivos.