Odoo REST 和 XML-RPC API 集成教程：连接任何系统

Odoo 通过外部 API 公开其整个数据模型，从而可以与几乎任何系统集成——电子商务平台、CRM 工具、商业智能软件、移动应用程序和自定义应用程序。本教程涵盖所有三种 API 协议（XML-RPC、JSON-RPC 和 REST）、身份验证方法、CRUD 操作以及实际集成模式以及代码示例和最佳实践。

要点

• Odoo 提供三种 API 协议：XML-RPC（最成熟）、JSON-RPC（浏览器友好）和 REST（Odoo 19，兼容 OpenAPI）
• 所有 API 都需要使用数据库名称、用户名和密码或 API 密钥进行身份验证
• CRUD 操作在所有协议中遵循一致的模式：搜索、读取、创建、写入、取消链接
• 域过滤器使用波兰表示法语法进行复杂查询
• 分页、字段选择和批量操作优化大型数据集的性能

API协议比较

身份验证

XML-RPC 身份验证

XML-RPC 身份验证使用两步过程：进行身份验证以获取用户 ID (uid)，然后使用该 uid 进行后续调用。

身份验证调用使用 authenticate 方法命中 /xmlrpc/2/common 端点，传递数据库名称、用户名、密码和一个空对象。响应是数字用户 ID。所有后续数据调用都使用 /xmlrpc/2/object 和 execute_kw 方法，传递数据库、uid、密码、模型名称、方法名称和参数。

JSON-RPC 身份验证

JSON-RPC 通过 /web/session/authenticate 端点使用基于会话的身份验证。请求正文是一个 JSON 对象，其中包含 jsonrpc: "2.0"、call 的方法以及包含 db、login 和 password 的参数。响应在 cookie 中包含一个会话 ID，用于验证后续请求。

REST API 身份验证 (Odoo 19)

REST API 支持 Odoo 后端生成的 API 密钥：

1. 导航至 设置 > 用户 > API 密钥
2. 生成指定权限的新密钥
3. 将密钥包含在 Authorization: Bearer 标头中

REST 端点对于集合遵循 /api/{model} 模式，对于单个记录遵循 /api/{model}/{id} 模式。

CRUD 操作

搜索并阅读

最常见的操作是搜索具有特定条件的记录并读取其字段值。

域过滤器 使用带有运算符的波兰表示法（前缀表示法）：

组合条件：使用 & (AND)、| (OR) 和 ! (NOT) 作为前缀运算符：

• AND: ['&', ['state', '=', 'sale'], ['amount_total', '>', 1000]] 匹配超过 1000 个销售订单
• OR: ['|', ['state', '=', 'sale'], ['state', '=', 'done']] 匹配任一状态
• 复杂：['&', ['state', '=', 'sale'], '|', ['partner_id', '=', 5], ['partner_id', '=', 10]]

字段选择：仅请求您需要的字段，以减少有效负载大小并提高性能。传递带有字段名称列表的 fields 参数。如果省略，则返回所有字段。

分页：使用 offset 和 limit 参数对结果进行分页。示例：offset: 20, limit: 20 返回记录 21-40。

创建记录

通过使用字段值字典调用 create 方法来创建记录。必须包含必填字段。响应返回新创建的记录的 ID（或用于批量创建的 ID 数组）。

示例：创建联系人至少需要 name 字段。可选字段包括 email、phone、company_id、street、city、state_id、country_id 和自定义字段。

对于相关记录（one2many 或 Many2many），请使用特殊命令元组：

更新记录

通过使用记录 ID 和已更改字段的字典调用 write 方法来更新记录。仅包含需要更改的字段——省略的字段保留其当前值。

支持批量更新：传递 ID 列表，以便在一次调用中更新具有相同值的多条记录。

删除记录

通过使用记录 ID 调用 unlink 方法来删​​除记录。成功时该方法返回 True。

删除时要小心——许多 Odoo 记录都受到业务规则的保护。例如，尝试删除已过帐的发票将引发错误。请改用适当的业务方法（例如，删除前的 button_cancel）。

现实世界的集成模式

电子商务订单同步

