Tutorial de integração de API Odoo REST e XML-RPC: Conecte qualquer sistema

Odoo expõe todo o seu modelo de dados por meio de APIs externas, tornando possível a integração com praticamente qualquer sistema – plataformas de comércio eletrônico, ferramentas de CRM, software de business intelligence, aplicativos móveis e aplicativos personalizados. Este tutorial cobre todos os três protocolos API (XML-RPC, JSON-RPC e REST), métodos de autenticação, operações CRUD e padrões de integração do mundo real com exemplos de código e práticas recomendadas.

Principais conclusões

• Odoo fornece três protocolos API: XML-RPC (mais maduro), JSON-RPC (amigável ao navegador) e REST (Odoo 19, compatível com OpenAPI)
• Todas as APIs exigem autenticação usando nome de banco de dados, nome de usuário e senha ou chave de API
• As operações CRUD seguem um padrão consistente em todos os protocolos: pesquisar, ler, criar, escrever, desvincular
• Os filtros de domínio usam uma sintaxe de notação polonesa para consultas complexas
• Paginação, seleção de campos e operações em lote otimizam o desempenho de grandes conjuntos de dados

Comparação de protocolo API

Autenticação

Autenticação XML-RPC

A autenticação XML-RPC usa um processo de duas etapas: autenticar para obter um ID de usuário (uid) e, em seguida, usar esse uid para chamadas subsequentes.

A chamada de autenticação atinge o endpoint /xmlrpc/2/common com o método authenticate, passando o nome do banco de dados, nome de usuário, senha e um objeto vazio. A resposta é o ID numérico do usuário. Todas as chamadas de dados subsequentes usam /xmlrpc/2/object com o método execute_kw, passando o banco de dados, uid, senha, nome do modelo, nome do método e argumentos.

Autenticação JSON-RPC

JSON-RPC usa autenticação baseada em sessão por meio do endpoint /web/session/authenticate. O corpo da solicitação é um objeto JSON com jsonrpc: "2.0", um método de call e parâmetros contendo db, login e password. A resposta inclui um ID de sessão no cookie que autentica as solicitações subsequentes.

Autenticação da API REST (Odoo 19)

A API REST oferece suporte a chaves de API geradas no back-end do Odoo:

1. Navegue até Configurações > Usuários > Chaves de API
2. Gere uma nova chave com permissões especificadas
3. Inclua a chave no cabeçalho Authorization: Bearer

Os endpoints REST seguem o padrão /api/{model} para coleções e /api/{model}/{id} para registros individuais.

Operações CRUD

Pesquise e leia

A operação mais comum é a busca de registros com critérios específicos e a leitura dos valores de seus campos.

Filtros de domínio usam notação polonesa (notação de prefixo) com operadores:

Condições de combinação: Use & (AND), | (OR) e ! (NOT) como operadores de prefixo:

• AND: ['&', ['state', '=', 'sale'], ['amount_total', '>', 1000]] corresponde a pedidos de venda acima de 1.000
• OR: ['|', ['state', '=', 'sale'], ['state', '=', 'done']] corresponde a qualquer um dos estados
• Complexo: ['&', ['state', '=', 'sale'], '|', ['partner_id', '=', 5], ['partner_id', '=', 10]]

Seleção de campos: solicite apenas os campos necessários para reduzir o tamanho da carga útil e melhorar o desempenho. Passe um parâmetro fields com uma lista de nomes de campos. Se omitido, todos os campos serão retornados.

Paginação: Use os parâmetros offset e limit para paginar os resultados. Exemplo: offset: 20, limit: 20 retorna os registros 21-40.

Criar registros

Crie registros chamando o método create com um dicionário de valores de campo. Os campos obrigatórios devem ser incluídos. A resposta retorna o ID do registro recém-criado (ou uma matriz de IDs para criação em lote).

Exemplo: A criação de um contato requer no mínimo o campo name. Os campos opcionais incluem email, phone, company_id, street, city, state_id, country_id e campos personalizados.

Para registros relacionados (one2many ou many2many), use tuplas de comandos especiais:

Atualizar registros

Atualize os registros chamando o método write com os IDs dos registros e um dicionário de campos alterados. Inclua apenas os campos que precisam ser alterados --- os campos omitidos mantêm seus valores atuais.

As atualizações em lote são suportadas: passe uma lista de IDs para atualizar vários registros com os mesmos valores em uma única chamada.

Excluir registros

Exclua registros chamando o método unlink com os IDs dos registros. O método retorna True em caso de sucesso.

Tenha cuidado com a exclusão: muitos registros Odoo são protegidos por regras de negócios. A tentativa de excluir uma fatura lançada, por exemplo, gerará um erro. Use o método comercial apropriado (por exemplo, button_cancel antes da exclusão).

Padrões de integração do mundo real

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

Sincronize pedidos de uma plataforma externa de comércio eletrônico com o Odoo:

