批量寄送（合并）

本文档介绍如何通过 Zonos GraphQL API 创建日本邮政延迟支付寄送批次的三阶段流程：打开合并、将 n 个货件附加到该合并、然后关闭它以接收日本邮政的寄送单（清单文档）。

何时使用此流程 

日本邮政的延迟支付计划（後納）允许商户在一天结束时在一次交易中结清日常运费单，而不是在送货时按包裹支付。商户将当日所有包裹和一份寄送单（差出票）一起送到邮局，最多涵盖 250 个货件。邮资费用将计入商户预先登记的稍后支付号码。

如果您正在单独发送日本邮政标签并在柜台按件支付，则不需要此流程 — 直接调用单货件链而不使用合并。

概述 

1. shipmentConsolidationCreate            → 打开批次（返回合并 ID）
2. 附加货件 × n                           → 创建每个货件 + 标签，附加到批次
3. shipmentConsolidationUpdate(CLOSED)    → 关闭批次（返回寄送单）

有两种方式将货件附加到批次 — 选择适合您集成的方式（或混合使用）：

• 在标签创建时附加 — 通过 shipmentConsolidationId 字段将第 1 步中的合并 ID 传入每个 shipmentCreateWorkflow 调用。
• 按 ID 附加现有货件 — 在 shipmentConsolidationCreate 上传递 shipmentIds（以播种批次）或在 shipmentConsolidationUpdate 上传递（以添加到打开的批次）。每个货件必须已有其日本邮政标签。

无论哪种方式，每个标签都是用您的稍后支付号码创建的，以便日本邮政在第 3 步关闭批次时接受它到寄送单上。

为什么不是一个 Mutation 而是分开的调用？ 第 2.1、2.2、...、2.n 步在商户的整个工作日中进行 — 随着订单不断到来，标签被打印，包裹被密封。批次无法像单货件链那样一步完成：打开合并和关闭它之间有数小时的间隔。

前置条件 

在此流程适用于给定验证账户之前：

• 您的账户必须有一个日本邮政延迟支付稍后支付号码（後納お客様番号）保存在其上 — 一个连字符格式的值，如 1111111111-222222-3333333333-444444。通过 accountNumber 在 shipmentConsolidationCreate 上传递它（步骤 1）。
• 您的 API 密钥必须持有 SHIPMENT_WRITE，加上每货件工作流需要的标准范围。

端点和身份验证 

下面的所有三个步骤都是发送到同一端点的 GraphQL 操作。您在标题中传递的内容取决于您的设置 — 选择您的选项卡。

URL：

https://api.zonos.com/graphql

标题：

credentialToken: {{YOUR_API_TOKEN}}

示例请求 

一个复制和适应示例来打开合并 — Mutation、其变量和响应。这是启动流程的批次特定调用；附加货件（步骤 2）重用单货件示例，关闭批次（步骤 3）返回清单文档。下面的步骤中分解了每个字段。

步骤 1：shipmentConsolidationCreate 

打开合并。承运商代码将批次锁定为日本邮政；所有成员货件必须使用日本邮政服务级别。如果您已经有标记的货件准备好，通过 shipmentIds 用它们的 ID 播种批次 — 否则创建一个空的并在步骤 2 中附加货件。

Mutation：

mutation {
  shipmentConsolidationCreate(
    input: {
      carrierCode: JAPAN_POST
      accountNumber: "1111111111-222222-3333333333-444444"
      name: "Tokyo dispatch — 2026-05-01"
      externalId: "merchant-batch-20260501-001"
      shipmentIds: ["shipment_01hxa...", "shipment_01hxb..."]
    }
  ) {
    id
    status
    accountNumber
    carrierCode
    shipments {
      id
    }
  }
}

响应：

{
  "data": {
    "shipmentConsolidationCreate": {
      "id": "shco_01hjk...",
      "status": "OPEN",
      "accountNumber": "1111111111-222222-3333333333-444444",
      "carrierCode": "JAPAN_POST",
      "shipments": [
        { "id": "shipment_01hxa..." },
        { "id": "shipment_01hxb..." }
      ]
    }
  }
}

保留 id（例如 shco_01HJK...）— 您将在下面的所有内容中使用它。status 是 OPEN，直到步骤 3。

步骤 2：附加货件 

