Cuando los clientes eligen un plan de precios para el software, Google crea una autorización, que indica que el cliente compró el producto en Cloud Marketplace. En esta sección, se explica cómo crear y administrar autorizaciones para tus clientes con la API de Partner Procurement.
Para obtener más información sobre cómo administrar derechos, consulta la documentación de referencia.
Antes de comenzar
- Configura el acceso a la API de Cloud Commerce Partner Procurement, como se describe en Integra tu app.
Si activaste varios pedidos del mismo producto, la API de Partner Procurement puede enviar varios eventos con el tipo de evento ENTITLEMENT_ACTIVE para el mismo valor de ACCOUNT_ID, cada uno con un ENTITLEMENT_ID único que representa una oferta diferente. Esto significa que debes asegurarte de que la lógica de control de eventos de tu app pueda responder a ENTITLEMENT_ID en lugar de ACCOUNT_ID o PRODUCT_ID.
Debes asegurarte de que tu integración de frontend pueda controlar el nuevo objeto orders incluido en la carga útil de JWT. Para obtener más información, consulta Integra el frontend de tu app.
Para obtener más información sobre cómo activar varios pedidos del mismo producto, consulta Cómo activar varios pedidos del mismo producto.
Cómo aprobar un derecho
Cuando un cliente elige un plan de precios, Cloud Marketplace crea una autorización y envía el siguiente mensaje de Pub/Sub a tu app:
{ "eventId": "...", "eventType": "ENTITLEMENT_CREATION_REQUESTED", "providerId": "YOUR_PARTNER_ID", "entitlement": { "id": "ENTITLEMENT_ID", "updateTime": "...", "newOfferDuration": "P2Y3M", // Contract duration for offer-based entitlements }, }
En el ejemplo anterior, ENTITLEMENT_ID es un ID creado por Cloud Marketplace. Si la oferta tiene una duración especificada, esta se proporciona en años y meses. Si la oferta tiene una fecha de finalización especificada, en lugar de una duración, el campo que indica la duración está vacío.
En tu sistema, actualiza la cuenta del usuario para reflejar que compró un plan. Luego, para aprobar la autorización, realiza una solicitud HTTP POST a la API de Partner Procurement y envía el ENTITLEMENT_ID que aprobaste:
POST v1/providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID:approve
Cómo rechazar un derecho
Para rechazar un derecho, realiza una solicitud HTTP POST a la API de Partner Procurement y usa el método reject en tu solicitud:
POST v1/providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID:reject
Para indicar un motivo para rechazar el derecho en el cuerpo de la solicitud, usa el siguiente formato:
{ "reason": "..." }
Cambia un plan de derechos
De acuerdo con la manera en que configures los planes de precios, los clientes podrían cambiar sus planes. Si un cliente selecciona un plan de precios nuevo, recibirás un mensaje de Pub/Sub en el siguiente 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" }, }
Si la oferta tiene una duración especificada, esta se proporciona en años y meses. Si la oferta tiene una fecha de finalización especificada, en lugar de una duración, el campo que indica la duración está vacío.
Para aprobar el cambio de plan, realiza la siguiente solicitud HTTP POST a la API de socio:
POST v1/providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID:approvePlanChange
El cuerpo de la solicitud debe contar con el plan que se aprueba:
{
"pendingPlanName": PLAN_NAME
}
Después de que se apruebe el cambio, recibirás otro mensaje de Pub/Sub cuando entre en vigencia. En el mensaje, el campo eventType cambia a ENTITLEMENT_PLAN_CHANGED. Para verificar el estado de un plan, realiza la siguiente solicitud HTTP GET a la API de Partner Procurement.
GET v1/providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID
La respuesta es similar a la siguiente, el campo state indica si el plan nuevo está activo o si el cambio del plan todavía está pendiente.
{ "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", ... }
Cancela un derecho
Si un usuario decide cancelar la autorización, recibirás una notificación de Pub/Sub. De igual manera que cuando se cambia un plan, la cancelación se efectuará al final del ciclo de facturación actual.
La notificación está en el siguiente 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": "..." }, }
Cómo borrar un derecho
Si un usuario realiza una solicitud directa al equipo de asistencia de Google o abandona la plataforma de Google, se cancelan de inmediato sus derechos y se borran después de un período de gracia de 60 días. Para proteger la privacidad del usuario, debes borrar sus datos de los servidores cuando recibes la notificación.
Cuando se cancelan las autorizaciones y se borra la cuenta, recibirás notificaciones similares a las que se muestran a continuación:
{ "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": "...", }, }
Lista de tipos de eventos para tareas de la cuenta
A continuación, se muestra una lista de los eventType que tu app podría recibir en mensajes de Pub/Sub:
| eventType | Descripción |
|---|---|
| ACCOUNT_CREATION_REQUESTED | Obsoleta |
| ACCOUNT_ACTIVE | Indica que se creó la cuenta del cliente. |
| ACCOUNT_DELETED | Indica que la cuenta del cliente se borró de los sistemas de Google Cloud. |
| ENTITLEMENT_CREATION_REQUESTED | Indica que un cliente seleccionó uno de sus planes de precios. |
| ENTITLEMENT_OFFER_ACCEPTED | Indica que un cliente aceptó una oferta. Incluye la hora de inicio programada de la oferta, si la hay. Este evento se envía para las ofertas privadas y las ofertas estándar (compras públicas). |
| ENTITLEMENT_ACTIVE | Indica que el plan elegido de un cliente ahora está activo. |
| ENTITLEMENT_PLAN_CHANGE_REQUESTED | Indica que un cliente eligió un plan nuevo. |
| ENTITLEMENT_PLAN_CHANGED | Indica que el cambio de plan del cliente está aprobado y que los cambios entraron en vigencia. |
| ENTITLEMENT_PLAN_CHANGE_CANCELLED | Indica que se canceló el cambio de plan de un cliente, ya sea porque no se aprobó o porque volvió a su plan anterior. |
| ENTITLEMENT_PENDING_CANCELLATION | Indica que un cliente canceló su plan y la cancelación está pendiente hasta el final del ciclo de facturación. |
| ENTITLEMENT_CANCELLATION_REVERTED | Indica que se revocó la cancelación pendiente de un cliente. Ten en cuenta que las cancelaciones no se pueden revertir después de su finalización. |
| ENTITLEMENT_CANCELLED | Indica que se canceló el plan de un cliente. |
| ENTITLEMENT_CANCELLING | Indica que el plan del cliente está en proceso de cancelación. |
| ENTITLEMENT_RENEWED | Indica que se renovó el derecho de un cliente por otro período. No es necesario que realices ninguna acción para completar la renovación. |
| ENTITLEMENT_OFFER_ENDED | Indica que finalizó la oferta privada de un cliente. Si se canceló el derecho del cliente, se activa un evento ENTITLEMENT_CANCELLED independiente. Si el derecho del cliente sigue activo, su plan volverá a tener el precio sin descuento. |
| ENTITLEMENT_DELETED | Indica que la información sobre el plan de un cliente se borró de Cloud Marketplace. |