订单 vs 发货 vs 包裹 vs 面单：写给 OMS、WMS 与 3PL API 的物流数据模型

四个实体与一张与厂商无关的关系树

四个实体，四个不同的职责。把任何两个搞混，集成就会开始腐烂。

• 订单（Order）：商业承诺。客户同意购买并支付的东西。活在 OMS 或 ERP 里，有订单行、合计和客户。
• 履约（Fulfillment，又名 Shipment）：履约动作。谁在什么时候履约什么。这是商业世界和物流世界之间的接缝。一个订单拆成 N 个履约，通常按仓库或履约服务商拆。
• 包裹（Package）：物理容器。真正离开仓库的那个箱子，有重量和尺寸。承运商扫描和搬运的就是它。
• 面单（Label）：承运商票据。承运一票包裹的权利凭证，带着面单号和追踪号。它既是票据也是金融工具，所以作废一张面单必须动钱，而不只是改状态。

与厂商无关的关系树：

Order
└── Fulfillment / Shipment
    ├── Package
    │   ├── Label
    │   └── Tracking Number
    └── Charges / Adjustments / Reversals

这棵树里有两条关系最值得强调，因为它们是大家最爱压平掉的东西。第一，一个履约可以产出多个包裹：三箱的订单是一个履约，不是三个。第二，一个包裹可以带多个追踪号：DHL 飞到边境、再转 USPS 送到门口的包裹有两段，每段都有自己的承运商和追踪号。如果你直接建模「order → tracking」，这两个事实都会消失。

为什么第二层叫「Fulfillment」而不是「Shipment」？因为平台们口径不一：Shopify 叫 fulfillment，Amazon 把 FBA 批次叫 shipment，多数 WMS 把每次派送都叫 shipment。树必须保持与厂商无关，所以这一层就是 fulfillment/shipment 这个概念本身，不管某个平台怎么叫。你的适配器把平台的名字映射到这个节点就停了，树的其他部分永远不变。想深入理解为什么订单状态、发货状态和追踪状态总是对不上，可以读姊妹篇订单状态 vs 发货状态 vs 追踪状态。

一套可落地的 JSON 模型

先定约定，因为每个系统各写各的时候，示例根本没法读。字段名用 snake_case。所有规范 ID 用 UUID。所有时间戳用 ISO 8601 UTC。一切嵌套都和关系树完全一致，这让数据自洽：追踪活在包裹下，费用活在履约下，每个履约都带着 order_id 回指商业承诺。

下面是完整订单的嵌套视图，为可读性做了精简：

{
  "order": {
    "id": "9f2c1d4e-6a3b-4c8d-9e0f-1a2b3c4d5e6f",
    "external_reference": "SHOP-1001",
    "status": "fulfilled",
    "fulfillments": [
      {
        "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
        "warehouse_id": "wh_east",
        "status": "shipped",
        "packages": [
          {
            "id": "3c4d5e6f-7a8b-4c9d-0e1f-2a3b4c5d6e7f",
            "weight_kg": 2.4,
            "tracking": [
              { "carrier": "DHL", "carrier_tracking_id": "DHL1234567890", "status": "delivered_to_last_mile" },
              { "carrier": "USPS", "carrier_tracking_id": "9400111899223198765432", "status": "in_transit" }
            ],
            "labels": [
              { "id": "5e6f7a8b-9c0d-4e1f-2a3b-4c5d6e7f8091", "carrier": "DHL", "status": "purchased", "cost": { "amount": 18.40, "currency": "USD" } }
            ]
          }
        ],
        "charges": [
          { "id": "7a8b9c0d-1e2f-4a3b-4c5d-6e7f8091a2b3", "charge_type": "shipping", "amount": 18.40 },
          { "id": "8b9c0d1e-2f3a-4b4c-5d6e-7f8091a2b3c4", "charge_type": "adjustment", "amount": 6.20, "reason": "declared_value_insurance" }
        ]
      },
      {
        "id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
        "warehouse_id": "wh_west",
        "status": "shipped",
        "packages": [
          {
            "id": "4d5e6f7a-8b9c-4d0e-1f2a-3b4c5d6e7f80",
            "weight_kg": 0.9,
            "tracking": [
              { "carrier": "USPS", "carrier_tracking_id": "9400111899223198765433", "status": "delivered" }
            ],
            "labels": [
              { "id": "6f7a8b9c-0d1e-4f2a-3b4c-5d6e7f8091a2", "carrier": "USPS", "status": "voided", "cost": { "amount": 12.85, "currency": "USD" } },
              { "id": "0e1f2a3b-4c5d-4e6f-8a90-1b2c3d4e5f60", "carrier": "USPS", "status": "purchased", "cost": { "amount": 13.40, "currency": "USD" } }
            ]
          }
        ],
        "charges": [
          { "id": "8f9a0b1c-2d3e-4f4a-5b6c-7d8e9f0a1b2c", "charge_type": "shipping", "amount": 12.85 },
          { "id": "9c0d1e2f-3a4b-4c5d-6e7f-8091a2b3c4d5", "charge_type": "reversal", "amount": -12.85, "reason": "voided_label" },
          { "id": "0d1e2f3a-4b5c-4d6e-7f80-91a2b3c4d5e6f", "charge_type": "shipping", "amount": 13.40 }
        ]
      }
    ]
  }
}

一个包裹带多段追踪，这是让多承运商运输保持诚实的形态：

