Conector Odoo: guia completo
Instalar, configurar e explorar a sincronização em tempo real PrestaShop ⇄ Odoo (produtos, stock, encomendas, clientes) para PrestaShop 8 e 9.
O Conector Odoo sincroniza em tempo real e nos dois sentidos os seus produtos, o seu stock, as suas encomendas e os seus clientes entre o PrestaShop e o Odoo. Este guia cobre a instalação, a ligação ao Odoo, a escolha do sentido de sincronização, a sincronização inicial, o cron, o webhook de entrada e a resolução de problemas.
Pré-requisitos
- PrestaShop 8.0 a 9.x.
- PHP 7.4 a 8.3 com a extensão cURL ativa.
- Uma instância Odoo 14 a 18 (na cloud ou autoalojada) acessível por HTTPS a partir do seu servidor PrestaShop.
- Um utilizador Odoo com uma chave de API e permissões nos modelos de Vendas, Inventário e Contactos.
O módulo comunica com o Odoo através de JSON-RPC. A extensão PHP xmlrpc, retirada do PHP 8, não é necessária.
Instalação
- No back-office, abra Módulos > Gestor de módulos e depois Carregar um módulo e envie o ficheiro
dfodooconnect.zip. - Depois de instalado, abra a página de configuração através do botão Configurar ou do separador Odoo Connector no menu de administração.
Gerar uma chave de API no Odoo
- Inicie sessão no Odoo com a conta de serviço dedicada à sincronização.
- Abra Preferências > Segurança da conta > Chaves API e gere uma nova chave.
- Copie a chave: substitui a palavra-passe na configuração do módulo.
Crie um utilizador Odoo dedicado (por exemplo, «PrestaShop Sync») em vez de usar uma conta de administrador pessoal. Assim mantém um registo de auditoria claro do lado do Odoo.
Ligação ao Odoo
Na página de configuração, preencha os quatro campos do bloco Ligação Odoo:
- URL do Odoo: o endereço completo da sua instância, por exemplo
https://o-meu-odoo.com. - Base de dados: o nome exato da base de dados do Odoo.
- Utilizador: o identificador (login) da conta de serviço.
- Chave de API: a chave gerada na etapa anterior.
Clique em Testar a ligação. Em caso de sucesso, o módulo apresenta a versão do Odoo detetada e o identificador de utilizador (uid). Grave e assinale depois Ativar a sincronização.
Enquanto a caixa Ativar a sincronização não estiver assinalada, não é enviado qualquer dado ao Odoo, mesmo que a ligação seja válida.
Escolher as entidades e o sentido de sincronização
São geridas quatro entidades. Em cada uma, ativa ou desativa a sincronização; nos produtos e no stock, escolhe além disso o sentido.
- Clientes: do PrestaShop para o Odoo (contactos
res.partner). - Produtos: do PrestaShop para o Odoo, do Odoo para o PrestaShop, ou bidirecional.
- Stock: do PrestaShop para o Odoo, do Odoo para o PrestaShop, ou bidirecional.
- Encomendas: do PrestaShop para o Odoo (notas de encomenda
sale.order).
Duas opções completam o comportamento das encomendas: Confirmar automaticamente a encomenda no Odoo (passa o orçamento a nota de encomenda confirmada) e Gerar a fatura no Odoo.
Nota para Portugal — A opção de geração de faturas produz um documento no Odoo, segundo a configuração fiscal da sua instância. Se a sua empresa estiver obrigada a emitir faturas com SAF-T (PT), ATCUD e software certificado pela Autoridade Tributária, verifique com o seu integrador Odoo que a instância está configurada para o mercado português antes de ativar esta opção. O conector transmite os dados da encomenda; não certifica a faturação.
Sincronização inicial
Antes de ativar o fluxo em tempo real numa loja já existente, preencha o Odoo com os seus dados atuais a partir do bloco Sincronização inicial:
- Exportar todos os clientes: coloca cada cliente na fila de exportação.
- Exportar todos os produtos: necessário antes do stock e das encomendas, porque as linhas de encomenda e os ajustes de stock assentam na correspondência de produto.
- Exportar todas as encomendas: a lançar depois dos clientes e dos produtos.
Respeite a ordem clientes → produtos → encomendas. O módulo trata automaticamente as dependências em falta (coloca um produto sem correspondência na fila antes de repetir a encomenda), mas a ordem reduz o número de repetições.
Configuração do cron
O cron esvazia a fila de espera (repetição dos envios falhados) e importa o stock a partir do Odoo, quando esse sentido está ativado. Agende o URL fornecido no bloco Endpoints, a cada 1 a 5 minutos:
curl "https://a-sua-loja.com/module/dfodooconnect/cron?token=O_SEU_TOKEN"O token é gerado automaticamente na instalação e apresentado na configuração.
Webhook de entrada (do Odoo para o PrestaShop)
Para que as alterações feitas no Odoo desçam em tempo real, crie uma Ação automatizada no Odoo (ação de servidor do tipo webhook) que envie um pedido POST em JSON para o URL de webhook do módulo.
Atualização de stock:
{ "token": "O_SEU_TOKEN", "entity": "stock", "odoo_id": 42, "qty": 17 }Mudança de estado de encomenda:
{ "token": "O_SEU_TOKEN", "entity": "order_state", "odoo_id": 99, "state": "cancel" }Os estados reconhecidos são cancel, sale e done, correspondidos respetivamente a Anulada, Em preparação e Entregue do lado do PrestaShop.
O token do webhook tem de ser idêntico ao apresentado na configuração. Um pedido sem token válido é recusado com um código 403.
Painel e registo
O painel apresenta permanentemente quatro indicadores de fila (Pendentes, Sincronizados, Com erro, Abandonados), o número de correspondências por entidade e um registo de atividade com data e hora. Estão disponíveis duas ações de manutenção: Processar a fila agora e Importar o stock do Odoo.
A fila de espera resiliente
Cada alteração no PrestaShop é primeiro colocada numa fila e depois enviada de imediato ao Odoo em modo «best effort». Se o Odoo estiver inacessível, o trabalho fica em fila e o cron repete-o automaticamente. Ao fim do número de tentativas configurado (5 por predefinição), um trabalho definitivamente falhado passa a quarentena (Abandonado), para não bloquear o resto da fila.
É este mecanismo que garante que uma indisponibilidade do Odoo nunca bloqueia o processo de encomenda dos seus clientes.
Campos sincronizados
Clientes
Nome, e-mail, empresa, referência, morada predefinida (rua, localidade, código postal, telefone), número de IVA e país. A comparação antiduplicados é feita pelo e-mail.
Produtos
Nome, referência interna, preço de venda, preço de compra, peso, código de barras, descrição curta e estado ativo. A comparação antiduplicados é feita pela referência.
Stock
As quantidades disponíveis são transpostas através de um ajuste de inventário no local do Odoo configurado (ou no primeiro local interno, se não indicar nenhum).
Encomendas
Parceiro, referência do cliente, linhas de encomenda (produto, quantidade, preço unitário sem impostos) e portes. O cliente é sincronizado na altura, se ainda não o tiver sido.
Modo de teste (dry-run)
Ative o Modo de teste para validar o mapeamento sem escrever nada no Odoo: cada operação fica registada no registo com a menção DRY-RUN, mas nenhum dado é criado nem alterado. Ideal para uma validação antes da entrada em produção.
Resolução de problemas
- O teste de ligação falha: verifique o URL (com https), o nome exato da base de dados, o login e a chave de API. Certifique-se de que o servidor PrestaShop consegue alcançar a instância Odoo em saída.
- Uma encomenda fica pendente: provavelmente um produto da encomenda ainda não tem correspondência. O módulo coloca o produto na fila; volte a clicar em «Processar a fila agora» ao fim de alguns segundos.
- O stock não sobe para o PrestaShop: verifique se o sentido do stock inclui do Odoo para o PrestaShop e se o cron está a ser executado.
- Duplicados do lado do Odoo: certifique-se de que as referências de produto e os e-mails dos clientes estão preenchidos; são as chaves de comparação.
Desinstalação
A desinstalação elimina as tabelas de correspondência, de fila e de registo do módulo. Os seus dados no Odoo não são afetados. Para uma simples atualização, basta substituir os ficheiros: o esquema e as correspondências são preservados.