Pengiriman batch (konsolidasi)

Dokumen ini memandu alur tiga tahap untuk membuat batch pengiriman dengan pembayaran tertunda Japan Post melalui GraphQL API Zonos: buka konsolidasi, lampirkan n pengiriman ke dalamnya, kemudian tutup untuk menerima slip pengiriman Japan Post (dokumen manifest).

Kapan menggunakan alur ini 

Program pembayaran tertunda Japan Post (後納) memungkinkan pedagang menyelesaikan tagihan pengiriman harian mereka dalam satu transaksi di akhir hari, bukan per paket di tempat penjualan. Pedagang membawa semua paket hari itu ke kantor pos bersama satu slip pengiriman (差出票) yang mencakup hingga 250 pengiriman. Porto ditagihkan ke Nomor Pembayaran Kemudian yang telah terdaftar sebelumnya dari pedagang.

Jika Anda mengirim label Japan Post individual dan membayar paket demi paket di meja konter, Anda tidak memerlukan alur ini — panggil rantai pengiriman tunggal secara langsung tanpa konsolidasi.

Gambaran 

1. shipmentConsolidationCreate            → buka batch (mengembalikan ID konsolidasi)
2. Lampirkan pengiriman × n                → buat setiap pengiriman + label, terlampir pada batch
3. shipmentConsolidationUpdate(CLOSED)    → tutup batch (mengembalikan slip pengiriman)

Ada dua cara untuk melampirkan pengiriman ke batch — gunakan mana yang sesuai dengan integrasi Anda (atau campurkan):

• Lampirkan pada waktu pembuatan label — benang ID konsolidasi dari langkah 1 ke setiap panggilan shipmentCreateWorkflow melalui bidang shipmentConsolidationId.
• Lampirkan pengiriman yang ada menurut ID — lewatkan shipmentIds pada shipmentConsolidationCreate (untuk menabur batch) atau pada shipmentConsolidationUpdate (untuk menambah ke batch terbuka). Setiap pengiriman harus sudah memiliki label Japan Post.

Bagaimanapun juga, setiap label dibuat dengan Nomor Pembayaran Kemudian Anda yang tertanam sehingga Japan Post akan menerimanya pada slip pengiriman ketika langkah 3 menutup batch.

Mengapa panggilan terpisah daripada satu mutasi? Langkah 2.1, 2.2, ..., 2.n terjadi sepanjang hari pedagang — label dicetak dan paket disegel saat pesanan masuk. Batch tidak dapat menjadi perjalanan bulat tunggal seperti rantai pengiriman tunggal: ada celah multi-jam antara membuka konsolidasi dan menutupnya.

Prasyarat 

Sebelum alur ini berfungsi untuk Akun Terverifikasi tertentu:

• Akun Anda harus memiliki Nomor Pembayaran Kemudian (後納お客様番号) Japan Post yang disimpan di dalamnya — nilai berformat tanda hubung seperti 1111111111-222222-3333333333-444444. Lewatkan pada shipmentConsolidationCreate melalui accountNumber (Langkah 1).
• Kunci API Anda harus memegang SHIPMENT_WRITE, ditambah cakupan standar yang diperlukan alur per-pengiriman.

Endpoint dan autentikasi 

Ketiga langkah di bawah ini adalah operasi GraphQL yang dikirim ke endpoint yang sama. Apa yang Anda lewatkan di header tergantung pada setup Anda — pilih tab Anda.

URL:

https://api.zonos.com/graphql

Headers:

credentialToken: {{YOUR_API_TOKEN}}

Contoh permintaan 

Contoh copy-and-adapt membuka konsolidasi — mutasi, variabelnya, dan respons. Ini adalah panggilan spesifik batch yang memulai alur; melampirkan pengiriman (Langkah 2) menggunakan kembali contoh pengiriman tunggal, dan menutup batch (Langkah 3) mengembalikan dokumen manifest. Setiap bidang dipecah dalam langkah-langkah di bawah.

Langkah 1: shipmentConsolidationCreate 

Membuka konsolidasi. Kode operator mengunci batch ke Japan Post; semua pengiriman anggota harus menggunakan tingkat layanan Japan Post. Jika Anda sudah memiliki pengiriman berlabel siap, semai batch dengan ID mereka melalui shipmentIds — jika tidak, buat kosong dan lampirkan pengiriman di langkah 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
    }
  }
}

Response:

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

Pegang ID (mis. shco_01HJK...) — Anda akan menggunakannya untuk semuanya di bawah. status adalah OPEN hingga langkah 3.

Langkah 2: Lampirkan pengiriman 

Untuk setiap paket yang perlu Anda kirim hari ini, jalankan alur pengiriman tunggal yang lengkap untuk membuat pengiriman dan labelnya. Kemudian lampirkan pengiriman ke batch menggunakan salah satu dari metode di bawah.

Opsi A: Lampirkan pada waktu pembuatan label

Lewatkan ID konsolidasi pada langkah shipmentCreateWorkflow akhir dari rantai. Semua mutasi sebelumnya dalam rantai identik dengan alur pengiriman tunggal.

Bidang yang relevan pada shipmentCreateWorkflow:

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

Opsi B: Lampirkan pengiriman yang ada menurut ID

Jika pengiriman Anda sudah dibuat dan berlabel, tambahkan ke batch terbuka dengan shipmentIds pada shipmentConsolidationUpdate:

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

Biarkan status keluar dari input saat Anda masih menambahkan pengiriman — batch tetap OPEN. Setiap pengiriman harus menggunakan tingkat layanan Japan Post dan memiliki labelnya (nomor pelacakan) sebelum batch ditutup di Langkah 3.

Apa arti lampiran untuk label

Opsi mana pun yang Anda gunakan, ketika pengiriman Japan Post adalah bagian dari konsolidasi:

• Pengiriman memiliki nomor pelacakan, seperti biasanya.
• PDF label pengiriman tidak menyertakan salinan penerimaan pelanggan/kantor pos. Penerimaan itu ditunda ke Langkah 3, di mana mereka digabungkan ke dalam dokumen slip pengiriman untuk seluruh batch.
• Pengiriman terkait dengan konsolidasi; Anda dapat melakukan kueri ulang melalui shipmentConsolidation(id: ...) untuk melihat anggotanya.

Ulangi langkah ini untuk setiap paket dalam batch hari itu. Hingga 250 pengiriman per konsolidasi; upaya untuk menutup batch yang lebih besar gagal dengan kesalahan validasi yang jelas sebelum panggilan Japan Post apa pun dilakukan.

Anda juga dapat memverifikasi konten batch sebelum menutup:

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

Setiap pengiriman harus menampilkan nomor pelacakan di sini. Jika tidak, labelnya tidak pernah dibuat — urus itu sebelum menutup. status adalah OPEN hingga konsolidasi ditutup di Langkah 3.

Langkah 3: shipmentConsolidationUpdate(status: CLOSED) 

Menutup batch. Ini adalah panggilan yang meminta Japan Post untuk menghasilkan slip pengiriman dengan pembayaran tertunda yang mencakup nomor pelacakan setiap anggota, dan melampirkan PDF yang dihasilkan ke konsolidasi.

Operasi GraphQL dinamai CloseConsolidation untuk menggambarkan niatnya, menutup batch. Ini menjalankan mutasi shipmentConsolidationUpdate dengan status: CLOSED.

Mutation:

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

Pada permintaan CLOSED:

1. Konsolidasi divalidasi: ≤250 pengiriman, dan setiap anggota harus memiliki nomor pelacakan. Jika pengiriman kehilangan nomor pelacakannya (labelnya tidak pernah dibuat), panggilan ditolak.
2. Japan Post diminta untuk menghasilkan slip pengiriman dengan pembayaran tertunda yang mencakup nomor pelacakan setiap anggota.
3. Status bergerak singkat ke MANIFEST_CREATED saat PDF sedang diambil, kemudian ke CLOSED setelah dokumen telah dilampirkan.
4. PDF slip pengiriman (satu file berisi slip ditambah penerimaan pelanggan/kantor pos setiap anggota) dilampirkan ke konsolidasi sebagai CustomsDocument dengan documentType: MANIFEST_DOCUMENT.

Response:

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

Mengambil dokumen

Slip pengiriman dilampirkan langsung ke konsolidasi sebagai CustomsDocument dengan documentType: MANIFEST_DOCUMENT — ambil fileUrl dari respons penutupan di atas, atau kueri untuk itu kapan saja nanti:

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

Cetak PDF di fileUrl. Ini berisi:

• Halaman 1: Slip pengiriman dengan pembayaran tertunda — serahkan ini ke kantor pos.
• Halaman 2+: Penerimaan pelanggan/kantor pos untuk setiap paket — satu dijahit pada setiap paket, satunya lagi disimpan oleh kantor pos.

Setelah dicetak, bawa paket + slip pengiriman + penerimaan ke kantor pos dalam satu perjalanan. Japan Post menagihkan Nomor Pembayaran Kemudian Anda di akhir periode penagihan.

Menyatukannya 

Hari yang representatif untuk pedagang yang mengirim 50 paket Japan Post terlihat seperti:

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

Lebih suka batch di akhir hari? Buat label hari itu tanpa ID konsolidasi, kemudian buka konsolidasi sekali dengan setiap nilai shipmentIds (atau tambahkan dalam potongan melalui shipmentConsolidationUpdate) dan tutup dalam panggilan yang sama atau panggilan tindak lanjut.

Jika Anda mengirim di beberapa unit bisnis / akun penagihan, jalankan konsolidasi terpisah per akun — lewatkan accountNumber berbeda pada setiap shipmentConsolidationCreate dan rute pengiriman sesuai. Mengirim lebih dari 250 paket dalam sehari? Buka konsolidasi kedua.

Penanganan kesalahan 

Kesalahan validasi (tertangkap sebelum panggilan Japan Post apa pun)

• accountNumber tidak terformat dengan baik — ditolak di Langkah 1 (shipmentConsolidationCreate) sebelum konsolidasi bahkan disimpan. Pesan kesalahan mengidentifikasi segmen yang menyinggung.
• >250 pengiriman — ditolak di Langkah 3, sebelum panggilan Japan Post dilakukan.
• Pengiriman anggota kehilangan nomor pelacakan — ditolak di Langkah 3. Berarti pembuatan label diam-diam gagal sebelumnya; selidiki pengiriman yang terkena dampak melalui shipment(id: ...) { trackingDetails }.
• Tidak ada nomor pembayaran tertunda yang ditetapkan pada konsolidasi — ditolak di Langkah 3. Lewatkan accountNumber pada shipmentConsolidationCreate, atau simpan nomor akun default pada akun operator Japan Post Anda.

Kesalahan API Japan Post

Jika Japan Post menolak permintaan slip pengiriman, mutasi penutupan menonjolkan kode kesalahan operator dan pesan sebagai kesalahan GraphQL. Yang paling umum:

Percobaan lagi

Jika panggilan penutupan gagal setelah Japan Post menerima permintaan slip pengiriman (yaitu selama pengambilan PDF), mencoba lagi shipmentConsolidationUpdate(status: CLOSED) aman — platform akan melewati panggilan operator dan hanya mencoba mengambil dan melampirkan dokumen lagi.

Jika penutupan gagal sebelum Japan Post menerima permintaan (kesalahan validasi, E0xx, batas waktu jaringan), tidak ada keadaan yang telah berubah — perbaiki akar penyebab dan coba lagi.