很少有企业只使用一个系统。即使 Odoo 是核心 ERP，它通常也需要与支付网关、物流承运商、银行、网店、考勤设备或遗留应用进行通信。这些连接的质量决定了您的数据是否可信，还是团队每个月都要手工核对差异。
Odoo 19 Enterprise 提供一套分层工具：在各应用中配置的内置连接器、供开发人员使用的外部 API、可以接收和发送 webhook 的自动化规则，以及在无法建立实时连接时使用的文件导入。当需要在众多系统之间进行编排时，中间件工具则位于这些方式之上。
关于资料来源：本文依据 Odoo 19.0 版官方文档（odoo/documentation 仓库）编写。菜单、选项和方案条件可能因版本和托管方式而变化，因此在应用到生产环境之前，请务必先在测试数据库或复制的数据库中确认每一步。
选择合适的集成模式
从业务需求出发，而不是从技术出发。先弄清楚需要传输什么数据、朝哪个方向、多快完成，以及谁拥有主记录，然后选择能够满足需求的最轻量方案。
- 当 Odoo 已支持该服务商时，使用内置连接器，例如列表中的支付服务商、物流承运商、银行同步服务商或亚马逊连接器。
- 当另一个应用需要按自己的时间安排读取或写入 Odoo 记录时，使用外部 API。
- 当外部系统需要在事件发生的那一刻将其推送到 Odoo 时，使用传入 webhook。
- 当 Odoo 需要在发生变更后通知另一个系统时（例如创建记录或更新字段时），使用传出 webhook。
- 当涉及多个系统、数据需要大量转换，或需要集中重试和监控时，使用中间件。
- 当对方只能提供文件时（例如 CAMT.053、OFX、QIF、CSV 或 XLSX 格式的银行对账单），使用文件导入。
Odoo 19 的外部 API：JSON-2 与 API 密钥
Odoo 19 引入了 JSON-2 API，通过 HTTP 开放部分 ORM 功能。每次调用都是向 /json/2/ 加模型名称和方法名称形式的端点发送 POST 请求，例如 res.partner 模型的 search_read 方法。请求正文以 JSON 形式携带方法参数。
身份验证使用在 Authorization 请求头中以 bearer 令牌形式发送的 API 密钥。不存在使用用户 ID 和密码的单独登录步骤，因此密钥即代表用户身份，集成以该用户的访问权限执行操作。
要手动创建密钥，请打开您用户的“偏好设置”，进入“账户安全”，然后选择“新建 API 密钥”。描述和有效期为必填项，密钥值只显示一次，因此请立即将其存入安全的密钥保管库。文档说明，密钥的有效期不能超过三个月，因此请从一开始就规划好密钥轮换流程。
当一台服务器托管多个数据库时，可选的 X-Odoo-Database 请求头用于告诉 Odoo 调用针对的是哪个数据库。在反向代理之后，请确保 Host 请求头能正确传递到 Odoo。
每次 JSON-2 调用都在其自己的数据库事务中运行：成功时提交，出错时回滚。您不能将多次调用串联成一个事务，因此应优先使用一个完成相关工作的方法（例如 search_read 或某个业务方法），而不是多次小调用，以免数据只更新了一半。
错误以 4xx 或 5xx HTTP 状态码返回，并附带包含 name 和 message 的 JSON 正文。您的客户端代码应读取这两项并记录日志。
遗留的 XML-RPC 和 JSON-RPC：规划迁移
许多现有集成使用较旧的 XML-RPC 端点或 JSON-RPC 端点。在 Odoo 19 中，这些端点已被弃用，官方文档称它们计划在 Odoo 22 中移除。它们目前仍可使用，但新项目应基于 JSON-2 构建，现有集成则应列入清单，并作为升级路线图的一部分进行迁移。
- 清点所有调用旧端点的脚本、连接器和第三方工具。
- 用每个集成专用的 API 密钥取代用户名和密码身份验证。
- 由于每次调用对应一个事务，尽可能将多步骤序列改写为单次调用。
- 在切换生产流量之前，先在复制的数据库上测试迁移后的版本。
方案可用性同样重要。文档说明，通过外部 API 访问数据仅在 Odoo 定制版定价方案中提供，单应用免费版和标准版均不提供。在 Odoo Online 上设计基于 API 的集成之前，请先确认您的订阅。
Webhook 与自动化规则
自动化规则使 Odoo 无需自定义模块即可对事件作出响应。在 Odoo 19 Enterprise 中，您可以在 Studio 的“自动化”菜单中管理它们，传入 webhook 在 Studio 中也有单独的“Webhooks”入口。开发者模式提供更多控制，包括选择目标模型。
对于传入 webhook，请创建一条触发器为“通过 Webhook”的规则。Odoo 会自动生成 URL；外部系统向该 URL 发送携带 JSON 负载的 POST 请求。目标记录代码告诉 Odoo 负载对应哪条记录，“待执行动作”选项卡则定义接下来要做什么；当您需要创建记录而非更新记录时，通常使用“执行代码”动作。
在构建和排查问题期间，请启用“记录调用”。它会记录对该 URL 的请求历史，您可以通过规则上的“日志”智能按钮查看。
请将 webhook URL 视为机密。文档提醒，共享该 URL 可能会导致对数据库的意外访问。如果 URL 泄露，请使用“轮换密钥”生成新的 URL，并更新外部系统。
对于传出通知，请在规则中添加“发送 Webhook 通知”动作。它会将您所选字段的值通过 POST 请求发送到您指定的 URL，示例负载可帮助您在上线前检查数据结构。
编写“执行代码”动作时，请使用 log 函数将消息写入数据库日志表，这样故障对业务用户可见，而不仅仅出现在服务器日志中。
Studio 属于 Odoo Enterprise。Community 中没有 Studio 界面，因此相同的需求通常通过开发者模式下的配置，或由开发人员维护的小型自定义模块来实现。
常见集成的内置连接器
在编写代码之前，先确认 Odoo 是否已经支持该服务商。内置连接器随每个版本一同维护，通常是最安全的选择。
- 支付网关：在“会计”、“网站”或“销售”应用中，通过“配置 > 支付服务商”进行配置。列出的服务商包括 Stripe、Adyen、PayPal、Paymob、Mollie、Razorpay 等。在“凭证”选项卡中输入凭证，并先使用沙盒凭证在“测试模式”下运行，最好在复制的数据库上进行，以保护发票编号。付款日记账必须是银行日记账。
- 物流承运商：在库存设置的“运输连接器”部分启用。支持的连接器包括 DHL Express、FedEx、UPS、Sendcloud、EasyPost 等。每种运输方式都从测试环境开始；切换到生产环境后会生成真实的运单标签，承运商可能据此收费，因此请先核实运费和标签。“调试请求”选项会记录交换的消息。
- 银行：银行同步通过 Plaid、Yodlee、Salt Edge、Ponto、Enable Banking 和 Basiq 等第三方服务商导入交易，并需要有效的 Enterprise 订阅。如果您的银行不在支持范围内，请从会计仪表板上的银行日记账导入对账单文件。
- 电子商务和电商平台：Odoo 自己的“电子商务”应用共用同一个数据库，因此不需要连接器。对于亚马逊，亚马逊连接器会将订单同步为销售订单，并按内部参考匹配产品。
- 考勤设备：“考勤”应用支持在专用设备上使用自助终端模式，以及从后台签到。官方文档并未涵盖其他厂商的生物识别终端，因此它们通常通过将签到数据推送到 Odoo 的自定义模块或中间件进行连接。
n8n 等中间件
n8n 等中间件平台位于 Odoo 与其他系统之间。它们是第三方工具，不属于 Odoo，并通过上文所述的外部 API 和 webhook 与 Odoo 通信。
当一个事件必须更新多个系统、字段映射十分复杂，或您希望使用带有集中错误处理和重试的可视化流程时，它们非常有用。代价是多了一个需要托管、加固、监控和升级的组件，而且 API 访问的方案条件同样适用。
设计规则：幂等性、错误处理与日志记录
大多数集成问题源于重复消息、部分失败和静默错误。请从第一天起就针对这些情况进行设计。
- 使每次写入都具有幂等性：在 Odoo 记录上存储外部参考，并在创建前进行检查，这样重新发送的 webhook 或重试的调用就不会产生重复的订单或付款。
- 明确每个字段由谁负责，绝不让两个系统覆盖同一个值。
- 由于每次 JSON-2 调用都是独立事务，尽可能将一项业务操作放在一次调用中完成。
- 仅在临时故障时重试，并逐步延长间隔；将永久性故障发送到审核队列。
- 使用“记录调用”、“调试请求”或中间件的历史记录，为每次交换记录请求、响应和 Odoo 记录参考。
- 在最初几周内每天监控数据量和故障，并核对各系统之间的付款、发货和银行余额等合计数。
安全检查清单
- 创建一个专用的集成用户，只授予集成所需的访问权限，并以该用户身份生成 API 密钥。
- 每个集成使用一个密钥，在描述中注明其用途，选择较短的有效期，并在到期前轮换。
- 将密钥和 webhook URL 存放在密钥管理工具中，切勿放在电子表格、聊天消息或源代码中。
- 当与供应商的合作终止或怀疑发生泄露时，立即撤销密钥并轮换 webhook 密钥。
- 始终使用 HTTPS，并在生产环境启用之前，在复制的数据库上构建和测试每个集成。
1CBMS 如何为您提供帮助
1CBMS 为埃及和伊拉克的企业设计并实施 Odoo 19 集成，从配置支付服务商、承运商和银行数据源，到构建 JSON-2 API 和 webhook 集成、迁移遗留的 XML-RPC 脚本，以及通过自定义模块或中间件连接考勤设备和内部系统。我们首先梳理数据归属和数据流，在复制的数据库中全面测试，并交付清晰的文档和监控机制，让您的团队可以信赖这些数字。欢迎通过 www.1cbms.com 联系我们，评估您的集成全景。