Mengelola hak pelanggan untuk produk SaaS Anda

Saat pelanggan memilih paket harga untuk software Anda, Google akan membuat hak, yang menunjukkan bahwa pelanggan telah membeli produk Anda dari Cloud Marketplace. Bagian ini meninjau cara membuat dan mengelola hak untuk pelanggan Anda menggunakan Partner Procurement API.

Untuk mengetahui detail selengkapnya tentang cara mengelola hak, buka dokumentasi referensi.

Sebelum memulai

Jika Anda telah mengaktifkan beberapa pesanan produk yang sama, Partner Procurement API dapat mengirim beberapa peristiwa dengan jenis peristiwa ENTITLEMENT_ACTIVE untuk nilai ACCOUNT_ID yang sama, masing-masing dengan ENTITLEMENT_ID unik yang mewakili penawaran yang berbeda. Artinya, Anda harus memastikan bahwa logika penanganan peristiwa aplikasi dapat merespons ENTITLEMENT_ID, bukan ACCOUNT_ID atau PRODUCT_ID.

Anda harus memastikan bahwa integrasi frontend dapat menangani objek orders baru yang disertakan dalam payload JWT. Untuk informasi selengkapnya, lihat Mengintegrasikan frontend aplikasi.

Untuk informasi selengkapnya tentang cara mengaktifkan beberapa pesanan produk yang sama, lihat Mengaktifkan beberapa pesanan produk yang sama.

Menyetujui hak

Saat pelanggan memilih paket harga, Cloud Marketplace akan membuat hak dan mengirim pesan Pub/Sub berikut ke aplikasi Anda:

{
  "eventId": "...",
  "eventType": "ENTITLEMENT_CREATION_REQUESTED",
  "providerId": "YOUR_PARTNER_ID",
  "entitlement": {
    "id": "ENTITLEMENT_ID",
    "updateTime": "...",
    "newOfferDuration": "P2Y3M",   // Contract duration for offer-based entitlements
  },
}

dengan ENTITLEMENT_ID adalah ID yang dibuat oleh Cloud Marketplace. Jika penawaran memiliki durasi yang ditentukan, durasi tersebut diberikan dalam tahun dan bulan. Jika penawaran memiliki tanggal akhir yang ditentukan, bukan durasi, kolom yang menunjukkan durasi akan kosong.

Di sistem Anda, perbarui akun pengguna untuk menunjukkan bahwa mereka telah membeli paket. Kemudian, untuk menyetujui hak, buat permintaan HTTP POST ke Partner Procurement API, dan kirim ENTITLEMENT_ID yang Anda setujui:

POST v1/providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID:approve

Menolak hak

Untuk menolak hak, buat permintaan HTTP POST ke Partner Procurement API, dan gunakan metode reject dalam permintaan Anda:

POST v1/providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID:reject

Untuk memberikan alasan penolakan hak dalam isi permintaan, gunakan format berikut:

{
  "reason": "..."
}

Mengubah paket hak

Bergantung pada cara Anda menyiapkan paket harga, pelanggan mungkin dapat mengubah paket mereka. Jika pelanggan memilih paket harga baru, Anda akan menerima pesan Pub/Sub, dalam format berikut:

{
  "eventId": "...",
  "eventType": "ENTITLEMENT_PLAN_CHANGE_REQUESTED",
  "providerId": "YOUR_PARTNER_ID",
  "entitlement": {
    "id": "ENTITLEMENT_ID",
    "newPlan": "ultimate",   // New plan
    "updateTime": "...",
    "newOfferDuration": "P2Y3M",   // Contract duration for the new offer, for offer-based entitlements
    "newProduct": "test-product.cloud.goog"
    "newOffer": "projects/1234567/services/test-product.cloud.goog/standardOffers/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"
  },
}

Jika penawaran memiliki durasi yang ditentukan, durasi tersebut diberikan dalam tahun dan bulan. Jika penawaran memiliki tanggal akhir yang ditentukan, bukan durasi, kolom yang menunjukkan durasi akan kosong.

Untuk menyetujui perubahan paket, buat permintaan HTTP POST berikut ke Partner Procurement API:

POST v1/providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID:approvePlanChange

Isi permintaan harus memiliki rencana yang sedang disetujui:

{
  "pendingPlanName": PLAN_NAME
}

Setelah perubahan disetujui, Anda akan menerima pesan Pub/Sub lain saat perubahan diterapkan. Dalam pesan, kolom eventType berubah menjadi ENTITLEMENT_PLAN_CHANGED. Untuk memeriksa status rencana, buat permintaan HTTP GET berikut ke Partner Procurement API.

GET v1/providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID

Responsnya mirip dengan berikut ini, dengan kolom state yang menunjukkan apakah paket baru aktif, atau apakah perubahan paket masih tertunda:

