# Conector Odoo: guia completo

> Instalar, ligar e explorar o Conector Odoo: chave API, definições por separador, sincronização inicial, cron, webhooks Odoo, fila resiliente, antiduplicados e resolução de problemas para PrestaShop 8 e 9.

- Página: <https://www.datafirefly.com/pt/documentation/connecteur-odoo/>
- Idioma: pt
- Atualizado em: 2026-10-09
- Outros idiomas: [fr](https://www.datafirefly.com/documentation/connecteur-odoo/index.md), [en](https://www.datafirefly.com/en/documentation/odoo-connector/index.md), [es](https://www.datafirefly.com/es/documentation/conector-odoo/index.md), [de](https://www.datafirefly.com/de/documentation/odoo-konnektor/index.md), [it](https://www.datafirefly.com/it/documentation/connettore-odoo/index.md), [pl](https://www.datafirefly.com/pl/documentation/connecteur-odoo/index.md), [nl](https://www.datafirefly.com/nl/documentation/connecteur-odoo/index.md)
- Índice: <https://www.datafirefly.com/pt/documentation/llms.txt>

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.

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.

Instale a aplicação **Inventário** no Odoo _antes_ de enviar os seus produtos. A partir do Odoo 18, o controlo do stock de um artigo depende desta aplicação: os artigos criados sem ela não teriam controlo de stock.

## 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.

Um utilizador dedicado (por exemplo, «PrestaShop Sync») em vez de uma conta de administrador pessoal dá-lhe um histórico claro no Odoo e permite revogar o acesso a qualquer momento.

## 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**.

Por segurança, a chave API guardada nunca é enviada para um endereço, base de dados ou utilizador diferente dos que estão guardados: para testar outro servidor, introduza a respetiva chave API.

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`.

Sem diário configurado, o pagamento não é registado: o histórico indica-o com um aviso que menciona o módulo de pagamento em causa.

**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

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-` sem referência), os artigos com combinações pelas referências das suas variantes e as encomendas pela sua origem.

Comece com o **modo de teste** ativado: cada operação é registada no histórico sem escrever nada no Odoo. Desative-o depois de verificar o resultado.

## 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.

Um pedido sem token válido é recusado com um código 403. Pode ainda restringir os endereços IP autorizados no separador Ligação.

## 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.