Integrar o Pimcore com o PrestaShop é usar o Pimcore para gerir o catálogo e o PrestaShop para o vender. O Pimcore guarda produtos, atributos, imagens e traduções; o PrestaShop recebe essa informação através do seu serviço web e trata do carrinho, do pagamento e das encomendas. O ponto crítico não é a ligação em si, mas o mapeamento de dados entre os dois modelos.
Para a empresa, a vantagem é deixar de repetir o trabalho de catálogo em cada canal. O risco é montar um conector frágil, que falha em silêncio quando um campo muda de nome. Esta ligação costuma justificar-se quando o catálogo tem muitas variantes ou atributos, e insere-se numa estratégia mais ampla de integração de PIM com ecommerce.
Neste artigo vê como funciona a API do PrestaShop segundo a documentação oficial, como mapear os dados, que passos seguir, que riscos aparecem com mais frequência e uma lista de verificação para validar antes de arrancar.
Quando compensa integrar o Pimcore com o PrestaShop
Compensa quando editar produtos diretamente no PrestaShop já é um gargalo. O sinal mais fiável é a equipa gastar mais tempo a corrigir fichas do que a melhorá-las.
- o catálogo tem muitas combinações de tamanho, cor ou material
- os dados de produto vêm de fornecedores em formatos diferentes
- há mais de uma loja ou mais de um idioma a manter
- o mesmo catálogo tem de alimentar outros canais além do PrestaShop
Para um catálogo pequeno, o importador nativo do PrestaShop, com um ficheiro bem preparado, costuma bastar. Pode comparar a mesma decisão com outros PIM em Akeneo com PrestaShop e Plytix com PrestaShop.
Como funciona a API do PrestaShop
O PrestaShop expõe um serviço web em /api/, na raiz da instalação. Segundo a documentação oficial, a chave de acesso funciona como nome de utilizador e não há palavra-passe. A forma recomendada de a enviar é o cabeçalho de autorização básica, com a chave seguida de dois pontos. Colocar a chave no endereço é possível, mas a documentação indica o cabeçalho como a forma mais segura.
Os direitos são definidos por recurso. Ao consultar /api/ com uma chave, o PrestaShop devolve a lista de recursos a que ela tem acesso e os métodos permitidos em cada um: leitura, criação, alteração, alteração parcial, eliminação e consulta de cabeçalho. Sem permissões atribuídas, o acesso é recusado.
A documentação indica ainda que o formato por defeito é XML e que se pode pedir JSON com o parâmetro output_format ou com um cabeçalho próprio. Cada recurso tem um esquema em branco e um esquema com sinopse, que indicam os campos, os obrigatórios e os tamanhos máximos. Este esquema é a melhor base para construir o mapeamento.
Em servidores Apache, a documentação lembra que o módulo mod_rewrite tem de estar ativo e que o ficheiro .htaccess tem de ser processado, para que o endereço /api/ funcione. Se o conector devolver erros de endereço logo no primeiro teste, esta é a primeira coisa a verificar.
Na versão 9, a documentação apresenta também uma nova API de administração, construída sobre o API Platform 3 e com autenticação OAuth 2. A documentação consultada não afirma que substitua o serviço web clássico, que continua descrito numa secção própria. Convém por isso confirmar a versão da loja e qual das duas APIs o conector vai usar.
Como é o lado do Pimcore
Do lado do Pimcore, o Datahub fornece a origem dos dados. Segundo a documentação, inclui por defeito uma API GraphQL, com um esquema por endpoint e áreas de trabalho que limitam o que cada endpoint expõe. O endereço segue o formato /pimcore-graphql-webservices/ com o nome da configuração, e a chave de API vai como parâmetro.
Quando os dados de produto chegam de fornecedores, o módulo de importação do Pimcore lê CSV, JSON, XML e XLSX a partir de fontes como SFTP ou HTTP, escreve nos objetos com um mapeamento configurável e ignora registos sem alterações. Assim, o Pimcore limpa e consolida os dados antes de qualquer envio para a loja.
Mapeamento de dados entre Pimcore e PrestaShop
| Pimcore | PrestaShop | Cuidado |
|---|---|---|
| Produto base | Produto | Referência única |
| Variantes | Combinações | Atributos criados antes |
| Categorias | Categorias | Árvore igual nos dois |
| Imagens | Imagens do produto | Enviar depois do produto |
| Idioma | Idioma da loja | Identificador correto |
A ordem de criação importa. No PrestaShop, os atributos e os seus valores têm de existir antes de se criarem as combinações, e o produto tem de existir antes de lhe associar imagens. Um conector que envie tudo de uma vez falha nos casos em que a dependência ainda não existe.
Também convém decidir quem é o dono do stock e dos preços. Se vêm do ERP, não devem passar pelo Pimcore. Veja como se organiza essa ligação em Microsoft Dynamics 365 com PrestaShop ou em Odoo com PrestaShop.
Passos para integrar o Pimcore com o PrestaShop
- Confirmar a versão do PrestaShop e a API que vai ser usada.
- Criar uma chave de acesso com direitos apenas nos recursos necessários.
- Ler o esquema de cada recurso e fechar o mapeamento por escrito.
- Criar no PrestaShop os atributos, valores e categorias de que o catálogo depende.
- Configurar o endpoint do Datahub com esquema e área de trabalho mínimos.
- Testar com uma amostra que inclua variantes, imagens grandes e caracteres especiais.
- Fazer a carga completa e rever os erros um a um.
- Passar à sincronização incremental com registo e alertas.
O que testar na carga de ensaio
A amostra de ensaio deve incluir os casos difíceis, não só os produtos simples. Escolha um produto com muitas combinações, um sem imagem, um com caracteres especiais no nome e um com descrição muito longa. Se estes passarem, os restantes costumam passar.
Depois de cada ensaio, compare os produtos nos dois sistemas campo a campo e registe as diferenças. Esse registo serve de base ao ajuste do mapeamento e, mais tarde, de prova de que a carga completa foi validada antes de chegar aos clientes.
Riscos mais comuns
| Risco | Sinal | Prevenção |
|---|---|---|
| Chave com direitos a mais | Acesso a recursos sem uso | Permissões mínimas |
| Atributos em falta | Combinações recusadas | Criar atributos primeiro |
| Formato errado | Respostas em XML inesperadas | Pedir JSON de forma explícita |
| Imagens falhadas | Produtos sem foto | Validar ficheiros antes |
| Alterações na loja | Dados que revertem | Bloquear edição manual |
Em PrestaShop, a chave de acesso merece cuidado especial. Como não tem palavra-passe, quem a tiver tem os direitos que lhe foram atribuídos. A documentação oficial pede que se tenha extremo cuidado com os direitos da chave e com quem a recebe, e a prática correta é criar uma chave por integração.
O risco de SEO também existe. Se o conector reescrever títulos, descrições ou endereços de produtos já indexados, a loja pode perder posições. Decida antes da primeira carga quais campos o Pimcore controla e quais ficam protegidos na loja.
Lista de verificação antes de arrancar
- a versão do PrestaShop e a API escolhida estão confirmadas
- existe uma chave por integração, com os direitos mínimos
- o servidor tem o reencaminhamento de endereços ativo para /api/
- os atributos, valores e categorias existem antes das combinações
- o mapeamento foi fechado a partir dos esquemas oficiais
- há um ambiente de ensaio com cópia do catálogo
- os endereços e títulos otimizados existentes estão protegidos
- os erros ficam registados e alguém os revê
Como trabalhamos na Avafa
Partimos do esquema dos dois lados e fechamos o mapeamento por escrito antes de qualquer código. Depois testamos com uma amostra real e só então fazemos a carga completa, sempre com atenção ao que já está indexado. Conheça a nossa agência especializada em integrações de catálogos.
Perguntas frequentes
O PrestaShop aceita JSON na API?
Aceita. Segundo a documentação oficial, o formato por defeito é XML e o JSON pede-se com um parâmetro ou com um cabeçalho no pedido.
Como se autentica um conector no PrestaShop?
Com a chave de acesso como nome de utilizador e sem palavra-passe. A documentação recomenda enviá-la no cabeçalho de autorização e não no endereço.
Onde vejo os campos obrigatórios de cada recurso?
Nos esquemas do próprio serviço web, que indicam os campos, os obrigatórios e os tamanhos máximos. É a melhor referência para o mapeamento.
Devo usar a nova API de administração da versão 9?
Depende do que o conector precisa. A documentação consultada não diz que ela substitua o serviço web clássico, pelo que convém validar os recursos de que o projeto depende.
O Pimcore tem um conector pronto para o PrestaShop?
Na documentação consultada do Datahub não consta um conector para o PrestaShop. A ligação faz-se por código à medida ou por uma ferramenta de integração.