Mengelola pengelompokan wilayah

Wilayah Merchant API mewakili wilayah geografis yang dapat Anda gunakan sebagai target yang terkait dengan resource accounts.products.regionalInventories. Anda dapat menentukan wilayah sebagai kumpulan kode pos atau, di beberapa negara, menggunakan geotarget yang telah ditentukan sebelumnya. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan wilayah.

Merchant API menyediakan endpoint batch untuk mengelola wilayah, 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
  • Perbarui 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 oleh kode pos dan satu lagi oleh 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, di mana 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, bukan 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 region 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/") region 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 region 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 kesalahan umum dan solusinya.

"Jumlah permintaan dalam batch terlalu besar"

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 masing-masing berisi 100 atau kurang.

Bidang wajib belum diisi

Error ini terjadi saat kolom wajib diisi 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 diisi 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"
    }
  ]
}

"Wilayah dengan ID yang ditentukan sudah ada"

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.

"Nilai duplikat ditemukan untuk kolom region.name atau regionId"

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) bersifat unik dalam satu permintaan batch.

"Item tidak ditemukan"

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, verifikasi bahwa semua wilayah yang Anda coba perbarui ada sebelum mengirim permintaan.

Sebelumnya
Create and update regions