Conector Odoo: guia completo

O Conector Odoo sincroniza em tempo real e nos dois sentidos os seus produtos e combinações, o seu stock, os seus clientes, as suas encomendas, as suas faturas e os seus envios entre o PrestaShop e o Odoo. Este guia cobre a instalação, a ligação, cada separador de definições, a sincronização inicial, o cron, os webhooks Odoo e a resolução de problemas.

Pré-requisitos

• PrestaShop 8.0 a 9.x.
• PHP 7.4 a 8.5 com a extensão cURL.
• Odoo 14 a 20, autoalojado, Odoo.sh ou Odoo Online, acessível a partir do seu servidor PrestaShop. No Odoo Online, o seu plano tem de incluir o acesso à API externa.
• As aplicações Odoo Vendas e Inventário, mais Faturação se criar as faturas. A aplicação Entrega é necessária para devolver o número de seguimento ao PrestaShop.
• Um utilizador Odoo dedicado, com permissões de Vendas, Inventário e Faturação, e uma chave API.

Instalação e atualização

1. No back-office, abra Módulos > Gestor de módulos, clique em Carregar um módulo e largue o ficheiro zip do módulo.
2. Abra depois a configuração através do botão Configurar ou do menu Odoo Connector.

Para atualizar, carregue a nova versão da mesma forma: o PrestaShop executa a atualização e as suas definições, a sua chave API e os seus mapeamentos são preservados.

Gerar uma chave API no Odoo

1. Inicie sessão no Odoo com o utilizador dedicado à sincronização.
2. Clique no seu avatar, depois em O meu perfil (ou Preferências), separador Segurança da conta, e em Nova chave API.
3. Copie a chave: só é apresentada uma vez.

Separador Ligação

• URL do Odoo: o endereço da sua instância, começando por https:// (ou http://), por exemplo https://a-minha-empresa.odoo.com.
• Base de dados: o nome exato da base de dados do Odoo.
• Utilizador: o login (muitas vezes o e-mail) do utilizador dedicado.
• Chave API: guardada encriptada. Deixe o campo vazio para manter a chave atual.

Clique em Testar a ligação: o módulo apresenta a versão do Odoo, o utilizador e a empresa. Clique depois em Carregar listas do Odoo para escolher em listas a empresa, o armazém, a localização, a equipa de vendas, o vendedor e o diário de pagamento. Guarde e, em seguida, assinale Ativar a sincronização.

O mesmo separador propõe também o processamento em tempo real (as alterações partem logo após a apresentação da página ao visitante; se estiver desativado, é o cron que as envia), o modo de teste, o histórico detalhado, a lista de IP autorizados para o webhook e a ativação de cada fluxo: clientes, produtos, stock, encomendas.

Separador Produtos

• Sentido dos produtos: PrestaShop para Odoo, Odoo para PrestaShop, ou nos dois sentidos.
• Imagem de capa, árvore de categorias (com a categoria Odoo superior) e preço de compra enviado como custo (a desativar se o Odoo calcular os custos por custo médio ou FIFO).
• Arquivar as variantes Odoo ausentes no PrestaShop.
• Mapeamento de campos adicionais: uma linha por campo, no formato odoo_field=prestashop_field.
• Odoo para PrestaShop: preço, nome, referência e EAN13, estado ativo, à escolha.
• Importar os novos produtos Odoo: os artigos vendáveis criados no Odoo são criados no PrestaShop, com as suas variantes como combinações, na categoria e na regra de impostos escolhidas, ativos ou não.

Separador Stock

• Mestre do stock: Odoo (recomendado), PrestaShop, ou ambos. Os movimentos associados às encomendas nunca são contados duas vezes.
• Quantidade enviada para o PrestaShop: a quantidade disponível para venda (descontadas as reservas, recomendado para evitar vender acima do stock) ou a quantidade em stock.
• Armazém Odoo, aplicado também às encomendas, e localização específica opcional.

Separador Encomendas

• Envio das encomendas para o Odoo: assim que são criadas ou só depois de pagas, com uma data antes da qual as encomendas são ignoradas.
• Confirmar o orçamento Odoo na encomenda ou no pagamento: a confirmação cria a ordem de entrega no Odoo.
• Impostos: taxas do PrestaShop (são usados os impostos Odoo com a mesma taxa e os totais coincidem) ou deixar o Odoo calcular (impostos dos artigos e posições fiscais do Odoo).
• Estados PrestaShop que cancelam a encomenda Odoo, equipa de vendas e vendedor.
• As entregas no Odoo atualizam o PrestaShop: na validação da entrega, a encomenda passa ao estado escolhido (Enviado por predefinição) com o número de seguimento, e o cliente recebe o e-mail de envio.
• Os cancelamentos no Odoo atualizam o PrestaShop.

Cada linha de encomenda aponta para a variante Odoo da combinação. Os portes, o embrulho para oferta e os descontos são acrescentados em linhas distintas, sendo os descontos repartidos por taxa de imposto. O módulo compara o total do Odoo com o do PrestaShop e assinala qualquer diferença no histórico.

Separador Faturação

• Faturas Odoo: não criar, criar como rascunho, ou criar e validar. A fatura é criada a partir da encomenda confirmada, na encomenda ou no pagamento.
• Registar o pagamento no Odoo: a fatura validada de uma encomenda paga é marcada como paga no diário correspondente.
• Diário de pagamento predefinido e diário por módulo de pagamento: uma linha por módulo, no formato module_name=journal_id, por exemplo stripe_official=7.

Sincronização inicial

Numa loja já existente, preencha o Odoo a partir do separador Ferramentas, por esta ordem:

1. Enviar todos os clientes.
2. Enviar todos os produtos.
3. Importar todo o stock Odoo, se o Odoo for o mestre do stock.
4. Enviar encomendas efetuadas desde uma data.