1. Pesquisa de novos pedidos: consulte a API de comércio eletrônico para pedidos desde o último carimbo de data/hora de sincronização
2. Combinar clientes: Pesquise contatos do Odoo por e-mail; criar se não for encontrado
3. Criar pedido de venda: Crie o pedido com informações de cliente, linhas, frete e pagamento
4. Confirmar pedido: Chame action_confirm para processar o pedido através do fluxo de trabalho
5. Atualizar comércio eletrônico: Envie a referência do pedido Odoo de volta para a plataforma de comércio eletrônico

Sincronização de inventário

Mantenha os níveis de estoque sincronizados entre o Odoo e um canal externo:

1. Leia os níveis de estoque: Ligue para search_read em stock.quant com filtros de localização
2. Atualizações push: Envie alterações de quantidade para o canal externo
3. Gerenciar reservas: Conta para estoque reservado (comprometido com pedidos pendentes)
4. Programar sincronização: Execute a cada 15-30 minutos para manter a precisão

Importação de leads de CRM

Importe leads de plataformas de marketing para o Odoo CRM:

1. Obter leads: Extraia novos leads da API da plataforma de marketing
2. Desduplicar: pesquise contatos existentes no Odoo por e-mail ou telefone
3. Criar leads: Crie registros em crm.lead com rastreamento de origem
4. Atribuir: use as regras de atribuição de leads do Odoo ou atribua com base em lógica personalizada

Exportação de dados financeiros

Exporte dados financeiros para uma plataforma de business intelligence:

1. Exportar plano de contas: Leia account.account para a estrutura da conta
2. Exportar lançamentos contábeis manuais: Leia account.move.line com filtros de data
3. Exportar saldos: Use read_group para agregar saldos por conta e período
4. Programação: executado diariamente após a janela de fechamento contábil

Tratamento de erros

Erros comuns de API

Limitação de taxa

Odoo não impõe limites de taxa de API por padrão, mas as implantações de produção devem implementar a limitação de taxa no nível do proxy reverso. Para Odoo.sh, aplicam-se limites padrão para evitar abusos. Projete integrações com intervalos de pesquisa e operações em lote razoáveis.

Estratégia de Nova Tentativa

Implemente a espera exponencial para erros transitórios:

1. Primeira tentativa após 1 segundo
2. Segunda tentativa após 4 segundos
3. Terceira tentativa após 16 segundos
4. Registrar e alertar após o máximo de tentativas

Otimização de desempenho

Operações em lote

Prefira operações em lote ao processamento de registros individuais:

• create aceita uma lista de dicionários de valores para criação em lote
• write aceita uma lista de IDs para atualizações em lote
• search_read com paginação é mais eficiente que chamadas read individuais

Seleção de Campo

Sempre especifique o parâmetro fields para evitar carregar dados desnecessários. Carregar todos os campos em um modelo com mais de 50 colunas cria uma sobrecarga significativa, especialmente para modelos como sale.order ou account.move.line.

Cache

Armazene em cache os dados que mudam lentamente localmente:

• Catálogo de produtos (atualização de hora em hora)
• Lista de clientes (atualização na notificação de alteração)
• Taxas de impostos e posições fiscais (atualização diária)

Serviços de Integração ECOSIRE

Construir integrações confiáveis ​​requer a compreensão do sistema externo e do modelo de dados do Odoo. Os serviços de integração Odoo da ECOSIRE cobrem design de API, desenvolvimento de conectores, mapeamento de dados e monitoramento contínuo. Para organizações que conectam plataformas de comércio eletrônico, nossa integração Shopify-Odoo e conectores de mercado especializados lidam com os cenários mais comuns.

Leitura Relacionada

• Guia de integração da API Odoo
• Pipelines ETL para dados ERP: Odoo e Shopify
• Guia de implantação do Docker Odoo
• Guia de desenvolvimento de módulo personalizado Odoo
• Segurança da API: autenticação e autorização

Qual protocolo API devo escolher para uma nova integração?

Para novos projetos no Odoo 19, use a API REST. Ele segue os padrões HTTP, possui documentação gerada automaticamente e oferece suporte a chaves API para autenticação. Para Odoo 17 ou 18, XML-RPC é a opção mais confiável e bem documentada. JSON-RPC é melhor para integrações baseadas em navegador ou aplicativos JavaScript.

Existe um limite de taxa na API externa do Odoo?

O próprio Odoo não impõe limites de taxa. No entanto, as implantações Odoo.sh têm limites no nível da infraestrutura, e as implantações auto-hospedadas devem implementar limitação de taxa no nível do proxy reverso (Nginx). Projete integrações para usar operações em lote e intervalos de pesquisa razoáveis, independentemente dos limites.

Posso acionar fluxos de trabalho (confirmar pedido, lançar fatura) por meio da API?

Sim. Use o método execute_kw com o nome do método de fluxo de trabalho. Por exemplo, chame action_confirm em um pedido de venda para confirmá-lo ou action_post em um movimento de conta para lançar um lançamento contábil manual. Os métodos de fluxo de trabalho impõem as mesmas regras de negócios da IU.