Shopify 到 Odoo 订单导入：完整的自动化指南

每个需要手动重新输入 Odoo 的 Shopify 订单都是一种责任 - 可能会出现数据输入错误、履行处理延迟，以及每增加一个订单就会消耗员工时间。对于每天处理 200 个订单的商店来说，手动订单导入每天大约消耗员工 3-4 小时的时间，并会导致库存、运输和会计方面出现 2-5% 的错误率。

Shopify 到 Odoo 订单管道的自动化完全消除了这一瓶颈。订单在下达后几秒钟内到达 Odoo，客户记录自动合并，付款状态实时同步，履行更新与跟踪号码一起写回 Shopify，错误情况会被捕获并排队等待解决，而不是默默地丢弃。

本指南涵盖了完整的订单导入自动化 - 从启动流程的 Shopify Webhook 到关闭循环的履行写回。每个步骤都包括生产级实施所需处理的特定数据映射、边缘情况和故障模式。

要点

• Shopify webhooks 提供实时订单事件 - 订单/创建、订单/更新、订单/取消 - 触发导入管道
• 客户同步使用电子邮件作为主要匹配键，自动创建新客户并自动合并现有客户
• 付款状态映射将 Shopify 的付款状态（已授权、已付款、部分付款、已退款）转换为 Odoo 付款记录
• 产品匹配使用 SKU 作为主要标识符将 Shopify 订单项连接到 Odoo 产品 - 变体级别匹配至关重要
• 履行写回将 Odoo 递送确认发送回 Shopify，其中包含跟踪号码、承运商信息和每行商品的履行数据
• 部分履行（从多个仓库分批发货）需要行项目级履行跟踪，而不是订单级
• 错误处理必须包括重试队列、死信处理和警报——无声故障是最危险的故障
• 幂等键（Shopify 订单 ID）可防止 webhook 重试重复订单

---

架构：订单导入管道

完整的订单导入管道有六个阶段，每个阶段都有特定的数据转换和故障模式：

Stage 1: Webhook Reception
  Shopify → orders/create webhook → Integration endpoint

Stage 2: Customer Resolution
  Find or create Odoo customer from Shopify customer data

Stage 3: Product Matching
  Map Shopify line items to Odoo products by SKU/variant

Stage 4: Order Creation
  Create Odoo sale order with lines, taxes, shipping, discounts

Stage 5: Payment Recording
  Record payment status based on Shopify financial_status

Stage 6: Fulfillment Writeback
  Odoo delivery → Shopify fulfillment with tracking

每个阶段都是一个独特的操作，可以独立失败。强大的实现将它们作为具有检查点的管道进行处理 - 如果阶段 4 失败，阶段 1-3 不会在重试时重新执行。

---

第 1 阶段：接收 Shopify 订单 Webhook

Shopify webhook 是实时订单导入的基础。发生订单事件时，Shopify 会向您注册的终端节点发送包含完整订单负载的 HTTP POST 请求。

所需的 Webhook 订阅

Webhook 验证

每个传入的 Webhook 都必须使用 Shopify 的 HMAC-SHA256 签名进行验证。 Webhook 负载使用您的应用程序的共享密钥进行签名 - 在处理之前验证签名。未经验证的 Webhook 应被拒绝并返回 401 响应。

处理 Webhook 交付保证

Shopify 保证至少一次传送，这意味着同一个 Webhook 可能会发送多次 - 在网络超时后、Shopify 重试周期期间或事件恢复期间。您的端点必须是幂等的：接收相同的订单/创建 webhook 两次不得创建两个 Odoo 订单。

实现模式：使用Shopify的订单ID作为幂等键。在创建 Odoo 订单之前，请检查具有该 Shopify 参考的订单是否已存在。如果是，则跳过创建并返回 200 响应，以便 Shopify 停止重试。

响应时间要求

Shopify 预计在 5 秒内收到 200 条回复。如果您的端点需要更长的时间，Shopify 会将交付标记为失败并重试。因此，webhook 端点应该接受有效负载，验证 HMAC 签名，将订单排队以进行异步处理，并立即返回 200。实际的订单创建发生在后台工作人员中。

---

第二阶段：客户解决方案

每个 Shopify 订单都包含客户数据 - 电子邮件、姓名、电话、送货地址和帐单地址。集成必须根据 Odoo 的联系人数据库解决此问题。

客户匹配算法

推荐的匹配逻辑遵循以下优先级顺序：

1. 精确电子邮件匹配：在 Odoo 联系人中搜索 Shopify 订单中的电子邮件地址。电子邮件是最可靠的唯一标​​识符。
2. 电话匹配（如果没有电子邮件匹配）：某些 B2B 订单或 POS 订单可能没有电子邮件。回退到与规范化匹配的电话号码（去除空格、破折号、国家/地区代码规范化）。
3. 创建新联系人：如果未找到匹配项，请使用 Shopify 订单中的所有可用数据创建新的 Odoo 联系人。

现有客户的现场合并

当现有 Odoo 客户匹配时，集成应更新（而不是覆盖）缺失的字段：

If Odoo contact has no phone but Shopify order does → add phone
If Odoo contact has phone and Shopify order has different phone → keep Odoo (source of truth)
If Shopify order has new shipping address → add as child contact (delivery address)

地址处理

B2B 客户处理

对于 B2B 订单（Shopify Plus B2B 功能），集成应将 Shopify 公司映射到 Odoo 公司类型联系人，并将个人买家作为子联系人。这保留了 B2B 运营在信用条款、批量定价和账户管理方面所需的公司与个人关系。

---

第三阶段：产品匹配

Shopify 订单上的每个订单项必须与 Odoo 中的产品匹配。这种匹配是许多集成失败的地方，因为 Shopify 和 Odoo 代表产品的方式不同。

基于 SKU 的匹配

SKU 是建议的主要匹配键。当您在 Odoo 中管理产品并将其同步到 Shopify 时，应在 Odoo 产品变体和 Shopify 变体上设置 Odoo 内部参考 (SKU)。该集成将 Shopify 订单项 SKU 与 Odoo 产品变型内部参考相匹配。

变体匹配复杂性

Shopify 变体（尺寸：大，颜色：蓝色）必须与具有等效属性值的 Odoo 产品变体相匹配。当 SKU 一致时，这很简单，但当系统之间的 SKU 不同、Shopify 具有 Odoo 中不存在的变体（例如，在 Shopify 上添加的新变体但尚未同步到 Odoo）时，或者当 Odoo 产品使用可配置属性而 Shopify 使用预定义变体时，就会中断。

处理不匹配的产品：当 Shopify 订单项无法与 Odoo 产品匹配时，集成不应默默地跳过它。相反，它应该创建带有占位符产品线的订单（例如，描述中带有 Shopify 变体标题的包罗万象的“不匹配的 Shopify 产品”项目），标记订单以供审核，并提醒运营团队。

捆绑和套件产品

如果您在 Shopify 上销售捆绑产品（例如，作为三个独立产品提供的“入门套件”），则集成需要知道是创建单个 Odoo 订单行（针对捆绑产品）还是创建多个订单行（针对组件产品）。这取决于您的 Odoo 库存设置 - 您是否将捆绑产品作为单个项目或单个组件进行跟踪。

---

第 4 阶段：在 Odoo 中创建订单

解决客户问题并匹配产品后，集成将创建 Odoo 销售订单。这是数据最密集的阶段，需要仔细的字段映射。

字段映射：Shopify 到 Odoo 销售订单

行项目映射

折扣处理

Shopify 表示折扣的方式与 Odoo 不同。 Shopify 提供每个订单项的折扣金额以及订单级别的整体折扣代码。 Odoo 预计每行都有折扣百分比。

转换：discount_percentage = (shopify_discount_amount / (quantity * unit_price)) * 100

对于订单级折扣（例如“整个订单 10% 折扣”），折扣必须按比例分配到各个订单项。一些实现为订单级折扣添加单独的负金额行项目而不是分配 - 两种方法都是有效的，但按比例分配会产生更清晰的每行项目利润分析。

航线

Shopify 运费应映射到单独订单行上的专用 Odoo 产品（例如“Shopify Shipping”）。这使得报告中的运输收入与产品收入不同。

订单确认

