Gửi hàng loạt (hợp nhất)

Tài liệu này hướng dẫn quy trình ba bước để tạo lô gửi hàng loạt có thanh toán trì hoãn của Japan Post thông qua API GraphQL của Zonos: mở một hợp nhất, đính kèm n bưu kiện vào nó, sau đó đóng để nhận tờ khai gửi hàng của Japan Post (tài liệu tờ khai).

Khi nào sử dụng luồng này 

Chương trình thanh toán trì hoãn của Japan Post (後納) cho phép một thương gia giải quyết hóa đơn vận chuyển hàng ngày của họ trong một giao dịch vào cuối ngày, thay vì từng bưu kiện tại quầy. Thương gia mang tất cả các bưu kiện của ngày đến bưu điện cùng với một tờ khai gửi hàng (差出票) bao gồm tối đa 250 bưu kiện. Cước phí được tính hóa đơn cho Số Thanh toán Trì hoãn được đăng ký trước của thương gia.

Nếu bạn đang gửi các nhãn Japan Post riêng lẻ và thanh toán từng bưu kiện tại quầy, bạn không cần luồng này — gọi trực tiếp chuỗi bưu kiện đơn mà không cần hợp nhất.

Tổng quan 

1. shipmentConsolidationCreate            → mở lô (trả về ID hợp nhất)
2. Đính kèm bưu kiện × n                   → tạo từng bưu kiện + nhãn, được gắn vào lô
3. shipmentConsolidationUpdate(CLOSED)    → đóng lô (trả về tờ khai gửi hàng)

Có hai cách để đính kèm bưu kiện vào lô — sử dụng cách nào phù hợp với tích hợp của bạn (hoặc kết hợp chúng):

• Đính kèm tại thời điểm tạo nhãn — truyền ID hợp nhất từ bước 1 vào từng cuộc gọi shipmentCreateWorkflow thông qua trường shipmentConsolidationId.
• Đính kèm các bưu kiện hiện có theo ID — truyền shipmentIds trên shipmentConsolidationCreate (để hạt giống lô) hoặc trên shipmentConsolidationUpdate (để thêm vào lô mở). Mỗi bưu kiện phải đã có nhãn Japan Post.

Dù bằng cách nào, mỗi nhãn được tạo với Số Thanh toán Trì hoãn của bạn được nhúng vào để Japan Post sẽ chấp nhận nó trên tờ khai gửi hàng khi bước 3 đóng lô.

Tại sao lại gọi riêng thay vì một mutation? Các bước 2.1, 2.2, ..., 2.n xảy ra trong suốt ngày của thương gia — nhãn được in và bưu kiện được đóng kín khi các đơn hàng đến. Lô không thể là một chuyến tròn như chuỗi bưu kiện đơn được: có khoảng cách nhiều giờ giữa việc mở hợp nhất và đóng nó.

Điều kiện tiên quyết 

Trước khi luồng này hoạt động cho một Tài khoản Được xác minh nhất định:

• Tài khoản của bạn phải có Số Thanh toán Trì hoãn của Japan Post (後納お客様番号) được lưu trên đó — một giá trị được định dạng bằng dấu gạch ngang như 1111111111-222222-3333333333-444444. Truyền nó trên shipmentConsolidationCreate thông qua accountNumber (Bước 1).
• Khóa API của bạn phải giữ SHIPMENT_WRITE, cộng với các phạm vi tiêu chuẩn mà luồng công việc cho mỗi bưu kiện cần.

Điểm cuối và xác thực 

Cả ba bước dưới đây đều là các hoạt động GraphQL được gửi đến cùng một điểm cuối. Những gì bạn truyền trong các tiêu đề phụ thuộc vào cài đặt của bạn — chọn tab của bạn.

URL:

https://api.zonos.com/graphql

Tiêu đề:

credentialToken: {{YOUR_API_TOKEN}}

Ví dụ yêu cầu 

Một ví dụ sao chép và điều chỉnh về việc mở một hợp nhất — mutation, các biến của nó và phản hồi. Đây là cuộc gọi cụ thể batch bắt đầu luồng; đính kèm bưu kiện (Bước 2) tái sử dụng ví dụ bưu kiện đơn, và đóng lô (Bước 3) trả về tài liệu tờ khai. Mỗi trường được chia nhỏ trong các bước dưới đây.

Bước 1: shipmentConsolidationCreate 

