Buat satu pengiriman

CreateDeclarationShipment merantai enam mutasi *Workflow menjadi satu permintaan GraphQL. Setiap langkah dibangun di atas data yang diberikan oleh langkah-langkah sebelumnya, dan semuanya disampaikan bersama-sama sehingga pengiriman lengkap dapat dibuat dalam satu perjalanan bolak-balik:

partyCreateWorkflow            → jelaskan pihak asal + tujuan
itemCreateWorkflow             → jelaskan item baris
cartonsCreateWorkflow          → jelaskan kemasan fisik
shipmentRatingCreateWorkflow   → catat kutipan tarif operator
landedCostCalculateWorkflow    → hitung bea cukai / pajak / biaya
shipmentCreateWorkflow         → buat pengiriman + label

Mutasi Workflow dirancang untuk dirantai: Anda tidak perlu mengalirkan ID dari satu langkah ke langkah berikutnya, dan Anda tidak perlu mengirim permintaan terpisah per langkah. Kirimkan seluruh dokumen, dapatkan Shipment akhir kembali.

Ketika serviceLevel pada langkah akhir adalah tingkat layanan Japan Post (japan_post.*), Zonos memanggil Japan Post Label API (kode 52) atas nama Anda menggunakan Nomor Pembayaran Kemudian Akun Terverifikasi Anda, menghasilkan label dan nomor pelacakan, membuat ID Deklarasi, dan menautkannya — semuanya di dalam langkah shipmentCreateWorkflow akhir itu.

Mengapa satu mutasi? Setiap langkah tergantung pada yang sebelumnya (biaya pendaratan membutuhkan item + pihak; label membutuhkan semuanya). Menggabungkannya ke dalam satu dokumen GraphQL menjaga data tetap konsisten dan menghindari lima perjalanan bolak-balik ekstra.

Endpoint dan autentikasi 

Permintaan dalam rantai ini semuanya menggunakan endpoint yang sama. Apa yang Anda sertakan di header tergantung pada setup Anda — pilih tab Anda.

URL:

https://api.zonos.com/graphql

Headers:

credentialToken: {{YOUR_API_TOKEN}}

Contoh permintaan 

Permintaan CreateDeclarationShipment lengkap yang dapat Anda salin dan sesuaikan — mutasi, variabelnya, dan respons — untuk satu paket Japan Post yang dikirim DDP ke A.S. Setiap input dipecah dalam bagian langkah demi langkah di bawah.

Langkah demi langkah 

Kolom Status pada setiap tabel di bawah menggunakan istilah-istilah berikut:

• Diperlukan — permintaan gagal tanpanya.
• Diperlukan untuk label — opsional dalam skema GraphQL, tetapi diperlukan untuk menghasilkan label A.S. Japan Post yang valid.
• Kondisional — diperlukan tergantung pada bidang lain (dicatat secara inline).
• Direkomendasikan — opsional, tetapi mendorong bea cukai dan pajak yang akurat.
• Opsional — tidak diperlukan.

1. partyCreateWorkflow

Membuat pihak-pihak yang terlibat dalam pengiriman — minimal ORIGIN (tempat pengiriman dikirim) dan DESTINATION (pembeli / penerima).

Contoh payload:

[
  { "type": "DESTINATION", "location": { "countryCode": "US" }, "person": {} },
  { "type": "ORIGIN", "location": { "countryCode": "JP" }, "person": {} }
]

Respons mengembalikan ID Party yang dibuat dan bidang alamat yang diselesaikan.

2. itemCreateWorkflow

Membuat item baris yang membentuk pengiriman. Ini adalah SKU yang akan muncul pada faktur komersial dan mendorong perhitungan biaya pendaratan.

Kode HS, negara asal, dan jumlah adalah tiga bidang yang paling mempengaruhi hasil bea cukai / pajak di langkah 5.

3. cartonsCreateWorkflow

Membuat paket fisik — kotak, polybag, atau surat yang akan menampung item.

Setiap karton menjadi satu paket pada label operator di langkah 6. Beberapa karton → pengiriman multi-piece dengan satu nomor pelacakan per karton.

4. shipmentRatingCreateWorkflow

Mencatat kutipan tarif yang dikenakan pedagang kepada pembeli untuk pengiriman.

Ini adalah tarif yang dijumlahkan pembeli saat checkout. Ini masuk ke perhitungan biaya pendaratan sebagai subtotal "pengiriman" sehingga bea cukai dan pajak dihitung terhadap nilai CIF yang benar.

5. landedCostCalculateWorkflow

Menjalankan perhitungan bea cukai, pajak, dan biaya untuk negara tujuan. Menggunakan item, pihak, dan biaya pengiriman dari langkah-langkah sebelumnya.

Respons mencakup amountSubtotals (duties, taxes, fees, shipping, landedCostTotal) — ini adalah angka yang Anda tampilkan kepada pembeli saat checkout dan yang dicetak pada faktur komersial.

6. shipmentCreateWorkflow

Langkah terminal — membuat entitas Shipment, menghasilkan label operator, dan (opsional) faktur komersial / slip kemasan.

Untuk Akun Terverifikasi Japan Post, ini juga tempat Zonos memanggil Japan Post Label API (kode 52) atas nama Anda, menyuntikkan Nomor Pembayaran Kemudian Anda, membuat ID Deklarasi, dan menautkan ID Deklarasi ke nomor pelacakan yang dikembalikan oleh Japan Post.

Bidang kunci:

Pada contentsType, dua nilai paling umum untuk lalu lintas Akun Terverifikasi adalah ECOMMERCE_GOODS (dijual kepada konsumen, BtoC) dan COMMERCIAL_GOODS (dijual antar bisnis, BtoB). Nilai-nilai ini menentukan pkgType yang dikirim Zonos pada panggilan label Japan Post, sehingga pilihan tersebut mengubah apa yang dicetak pada deklarasi bea cukai — bukan sekadar label.

Sub-input nonDelivery

Memberitahu Japan Post apa yang harus dilakukan dengan paket jika tidak dapat dikirim — ditolak oleh penerima, ditolak di perbatasan, atau tidak dapat dikirim sesuai alamat.

option menerima persis empat nilai ini. Tidak ada nilai RETURN — gunakan RETURN_AFTER_RETENTION atau RETURN_IMMEDIATELY untuk memilih kapan paket dikembalikan.

API mengekspos kedua varian pengembalian secara terpisah; opsi Return pada Dashboard mencakup keduanya.

transportMethod menerima AIR atau MOST_ECONOMICAL, dan menentukan bagaimana paket yang dikembalikan melakukan perjalanan kembali. Ini hanya berlaku untuk dua opsi RETURN_* — Dashboard menampilkan bidang Return method yang sesuai hanya ketika Return dipilih.

{
  "nonDelivery": {
    "option": "RETURN_AFTER_RETENTION",
    "transportMethod": "MOST_ECONOMICAL"
  }
}

Pemilih If undeliverable pada dialog Create label Dashboard menulis bidang yang sama ini, sehingga label yang dibuat di Dashboard dan label yang dibuat melalui API berperilaku identik.

Sub-input references

Bidang-bidang ini dicetak pada label operator dan / atau faktur komersial. Gunakan untuk menampilkan nomor PO, nomor lisensi, dan komentar teks bebas yang harus dilihat penerima atau otoritas bea cukai.

Respons

Bidang menarik pada Shipment yang dikembalikan adalah:

{
  id
  trackingDetails {
    number
  }
  shipmentCartons {
    label {
      url
      labelImage
    }
  }
}

trackingDetails.number adalah nomor pelacakan Japan Post.

Objek label dapat mengembalikan label dengan dua cara — minta mana pun yang sesuai dengan alur kerja Anda (atau keduanya):

Pilih hanya bidang yang Anda butuhkan. Meminta url membuat respons kecil; meminta labelImage mengembalikan label lengkap inline sehingga Anda tidak memerlukan perjalanan bolak-balik kedua untuk mengambilnya. Contoh di atas meminta url.

Tingkat layanan Japan Post 

Berikan salah satu kode ini sebagai serviceLevelCode di shipmentRatingCreateWorkflow.

Kode tingkat layanan menggunakan titik, bukan garis bawah. Anda mungkin melihat bentuk garis bawah (japan_post_air_parcel) dalam pesan kesalahan dan referensi internal, tetapi itu bukan input yang valid.

Layanan udara

Layanan permukaan

Memilih di antara layanan serupa

