Bangun katalog Verified Account Anda secara terprogram, langsung dari sistem Anda sendiri.
Catalog API adalah salah satu dari tiga cara untuk membangun katalog Verified Account Anda, dan merupakan pilihan bagi pengirim yang memiliki sumber daya developer serta sistem yang sudah menyimpan data produk mereka—ERP, WMS, PIM, atau platform pengiriman. Sistem tersebut tetap menjadi sumber data utama dan menulis produk langsung ke Zonos, alih-alih menyinkronkan dari integrasi kanal atau mengunggah file CSV. Jika Anda berjualan melalui kanal yang didukung, atau lebih memilih tidak menulis kode, kedua opsi tersebut membangun katalog yang sama dengan usaha yang lebih sedikit.
Item yang dibuat melalui API diperlakukan persis sama seperti item dari sumber lain mana pun—begitu sebuah item masuk ke katalog Anda, Zonos tidak mempedulikan bagaimana item itu sampai di sana. Setiap item diklasifikasikan untuk keperluan pabean jika Anda tidak menyertakan kode HS, disaring berdasarkan persyaratan U.S. Partner Government Agency (PGA), dan digunakan untuk menghitung bea masuk dan pajak atas pengiriman tempat item tersebut muncul.
Ada satu bagian dari proses itu yang berada di luar API. Ketika penyaringan PGA menandai sebuah item sebagai Needs attention, kuesioner kepatuhan di balik tanda tersebut harus dijawab dan dikonfirmasi di Dashboard—tidak ada API untuk itu, dan Zonos mengisi terlebih dahulu apa yang bisa diisi sehingga sebagian besar pekerjaannya adalah meninjau dan mengonfirmasi. Orang yang membangun integrasi ini biasanya bukan orang yang menyelesaikan tanda-tanda tersebut, jadi rencanakan agar seseorang di organisasi Anda menanganinya di Dashboard setelah katalog Anda dimuat. Item yang ditandai tidak diblokir untuk dikirim, tetapi menyelesaikannya sebelum Anda mengirim adalah hal yang mencegah pengiriman tertahan di perbatasan AS.
Buat item katalog untuk setiap produk yang Anda kirim.
Pastikan setiap item memiliki pengenal yang akan diteruskan oleh operator pos Anda.
Saat data pengiriman Anda sampai ke Zonos, setiap baris dicocokkan kembali dengan item katalog Anda, dan data produk item tersebut diterapkan pada perhitungan.
Membuat item katalog
catalogItemCreate menerima daftar, sehingga Anda dapat mengirim banyak produk dalam satu permintaan.
Jika Anda mengirim produk yang SKU atau ID produknya sudah ada, Zonos akan memperbarui produk tersebut alih-alih menambahkan produk kedua. Percobaan ulang dan pengiriman berulang aman dilakukan.
Konsekuensinya, dua produk berbeda yang memiliki SKU atau ID produk yang sama akan digabungkan menjadi satu. Periksa data Anda untuk menemukan duplikat sebelum melakukan pemuatan massal.
Pengenal unik Anda untuk produk tersebut. *Setiap produk memerlukan SKU atau ID produk, atau keduanya.
productId
Ya*
Pengenal produk dari platform Anda. *Setiap produk memerlukan SKU atau ID produk, atau keduanya.
manufacturerProductId
Hanya UE
Non-Standardised Manufacturer Product Identifier (NS-PID). Wajib pada pengiriman B2C ke UE yang bernilai 150 EUR atau kurang.
gtin
Hanya UE
Standardised Manufacturer Product Identifier (S-PID), hanya angka. Wajib pada pengiriman B2C ke UE yang bernilai 150 EUR atau kurang, jika produk memiliki barcode.
name
Ya
Nama produk.
customsDescription
Disarankan
Penjelasan tentang produk dalam istilah sederhana, untuk deklarasi pabean. Gunakan "Kaus katun", bukan "Summer Vibes Tee".
countryOfOrigin
Disarankan
Kode ISO 2 huruf untuk negara tempat produk diproduksi. Diperlukan untuk menghitung bea masuk secara akurat.
measurements
Disarankan
Berat dan dimensi, digunakan untuk penghitungan tarif dan pengajuan pabean.
hsCode
Tidak
Kode HS universal 6 digit. Jika Anda tidak menyertakannya, Zonos akan mengklasifikasikan produk dari nama dan deskripsinya.
amount
Tidak
Harga produk dalam bentuk angka.
currencyCode
Tidak
Kode ISO 3 huruf untuk mata uang harga. Wajib jika Anda menyertakan amount.
itemType
Tidak
PHYSICAL_GOOD, DIGITAL_GOOD, SERVICE, SUBSCRIPTION, BUNDLE, atau PARTIAL_ITEM. Mencegah item nonfisik dideklarasikan sebagai barang dagangan.
provinceOfOrigin
Tidak
Negara bagian atau provinsi asal produk. Diwajibkan oleh beberapa negara tujuan.
productComposition
Tidak
Daftar {material, percentage}. Tekstil tidak dapat diklasifikasikan lebih dari 6 digit tanpa informasi ini.
catalogItemUrl
Tidak
Tautan ke halaman produk di situs Anda. Meningkatkan akurasi klasifikasi.
imageUrl
Tidak
URL gambar produk yang dapat diakses publik. Meningkatkan akurasi klasifikasi.
Menambahkan pengenal produk UE (PID)
Jika Anda mengirim ke UE dengan Verified Account Anda, UE mewajibkan pengenal produk (PID) pada pengiriman business-to-consumer (B2C) yang bernilai 150 EUR atau kurang, mulai 1 November 2026. Simpan pengenal tersebut pada item katalog Anda. Untuk sebagian besar Verified Account, layanan pos Anda mengirimkan data pengiriman ke Zonos, lalu Zonos mencocokkan setiap item dalam pengiriman dengan katalog Anda dan menerapkan pengenal yang telah Anda simpan, sehingga Anda tidak perlu mengirim data tambahan apa pun saat pengiriman.
Kirim pengenal tersebut dengan catalogItemCreate untuk produk baru. Untuk produk yang sudah ada di katalog Anda, kirim dengan catalogItemUpdate, yang menerima kolom yang sama. Cocokkan sku setiap item dengan SKU yang Anda gunakan di tempat lain, agar Zonos dapat menghubungkan keduanya.
Kirim gtin hanya dalam bentuk angka, tanpa tanda hubung atau spasi. Nilai UPC, EAN, JAN, dan ISBN 13 digit semuanya dimasukkan ke dalam satu kolom ini. Jika Anda memiliki ISBN 10 digit, kirim versi 13 digitnya.
Jika produk tidak memiliki barcode, jangan sertakan gtin sama sekali, daripada mengirim string kosong, menggunakan ulang SKU Anda, atau mengisinya dengan teks pengganti seperti N/A.
Jika Anda memanggil Landed Cost API sendiri, Anda juga dapat menyertakan pengenal ini dalam permintaan landed cost Anda. Sebagian besar Verified Account tidak melakukannya, karena layanan pos-lah yang mengirimkan data pengiriman ke Zonos.
Zonos menautkan setiap baris pengiriman kembali ke item katalog menggunakan pengenal Anda, dengan urutan berikut: ID produk, lalu SKU, lalu nama. Pastikan pengenal mana pun yang Anda gunakan akurat dan konsisten antara katalog Anda dan data yang Anda kirim ke operator Anda.
Pengiriman pos memiliki batasan tambahan. Zonos menerima kumpulan kolom yang terbatas dari operator pos, dan di banyak jalur pengiriman, deskripsi pabean adalah satu-satunya kolom yang memuat informasi spesifik produk. Deskripsi yang sama di seluruh katalog Anda tidak dapat mengidentifikasi apa pun dengan sendirinya.
Cara memformat pengenal dalam data pengiriman yang Anda kirim ke operator bergantung pada layanan pos Anda, karena setiap layanan pos mencocokkan pengiriman dengan katalog Anda secara berbeda. Buka semua layanan pos dan pilih layanan pos Anda. Halamannya menunjukkan cara kerja pencocokan untuk layanan pos tersebut dan apa persisnya yang harus dikirim.
Menetapkan customsDescription item ke string yang sama dengan yang Anda kirim ke operator tidak wajib, tetapi hal ini membuat kedua sisi dapat dibandingkan secara langsung ketika suatu baris tidak cocok dan Anda perlu mencari tahu penyebabnya.
Pencocokan umumnya gagal ketika:
Pengenal yang digunakan layanan pos Anda untuk pencocokan tidak ada dalam data pengiriman.
Pengenal tidak sama persis dengan apa pun di katalog Anda.
Pengenal terpotong oleh batas karakter operator.
Format berubah di antara pengiriman.
Perilaku ini masih dalam tahap finalisasi dan dapat berubah sebelum peluncuran.
Memperbarui item katalog
catalogItemUpdate menggunakan tipe input yang sama dengan pembuatan. Kirim hanya kolom yang ingin Anda ubah.
Catatan: Kolom yang tidak disertakan tidak akan diubah, sehingga pembaruan parsial aman dilakukan. Mengirim null tidak menghapus nilai, melainkan diabaikan. Anda dapat menimpa nilai dengan nilai lain, tetapi Anda tidak dapat mengosongkannya melalui API. Hubungi perwakilan Zonos Anda jika Anda perlu mengosongkan suatu kolom.
Membaca kembali item Anda
Query catalogItem menerima id, productId, atau sku. Gunakan query ini untuk memastikan data yang disimpan Zonos untuk suatu produk.
1queryCatalogItem($sku: String!){
2 catalogItem(sku:$sku) {
3 id
4 itemKey
5 name
6 customsDescription
7 hsCode
8 productId
9 sku
10 countryOfOrigin
11}
12}
Menghapus item katalog
catalogItemDelete menerima ID item katalog Zonos, bukan SKU atau ID produk Anda. Dapatkan ID tersebut terlebih dahulu dengan query catalogItem.
Catalog API
Catalog API
Bangun katalog Verified Account Anda secara terprogram, langsung dari sistem Anda sendiri.
Catalog API adalah salah satu dari tiga cara untuk membangun katalog Verified Account Anda, dan merupakan pilihan bagi pengirim yang memiliki sumber daya developer serta sistem yang sudah menyimpan data produk mereka—ERP, WMS, PIM, atau platform pengiriman. Sistem tersebut tetap menjadi sumber data utama dan menulis produk langsung ke Zonos, alih-alih menyinkronkan dari integrasi kanal atau mengunggah file CSV. Jika Anda berjualan melalui kanal yang didukung, atau lebih memilih tidak menulis kode, kedua opsi tersebut membangun katalog yang sama dengan usaha yang lebih sedikit.
Item yang dibuat melalui API diperlakukan persis sama seperti item dari sumber lain mana pun—begitu sebuah item masuk ke katalog Anda, Zonos tidak mempedulikan bagaimana item itu sampai di sana. Setiap item diklasifikasikan untuk keperluan pabean jika Anda tidak menyertakan kode HS, disaring berdasarkan persyaratan U.S. Partner Government Agency (PGA), dan digunakan untuk menghitung bea masuk dan pajak atas pengiriman tempat item tersebut muncul.
Ada satu bagian dari proses itu yang berada di luar API. Ketika penyaringan PGA menandai sebuah item sebagai Needs attention, kuesioner kepatuhan di balik tanda tersebut harus dijawab dan dikonfirmasi di Dashboard—tidak ada API untuk itu, dan Zonos mengisi terlebih dahulu apa yang bisa diisi sehingga sebagian besar pekerjaannya adalah meninjau dan mengonfirmasi. Orang yang membangun integrasi ini biasanya bukan orang yang menyelesaikan tanda-tanda tersebut, jadi rencanakan agar seseorang di organisasi Anda menanganinya di Dashboard setelah katalog Anda dimuat. Item yang ditandai tidak diblokir untuk dikirim, tetapi menyelesaikannya sebelum Anda mengirim adalah hal yang mencegah pengiriman tertahan di perbatasan AS.
Cara kerjanya
Buat item katalog untuk setiap produk yang Anda kirim.
Pastikan setiap item memiliki pengenal yang akan diteruskan oleh operator pos Anda.
Saat data pengiriman Anda sampai ke Zonos, setiap baris dicocokkan kembali dengan item katalog Anda, dan data produk item tersebut diterapkan pada perhitungan.
Membuat item katalog
catalogItemCreatemenerima daftar, sehingga Anda dapat mengirim banyak produk dalam satu permintaan.mutation CatalogItemCreate($input: [CatalogItemInput!]!) {catalogItemCreate(input: $input) {iditemKeynameproductIdskuhsCodecustomsDescriptioncountryOfOrigin}}Mengirim produk yang sama dua kali
Jika Anda mengirim produk yang SKU atau ID produknya sudah ada, Zonos akan memperbarui produk tersebut alih-alih menambahkan produk kedua. Percobaan ulang dan pengiriman berulang aman dilakukan.
Konsekuensinya, dua produk berbeda yang memiliki SKU atau ID produk yang sama akan digabungkan menjadi satu. Periksa data Anda untuk menemukan duplikat sebelum melakukan pemuatan massal.
Kolom
skuproductIdmanufacturerProductIdgtinnamecustomsDescriptioncountryOfOriginmeasurementshsCodeamountcurrencyCodeamount.itemTypePHYSICAL_GOOD,DIGITAL_GOOD,SERVICE,SUBSCRIPTION,BUNDLE, atauPARTIAL_ITEM. Mencegah item nonfisik dideklarasikan sebagai barang dagangan.provinceOfOriginproductComposition{material, percentage}. Tekstil tidak dapat diklasifikasikan lebih dari 6 digit tanpa informasi ini.catalogItemUrlimageUrlMenambahkan pengenal produk UE (PID)
Jika Anda mengirim ke UE dengan Verified Account Anda, UE mewajibkan pengenal produk (PID) pada pengiriman business-to-consumer (B2C) yang bernilai 150 EUR atau kurang, mulai 1 November 2026. Simpan pengenal tersebut pada item katalog Anda. Untuk sebagian besar Verified Account, layanan pos Anda mengirimkan data pengiriman ke Zonos, lalu Zonos mencocokkan setiap item dalam pengiriman dengan katalog Anda dan menerapkan pengenal yang telah Anda simpan, sehingga Anda tidak perlu mengirim data tambahan apa pun saat pengiriman.
skumanufacturerProductIdgtinKirim pengenal tersebut dengan
catalogItemCreateuntuk produk baru. Untuk produk yang sudah ada di katalog Anda, kirim dengancatalogItemUpdate, yang menerima kolom yang sama. Cocokkanskusetiap item dengan SKU yang Anda gunakan di tempat lain, agar Zonos dapat menghubungkan keduanya.mutation CatalogItemCreate($input: [CatalogItemInput!]!) {catalogItemCreate(input: $input) {idskumanufacturerProductIdgtin}Kirim
gtinhanya dalam bentuk angka, tanpa tanda hubung atau spasi. Nilai UPC, EAN, JAN, dan ISBN 13 digit semuanya dimasukkan ke dalam satu kolom ini. Jika Anda memiliki ISBN 10 digit, kirim versi 13 digitnya.Jika produk tidak memiliki barcode, jangan sertakan
gtinsama sekali, daripada mengirim string kosong, menggunakan ulang SKU Anda, atau mengisinya dengan teks pengganti sepertiN/A.Jika Anda memanggil Landed Cost API sendiri, Anda juga dapat menyertakan pengenal ini dalam permintaan landed cost Anda. Sebagian besar Verified Account tidak melakukannya, karena layanan pos-lah yang mengirimkan data pengiriman ke Zonos.
Untuk mengetahui apa yang diwajibkan oleh regulasi, lihat panduan pengenal produk UE.
Membuat item Anda dapat dicocokkan
Zonos menautkan setiap baris pengiriman kembali ke item katalog menggunakan pengenal Anda, dengan urutan berikut: ID produk, lalu SKU, lalu nama. Pastikan pengenal mana pun yang Anda gunakan akurat dan konsisten antara katalog Anda dan data yang Anda kirim ke operator Anda.
Pengiriman pos memiliki batasan tambahan. Zonos menerima kumpulan kolom yang terbatas dari operator pos, dan di banyak jalur pengiriman, deskripsi pabean adalah satu-satunya kolom yang memuat informasi spesifik produk. Deskripsi yang sama di seluruh katalog Anda tidak dapat mengidentifikasi apa pun dengan sendirinya.
Cara memformat pengenal dalam data pengiriman yang Anda kirim ke operator bergantung pada layanan pos Anda, karena setiap layanan pos mencocokkan pengiriman dengan katalog Anda secara berbeda. Buka semua layanan pos dan pilih layanan pos Anda. Halamannya menunjukkan cara kerja pencocokan untuk layanan pos tersebut dan apa persisnya yang harus dikirim.
Menetapkan
customsDescriptionitem ke string yang sama dengan yang Anda kirim ke operator tidak wajib, tetapi hal ini membuat kedua sisi dapat dibandingkan secara langsung ketika suatu baris tidak cocok dan Anda perlu mencari tahu penyebabnya.Pencocokan umumnya gagal ketika:
Memperbarui item katalog
catalogItemUpdatemenggunakan tipe input yang sama dengan pembuatan. Kirim hanya kolom yang ingin Anda ubah.mutation CatalogItemUpdate($input: [CatalogItemInput!]!) {catalogItemUpdate(input: $input) {iditemKeyhsCodecustomsDescription}}Membaca kembali item Anda
Query
catalogItemmenerimaid,productId, atausku. Gunakan query ini untuk memastikan data yang disimpan Zonos untuk suatu produk.query CatalogItem($sku: String!) {catalogItem(sku: $sku) {iditemKeynamecustomsDescriptionhsCodeproductIdskucountryOfOrigin}}Menghapus item katalog
catalogItemDeletemenerima ID item katalog Zonos, bukan SKU atau ID produk Anda. Dapatkan ID tersebut terlebih dahulu dengan querycatalogItem.mutation CatalogItemDelete($input: [ID!]!) {catalogItemDelete(input: $input)}Terkait
CatalogItemInput
catalogItemCreate catalogItemDelete catalogItemUpdate
Apakah halaman ini bermanfaat?