Mở hợp nhất. Mã mã vận chuyển khóa lô cho Japan Post; tất cả các bưu kiện thành viên phải sử dụng mức dịch vụ của Japan Post. Nếu bạn đã có các bưu kiện được dán nhãn, hạt giống lô bằng ID của chúng thông qua shipmentIds — nếu không hãy tạo nó trống và đính kèm bưu kiện ở bước 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
    }
  }
}

Phản hồi:

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

Giữ id (ví dụ: shco_01HJK...) — bạn sẽ sử dụng nó cho mọi thứ dưới đây. Trạng thái (status) là OPEN cho đến bước 3.

Bước 2: Đính kèm bưu kiện 

Đối với mỗi bưu kiện bạn cần gửi hôm nay, chạy quy trình chuỗi bưu kiện đơn đầy đủ để tạo bưu kiện và nhãn của nó. Sau đó đính kèm bưu kiện vào lô bằng một trong các phương pháp dưới đây.

Tùy chọn A: Đính kèm tại thời điểm tạo nhãn

Truyền ID hợp nhất trên bước shipmentCreateWorkflow cuối cùng của chuỗi. Tất cả các mutation trước trong chuỗi giống với quy trình bưu kiện đơn.

Các trường liên quan trên shipmentCreateWorkflow:

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

Tùy chọn B: Đính kèm các bưu kiện hiện có theo ID

Nếu bưu kiện của bạn đã được tạo và dán nhãn, hãy thêm chúng vào lô mở bằng shipmentIds trên shipmentConsolidationUpdate:

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

Bỏ status ngoài đầu vào trong khi bạn vẫn đang thêm bưu kiện — lô vẫn ở trạng thái OPEN. Mỗi bưu kiện phải sử dụng mức dịch vụ Japan Post và có nhãn (số theo dõi) của nó trước khi lô được đóng ở Bước 3.

Ý nghĩa đính kèm đối với nhãn

Dù bạn sử dụng tùy chọn nào, khi một bưu kiện Japan Post là một phần của hợp nhất:

• Bưu kiện có một số theo dõi, như bình thường.
• PDF không bao gồm các bản sao nhận hàng của khách hàng/bưu điện của nhãn vận chuyển. Những biên lai đó được trì hoãn đến Bước 3, nơi chúng được gộp vào tài liệu tờ khai gửi hàng cho toàn bộ lô.
• Bưu kiện được liên kết với hợp nhất; bạn có thể truy vấn lại nó thông qua shipmentConsolidation(id: ...) để xem các thành viên của nó.

Lặp lại bước này cho mỗi bưu kiện trong lô ngày hôm nay. Tối đa 250 bưu kiện trên mỗi hợp nhất; cố gắng đóng một lô lớn hơn sẽ thất bại với lỗi xác thực rõ ràng trước khi bất kỳ cuộc gọi Japan Post nào được thực hiện.

Bạn cũng có thể xác minh nội dung lô trước khi đóng:

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

Mỗi bưu kiện nên hiển thị một số theo dõi ở đây. Nếu không, nhãn của nó không bao giờ được tạo — hãy sắp xếp nó trước khi đóng. Trạng thái (status) là OPEN cho đến khi hợp nhất được đóng ở Bước 3.

Bước 3: shipmentConsolidationUpdate(status: CLOSED) 

Đóng lô. Đây là cuộc gọi yêu cầu Japan Post tạo tờ khai gửi hàng có thanh toán trì hoãn bao gồm số theo dõi của mỗi thành viên và gắn PDF kết quả vào hợp nhất.

Hoạt động GraphQL được đặt tên là CloseConsolidation để mô tả mục đích của nó, đóng lô. Nó chạy mutation shipmentConsolidationUpdate với status: CLOSED.

Mutation:

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

Trên một yêu cầu CLOSED:

1. Hợp nhất được xác thực: ≤250 bưu kiện, và mỗi thành viên phải có một số theo dõi. Nếu một bưu kiện thiếu số theo dõi của nó (nhãn của nó không bao giờ được tạo), cuộc gọi sẽ bị từ chối.
2. Japan Post được yêu cầu tạo tờ khai gửi hàng có thanh toán trì hoãn bao gồm số theo dõi của mỗi thành viên.
3. Trạng thái chuyển sang MANIFEST_CREATED trong khi PDF đang được tìm nạp, sau đó sang CLOSED khi tài liệu đã được gắn vào.
4. PDF tờ khai gửi hàng (một tệp chứa tờ khai cộng với biên lai khách hàng/bưu điện của mỗi thành viên) được gắn vào hợp nhất dưới dạng CustomsDocument với documentType: MANIFEST_DOCUMENT.

