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 lewatkan 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:

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.

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.

Izin 

Setiap langkah dijamin 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.