批量派送（合併）

本文件介紹透過 Zonos GraphQL API 建立日本郵局延期付款派送批次的三階段流程：開啟合併、附加 n 份寄件至其中，然後關閉以接收日本郵局的派送單（清單文件）。

何時使用此流程 

日本郵局的延期付款計畫（後納）允許商戶在一天結束時透過一筆交易結算其日常運費帳單，而不是在郵局投遞時逐件付款。商戶將當天所有包裹連同一份涵蓋最多 250 份寄件的派送單（差出票）帶到郵局。郵資按商戶預先登記的 Later Pay Number 開具發票。

如果您獨立寄送日本郵局標籤並在櫃台按件付款，您無須使用此流程 — 直接呼叫單份寄件流程，不需使用合併。

概述 

1. shipmentConsolidationCreate            → 開啟批次（傳回合併 ID）
2. 附加寄件 × n                             → 建立各寄件 + 標籤，附加至批次
3. shipmentConsolidationUpdate(CLOSED)    → 關閉批次（傳回派送單）

有兩種方式可將寄件附加到批次 — 選擇適合您整合的方式（或混合使用）：

• 在標籤建立時附加 — 透過 shipmentConsolidationId 欄位將第 1 步中的合併 ID 傳入每個 shipmentCreateWorkflow 呼叫。
• 依 ID 附加現有寄件 — 在 shipmentConsolidationCreate 上傳遞 shipmentIds（為批次設定種子）或在 shipmentConsolidationUpdate 上傳遞（新增至開啟的批次）。各寄件必須已具有其日本郵局標籤。

無論哪種方式，各標籤都會以您的 Later Pay Number 嵌入方式建立，以便日本郵局在第 3 步關閉批次時接受其進入派送單。

為什麼是分別呼叫而不是一個變更？ 第 2.1、2.2、...、2.n 步發生在商戶的一整天 — 標籤列印、包裹封存會在訂單到達時進行。該批次無法如單份寄件流程那樣成為單一往返：開啟合併和關閉合併之間有數小時的間隔。

先決條件 

在此流程對指定的驗證帳戶生效前：

• 您的帳戶必須已儲存日本郵局延期付款 Later Pay Number（後納お客様番号） — 一個連字號格式的值，如 1111111111-222222-3333333333-444444。透過 accountNumber（第 1 步）在 shipmentConsolidationCreate 上傳遞。
• 您的 API 金鑰必須持有 SHIPMENT_WRITE，加上每個寄件工作流程所需的標準作用域。

端點和驗證 

以下三個步驟都是傳送至同一端點的 GraphQL 操作。您在標題中傳遞的內容取決於您的設定 — 選擇您的分頁籤。

URL：

https://api.zonos.com/graphql

標題：

credentialToken: {{YOUR_API_TOKEN}}

範例請求 

開啟合併的複製並調整範例 — 變更、其變數和回應。這是啟動流程的批次特定呼叫；附加寄件（第 2 步）重複使用單份寄件範例，關閉批次（第 3 步）會傳回清單文件。各欄位在下方的步驟中有詳細說明。

步驟 1：shipmentConsolidationCreate 

開啟合併。承運商代碼將批次鎖定為日本郵局；所有成員寄件必須使用日本郵局服務級別。如果您已有已標籤的寄件準備好，透過 shipmentIds 使用其 ID 為批次設定種子 — 否則建立空批次，並在第 2 步中附加寄件。

變更：

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。鏈中所有前述變更與單份寄件工作流程相同。

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 以描述其意圖，關閉批次。它以 status: CLOSED 執行 shipmentConsolidationUpdate 變更。

變更：

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 及國際包裹寄件產生，因為它們是依追蹤號碼建立的。

列印後，在一趟中將包裹 + 派送單 + 收據帶至郵局。日本郵局在計費期結束時按您的 Later Pay Number 開具發票。

第 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 錯誤

如果日本郵局拒絕派送單請求，關閉變更會將承運商的錯誤代碼和訊息呈現為 GraphQL 錯誤。最常見的：

重試

如果關閉呼叫在日本郵局已接受派送單請求之後失敗（即在 PDF 擷取期間），重試 shipmentConsolidationUpdate(status: CLOSED) 是安全的 — 平台將跳過承運商呼叫，只重新嘗試擷取和附加文件。

如果關閉在日本郵局接受請求之前失敗（驗證錯誤、E0xx、網路逾時），沒有狀態改變 — 修正根本原因並重試。