Paket kecil vs. International Air Packet. Keduanya dibatasi hingga 2 kg. japan_post.air.packet adalah layanan paket kecil Japan Post yang dapat dilacak. japan_post.air.small_packet adalah setara yang tidak dapat dilacak. Jika Anda memerlukan pelacakan pada paket ringan, gunakan japan_post.air.packet.

Varian terdaftar. Untuk surat dan barang cetakan, pelacakan ditambahkan oleh versi terdaftar (書留) dari layanan tersebut. japan_post.air.printed_matter dan japan_post.air.letter tidak menyertakannya sendiri.

Kode yang tidak digunakan lagi

japan_post.air.epacket_light sebelumnya adalah International e-Packet Light. Japan Post mengganti nama layanan ini menjadi International Air Packet pada 1 Juni 2026, dan memperluasnya ke semua negara dan wilayah. Layanan itu sendiri tidak berubah.

Kode lama masih dapat digunakan sehingga integrasi yang ada tetap berfungsi, tetapi gunakan japan_post.air.packet untuk pekerjaan baru.

Kode mode transportasi

japan_post.air, japan_post.surface, japan_post.economy_air, dan japan_post.custom juga dapat digunakan, tetapi kode-kode ini mengidentifikasi mode transportasi atau fallback, bukan produk pos tertentu. Gunakan salah satu kode layanan di atas untuk pengiriman normal.

Validasi kode yang Anda kirim

serviceLevelCode yang tidak dikenali tidak memunculkan kesalahan. Permintaan mengembalikan HTTP 200 tanpa array errors, serviceLevel kembali sebagai null, dan biaya pengiriman hilang dari total biaya pendaratan — sehingga respons terlihat benar padahal jumlahnya salah.

Selalu pastikan bahwa shipmentRatingCreateWorkflow.serviceLevel tidak bernilai null sebelum mengandalkan totalnya.

Untuk mengambil daftar saat ini kapan saja:

{
  serviceLevels(carrier: "carrier_00004c9b-9431-4518-bfbc-b9f8476335b1") {
    code
    name
  }
}

Kueri ini menggunakan ID operator. Memberikan kode operator japan_post mengembalikan daftar kosong tanpa kesalahan.

Penanganan kesalahan 

• Kesalahan validasi (bidang yang diperlukan hilang, kode negara tidak valid, dll.) kembali dalam array errors GraphQL standar dan menghentikan sisa rantai.
• Kesalahan Japan Post (kegagalan pembuatan label, alamat tidak valid, dll.) muncul sebagai kesalahan GraphQL pada shipmentCreateWorkflow. Jika diperlukan percobaan lagi, hubungi dukungan — jalur yang disarankan adalah mengirim ulang mutasi lengkap dengan input yang diperbaiki.

VALIDATION_INVALID_TYPE_VARIABLE

{
  "errors": [
    {
      "message": "invalid type for variable: 'shipmentInput'",
      "extensions": {
        "name": "shipmentInput",
        "code": "VALIDATION_INVALID_TYPE_VARIABLE"
      }
    }
  ]
}

Kesalahan ini menyebutkan seluruh variabel, bukan bidang yang sebenarnya salah. Ini hampir selalu berarti satu nilai enum di dalam variabel tersebut bukan anggota dari enum-nya — paling sering nonDelivery.option, contentsType, atau serviceLevel.

Ini bukan masalah tipe JSON. Memberi atau menghapus tanda kutip pada boolean dan angka Anda tidak akan mengubahnya, karena payload tidak pernah mencapai tahap itu — enum ditolak lebih dulu.

Untuk menemukan bidang yang salah, periksa setiap bidang bernilai enum dalam variabel tersebut terhadap nilai yang diterimanya:

Anggota enum lengkap untuk input apa pun tercantum pada halaman jenisnya di referensi API.

Izin 

Setiap langkah diamankan secara independen. Kunci API Anda harus memegang cakupan penulisan untuk setiap entitas dalam rantai (ITEM_WRITE, CARTON_WRITE, SHIPMENT_RATING_WRITE, LANDED_COST_WRITE, SHIPMENT_WRITE). Peran pedagang standar pada Akun Terverifikasi memberikan semuanya.

Langkah selanjutnya 

• Pengiriman batch (konsolidasi) — bundel paket hari itu ke dalam satu slip pengiriman pembayaran tertunda Japan Post.