Region Merchant API mewakili wilayah geografis yang dapat Anda gunakan sebagai target terkait dengan resource accounts.products.regionalInventories. Anda dapat menentukan wilayah sebagai kumpulan kode pos atau, di beberapa negara, menggunakan geotargeting yang telah ditentukan. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan
wilayah.
Merchant API menyediakan endpoint batch untuk mengelola wilayah Anda, sehingga Anda dapat membuat, memperbarui, dan menghapus hingga 100 wilayah dalam satu panggilan API. Hal ini ideal bagi penjual yang mengelola ketersediaan dan harga regional (RAAP) dalam skala besar, sehingga meningkatkan efisiensi dan menyederhanakan integrasi.
Ringkasan
Batch API memungkinkan Anda melakukan hal berikut dengan metode terkait:
- Membuat beberapa wilayah dalam satu permintaan:
regions:batchCreate - Menghapus beberapa wilayah sekaligus:
regions:batchDelete - Memperbarui beberapa wilayah secara bersamaan:
regions:batchUpdate
Prasyarat
Semua permintaan batch memerlukan peran pengguna ADMIN untuk autentikasi.
Membuat beberapa wilayah
Contoh ini menunjukkan cara membuat dua wilayah baru — satu ditentukan berdasarkan kode pos dan yang lainnya berdasarkan penargetan geografis — dalam satu panggilan BatchCreateRegions.
Permintaan
Buat URL permintaan sebagai berikut:
POST
https://merchantapi.googleapis.com/v1beta/accounts/{ACCOUNT_ID}/regions:batchCreate
Isi permintaan berisi daftar requests, dengan setiap objek menentukan
regionId dan data region yang akan dibuat.
{
"requests": [
{
"regionId": "seattle-area-98340",
"region": {
"displayName": "Seattle Region",
"postalCodeArea": {
"regionCode": "US",
"postalCodes": [
{
"begin": "98340"
}
]
}
}
},
{
"regionId": "co-de-states",
"region": {
"displayName": "Colorado and Delaware",
"geoTargetArea": {
"geotargetCriteriaIds": [
"21138",
"21141"
]
}
}
}
]
}
Respons
Permintaan yang berhasil akan menampilkan daftar objek region baru.
{
"regions": [
{
"name": "accounts/{ACCOUNT_ID}/regions/seattle-area-98340",
"displayName": "Seattle Region",
"postalCodeArea": {
"regionCode": "US",
"postalCodes": [
{
"begin": "98340"
}
]
},
"regionalInventoryEligible": true,
"shippingEligible": true
},
{
"name": "accounts/{ACCOUNT_ID}/regions/co-de-states",
"displayName": "Colorado and Delaware",
"geotargetArea": {
"geotargetCriteriaIds": [
"21138",
"21141"
]
},
"regionalInventoryEligible": false,
"shippingEligible": false
}
]
}
Memperbarui beberapa wilayah
Contoh ini menunjukkan cara menggunakan BatchUpdateRegions untuk memperbarui displayName dan postalCodeArea untuk dua wilayah yang ada. Anda harus memberikan region.name untuk memperbarui wilayah target.
Permintaan
Buat URL permintaan sebagai berikut:
POST https://merchantapi.googleapis.com/v1beta/accounts/{ACCOUNT_ID}/regions:batchUpdate
Isi permintaan berisi daftar requests. Setiap objek harus menentukan data region yang akan diperbarui. Kolom region.name harus berisi ID wilayah yang akan diperbarui, misalnya, "98005". Tentukan resource sebagai name daripada
accounts/{ACCOUNT_ID}/regions/name. Menyertakan updateMask untuk menunjukkan kolom yang akan diubah bersifat opsional.
{
"requests": [
{
"region": {
"name": "98005",
"displayName": "Seattle Updated Region",
"postalCodeArea": {
"regionCode": "US",
"postalCodes": [
{
"begin": "98330"
}
]
}
},
"updateMask": "displayName,postalCodeArea"
},
{
"region": {
"name": "07086",
"displayName": "NewYork Updated Region",
"postalCodeArea": {
"regionCode": "US",
"postalCodes": [
{
"begin": "11*"
}
]
}
},
"updateMask": "displayName,postalCodeArea"
}
]
}
Respons
Permintaan yang berhasil akan menampilkan daftar objek region yang diperbarui.
{
"regions": [
{
"name": "accounts/{ACCOUNT_ID}/regions/98005",
"displayName": "Seattle Updated Region",
"postalCodeArea": {
"regionCode": "US",
"postalCodes": [
{
"begin": "98330"
}
]
},
"regionalInventoryEligible": true,
"shippingEligible": true
},
{
"name": "accounts/{ACCOUNT_ID}/regions/07086",
"displayName": "NewYork Updated Region",
"postalCodeArea": {
"regionCode": "US",
"postalCodes": [
{
"begin": "11*"
}
]
},
"regionalInventoryEligible": true,
"shippingEligible": true
}
]
}
Menghapus beberapa wilayah
Anda dapat menghapus beberapa wilayah dalam satu panggilan.
Permintaan
Contoh ini menunjukkan cara menggunakan BatchDeleteRegions untuk menghapus dua wilayah dalam satu panggilan.
POST
https://merchantapi.googleapis.com/v1beta/accounts/{ACCOUNT_ID}/regions:batchDelete
Isi permintaan berisi daftar requests, dengan setiap objek menentukan
name (tanpa "accounts/{ACCOUNT_ID}/regions/") wilayah yang akan dihapus.
{
"requests":
[
{
"name": "98005"
},
{
"name": "07086"
}
]
}
Respons
Permintaan yang berhasil akan menampilkan isi respons kosong, yang menunjukkan bahwa wilayah yang ditentukan telah dihapus (atau tidak ada).
{}
Batasan
Sebelum memulai, perhatikan aturan berikut:
- Operasi atomik: Permintaan batch bersifat atomik. Jika satu operasi dalam batch gagal (misalnya, satu wilayah gagal dibuat), seluruh batch akan gagal, dan tidak ada perubahan yang akan dilakukan. API akan menampilkan error yang menjelaskan penyebab kegagalan.
- Batas batch: Setiap permintaan batch dapat berisi maksimum 100 operasi wilayah.
- Kuota: Endpoint ini menggunakan grup kuota yang sama dengan
endpoint operasi tunggalnya (
regions.create,regions.delete,regions.update).
Error dan masalah umum
Berikut beberapa masalah umum dan solusinya.
"The number of requests in a batch is too large"
Error ini terjadi jika jumlah operasi dalam array permintaan Anda melebihi batas 100.
"error":
{
"code": 400,
"message": "The number of requests in a batch is too large.",
"status": "INVALID_ARGUMENT"
}
Untuk memperbaikinya, bagi operasi Anda menjadi beberapa permintaan batch yang berisi 100 atau kurang.
Bidang wajib belum diisi
Error ini terjadi jika kolom wajib tidak ada. Pesan error menentukan parameter yang tidak ada.
Pesan errornya adalah sebagai berikut:
- Untuk
batchCreate:[regionId] Required parameter: regionId - Untuk
batchUpdate:[region.name] Required field not provided. - Untuk
batchDelete:[name] Required parameter: name
Untuk memperbaikinya, pastikan semua kolom wajib ada di setiap operasi. Misalnya, setiap entri dalam permintaan batchUpdate harus menyertakan region.name.
Memposting permintaan berikut akan menghasilkan error:
{
"requests":
[
{
"region":
{
"displayName": "An update without a region name"
},
"updateMask": "displayName"
}
]
}
"Region with specified ID already exists"
Error akan terjadi jika Anda mencoba membuat wilayah dengan regionId yang sudah ada.
Pesan errornya adalah [regionId] Region with specified id already exists..
Untuk memperbaikinya, pastikan semua nilai regionId unik dalam batch dan tidak bertentangan dengan wilayah yang ada.
"Duplicate value found for field region.name or regionId found"
Error akan terjadi jika Anda mencoba membuat atau memperbarui beberapa wilayah dengan ID yang sama dalam satu permintaan batch.
Pesan errornya adalah Duplicate value found for field {fieldName} in this batch
request with value {duplicated_value}..
Untuk memperbaikinya, pastikan semua nilai regionId (untuk batchCreate) atau region.name (untuk batchUpdate) unik dalam satu permintaan batch.
"Item not found"
Saat menggunakan batchUpdate, jika ada wilayah yang ditentukan dalam permintaan tidak ada, seluruh batch akan gagal dengan error 404 NOT_FOUND. Hal ini berbeda dengan batchDelete, yang berhasil untuk wilayah yang tidak ada.
"error": {
"code": 404,
"message": "item not found",
"status": "NOT_FOUND"
}
Untuk memperbaikinya, pastikan semua wilayah yang Anda coba perbarui ada sebelum mengirim permintaan.