Odoo API 集成指南：将 Odoo 连接到任何系统

Odoo 很少单独运作。企业需要将其连接到电子商务平台、支付处理器、运输公司、营销工具和自定义应用程序。 Odoo 外部 API 提供两种协议 — XML-RPC 和 JSON-RPC — 使任何系统都能以编程方式读取、创建、更新和删除 Odoo 中的记录。

身份验证

API 密钥认证

在 Odoo 中生成 API 密钥：导航至您的用户个人资料，然后选择帐户安全，然后选择 API 密钥。创建带有描述性标签的密钥。使用此密钥代替您的密码进行 API 身份验证 - 它可以独立撤销，而无需更改您的登录凭据。

连接参数

每个 API 调用都需要：Odoo 服务器 URL、数据库名称、您的用户名（登录电子邮件）和 API 密钥。安全地存储这些信息——切勿在源代码中硬编码凭证。

XML-RPC 协议

连接设置

XML-RPC 使用两个端点：/xmlrpc/2/common 用于身份验证，/xmlrpc/2/object 用于数据操作。首先进行身份验证以获取用户 ID，然后使用该 ID 进行后续调用。

CRUD 操作

搜索和读取：使用域过滤器查询记录（类似于 SQL WHERE 子句）。域使用元组：[('state', '=', 'sale'), ('amount_total', '>', 1000)] 查找超过 1,000 美元的已确认销售订单。

创建：传递字段值的字典。 API 返回新记录 ID。必须包含必填字段，否则调用会失败并出现验证错误。

写入：通过传递记录 ID 和更改值的字典来更新现有记录。仅包含您要修改的字段。

Unlink: Delete records by ID.请谨慎使用 - 某些记录如果具有相关记录则无法删除。

JSON-RPC 协议

为什么选择 JSON-RPC

JSON-RPC 通常是现代集成的首选：它使用 JSON（比 XML 对开发人员更友好），可以更好地与 JavaScript/TypeScript 应用程序配合使用，并且为大型有效负载提供稍微更好的性能。

请求格式

JSON-RPC 调用转到单个端点：/jsonrpc。每个请求都包含标准 JSON-RPC 2.0 信封中的服务名称、方法和参数。

常见集成模式

电子商务订单同步

将订单从 Shopify 或 WooCommerce 同步到 Odoo：

1. 监听电商平台的订单webhooks
2. 将客户数据映射到 Odoo 合作伙伴记录（创建或匹配现有）
3. 创建销售订单，其中行项目映射到 Odoo 产品
4. 确认订单以触发履行工作流程
5. 将跟踪信息同步回电子商务平台

支付处理器集成

连接 Stripe、PayPal 或其他处理器：

1. 接收付款确认webhooks
2. 通过参考号将付款与 Odoo 发票匹配
3. 在 Odoo Accounting 中注册付款 4.与银行对账单自动对账

CRM 同步

使 Odoo CRM 与外部营销工具保持同步：

1. 来自营销平台的新线索创造了 Odoo 线索
2. 潜在客户评分更新双向流动 3.赢得的机会触发营销工具中的后续活动
3. 联系信息跨系统保持同步

错误处理

常见错误

• 访问被拒绝：凭据无效或权限不足
• 验证错误：必填字段缺失或值无效
• 未找到记录：引用不存在的 ID
• 并发更新：另一个用户同时修改该记录

最佳实践

1. 实施重试逻辑，针对瞬态故障采用指数退避
2. 发送前验证数据以尽早发现错误
3. 记录所有 API 调用用于调试和审计目的
4. 处理速率限制 — 批量操作而不是单独调用
5. 使用幂等操作安全地重试失败的调用

性能优化

• 批量读取：使用 search_read 而不是单独的 search + read 调用
• 限制字段：仅请求您需要的字段，而不是模型上的所有字段
• 分页：对大型结果集使用 limit 和 offset
• 缓存：在本地缓存缓慢变化的数据（产品目录、货币汇率）

Webhook 模式

Odoo 并非在所有版本中都具有本机出站 Webhook。常见方法：

• 自动操作：记录更改时触发并调用外部 URL 的服务器操作
• 自定义控制器：构建一个 Odoo 模块，为外部系统公开 webhook 端点
• Polling: External systems poll Odoo at intervals for changes (simpler but less real-time)

安全考虑

• 使用 API 密钥而不是密码
• 通过网络级别的 IP 地址限制 API 访问
• 使用 HTTPS 进行所有 API 通信
• 实施适当的访问权限 — API 用户应拥有最低限度的必要权限
• 定期轮换 API 密钥并立即撤销受损密钥

我们的 Odoo 集成服务 通过适当的错误处理、监控和安全性构建生产级集成。

常见问题

我应该使用哪种协议 - XML-RPC 还是 JSON-RPC？

用于新项目的 JSON-RPC。它对开发人员更加友好，可以更好地与现代工具配合使用，并且是 Odoo 的发展方向。 XML-RPC 适用于遗留系统或语言，具有更好的 XML-RPC 库支持。

有 REST API 吗？

Odoo 17+ 包括 REST API 和 RPC 端点。它遵循带有 JSON 有效负载的标准 REST 约定，并且通常更容易用于 Web 应用程序。

如何处理大数据迁移？

对于初始数据加载，请使用 CSV 导入功能或编写迁移脚本，批量创建记录（每批 100-500 条记录），并对每批进行错误处理。

我可以使用自定义端点扩展 API 吗？

是的。使用控制器类创建自定义 Odoo 模块，这些控制器类为标准 API 未涵盖的专门操作公开额外的 HTTP 端点。