批次分派(整合)

本文件介紹通過 Zonos GraphQL API 建立日本郵便延期付款分派批次的三階段流程：開啟整合、將 n 個貨件附加到其中，然後關閉以取得日本郵便的分派單(清單文件)。

何時使用此流程 

日本郵便的延期付款計畫(後納)讓商家在一天結束時透過一筆交易清算每日運費帳單，而不是在運送時按件計費。商家帶著當天的所有包裹到郵局，並帶著一張分派單(差出票)，最多可涵蓋 250 件貨件。郵資計入商家預先登記的延期付款號碼。

如果您正在運送個別日本郵便標籤並在櫃台按件付款，您不需要此流程 — 直接呼叫單件運費鏈，無需整合。

概述 

1. shipmentConsolidationCreate            → 開啟批次(傳回整合 ID)
2. 附加貨件 × n                           → 建立每件貨件 + 標籤，附加到批次
3. shipmentConsolidationUpdate(CLOSED)    → 關閉批次(傳回分派單)

有兩種方式可以將貨件附加到批次 — 選擇適合您的整合方式(或混合使用):

• 在標籤建立時附加 — 將第 1 步的整合 ID 通過 shipmentConsolidationId 欄位串接到每個 shipmentCreateWorkflow 呼叫。
• 按 ID 附加現有貨件 — 在 shipmentConsolidationCreate (用種子填充批次) 或 shipmentConsolidationUpdate (添加到開啟批次) 時傳遞 shipmentIds。每件貨件必須已有其日本郵便標籤。

無論哪種方式，每個標籤都會使用您的延期付款號碼建立，以便日本郵便在第 3 步關閉批次時將其接受到分派單。

為什麼使用分開的呼叫而不是一個突變? 第 2.1、2.2 ...、2.n 步在商家的整天內發生 — 隨著訂單的到來，標籤被列印，包裹被封存。批次無法像單件運費鏈那樣進行單一往返：開啟整合和關閉它之間有多個小時的間隔。

先決條件 

此流程對於給定的驗證帳戶生效之前：

• 您的帳戶必須已儲存日本郵便延期付款號碼(後納お客様番号) — 一個像 1111111111-222222-3333333333-444444 這樣的連字號格式值。在第 1 步通過 shipmentConsolidationCreate 上的 accountNumber 傳遞它。
• 您的 API 金鑰必須持有 SHIPMENT_WRITE，加上每件運費工作流程需要的標準範圍。

端點和驗證 

以下三個步驟都是發送到同一個端點的 GraphQL 操作。您在標頭中傳遞的內容取決於您的設定 — 選擇您的索引標籤。

URL:

https://api.zonos.com/graphql

Headers:

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(一個包含滑動和每個成員的客戶/郵局收據的文件)作為 documentType: MANIFEST_DOCUMENT 的 CustomsDocument 附加到整合。

回應:

{
  "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"
        }
      ]
    }
  }
}

取得文件

分派單直接作為 documentType: MANIFEST_DOCUMENT 的 CustomsDocument 附加到整合 — 從上面的關閉回應中獲取 fileUrl，或稍後任何時間查詢它：

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

列印 fileUrl 處的 PDF。它包含：

• 第 1 頁: 延期付款分派單 — 將此交給郵局。
• 第 2+ 頁: 每件包裹的客戶/郵局收據 — 一張訂在每件包裹上，另一張由郵局保留。

列印後，帶著包裹 + 分派單 + 收據一起去郵局。日本郵便在帳單期結束時向您的延期付款號碼開發票。

放在一起 

商家運費 50 件日本郵便包裹的典型一天看起來像：

08:00 → shipmentConsolidationCreate(JAPAN_POST, accountNumber)  → shco_01HJK...
08:30 → CreateDeclarationShipment( ... shipmentConsolidationId: "shco_01HJK..." )    parcel 1
09:15 → CreateDeclarationShipment( ... shipmentConsolidationId: "shco_01HJK..." )    parcel 2
...
16:45 → CreateDeclarationShipment( ... shipmentConsolidationId: "shco_01HJK..." )    parcel 50
17:30 → shipmentConsolidationUpdate(id: "shco_01HJK...", status: CLOSED)
17:32 → Print 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、網路逾時)，沒有狀態改變 — 修復根本原因並重試。