将订单从外部电子商务平台同步到 Odoo：

1. 轮询新订单：查询自上次同步时间戳以来的订单的电子商务 API
2. 匹配客户：通过电子邮件搜索Odoo联系人；如果没有找到则创建
3. 创建销售订单：使用客户、线路、运输和付款信息构建订单
4. 确认订单：调用action_confirm通过工作流程处理订单
5. 更新电子商务：将 Odoo 订单参考发送回电子商务平台

库存同步

保持 Odoo 和外部渠道之间的库存水平同步：

1. 读取库存水平：使用位置过滤器在 stock.quant 上调用 search_read
2. 推送更新：将数量变化发送到外部渠道
3. 处理预订：保留库存的账户（致力于挂单）
4. 计划同步：每 15-30 分钟运行一次以保持准确性

CRM 潜在客户导入

将销售线索从营销平台导入 Odoo CRM：

1. 获取线索：从营销平台API中拉取新线索
2. Deduplicate: Search Odoo for existing contacts by email or phone
3. 创建潜在客户：在 crm.lead 中创建记录并进行源跟踪
4. 分配：使用Odoo的线索分配规则或根据自定义逻辑进行分配

财务数据导出

将财务数据导出到商业智能平台：

1. 导出科目表：读取account.account了解科目结构
2. 导出日记帐分录：使用日期过滤器读取 account.move.line
3. 导出余额：使用read_group按账户和期间汇总余额
4. 时间表：每天在会计关闭窗口后运行

错误处理

常见 API 错误

速率限制

默认情况下，Odoo 不强制实施 API 速率限制，但生产部署应在反向代理级别实施速率限制。对于 Odoo.sh，应用默认限制以防止滥用。设计具有合理轮询间隔和批量操作的集成。

重试策略

对瞬态错误实施指数退避：

1. 1秒后第一次重试
2. Second retry after 4 seconds
3. 16秒后第三次重试
4. 最大重试次数后记录并发出警报

性能优化

批量操作

优先选择批量操作而不是单个记录处理：

• create 接受用于批量创建的值字典列表
• write 接受批量更新的 ID 列表
• 带有分页的 search_read 比单独的 read 调用更有效

字段选择

始终指定 fields 参数以避免加载不必要的数据。在具有 50 多个列的模型上加载所有字段会产生巨大的开销，特别是对于 sale.order 或 account.move.line 这样的模型。

缓存

在本地缓存缓慢变化的数据：

• 产品目录（每小时刷新）
• 客户列表（更改通知时刷新）
• 税率和财政状况（每日刷新）

ECOSIRE 集成服务

构建可靠的集成需要了解外部系统和 Odoo 的数据模型。 ECOSIRE 的 Odoo 集成服务 涵盖 API 设计、连接器开发、数据映射和持续监控。对于连接电子商务平台的组织，我们专门的 Shopify-Odoo 集成 和 市场连接器 可以处理最常见的场景。

相关阅读

• Odoo API 集成指南
• ERP 数据的 ETL 管道：Odoo 和 Shopify
• Docker Odoo部署指南
• Odoo 自定义模块开发指南
• API安全：身份验证和授权

我应该为新集成选择哪种 API 协议？

对于 Odoo 19 上的新项目，请使用 REST API。它遵循 HTTP 标准，具有自动生成的文档，并支持用于身份验证的 API 密钥。对于 Odoo 17 或 18，XML-RPC 是最可靠且文档齐全的选项。 JSON-RPC 最适合基于浏览器的集成或 JavaScript 应用程序。

Odoo 的外部 API 有速率限制吗？

Odoo 本身不强制执行速率限制。但是，Odoo.sh 部署具有基础设施级别的限制，自托管部署应在反向代理 (Nginx) 级别实施速率限制。设计集成以使用批处理操作和合理的轮询间隔，而不受限制。

我可以通过 API 触发工作流程（确认订单、发布发票）吗？

是的。将 execute_kw 方法与工作流方法名称结合使用。例如，在 sales.order 上调用 action_confirm 进行确认，或在 account.move 上调用 action_post 来过帐日记账分录。工作流方法强制执行与 UI 相同的业务规则。