Muito poucas empresas funcionam com um único sistema. Mesmo quando o Odoo é o ERP central, normalmente tem de comunicar com um gateway de pagamento, uma transportadora, um banco, uma loja online, um dispositivo de assiduidade ou uma aplicação antiga. A qualidade dessas ligações determina se os seus dados são fiáveis ou se a equipa passa todos os meses a reconciliar diferenças à mão.
O Odoo 19 Enterprise oferece um conjunto de ferramentas em camadas: conectores integrados configurados a partir das aplicações, uma API externa para programadores, regras de automação que podem receber e enviar webhooks e importações de ficheiros para os casos em que não é possível uma ligação em tempo real. As ferramentas de middleware ficam por cima destas camadas quando é preciso orquestrar muitos sistemas.
Uma nota sobre as fontes: este artigo segue a documentação oficial do Odoo para a versão 19.0 (o repositório odoo/documentation). Os menus, as opções e as condições dos planos podem mudar entre versões e tipos de alojamento, por isso confirme sempre cada passo numa base de dados de teste ou duplicada antes de o aplicar em produção.
Escolher o padrão de integração certo
Parta da necessidade de negócio e não da tecnologia. Pergunte que dados têm de circular, em que sentido, com que rapidez e quem é o dono do registo mestre. Depois escolha a opção mais leve que satisfaz a necessidade.
- Use um conector integrado quando o Odoo já suporta o fornecedor, como um fornecedor de pagamento listado, uma transportadora, um fornecedor de sincronização bancária ou o conector Amazon.
- Use a API externa quando outra aplicação precisa de ler ou escrever registos do Odoo segundo o seu próprio calendário.
- Use um webhook de entrada quando um sistema externo deve enviar um evento para o Odoo no momento em que acontece.
- Use um webhook de saída quando o Odoo deve notificar outro sistema após uma alteração, por exemplo quando um registo é criado ou um campo é atualizado.
- Use middleware quando estão envolvidos vários sistemas, quando os dados precisam de transformações pesadas ou quando precisa de novas tentativas e monitorização centralizadas.
- Use a importação de ficheiros quando a outra parte só fornece ficheiros, como extratos bancários nos formatos CAMT.053, OFX, QIF, CSV ou XLSX.
A API externa no Odoo 19: JSON-2 e chaves de API
O Odoo 19 introduz a API JSON-2, que expõe parte do ORM por HTTP. Cada chamada é um pedido POST para um endpoint da forma /json/2/ seguido do nome do modelo e do nome do método, por exemplo o método search_read do modelo res.partner. O corpo do pedido transporta os argumentos do método em JSON.
A autenticação usa uma chave de API enviada no cabeçalho Authorization como bearer token. Não existe um passo de início de sessão separado com ID de utilizador e palavra-passe, pelo que a chave identifica o utilizador e a integração atua com os direitos de acesso desse utilizador.
Para criar uma chave manualmente, abra as Preferências do seu utilizador, vá a Segurança da Conta e escolha Nova Chave de API. São obrigatórios uma descrição e um prazo de validade, e o valor da chave só é mostrado uma vez, por isso guarde-o de imediato num cofre de segredos seguro. A documentação indica que não é possível criar chaves com validade superior a três meses, por isso planeie desde o início uma rotina de rotação de chaves.
Quando um servidor aloja várias bases de dados, o cabeçalho opcional X-Odoo-Database indica ao Odoo a base de dados a que a chamada se destina. Atrás de um reverse proxy, garanta que o cabeçalho Host chega corretamente ao Odoo.
Cada chamada JSON-2 é executada na sua própria transação de base de dados: é confirmada em caso de sucesso e revertida em caso de erro. Não é possível encadear várias chamadas numa única transação, por isso prefira um único método que faça o trabalho relacionado, como um search_read ou um método de negócio, em vez de muitas chamadas pequenas que podem deixar os dados atualizados a meio.
Os erros são devolvidos com um estado HTTP 4xx ou 5xx e um corpo JSON que inclui um nome e uma mensagem. O seu código cliente deve ler ambos e registá-los.
XML-RPC e JSON-RPC antigos: planeie a migração
Muitas integrações existentes usam os antigos endpoints XML-RPC ou o endpoint JSON-RPC. No Odoo 19 estão descontinuados, e a documentação oficial indica que a sua remoção está prevista para o Odoo 22. Continuam a funcionar hoje, mas os novos projetos devem ser construídos sobre o JSON-2, e os existentes devem ser inventariados e migrados no âmbito do seu roteiro de atualizações.
- Inventarie todos os scripts, conectores e ferramentas de terceiros que chamam os endpoints antigos.
- Substitua a autenticação por utilizador e palavra-passe por chaves de API dedicadas a cada integração.
- Reescreva sequências de vários passos em chamadas únicas sempre que possível, devido ao comportamento de uma transação por chamada.
- Teste a versão migrada numa base de dados duplicada antes de mudar o tráfego de produção.
A disponibilidade por plano também conta. A documentação indica que o acesso aos dados através da API externa só está disponível nos planos de preços Personalizado do Odoo, e não nos planos One App Free ou Padrão. Verifique a sua subscrição antes de desenhar uma integração baseada na API no Odoo Online.
Webhooks e regras de automação
As regras de automação permitem ao Odoo reagir a eventos sem módulos personalizados. No Odoo 19 Enterprise, são geridas no Studio através do menu Automações, e os webhooks de entrada têm também a sua própria entrada Webhooks no Studio. O modo de programador dá mais controlo, incluindo a escolha do modelo de destino.
Para um webhook de entrada, crie uma regra com o acionador Em webhook. O Odoo gera o URL automaticamente; o sistema externo envia um pedido POST com um payload JSON para esse URL. O código do registo de destino indica ao Odoo a que registo o payload se refere, e o separador Ações a Executar define o que acontece a seguir, normalmente uma ação Executar Código quando precisa de criar registos em vez de atualizar um.
Ative Registar Chamadas enquanto constrói e diagnostica. Esta opção guarda o histórico de pedidos ao URL, que pode abrir a partir do botão inteligente Registos na regra.
Trate o URL do webhook como um segredo. A documentação avisa que partilhá-lo pode dar acesso não pretendido à base de dados. Se for exposto, use Rodar Segredo para gerar um novo URL e atualize o sistema externo.
Para notificações de saída, acrescente a ação Enviar Notificação de Webhook a uma regra. Esta envia um pedido POST com os valores dos campos que selecionar para o URL que indicar, e um payload de exemplo ajuda a verificar a estrutura antes de entrar em produção.
Ao escrever ações Executar Código, use a função log para escrever mensagens na tabela de registos da base de dados, para que as falhas fiquem visíveis para os utilizadores funcionais e não apenas nos registos do servidor.
O Studio faz parte do Odoo Enterprise. No Community não existe interface do Studio, pelo que as mesmas necessidades são normalmente cobertas por configuração em modo de programador ou por pequenos módulos personalizados mantidos por um programador.
Conectores integrados para as integrações mais comuns
Antes de escrever código, verifique se o Odoo já cobre o fornecedor. Os conectores integrados são mantidos em cada versão e costumam ser a opção mais segura.
- Gateways de pagamento: configure-os em Configuração, Fornecedores de Pagamento, nas aplicações Contabilidade, Website ou Vendas. Os fornecedores listados incluem Stripe, Adyen, PayPal, Paymob, Mollie, Razorpay e outros. Introduza as credenciais no separador Credenciais e use primeiro o modo de teste com credenciais de sandbox, de preferência numa base de dados duplicada para proteger a numeração das faturas. O diário de pagamento tem de ser um diário de Banco.
- Transportadoras: ative-as nas definições do Inventário, na secção Conectores de Envio. Os conectores suportados incluem DHL Express, FedEx, UPS, Sendcloud, EasyPost e outros. Cada método de envio começa num ambiente de teste; mudar para produção cria etiquetas reais que a transportadora pode faturar, por isso verifique primeiro as tarifas e as etiquetas. A opção Depurar Pedidos regista as mensagens trocadas.
- Bancos: a sincronização bancária importa transações através de fornecedores terceiros como Plaid, Yodlee, Salt Edge, Ponto, Enable Banking e Basiq, e exige uma subscrição Enterprise válida. Se o seu banco não estiver coberto, importe os ficheiros de extrato a partir do diário de Banco no painel da Contabilidade.
- Comércio eletrónico e marketplaces: a aplicação eCommerce do próprio Odoo partilha a mesma base de dados, pelo que não é necessário conector. Para a Amazon, o Conector Amazon sincroniza as encomendas como encomendas de venda e faz a correspondência dos artigos pela referência interna.
- Dispositivos de assiduidade: a aplicação Assiduidade suporta o modo quiosque num dispositivo dedicado e o registo de entrada a partir do backend. Os terminais biométricos de outros fabricantes não são cobertos pela documentação oficial, pelo que costumam ser ligados através de um módulo personalizado ou de middleware que envia os registos de entrada para o Odoo.
Middleware como o n8n
As plataformas de middleware como o n8n situam-se entre o Odoo e os outros sistemas. São ferramentas de terceiros, não fazem parte do Odoo, e comunicam com o Odoo através da mesma API externa e dos mesmos webhooks descritos acima.
São úteis quando um evento tem de atualizar vários sistemas, quando o mapeamento de campos é complexo ou quando quer um fluxo visual com tratamento de erros e novas tentativas centralizados. A contrapartida é mais um componente para alojar, proteger, monitorizar e atualizar, e continuam a aplicar-se as mesmas condições de plano para o acesso à API.
Regras de desenho: idempotência, tratamento de erros e registos
A maioria dos problemas de integração resulta de mensagens repetidas, falhas parciais e erros silenciosos. Desenhe a pensar neles desde o primeiro dia.
- Torne cada escrita idempotente: guarde a referência externa no registo do Odoo e verifique-a antes de criar, para que um webhook reenviado ou uma chamada repetida não crie uma encomenda ou um pagamento duplicado.
- Decida quem é o dono de cada campo e nunca deixe dois sistemas sobrescreverem o mesmo valor.
- Mantenha uma operação de negócio numa só chamada sempre que possível, porque cada chamada JSON-2 é uma transação própria.
- Repita apenas em falhas temporárias, com intervalos crescentes, e envie as falhas permanentes para uma fila de revisão.
- Registe o pedido, a resposta e a referência do registo do Odoo em cada troca, usando Registar Chamadas, Depurar Pedidos ou o histórico do seu middleware.
- Monitorize diariamente os volumes e as falhas nas primeiras semanas e reconcilie totais como pagamentos, envios e saldos bancários entre sistemas.
Lista de verificação de segurança
- Crie um utilizador de integração dedicado, apenas com os direitos de acesso de que a integração precisa, e gere a chave de API a partir desse utilizador.
- Use uma chave por integração, registe a sua finalidade na descrição, escolha um prazo curto e faça a rotação antes de expirar.
- Guarde as chaves e os URLs de webhooks num gestor de segredos, nunca em folhas de cálculo, mensagens de chat ou código-fonte.
- Revogue as chaves e rode os segredos dos webhooks de imediato quando termina a relação com um fornecedor ou se suspeita de uma fuga.
- Use sempre HTTPS, e construa e teste cada integração numa base de dados duplicada antes de a ativar em produção.
Como a 1CBMS pode ajudar
A 1CBMS desenha e implementa integrações do Odoo 19 para empresas no Egito e no Iraque, desde a configuração de fornecedores de pagamento, transportadoras e feeds bancários até à construção de integrações com a API JSON-2 e webhooks, à migração de scripts XML-RPC antigos e à ligação de dispositivos de assiduidade e sistemas internos através de módulos personalizados ou middleware. Começamos por mapear a propriedade e os fluxos dos dados, testamos tudo numa base de dados duplicada e entregamos documentação e monitorização claras para que a sua equipa possa confiar nos números. Contacte-nos em www.1cbms.com para rever o seu panorama de integrações.