Phản hồi:

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

Truy xuất các tài liệu

Tờ khai gửi hàng được gắn trực tiếp vào hợp nhất dưới dạng CustomsDocument với documentType: MANIFEST_DOCUMENT — chụp fileUrl từ phản hồi đóng ở trên, hoặc truy vấn nó bất kỳ lúc nào sau:

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

In PDF tại fileUrl. Nó chứa:

• Trang 1: Tờ khai gửi hàng có thanh toán trì hoãn — trao cho bưu điện.
• Trang 2+: Biên lai khách hàng/bưu điện cho mỗi bưu kiện — một dán vào mỗi bưu kiện, cái kia được bưu điện giữ lại.

Sau khi in, mang các bưu kiện + tờ khai gửi hàng + các biên lai đến bưu điện trong một chuyến. Japan Post tính hóa đơn cho Số Thanh toán Trì hoãn của bạn vào cuối kỳ thanh toán.

Tập hợp nó lại với nhau 

Một ngày đại diện cho thương gia gửi 50 bưu kiện Japan Post trông như:

08:00 → shipmentConsolidationCreate(JAPAN_POST, accountNumber)  → shco_01HJK...
08:30 → CreateDeclarationShipment( ... shipmentConsolidationId: "shco_01HJK..." )    bưu kiện 1
09:15 → CreateDeclarationShipment( ... shipmentConsolidationId: "shco_01HJK..." )    bưu kiện 2
...
16:45 → CreateDeclarationShipment( ... shipmentConsolidationId: "shco_01HJK..." )    bưu kiện 50
17:30 → shipmentConsolidationUpdate(id: "shco_01HJK...", status: CLOSED)
17:32 → In PDF

Thích gộp vào cuối ngày thay vì? Tạo nhãn ngày hôm nay mà không có ID hợp nhất, sau đó mở hợp nhất một lần với mọi giá trị shipmentIds (hoặc thêm chúng theo từng đợt qua shipmentConsolidationUpdate) và đóng nó trong cùng một cuộc gọi hoặc cuộc gọi tiếp theo.

Nếu bạn gửi hàng trên nhiều đơn vị kinh doanh / tài khoản thanh toán, chạy một hợp nhất riêng cho mỗi tài khoản — truyền accountNumber khác nhau trên từng shipmentConsolidationCreate và định tuyến bưu kiện tương ứng. Gửi hơn 250 bưu kiện trong một ngày? Mở hợp nhất thứ hai.

Xử lý lỗi 

Lỗi xác thực (bị bắt trước bất kỳ cuộc gọi Japan Post nào)

• accountNumber không đúng định dạng — bị từ chối ở Bước 1 (shipmentConsolidationCreate) trước khi hợp nhất được lưu lại. Thông báo lỗi xác định phân khúc có lỗi.
• >250 bưu kiện — bị từ chối ở Bước 3, trước cuộc gọi Japan Post.
• Bưu kiện thành viên thiếu số theo dõi — bị từ chối ở Bước 3. Có nghĩa là tạo nhãn đã thất bại âm thầm trước đó; điều tra bưu kiện bị ảnh hưởng qua shipment(id: ...) { trackingDetails }.
• Không có số thanh toán trì hoãn được đặt trên hợp nhất — bị từ chối ở Bước 3. Truyền accountNumber trên shipmentConsolidationCreate, hoặc lưu số tài khoản mặc định trên tài khoản mã vận chuyển Japan Post của bạn.

Lỗi API Japan Post

Nếu Japan Post từ chối yêu cầu tờ khai gửi hàng, mutation đóng hiển thị mã lỗi và thông báo của mã vận chuyển dưới dạng lỗi GraphQL. Những lỗi phổ biến nhất:

Thử lại

Nếu cuộc gọi đóng thất bại sau Japan Post đã chấp nhận yêu cầu tờ khai gửi hàng (tức là trong khi truy xuất PDF), việc thử lại shipmentConsolidationUpdate(status: CLOSED) là an toàn — nền tảng sẽ bỏ qua cuộc gọi mã vận chuyển và chỉ cố gắng lại tìm nạp và gắn tài liệu.

Nếu phần đóng thất bại trước Japan Post đã chấp nhận yêu cầu (lỗi xác thực, E0xx, hết thời gian chờ mạng), không có trạng thái nào được thay đổi — sửa nguyên nhân gốc và thử lại.