As tarefas partem por lotes através do cron. Se o seu catálogo ou os seus clientes já existirem no Odoo, são encontrados em vez de recriados: os clientes pelo e-mail, as moradas pela sua referência, os artigos simples pela sua referência (ou PS-<id> sem referência), os artigos com combinações pelas referências das suas variantes e as encomendas pela sua origem.

Cron

O cron processa a fila de espera e lê as alterações feitas no Odoo (stock, produtos, entregas, cancelamentos). Agende-o a cada 1 a 5 minutos com o URL apresentado no painel de controlo:

curl -s "https://a-sua-loja.com/module/dfodooconnect/cron?token=O_SEU_TOKEN"

ou, sem limite de duração HTTP, em linha de comandos no servidor:

php /caminho/para/prestashop/modules/dfodooconnect/cron.php

Nunca correm duas execuções em simultâneo. O botão Sincronizar agora do painel de controlo lança uma execução imediata.

Webhooks Odoo (tempo real a partir do Odoo)

Sem webhook, o cron lê as alterações do Odoo em cada execução. Para um retorno imediato, a partir do Odoo 17, crie sem código uma regra por modelo em Definições > Técnico > Regras de automatização:

• Modelos: Produto, Variante de produto, Quant ou Movimento de stock, Transferência, Encomenda de venda.
• Acionador: Ao guardar.
• Ação: Enviar notificação webhook para o URL do webhook apresentado no painel de controlo.

O token é obrigatório: o URL do webhook apresentado no painel de controlo já o contém (?token=). Para os seus próprios scripts, pode também ser enviado no cabeçalho X-DF-Token. O conteúdo recebido nunca é aplicado tal como está: indica apenas que registo mudou, e o módulo volta a lê-lo no Odoo através da API.

Painel de controlo e acompanhamento

O painel de controlo indica o estado de saúde (última execução do cron, última chamada ao Odoo bem-sucedida, tarefa em espera mais antiga, erros e avisos nas últimas 24 h), os contadores da fila (Pendente, A repetir, Em quarentena, Concluídas) e o número de registos associados. Os separadores Fila, Mapeamentos e Histórico são filtráveis, e um painel Odoo nas fichas de encomenda, produto e cliente propõe um botão Sincronizar agora.

A fila de espera resiliente

Cada alteração é colocada numa fila processada depois do envio da página ao cliente: o túnel de encomenda nunca espera pelo Odoo. Em caso de falha, a tarefa é repetida com um intervalo crescente (de 1 minuto a 24 horas); depois do número de tentativas configurado (8 por predefinição), passa a quarentena e pode ser repetida com um clique. Se o Odoo deixar de responder, um disjuntor suspende as chamadas e guarda as tarefas sem consumir as suas tentativas, e a sincronização retoma sozinha quando o Odoo volta a estar disponível.

Mudar de base de dados Odoo

Se passar de uma base de dados Odoo para outra (base de teste para produção, migração), o módulo deteta-o graças ao identificador único da base. Esquece então os mapeamentos e as definições próprias da base anterior (empresa, armazém, localização, equipa, vendedor, diário) e indica-o com uma mensagem: recarregue as listas do Odoo e verifique as definições. Na sincronização seguinte, os registos da nova base são encontrados pelas suas referências.

Campos sincronizados

Clientes

Contacto Odoo com nome (ou empresa), e-mail, número de IVA, SIRET, país, região, idioma e telefone. As moradas de faturação e de entrega tornam-se contactos filhos no momento do envio das encomendas. Um número de IVA recusado pelo Odoo não impede o envio: o contacto é criado sem IVA e é acrescentado um aviso ao histórico.

Produtos e combinações

Nome, preço sem impostos, custo, peso convertido em kg, referência, código de barras, imposto à mesma taxa (imposto de serviços para os produtos virtuais), categoria e imagem. Cada combinação está ligada a uma variante Odoo; os atributos e os respetivos valores são criados quando necessário. Um produto sem alterações não é reescrito no Odoo.

Stock

Por combinação, no armazém ou na localização escolhida.

Encomendas

Cliente, moradas de faturação e de entrega, linhas por variante, portes, embrulho para oferta, descontos, moeda através de lista de preços, armazém, equipa e vendedor.

Resolução de problemas

• «Authentication refused by Odoo»: o utilizador ou a chave API está incorreto, ou a chave foi revogada. Gere uma nova chave.
• «Odoo closed the connection: check the database name»: a base de dados indicada não existe neste servidor.
• «Odoo redirects this URL»: use o endereço indicado na mensagem (muitas vezes a versão https://).
• «No Odoo sale tax at 20%»: crie no Odoo um imposto de venda à taxa indicada, em percentagem e não incluído no preço.
• «No Odoo payment journal for payment module…»: escolha um diário de pagamento predefinido ou por módulo no separador Faturação.
• O número de seguimento não chega ao PrestaShop: instale a aplicação Entrega no Odoo. O estado Enviado funciona sem ela.
• «Total mismatch»: o total do Odoo difere do do PrestaShop; verifique os impostos Odoo correspondentes às taxas da encomenda.
• O stock ou as entregas não chegam ao PrestaShop: verifique se o cron está a ser executado (data da última execução do cron no painel de controlo) e o sentido configurado.
• Uma tarefa está em quarentena: leia a respetiva mensagem no separador Fila, corrija a causa e volte a executá-la.

Desinstalação

A desinstalação elimina as tabelas de mapeamento, de fila e de histórico, bem como as definições do módulo. Os seus dados no Odoo não são alterados. Em caso de reinstalação, os registos existentes no Odoo são encontrados pelas suas referências, sem duplicados.