对于您需要在今天运送的每个包裹，运行完整的链式单货件工作流来创建货件及其标签。然后使用下面的两种方法之一将货件附加到批次。

选项 A：在标签创建时附加

在链的最后 shipmentCreateWorkflow 步骤上传递合并 ID。链中的所有前述 Mutation 与单货件工作流相同。

shipmentCreateWorkflow 上的相关字段：

shipmentCreateWorkflow(
  input: {
    serviceLevel: "japan_post.air.ems_merchandise"
    shipmentConsolidationId: "shco_01hjk..."
    generateLabel: true
  }
) {
  id
  trackingDetails {
    number
  }
  shipmentCartons {
    label {
      labelImage
    }
  }
}

选项 B：按 ID 附加现有货件

如果您的货件已经创建并标记，使用 shipmentConsolidationUpdate 上的 shipmentIds 将它们添加到打开的批次：

mutation {
  shipmentConsolidationUpdate(
    input: {
      id: "shco_01hjk..."
      shipmentIds: ["shipment_01hxd...", "shipment_01hxe..."]
    }
  ) {
    id
    status
    shipments {
      id
    }
  }
}

在您仍在添加货件时，请不要在输入中包含 status 字段 — 批次将保持 OPEN。每个货件必须使用日本邮政服务级别，并在步骤 3 中关闭批次之前有其标签（跟踪号）。

附加对标签的含义

无论您使用哪个选项，当日本邮政货件是合并的一部分时：

• 货件有跟踪号，如常。
• 运费单 PDF 不包括客户/邮局收据副本。这些收据被推迟到步骤 3，在那里它们被捆绑到整个批次的寄送单文档中。
• 货件与合并相关联；您可以通过 shipmentConsolidation(id: ...) 重新查询它以查看其成员。

对当日批次中的每个包裹重复此步骤。每个合并最多250 个货件；尝试关闭更大的批次会失败，但在任何日本邮政调用前会出现明确的验证错误。

您也可以在关闭前验证批次的内容：

query {
  shipmentConsolidation(id: "shco_01hjk...") {
    status
    shipments {
      id
      trackingDetails {
        number
      }
    }
  }
}

每个货件应该在此处显示跟踪号。如果没有，其标签从未被创建 — 在关闭前解决该问题。status 是 OPEN，直到合并在步骤 3 中关闭。

步骤 3：shipmentConsolidationUpdate(status: CLOSED) 

关闭批次。这是要求日本邮政生成覆盖每个成员跟踪号的延迟支付寄送单并将结果 PDF 附加到合并的调用。

GraphQL 操作名为 CloseConsolidation 以描述其意图，关闭批次。它运行 shipmentConsolidationUpdate Mutation，带有 status: CLOSED。

Mutation：

mutation CloseConsolidation {
  shipmentConsolidationUpdate(input: { id: "shco_01hjk...", status: CLOSED }) {
    id
    status
    statusTransitions {
      status
      changedAt
      note
    }
    customsDocuments {
      documentType
      fileUrl
    }
  }
}

在 CLOSED 请求时：

1. 合并被验证：≤250 个货件，每个成员都必须有跟踪号。如果货件缺少其跟踪号（其标签从未被创建），该调用会被拒绝。
2. 要求日本邮政生成覆盖每个成员跟踪号的延迟支付寄送单。
3. 状态短暂移动到 MANIFEST_CREATED，同时正在获取寄送单 PDF，然后在文档被附加后移动到 CLOSED。
4. 寄送单 PDF（一个包含该寄送单加上每个成员的客户/邮局收据的文件）被附加到合并作为 CustomsDocument，documentType: MANIFEST_DOCUMENT。

响应：

{
  "data": {
    "shipmentConsolidationUpdate": {
      "id": "shco_01hjk...",
      "status": "CLOSED",
      "statusTransitions": [
        {
          "status": "OPEN",
          "changedAt": "2026-05-01T08:00:00Z",
          "note": "Shipment batch created"
        },
        {
          "status": "MANIFEST_CREATED",
          "changedAt": "2026-05-01T17:30:12Z",
          "note": "Dispatch slip created with Japan Post"
        },
        {
          "status": "CLOSED",
          "changedAt": "2026-05-01T17:30:14Z",
          "note": "Dispatch slip downloaded and uploaded"
        }
      ],
      "customsDocuments": [
        {
          "documentType": "MANIFEST_DOCUMENT",
          "fileUrl": "https://customs-docs.zonos.com/.../japanpost-dispatch-slip.pdf"
        }
      ]
    }
  }
}