在草稿状态下创建销售订单后，集成应自动确认它 (action_confirm) 以触发下游工作流程 — 交货订单创建、制造订单（对于 MTO 产品）和采购订单（对于代发货产品）。仅当付款状态为“已付款”或“已授权”时才自动确认 - 将草稿订单保留为“待处理”付款状态。

---

第五阶段：付款记录

Shopify 的 financial_status 字段表示订单的付款状态。集成必须将其转换为 Odoo 付款记录。

付款状态映射

自动发票创建

对于“已付款”订单，集成应自动创建并验证 Odoo 发票，然后根据其注册付款。这可以保持应收账款干净——全额付款的 Shopify 订单在 Odoo 中应收账款余额为零。

对于“授权”订单（启用手动捕获时，常见于 Shopify Payments），集成应创建销售订单而不是发票。当稍后捕获付款时（触发订单/更新的 Webhook，其中 Financial_status 更改为“已付款”），集成将创建发票并注册付款。

支付方式配置

为 Shopify 付款创建专用的 Odoo 付款日记帐（例如“银行”类型的“Shopify Payments”日记帐）。所有自动付款注册都应使用此日记帐。这使得 Shopify 付款记录与其他付款方式分开，并简化了银行对账。

---

第 6 阶段：履行写回

最后阶段关闭循环 - 当 Odoo 中履行订单（交货订单已验证）时，集成会将履行数据发送回 Shopify，更新订单状态并向客户提供跟踪信息。

触发写回

在 Odoo 中，履行事件是交货订单 (stock.picking) 的验证。集成应侦听交货订单确认事件并触发 Shopify 履行 API 调用。

履行数据映射

部分履行处理

处理分批货件

当 Odoo 将交货单拆分为多个发货（缺货情况）时，每个发货都会生成一个单独的交货单。整合必须：

1.检测新交货订单为延期交货（与同一个销售订单相关） 2. 确定本次装运中包含哪些行项目 3. 仅在 Shopify 上为这些商品创建部分履行 4. 包含该特定货件的正确追踪号码

代发货订单的履行写回

对于代发货履行（供应商直接向客户发货），跟踪信息来自采购订单收据，而不是仓库交货单。集成应监控代发货订单的购买收据确认，并使用供应商的跟踪号码进行 Shopify 履行。

---

错误处理和恢复

订单导入管道中的错误分为三类，每一类都需要不同的恢复策略。

暂时错误（自动重试）

网络超时、API 速率限制、服务临时不可用 — 这些都会自行解决。集成应实现指数退避重试：30 秒后第一次重试，2 分钟后第二次重试，10 分钟后第三次重试，直至可配置的最大重试次数（通常为 5-10）。

数据错误（隔离审查）

不匹配的产品、无效的地址、缺少必填字段——这些都需要人工干预。集成应将订单隔离在审查队列中，并明确说明失败的原因，为运营团队创建 Odoo 活动或通知，并在数据问题修复后提供一键重试机制。

系统错误（立即警报）

身份验证失败、API 权限更改、连接器配置错误 - 这些都会影响所有订单，而不仅仅是一个订单。集成应检测模式（例如，连续 5 次失败）并通过电子邮件和仪表板警报立即升级。

死信队列

所有重试尝试均失败的订单将移至死信队列——不可处理订单的持久记录。必须每天监控该队列。常见的死信原因包括 Shopify 中存在但从未同步到 Odoo 的产品、Odoo 拒绝的包含无效字符的客户数据、未通过 Odoo 验证的零价商品订单，以及未在 Odoo 中配置新 Shopify 货币时出现的货币不匹配。

---

测试订单导入管道

在上线之前，测试管道中的每条路径：

功能测试场景

负载测试

如果您的商店处理大量订单（每天超过 500 个订单），请使用类似生产的数据量对导入管道进行负载测试。验证管道是否可以处理突发流量（限时抢购）、数据库锁是否不会造成瓶颈，以及是否遵守 Shopify 和 Odoo API 速率限制。

---

性能优化

历史导入的批处理

最初设置集成或导入历史订单时，使用 Shopify 的 REST API 批量获取 250 个订单（最大页面大小），而不是单独处理每个订单。使用 ORM create 方法和值列表批量创建 Odoo 记录。

