Guia de integração da API Odoo: Conecte o Odoo a qualquer sistema

Odoo raramente opera isoladamente. As empresas precisam dele conectado a plataformas de comércio eletrônico, processadores de pagamento, transportadoras, ferramentas de marketing e aplicativos personalizados. A API externa Odoo fornece dois protocolos – XML-RPC e JSON-RPC – que permitem que qualquer sistema leia, crie, atualize e exclua registros no Odoo programaticamente.

Autenticação

Autenticação de chave de API

Gere uma chave de API no Odoo: navegue até seu perfil de usuário, depois Segurança da conta e Chaves de API. Crie uma chave com um rótulo descritivo. Use esta chave em vez de sua senha para autenticação API — ela pode ser revogada de forma independente, sem alterar suas credenciais de login.

Parâmetros de conexão

Cada chamada de API requer: a URL do servidor Odoo, o nome do banco de dados, seu nome de usuário (e-mail de login) e a chave de API. Armazene-os com segurança – nunca codifique credenciais no código-fonte.

Protocolo XML-RPC

Configuração de conexão

XML-RPC usa dois endpoints: /xmlrpc/2/common para autenticação e /xmlrpc/2/object para operações de dados. Autentique primeiro para obter um ID de usuário e, em seguida, use esse ID para chamadas subsequentes.

Operações CRUD

Pesquisa e leitura: consulta registros com filtros de domínio (semelhantes às cláusulas SQL WHERE). Os domínios usam tuplas: [('state', '=', 'sale'), ('amount_total', '>', 1000)] encontra pedidos de vendas confirmados acima de US$ 1.000.

Criar: Passe um dicionário de valores de campo. A API retorna o novo ID do registro. Os campos obrigatórios devem ser incluídos ou a chamada falhará com um erro de validação.

Escrever: Atualize os registros existentes passando os IDs dos registros e um dicionário de valores alterados. Inclua apenas os campos que você deseja modificar.

Desvincular: exclui registros por ID. Use com cuidado — alguns registros não podem ser excluídos se tiverem registros dependentes.

Protocolo JSON-RPC

Por que JSON-RPC

JSON-RPC é geralmente preferido para integrações modernas: ele usa JSON (mais amigável ao desenvolvedor do que XML), funciona melhor com aplicativos JavaScript/TypeScript e oferece desempenho um pouco melhor para cargas grandes.

Formato de solicitação

As chamadas JSON-RPC vão para um único endpoint: /jsonrpc. Cada solicitação inclui o nome do serviço, o método e os argumentos em um envelope JSON-RPC 2.0 padrão.

Padrões de integração comuns

Sincronização de pedidos de comércio eletrônico

Sincronize pedidos do Shopify ou WooCommerce com o Odoo:

1. Ouça webhooks de pedidos na plataforma de comércio eletrônico
2. Mapeie os dados do cliente para registros de parceiros Odoo (crie ou combine os existentes)
3. Crie um pedido de venda com itens de linha mapeados para produtos Odoo
4. Confirme o pedido para acionar fluxos de trabalho de atendimento
5. Sincronize as informações de rastreamento com a plataforma de comércio eletrônico

Integração do processador de pagamento

Conecte Stripe, PayPal ou outros processadores:

1. Receba webhooks de confirmação de pagamento
2. Combine os pagamentos com as faturas Odoo por número de referência
3. Cadastre o pagamento no Odoo Accounting
4. Reconcilie com extratos bancários automaticamente

Sincronização de CRM

Mantenha o Odoo CRM sincronizado com ferramentas de marketing externas:

1. Novos leads de plataformas de marketing criam leads Odoo
2. As atualizações de pontuação de leads fluem bidirecionalmente
3. Oportunidades conquistadas acionam campanhas de acompanhamento na ferramenta de marketing
4. As informações de contato permanecem sincronizadas entre sistemas

Tratamento de erros

Erros Comuns

• Acesso negado: credenciais inválidas ou permissões insuficientes
• Erro de validação: campos obrigatórios ausentes ou valores inválidos
• Registro não encontrado: referenciando um ID que não existe
• Atualização simultânea: outro usuário modificou o registro simultaneamente

Melhores Práticas

1. Implementar lógica de nova tentativa com espera exponencial para falhas transitórias
2. Valide os dados antes de enviar para detectar erros antecipadamente
3. Registre todas as chamadas de API para fins de depuração e auditoria
4. Lidar com limites de taxa — operações em lote em vez de chamadas individuais
5. Use operações idempotentes para tentar novamente chamadas com falha com segurança

Otimização de desempenho

• Leituras em lote: use search_read em vez de chamadas search + read separadas
• Limitar campos: solicite apenas os campos necessários, não todos os campos do modelo
• Paginação: use limit e offset para grandes conjuntos de resultados
• Cache: armazene em cache dados que mudam lentamente (catálogos de produtos, taxas de câmbio) localmente

Padrões de webhook

Odoo não possui webhooks de saída nativos em todas as versões. Abordagens comuns:

• Ações automatizadas: ações do servidor que são acionadas em alterações de registro e chamam URLs externos
• Controladores personalizados: crie um módulo Odoo que expõe endpoints de webhook para sistemas externos
• Pesquisa: sistemas externos pesquisam o Odoo em intervalos em busca de alterações (mais simples, mas menos em tempo real)

Considerações de segurança

• Use chaves de API em vez de senhas
• Restringir o acesso à API por endereço IP no nível da rede
• Use HTTPS para todas as comunicações da API
• Implement proper access rights — API users should have minimum necessary permissions
• Alterne chaves de API regularmente e revogue chaves comprometidas imediatamente

Nosso serviço de integração Odoo cria integrações de nível de produção com tratamento de erros, monitoramento e segurança adequados.

Perguntas frequentes

Qual protocolo devo usar — ​​XML-RPC ou JSON-RPC?

JSON-RPC para novos projetos. É mais amigável ao desenvolvedor, funciona melhor com ferramentas modernas e é a direção que o Odoo está tomando. XML-RPC para sistemas legados ou linguagens com melhor suporte à biblioteca XML-RPC.

Existe uma API REST?

Odoo 17+ inclui uma API REST junto com os endpoints RPC. Ele segue convenções REST padrão com cargas JSON e geralmente é mais fácil de trabalhar para aplicativos da web.

Como lidar com grandes migrações de dados?

Para carregamentos de dados iniciais, use o recurso de importação de CSV ou escreva um script de migração que crie registros em lotes (100 a 500 registros por lote) com tratamento de erros para cada lote.

Posso estender a API com endpoints personalizados?

Sim. Crie módulos Odoo personalizados com classes de controlador que expõem terminais HTTP adicionais para operações especializadas não cobertas pela API padrão.