检索文档

寄送单直接附加到合并作为 CustomsDocument，documentType: MANIFEST_DOCUMENT — 从上面的关闭响应中获取 fileUrl，或稍后任何时间查询它：

query {
  shipmentConsolidation(id: "shco_01hjk...") {
    status
    customsDocuments {
      documentType
      fileUrl
    }
  }
}

打印 fileUrl 处的 PDF。它包含：

• 第 1 页： 延迟支付寄送单（後納差出票）— 交给邮局。批次中的每个货件都会列在此处，无论使用何种服务级别。
• 第 2+ 页： 客户/邮局收据 — 一份装订到每个包裹，另一份由邮局保留。这些页面仅针对 EMS 和国际包裹货件生成，因为它们与跟踪号相关联。

打印后，将包裹 + 寄送单 + 收据一起送到邮局。日本邮政在计费期结束时向您的稍后支付号码开具发票。

第 1 页上没有收据页的货件，并不代表货件遗漏。 小型包裹（小形包装物）不是可跟踪的日本邮政服务，因此它会列在第 1 页上，但不会生成第 2+ 页的收据。一批五个包裹的批次可能会在第 1 页上合法地列出全部五个，但只有 EMS 和国际包裹的货件才有收据页；一批全部为小型包裹的货件则只会有第 1 页，没有任何后续页面。这是日本邮政的预期行为，并非标签失败或清单调用失败。您无需为每个服务级别单独打开一个合并。已于 2026 年 8 月与日本邮政确认。

将其放在一起 

一个代表商户运送 50 个日本邮政包裹的典型日子看起来像：

08:00 → shipmentConsolidationCreate(JAPAN_POST, accountNumber)  → shco_01HJK...
08:30 → CreateDeclarationShipment( ... shipmentConsolidationId: "shco_01HJK..." )    包裹 1
09:15 → CreateDeclarationShipment( ... shipmentConsolidationId: "shco_01HJK..." )    包裹 2
...
16:45 → CreateDeclarationShipment( ... shipmentConsolidationId: "shco_01HJK..." )    包裹 50
17:30 → shipmentConsolidationUpdate(id: "shco_01HJK...", status: CLOSED)
17:32 → 打印 PDF

更喜欢在一天结束时批处理？在没有合并 ID 的情况下创建当天的标签，然后一次使用每个 shipmentIds 值打开合并（或通过 shipmentConsolidationUpdate 分块添加它们）并在同一或后续调用中关闭它。

如果您在多个业务单位/计费账户之间发货，为每个账户运行单独的合并 — 在每个 shipmentConsolidationCreate 上传递不同的 accountNumber 并相应地路由货件。在一天内运送超过 250 个包裹？打开第二个合并。

错误处理 

验证错误（在任何日本邮政调用之前捕获）

• accountNumber 格式错误 — 在步骤 1（shipmentConsolidationCreate）被拒绝，甚至在合并被保存之前。错误消息标识有问题的部分。
• >250 个货件 — 在步骤 3 被拒绝，在日本邮政调用之前。
• 成员货件缺少跟踪号 — 在步骤 3 被拒绝。意味着标签创建早期无声失败；通过 shipment(id: ...) { trackingDetails } 调查受影响的货件。
• 合并上未设置延迟支付号码 — 在步骤 3 被拒绝。在 shipmentConsolidationCreate 上传递 accountNumber，或在您的日本邮政承运商账户上保存默认账户号码。

日本邮政 API 错误

如果日本邮政拒绝寄送单请求，关闭 Mutation 会将承运商的错误代码和消息作为 GraphQL 错误呈现出来。最常见的：

重试

如果关闭调用在日本邮政接受寄送单请求后失败（即在 PDF 检索期间），重试 shipmentConsolidationUpdate(status: CLOSED) 是安全的 — 平台将跳过承运商调用并仅重新尝试获取和附加文档。

如果关闭在日本邮政接受请求前失败（验证错误、E0xx、网络超时），没有状态已更改 — 修复根本原因并重试。