缓存产品和客户查找

产品匹配（第 3 阶段）和客户解析（第 2 阶段）涉及每个订单的数据库查找。缓存经常访问的产品和客户以减少 Odoo API 调用。当产品或客户更新时，使缓存失效。

Webhook 处理并发

对于大容量存储，同时处理 Webhooks — 多个工作人员同时从消息队列中拉取。通过对幂等键检查使用数据库级锁定来确保并发安全，防止两个工作人员同时创建相同的订单。

---

常见问题

通过基于 Webhook 的自动化，Shopify 订单在 Odoo 中显示的速度有多快？

通过正确配置的基于 Webhook 的集成，Shopify 订单会在下单后 2-10 秒内显示在 Odoo 中。这包括 Webhook 交付、HMAC 验证、客户解析、产品匹配和销售订单创建。基于 Cron 的替代方案会根据轮询间隔增加 5-60 分钟的延迟。

如果收到 Shopify 订单时 Odoo 出现故障，会发生什么情况？

集成的消息队列会保存订单 Webhook 负载，直到 Odoo 可用。当 Odoo 重新上线时，队列会按顺序处理所有挂单。 Shopify 还会在长达 48 小时内重试失败的 Webhook 交付，从而提供辅助安全网。如果集成使用持久消息队列，订单永远不会丢失。

我可以将订单从多个 Shopify 商店导入到一个 Odoo 实例中吗？

是的。每个 Shopify 商店都通过自己的一组 API 凭据和 Webhook 订阅进行连接。该集成使用源商店标记每个订单（使用自定义字段或 Odoo 销售团队），以便您可以按商店进行报告。产品可以跨商店或特定商店共享，具体取决于您的目录策略。

集成如何处理 Shopify 草稿订单？

草稿订单（由商家为电话订单或 B2B 报价创建）应在完成（付款）时导入，而不是在创建为草稿时导入。订阅orders/create webhook，该钩子在草稿订单转换为真实订单时触发。或者，订阅草稿订单/更新并仅在状态更改为“已完成”时导入。

Shopify POS 订单怎么样 - 它们遵循相同的管道吗？

Shopify POS 订单触发与在线订单相同的订单/创建 Webhook。尽管您可能希望使用不同的 Odoo 销售团队或报告来源来标记 POS 订单，但集成可以以相同的方式处理它们。 POS 订单还可能包括现金或外部终端支付方式，这需要不同的 Odoo 支付日志配置。

导入后如何处理订单编辑（例如商家在 Shopify 上编辑订单）？

编辑订单时，Shopify 会触发订单/更新的 Webhook。集成应将更新的订单与现有的 Odoo 销售订单进行比较，并应用差异 - 添加的行项目、删除的项目、数量更改或价格调整。这是集成中最复杂的部分之一，一些实现通过取消 Odoo SO 并重新创建它来处理它，这更简单，但会创建更多会计条目。

自动化可以处理来自 Shopify Subscriptions 应用的订阅订单吗？

订阅订单（来自 Recharge、Bold Subscriptions 或 Shopify 本机订阅）会触发标准订单/为每个定期费用创建 Webhooks。集成像任何其他订单一样导入它们。要将定期订单链接到 Odoo 订阅记录，请使用应用程序元字段中的订阅 ID 作为参考，并将所有相关的 Odoo 销售订单与单个 Odoo 订阅相关联。

---

使用 ECOSIRE 实施

构建生产级 Shopify 到 Odoo 订单导入管道需要处理数十种边缘情况，这些情况在生产中遇到时并不明显——部分付款、包含数字和实物商品的订单、复杂的税务管辖区、多仓库路由和供应商代发货履行。

ECOSIRE 已为数百家 Shopify 商家实施了此管道。我们的 Shopify 集成服务 包括完整的订单自动化以及本指南中描述的完整管道、针对所有常见边缘情况的预构建处理、实时监控和警报以及随着 API 发展而进行的持续维护。

对于也希望实现财务自动化的企业，请参阅我们的 Shopify + Odoo 会计集成 指南，或将您的选项与我们的 Shopify-Odoo 连接器比较 进行比较。

安排咨询 与我们的集成团队讨论您的 Shopify 订单自动化要求。