{
  "id": "3c4d5e6f-7a8b-4c9d-0e1f-2a3b4c5d6e7f",
  "fulfillment_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "status": "in_transit",
  "weight_kg": 2.4,
  "dimensions_cm": { "length": 30, "width": 20, "height": 12 },
  "tracking": [
    { "segment": 1, "carrier": "DHL", "carrier_tracking_id": "DHL1234567890", "status": "delivered_to_last_mile" },
    { "segment": 2, "carrier": "USPS", "carrier_tracking_id": "9400111899223198765432", "status": "in_transit" }
  ],
  "created_at": "2026-08-21T13:52:18Z"
}

一张面单带着它的成本，因为计费需要用到：

{
  "id": "5e6f7a8b-9c0d-4e1f-2a3b-4c5d6e7f8091",
  "package_id": "3c4d5e6f-7a8b-4c9d-0e1f-2a3b4c5d6e7f",
  "carrier": "DHL",
  "label_format": "PDF",
  "label_url": "https://labels.example.com/5e6f7a8b-9c0d-4e1f-2a3b-4c5d6e7f8091.pdf",
  "status": "purchased",
  "cost": { "amount": 18.40, "currency": "USD" },
  "purchased_at": "2026-08-21T14:05:37Z"
}

然后是履约底下的资金轨迹：一笔运费、一笔调整、之后一笔冲销。调整修正之前的金额（正或负）。冲销精确镜像一笔费用，以负数记录，绝不修改原始行：

{
  "charges": [
    {
      "id": "7a8b9c0d-1e2f-4a3b-4c5d-6e7f8091a2b3",
      "fulfillment_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "charge_type": "shipping",
      "amount": 18.40,
      "currency": "USD",
      "description": "DHL express label for package 3c4d5e6f",
      "created_at": "2026-08-21T14:05:37Z"
    },
    {
      "id": "8b9c0d1e-2f3a-4b4c-5d6e-7f8091a2b3c4",
      "fulfillment_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "charge_type": "adjustment",
      "amount": 6.20,
      "currency": "USD",
      "reason": "declared_value_insurance",
      "description": "Additional declared-value insurance added after purchase",
      "created_at": "2026-08-21T15:02:11Z"
    }
  ]
}

状态流转：一次时序走查

下面是整段旅程的时序图，从客户到 OMS 到 WMS 到承运商，重试、作废和多承运商节点都标在它们真实发生的位置：

这段时间线里有三个时刻是前面决策兑现回报的地方。alt 分支是幂等 key 在干活：购买请求超时，重试复用同一个 key，承运商返回已存在的面单而不是扣两次钱。作废分支是冲销规则在起作用：面单死掉、钱被镜像、替换购买是一个干净的新面单 id。最后的妥投事件带着包裹第二段的追踪号，这之所以成立，只因为模型把追踪存到了包裹上，而不是订单上。

常见坑与建模决策

每一次集成评审里都会出现几个固定的失败模式。这里列出它们，以及防止每一种的建模决策。

• 「一单等于一包」的假设。写进 schema 就是订单上一列 tracking_number，订单第一次跨仓拆分或分三箱发货就崩。决策：把履约和包裹建模成真实实体，让追踪活在包裹上。
• 把追踪号当订单唯一键。多包裹订单有多个追踪号，多段包裹每个都有多个。拿追踪号当关联键会碰撞，或者更糟，悄悄只挑一个。决策：(carrier, tracking_number) 是唯一真正唯一的键，它标识一个包裹段，不是订单。
• 缺履约幂等。WMS 重试，重试创建了第二个履约，同样的货发了两次。决策：每次履约创建都带调用方生成的幂等 key，服务端按 (key, entity_type) 去重。
• 费用不挂履约。面单成本飘在订单或承运商账户上，月底没人能解释账单。决策：每笔费用、调整和冲销都带 fulfillment_id，账本只追加。
• 把平台空缺当平台事实。WooCommerce 没有原生面单，Etsy 没有包裹维度，Shopify 核心 API 也没有面单实体。把模型压平到最弱平台的团队，会在其他所有平台上丢失追踪和计费的保真度。决策：守住中立四实体树，在适配器里合成缺失层。

如果这篇文章你只带走一样东西，就带走它产出的这张清单。把它当作任何 OMS、WMS 或 3PL 集成的评审闸门：

1. 每个订单是否拆成一个或多个履约，每个履约是否知道自己的仓库？
2. 每次履约创建是否都带幂等 key？
3. 追踪是否按包裹存储，以 (carrier, tracking_number) 分段？
4. 费用、调整和冲销是否都带 fulfillment_id，且没有任何费用被修改过？
5. 能否把任何一美元从承运商账单追溯到履约、订单和客户？
6. 面单作废是否总在给同一包裹买新面单之前先写一笔冲销？

四个实体，五个决策，一张清单。这就是一套能扛住拆单、多段承运、作废风暴和月度对账的订单到面单数据模型的全部骨架。拿它建一次，以后每个新平台、新仓库、新承运商都只是一个适配器，而不是一次重设计。动手前可以用我们的API 上线就绪检查清单过一遍。

相关页面

订单状态 vs 发货状态 vs 追踪状态：为什么电商系统总是对不上阅读约 13 分钟RMA vs 退货包裹 vs 退货面单 vs 退款：一套逆向物流数据模型阅读约 14 分钟内嵌式还是独立式发货软件：运费、面单、跟踪与计费应该住在哪里阅读约 14 分钟

常见问题