Quando i clienti scelgono un piano tariffario per il tuo software, Google crea un diritto che indica che il cliente ha acquistato il tuo prodotto da Cloud Marketplace. Questa sezione illustra come creare e gestire i diritti per i tuoi clienti utilizzando l'API Partner Procurement.
Per ulteriori dettagli sulla gestione dei diritti, consulta la documentazione di riferimento.
Prima di iniziare
- Configura l'accesso all'API Cloud Commerce Partner Procurement, come descritto in Integrare l'app.
Se hai attivato più ordini dello stesso prodotto, l'API Partner Procurement può inviare più eventi con il tipo di eventoENTITLEMENT_ACTIVE per lo stesso valore di ACCOUNT_ID, ciascuno con unENTITLEMENT_ID univoco che rappresenta un'offerta diversa. Ciò significa che devi assicurarti che la logica di gestione degli eventi della tua app possa rispondere a ENTITLEMENT_ID anziché a ACCOUNT_ID o PRODUCT_ID.
Devi assicurarti che l'integrazione frontend possa gestire il nuovo oggetto orders
incluso nel payload JWT. Per ulteriori informazioni, consulta
Integrare il frontend dell'app.
Per ulteriori informazioni su come attivare più ordini dello stesso prodotto, consulta Attivare più ordini dello stesso prodotto.
Approvare un diritto
Quando un cliente sceglie un piano tariffario, Cloud Marketplace crea un diritto e invia il seguente messaggio Pub/Sub alla tua app:
{ "eventId": "...", "eventType": "ENTITLEMENT_CREATION_REQUESTED", "providerId": "YOUR_PARTNER_ID", "entitlement": { "id": "ENTITLEMENT_ID", "updateTime": "...", "newOfferDuration": "P2Y3M", // Contract duration for offer-based entitlements }, }
dove ENTITLEMENT_ID è un ID creato da Cloud Marketplace. Se l'offerta ha una durata specificata, questa viene fornita in anni e mesi. Se l'offerta ha una data di fine specificata, anziché una durata, il campo che indica la durata è vuoto.
Nel tuo sistema, aggiorna l'account dell'utente in modo che rifletta l'acquisto di un piano. Per approvare il diritto, invia una richiesta HTTP POST all'API Partner Procurement e invia il HTTP POST che stai approvando:ENTITLEMENT_ID
POST v1/providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID:approve
Rifiutare un diritto
Per rifiutare un diritto, invia una richiesta HTTP POST all'API Partner Procurement e utilizza il metodo reject nella richiesta:
POST v1/providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID:reject
Per fornire un motivo per il rifiuto del diritto nel corpo della richiesta, utilizza il seguente formato:
{ "reason": "..." }
Modificare un piano di diritti
A seconda di come imposti i tuoi piani tariffari, i clienti potrebbero essere in grado di cambiare piano. Se un cliente seleziona un nuovo piano tariffario, ricevi un messaggio Pub/Sub nel seguente formato:
{ "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" }, }
Se l'offerta ha una durata specificata, questa viene fornita in anni e mesi. Se l'offerta ha una data di fine specificata, anziché una durata, il campo che indica la durata è vuoto.
Per approvare la modifica del piano, invia la seguente richiesta HTTP POST all'API Partner Procurement:
POST v1/providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID:approvePlanChange
Il corpo della richiesta deve contenere il piano da approvare:
{
"pendingPlanName": PLAN_NAME
}
Una volta approvata la modifica, ricevi un altro messaggio Pub/Sub quando la modifica diventa effettiva. Nel messaggio, il campo eventType diventa
ENTITLEMENT_PLAN_CHANGED. Per controllare lo stato di un piano, invia la seguente richiestaHTTP GET all'API Partner Procurement.
GET v1/providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID
La risposta è simile alla seguente, con il campo state che indica se il nuovo piano è attivo o se la modifica del piano è ancora in attesa:
{ "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", ... }
Annullare un diritto
Se un utente decide di annullare il proprio diritto, ricevi una notifica Pub/Sub. Come per la modifica di un piano, l'annullamento effettivo potrebbe essere applicato alla fine del ciclo di fatturazione corrente.
La notifica ha il seguente formato:
{ "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": "..." }, }
Eliminare un diritto
Se un utente invia una richiesta diretta all'Assistenza Google o se abbandona la piattaforma Google, i suoi diritti vengono annullati immediatamente e i suoi diritti e i suoi account vengono eliminati dopo un periodo di tolleranza di 60 giorni. Per proteggere la privacy dell'utente, devi eliminare i suoi dati dai tuoi server quando ricevi una notifica.
Quando i diritti vengono annullati e l'account viene eliminato, ricevi notifiche simili alle seguenti:
{ "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": "...", }, }
Elenco dei tipi di eventi per le attività dell'account
Di seguito è riportato un elenco dei eventType che la tua app potrebbe ricevere nei messaggi Pub/Sub:
| eventType | Descrizione |
|---|---|
| ACCOUNT_CREATION_REQUESTED | Ritirato |
| ACCOUNT_ACTIVE | Indica che l'account del cliente è stato creato. |
| ACCOUNT_DELETED | Indica che l'account del cliente è stato eliminato dai sistemi Google Cloud. |
| ENTITLEMENT_CREATION_REQUESTED | Indica che un cliente ha selezionato uno dei tuoi piani tariffari. |
| ENTITLEMENT_OFFER_ACCEPTED | Indica che un'offerta è stata accettata da un cliente. Include l'ora di inizio pianificata dell'offerta, se esistente. Questo evento viene inviato sia per le offerte private sia per quelle standard (acquisti pubblici). |
| ENTITLEMENT_ACTIVE | Indica che il piano scelto da un cliente è ora attivo. |
| ENTITLEMENT_PLAN_CHANGE_REQUESTED | Indica che un cliente ha scelto un nuovo piano. |
| ENTITLEMENT_PLAN_CHANGED | Indica che la modifica del piano di un cliente è stata approvata e che le modifiche sono state applicate. |
| ENTITLEMENT_PLAN_CHANGE_CANCELLED | Indica che la modifica del piano di un cliente è stata annullata perché non è stata approvata o perché il cliente è tornato al piano precedente. |
| ENTITLEMENT_PENDING_CANCELLATION | Indica che un cliente ha annullato il proprio piano e che l'annullamento è in attesa fino al termine del ciclo di fatturazione. |
| ENTITLEMENT_CANCELLATION_REVERTED | Indica che l'annullamento in attesa di un cliente è stato annullato. Tieni presente che le cancellazioni non possono essere annullate una volta finalizzate. |
| ENTITLEMENT_CANCELLED | Indica che il piano di un cliente è stato annullato. |
| ENTITLEMENT_CANCELLING | Indica che il piano di un cliente è in fase di annullamento. |
| ENTITLEMENT_RENEWED | Indica che il diritto di un cliente è stato rinnovato per un altro periodo di tempo. Non è richiesta alcuna azione da parte tua per completare il rinnovo. |
| ENTITLEMENT_OFFER_ENDED | Indica che l'offerta privata di un cliente è terminata. Se il diritto del cliente è stato annullato, viene attivato un evento ENTITLEMENT_CANCELLED separato. Se il diritto del cliente è ancora attivo, il piano tornerà al prezzo non scontato. |
| ENTITLEMENT_DELETED | Indica che le informazioni sul piano di un cliente sono state eliminate da Cloud Marketplace. |