{
  "name": "providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID",
  "provider": "YOUR_PARTNER_ID",
  "account": "USER_ACCOUNT_ID",
  "product": "example-server",
  "plan": "pro",
  "state": "ENTITLEMENT_PENDING_PLAN_CHANGE",
  "newPendingPlan": "ultimate",
  ...
}

Membatalkan hak

Jika pengguna memutuskan untuk membatalkan haknya, Anda akan menerima notifikasi Pub/Sub. Serupa dengan mengubah paket, pembatalan yang sebenarnya mungkin berlaku pada akhir siklus penagihan saat ini.

Notifikasi dalam format berikut:

{
  "eventId": "...",
  // If the entitlement is canceled at the end of the month,
  // eventType is ENTITLEMENT_PENDING_CANCELLATION
  "eventType": "ENTITLEMENT_CANCELLED",
  "providerId": "YOUR_PARTNER_ID",
  "entitlement": {
    "id": "ENTITLEMENT_ID",
    "updateTime": "..."
  },
}

Menghapus hak

Jika pengguna mengajukan permintaan langsung ke dukungan Google, atau jika mereka keluar dari platform Google, hak mereka akan segera dibatalkan, dan hak serta akun mereka akan dihapus setelah masa tenggang 60 hari. Untuk melindungi privasi pengguna, Anda harus menghapus data mereka dari server saat Anda diberi tahu.

Saat hak dibatalkan dan akun dihapus, Anda akan menerima notifikasi yang mirip dengan berikut:

{
  "eventId": "...",
  "eventType": "ENTITLEMENT_DELETED",
  "providerId": "YOUR_PARTNER_ID",
  "entitlement": {
    "id": "ENTITLEMENT_ID",
    "updateTime": "...",
  },
}
 
{
  "eventId": "...",
  "eventType": "ACCOUNT_DELETED",
  "providerId": "YOUR_PARTNER_ID",
  "account": {
    "id": "USER_ACCOUNT_ID",
    "updateTime": "...",
  },
}

Daftar jenis peristiwa untuk tugas akun

Berikut adalah daftar eventType yang mungkin diterima aplikasi Anda dalam pesan Pub/Sub:

eventTypeDeskripsi
ACCOUNT_CREATION_REQUESTEDTidak digunakan lagi
ACCOUNT_ACTIVEMenunjukkan bahwa akun pelanggan telah dibuat.
ACCOUNT_DELETEDMenunjukkan bahwa akun pelanggan telah dihapus dari sistem Google Cloud.
ENTITLEMENT_CREATION_REQUESTEDMenunjukkan bahwa pelanggan memilih salah satu paket harga Anda.
ENTITLEMENT_OFFER_ACCEPTEDMenunjukkan bahwa penawaran telah diterima oleh pelanggan. Mencakup waktu mulai penawaran yang dijadwalkan, jika ada. Peristiwa ini dikirim untuk penawaran pribadi dan penawaran standar (pembelian publik).
ENTITLEMENT_ACTIVEMenunjukkan bahwa paket yang dipilih pelanggan kini aktif.
ENTITLEMENT_PLAN_CHANGE_REQUESTEDMenunjukkan bahwa pelanggan memilih paket baru.
ENTITLEMENT_PLAN_CHANGEDMenunjukkan bahwa perubahan paket pelanggan disetujui dan perubahan tersebut telah berlaku.
ENTITLEMENT_PLAN_CHANGE_CANCELLEDMenunjukkan bahwa perubahan paket pelanggan dibatalkan, baik karena tidak disetujui, atau karena pelanggan beralih kembali ke paket lama.
ENTITLEMENT_PENDING_CANCELLATIONMenunjukkan bahwa pelanggan membatalkan paketnya, dan pembatalan tersebut tertunda hingga akhir siklus penagihan.
ENTITLEMENT_CANCELLATION_REVERTEDMenunjukkan bahwa pembatalan pelanggan yang tertunda telah dibatalkan. Perhatikan bahwa pembatalan tidak dapat dikembalikan setelah bersifat final.
ENTITLEMENT_CANCELLEDMenunjukkan bahwa paket pelanggan dibatalkan.
ENTITLEMENT_CANCELLINGMenunjukkan bahwa paket pelanggan sedang dalam proses pembatalan.
ENTITLEMENT_RENEWEDMenunjukkan bahwa hak pelanggan diperpanjang untuk jangka waktu lain. Anda tidak perlu melakukan tindakan apa pun untuk menyelesaikan perpanjangan.
ENTITLEMENT_OFFER_ENDEDMenunjukkan bahwa penawaran pribadi pelanggan telah berakhir. Jika hak pelanggan dibatalkan, peristiwa ENTITLEMENT_CANCELLED terpisah akan dipicu. Jika hak pelanggan masih aktif, paketnya akan kembali ke harga tanpa diskon.
ENTITLEMENT_DELETEDMenunjukkan bahwa informasi tentang paket pelanggan telah dihapus dari Cloud Marketplace.
Sebelumnya
Mengelola akun pengguna