Dapatkan notifikasi push untuk perubahan pada data akun Anda

Anda dapat menggunakan Merchant Notifications API untuk mendapatkan notifikasi push terkait perubahan pada data akun. Misalnya, jika berlangganan notifikasi perubahan status produk, Anda dapat diberi tahu secara real time saat produk ditolak. Anda dapat berlangganan notifikasi untuk sub-akun atau akun tertaut lainnya.

Panduan ini memberikan contoh cara mengelola notifikasi untuk perubahan status produk. Anda dapat menggunakan contoh ini untuk mengelola notifikasi peristiwa lain dengan mengubah nilai kolom registeredEvent dalam permintaan Anda. Untuk mengetahui daftar lengkap jenis peristiwa, lihat referensi Merchant Notifications API.

Langganan

Untuk menerima notifikasi, Anda memerlukan callBackUri. URI callback Anda harus memenuhi persyaratan berikut:

• Harus berupa alamat HTTPS yang dapat diakses publik dengan sertifikat SSL yang valid, yang ditandatangani oleh certificate authority.
• Harus menerima permintaan POST HTTP dengan header Content-Type dan nilai application/json.
• Harus menampilkan salah satu kode respons berikut untuk mengonfirmasi bahwa notifikasi telah diterima.
  • 102
  • 200
  • 201
  • 202
  • 204

Anda dapat menggunakan URI callback yang sama untuk beberapa langganan. Sebaiknya gunakan URI callback unik per akun lanjutan, per jenis peristiwa untuk meminimalkan beban permintaan push ke satu URI.

Berikut adalah contoh permintaan untuk berlangganan notifikasi perubahan status produk untuk akun penjual tertentu. Gunakan ID penjual akun yang harus menerima notifikasi sebagai merchantId di URL permintaan, dan ID penjual akun yang akan menerima notifikasi sebagai targetMerchantId di isi permintaan. Jika akun Anda adalah akun mandiri tanpa akun tertaut, dan Anda ingin menerima notifikasi untuk akun Anda sendiri, gunakan ID penjual Anda sendiri di kedua tempat tersebut.

POST https://merchantapi.googleapis.com/notifications/v1beta/accounts/MERCHANT_ID/notificationsubscriptions/

{
  "registeredEvent": "PRODUCT_STATUS_CHANGE",
  "targetAccount": "accounts/TARGETMERCHANT_ID",
  "callBackUri": "https://example.com"
}

Panggilan yang berhasil akan menampilkan name untuk langganan Anda, termasuk ID langganan:

{
  "name":"accounts/MERCHANT_ID/notificationsubscriptions/subscriptionId",
  "registeredEvent": "PRODUCT_STATUS_CHANGE",
  "targetAccount": "accounts/TARGETMERCHANT_ID",
  "callBackUri": "https://example.com"
}

Anda dapat menggunakan name ini untuk GET dan DELETE langganan individual.

Anda dapat berlangganan notifikasi untuk perubahan status produk untuk semua akun tertaut dengan menyertakan "allManagedAccounts": true, bukan targetAccount, dalam permintaan Anda:

POST https://merchantapi.googleapis.com/notifications/v1beta/accounts/MERCHANT_ID/notificationsubscriptions/

{
  "registeredEvent": "PRODUCT_STATUS_CHANGE",
  "allManagedAccounts": true,
  "callBackUri": "https://example.com"
}

Untuk memperbarui langganan yang ada, gunakan PATCH dengan update_mask untuk menentukan kolom yang ingin Anda perbarui, dan nilai baru dalam isi JSON:

PATCH https://merchantapi.googleapis.com/notifications/v1beta/accounts/MERCHANT_ID/notificationsubscriptions/SUBSCRIPTION_ID?update_mask=callBackUri

{
  "​callBackUri": "https://my-own-personal-domain.com"
}

Mendekode notifikasi

Setelah membuat langganan, Anda akan menerima notifikasi ke callBackUri yang ditentukan dalam format berikut:

{"message":{"data":"{base64_encoded_string}"}}

Data notifikasi dienkode. Anda dapat mendekode data ke format teks yang dapat dibaca untuk digunakan dalam penerapan Anda. Berikut adalah contoh pengontrol spring boot yang dapat Anda gunakan untuk memproses data yang dienkode:

@RestController
public class ExampleController {
@RequestMapping(value = "/push",
  method = RequestMethod.POST,
  consumes = {"application/json"},
  produces = {"text/plain"})
  @ResponseStatus(HttpStatus.OK)
  public void doStuff(@RequestBody String message) {
        //wrapped message
        JSONObject jsonObject = new JSONObject(message);
        JSONObject jsonMessage = jsonObject.getJSONObject("message");
        message = jsonMessage.getString("data");
        byte[] decodedBytes = Base64.getDecoder().decode(message);
        String decodedMessage = new String(decodedBytes);
        // Implement your business logic here
  }
}

Berikut adalah contoh base64_encoded_string yang telah didekode:

{
  "account": "accounts/TARGETMERCHANT_ID",
  "managingAccount": "accounts/MERCHANT_ID",
  "resourceType": "PRODUCT",
  "attribute": "STATUS",
  "changes": [{
    "oldValue": "approved",
    "newValue": "disapproved",
    "regionCode": "US",
    "reportingContext": "SHOPPING_ADS"
  }, {
    "oldValue": "approved",
    "newValue": "disapproved",
    "regionCode": "JP",
    "reportingContext": "SHOPPING_ADS"
  },{
    "oldValue": "approved",
    "newValue": "disapproved",
    "regionCode": "GE",
    "reportingContext": "SHOPPING_ADS"
  }],
  "resourceId": "ONLINE~en~US~1234",
  "resource": "accounts/TARGETMERCHANT_ID/products/ONLINE~en~US~1234",
  "expirationTime": "2024-10-22T02:43:47.461464Z"
}

Jika tidak ada kolom oldValue dalam notifikasi, produk baru telah ditambahkan ke akun Anda. Jika tidak ada kolom newValue, produk telah dihapus dari akun Anda.

Kolom reportingContext hanya mendukung (SHOPPING_ADS, LOCAL_INVENTORY_ADS, YOUTUBE_SHOPPING, YOUTUBE_CHECKOUT, YOUTUBE_AFFILIATE) dari nilai enum ReportingContextEnum.

Untuk peristiwa perubahan status produk, kolom oldValue dan newValue akan memiliki salah satu nilai berikut : (approved, pending, disapproved, ``).

Menguji implementasi Anda

Berikut adalah contoh notifikasi yang dapat Anda gunakan untuk menguji URI callback dan decoding:

curl --header "Content-Type: application/json" --header "Accept: text/plain" --request POST --data '{"message":{"data":
"ewogICJhY2NvdW50IjogImFjY291bnRzLzEyMzQiLAogICJtYW5hZ2luZ0FjY291bnQiOiAiYWNjb3VudHMvNTY3OCIsCiAgInJlc291cmNlVHlwZSI6ICJQUk9EVUNUIiwKICAiYXR0cmlidXRlIjogIlNUQVRVUyIsCiAgImNoYW5nZXMiOiBbewogICAgIm9sZFZhbHVlIjogImFwcHJvdmVkIiwKICAgICJyZWdpb25Db2RlIjogIlVTIiwKICAgICJyZXBvcnRpbmdDb250ZXh0IjogIlNIT1BQSU5HX0FEUyIKICB9XSwKICAicmVzb3VyY2VJZCI6ICJPTkxJTkV+ZW5+VVN+MDAwMDAwMDAwMDAwIiwKICAicmVzb3VyY2UiOiAiYWNjb3VudHMvMTIzNC9wcm9kdWN0cy9PTkxJTkV+ZW5+VVN+MDAwMDAwMDAwMDAwIiwKICAiZXhwaXJhdGlvblRpbWUiOiAiMjAyNC0xMC0yMlQwMjo0Mzo0Ny40NjE0NjRaIgp9"}}' https://{callBackUri}

Sebagai respons terhadap panggilan ini, URI callback Anda akan menampilkan kode respons berhasil. Pesan yang didekode harus memiliki nilai berikut:

{
  "account": "accounts/1234",
  "managingAccount": "accounts/5678",
  "resourceType": "PRODUCT",
  "attribute": "STATUS",
  "changes": [{
    "oldValue": "approved",
    "regionCode": "US",
    "reportingContext": "SHOPPING_ADS"
  }],
  "resourceId": "ONLINE~en~US~000000000000",
  "resource": "accounts/1234/products/ONLINE~en~US~000000000000",
  "expirationTime": "2024-10-22T02:43:47.461464Z"
}