Gestionar los derechos de los clientes de tu producto de SaaS

Cuando los clientes eligen un plan de precios para tu software, Google crea un derecho, que indica que el cliente ha comprado tu producto en Cloud Marketplace. En esta sección se explica cómo crear y gestionar derechos para tus clientes mediante la API Partner Procurement.

Para obtener más información sobre cómo gestionar los derechos, consulta la documentación de referencia.

Antes de empezar

• Configura el acceso a la API Cloud Commerce Partner Procurement, tal como se describe en la sección sobre cómo integrar tu aplicación.

Si ha activado varios pedidos del mismo producto, la API 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 gestión de eventos de tu aplicación pueda responder a ENTITLEMENT_ID en lugar de a ACCOUNT_ID o PRODUCT_ID.

Debes asegurarte de que tu integración de frontend pueda gestionar el nuevo objeto orders incluido en la carga útil del JWT. Para obtener más información, consulta Integrar el frontend de tu aplicación.

Para obtener más información sobre cómo activar varios pedidos del mismo producto, consulta el artículo Activar varios pedidos del mismo producto.

Aprobar un derecho

Cuando un cliente elige un plan de precios, Cloud Marketplace crea un derecho y envía el siguiente mensaje de Pub/Sub a tu aplicación:

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

ENTITLEMENT_ID es un ID creado por Cloud Marketplace. Si la oferta tiene una duración específica, esta se indica en años y meses. Si la oferta tiene una fecha de finalización específica en lugar de una duración, el campo que indica la duración estará vacío.

En tu sistema, actualiza la cuenta del usuario para reflejar que ha comprado un plan. A continuación, para aprobar el derecho, haz una solicitud HTTP POST a la API Partner Procurement y envía el ENTITLEMENT_ID que quieras aprobar:

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

Rechazar un derecho

Para rechazar un derecho, haz una solicitud HTTP POST a la API Partner Procurement y usa el método reject en tu solicitud:

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

Para indicar el motivo por el que se rechaza el derecho en el cuerpo de la solicitud, utiliza el siguiente formato:

{
  "reason": "..."
}

Cambiar un plan de derechos

En función de cómo configures tus planes de precios, es posible que tus clientes puedan cambiar de plan. Si un cliente selecciona un nuevo plan de precios, recibirás un mensaje de Pub/Sub con 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 específica, esta se indica en años y meses. Si la oferta tiene una fecha de finalización específica en lugar de una duración, el campo que indica la duración estará vacío.

Para aprobar el cambio de plan, haz la siguiente solicitud HTTP POST a la API Partner Procurement:

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

El cuerpo de la solicitud debe incluir el plan que se va a aprobar:

{
  "pendingPlanName": PLAN_NAME
}

Una vez que se apruebe el cambio, recibirás otro mensaje de Pub/Sub cuando se aplique. En el mensaje, el campo eventType cambia a ENTITLEMENT_PLAN_CHANGED. Para comprobar el estado de un plan, haz la siguiente solicitud HTTP GET a la API Partner Procurement.

GET v1/providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID

La respuesta es similar a la siguiente, con el campo state que indica si el nuevo plan está activo o si el cambio de plan aún 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",
  ...
}

Cancelar un derecho

Si un usuario decide cancelar su derecho, recibirás una notificación de Pub/Sub. Al igual que al cambiar de plan, la cancelación puede hacerse efectiva al final del ciclo de facturación en curso.

La notificación tiene 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": "..."
  },
}

Eliminar un derecho

Si un usuario envía una solicitud directamente al equipo de Asistencia de Google o abandona la plataforma de Google, sus derechos se cancelarán inmediatamente y sus derechos y cuentas se eliminarán tras un periodo de gracia de 60 días. Para proteger la privacidad de los usuarios, debes eliminar sus datos de tus servidores cuando recibas la notificación.

Cuando se cancelan los derechos y se elimina la cuenta, recibes notificaciones similares a las siguientes:

{
  "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 de tareas de la cuenta

A continuación se muestra una lista de los eventTypes que puede recibir tu aplicación en los mensajes de Pub/Sub: