Notificaciones push

En esta página, se describe cómo usar las notificaciones push con la API de Reseller.

Descripción general

La API de Reseller usa la API de Pub/Sub para enviar notificaciones push sobre los eventos de suscripción de Google Workspace. Por ejemplo, puedes configurar notificaciones push para recibir avisos cuando cambien los estados de las suscripciones de los clientes.

Requisitos previos

Habilita la API de Pub/Sub para tu proyecto de Google Cloud.
Otorga roles de IAM de Pub/Sub a tu cuenta de servicio en tu proyecto de Cloud. Se recomienda otorgar el rol de roles/pubsub.editor, pero puedes usar permisos de Pub/Sub más específicos.

Crea un tema

Para crear un tema, regístrate en la API de Reseller con el método resellernotify.register. Este método toma la dirección de correo electrónico de una cuenta de servicio como parámetro. Solo las cuentas de servicio autorizadas por este método pueden suscribirse a tu tema.

POST https://reseller.googleapis.com/apps/reseller/v1/resellernotify/register
{
  "serviceAccountEmailAddress": "reseller@reseller-project.iam.gserviceaccount.com"
}

Una respuesta correcta devuelve un código de estado HTTP 200 y una respuesta JSON que contiene el nombre de tu tema de Pub/Sub.

Respuesta de ejemplo:

{
  "topicName": "projects/partner-watch/topics/C0abcdefg"
}

Para autorizar más cuentas de servicio, vuelve a llamar a resellernotify.register.

Cómo revocar el acceso de una cuenta de servicio

La API de Reseller puede anular el registro de cuentas de servicio con el extremo resellernotify.unregister:

POST https://reseller.googleapis.com/apps/reseller/v1/resellernotify/unregister
{
  "serviceAccountEmailAddress": "reseller@reseller-project.iam.gserviceaccount.com"
}

Cómo suscribirse a un tema

Después de crear el tema de Pub/Sub, configura cómo tu aplicación consumirá los eventos de cambio. Elija una de estas opciones:

Suscripción de envío: Proporcionas una devolución de llamada POST HTTP. Pub/Sub usa esta devolución de llamada para notificar a tu aplicación sobre los eventos nuevos.
Suscripción de extracción: Tu aplicación realiza periódicamente una llamada HTTP para obtener los cambios en cola.

Ejemplo de solicitud para suscribirse a un tema:

PUT https://pubsub.googleapis.com/v1/projects/PROJECT/subscriptions/SUBSCRIPTION_NAME
{
  "topic": "TOPIC_NAME"
  // Only needed for push configurations
  "pushConfig": {
    "pushEndpoint": "PUSH_NOTIFICATION_ENDPOINT"
  },
}

Reemplaza lo siguiente:

PROJECT: Es el proyecto de Google Cloud.
SUBSCRIPTION_NAME: Es un nombre de identificación para tu suscripción.
TOPIC_NAME: Es el tema de Pub/Sub que creaste anteriormente.
PUSH_NOTIFICATION_ENDPOINT: Es el extremo del controlador de notificaciones push.

Una respuesta correcta devuelve un código de estado HTTP 200. Respuesta de ejemplo:

{
  "name": "projects/PROJECT/subscriptions/SUBSCRIPTION_NAME",
  "topic": "TOPIC_NAME",
  "pushConfig": {
    "pushEndpoint": "PUSH_NOTIFICATION_ENDPOINT"
    },
  "ackDeadlineSeconds": 10
}

Formatos de notificación

A continuación, se muestra un ejemplo de notificación de Pub/Sub. Los datos del mensaje son una cadena JSON codificada en base64.

{
  "message": {
    "attributes": {},
    "data": "eyJza3VfaWQiOiAiR29vZ2xlLUFwcHMtVW5saW1pdGVkIiwgImV2ZW50X3R5cGUiOiAiU1VCU0NSSVBUSU9OX0NBTkNFTExFRCIsICJjdXN0b21lcl9kb21haW5fbmFtZSI6ICJkb21haW4uY29tIiwgInN1YnNjcmlwdGlvbl9pZCI6ICIxMjM0NTY3IiwgImN1c3RvbWVyX2lkIjogIkMwYWJjZGVmIiwgIm1lc3NhZ2VfaWQiOiAiODY3NTMwOSIsICJwdWJsaXNoX3RpbWUiOiB7InNlY29uZHMiOiAxNDU3NzMxODQ2LCAibmFub3MiOiAzNDkwMDAwMDB9LCAicmVzZWxsZXJfY3VzdG9tZXJfaWQiOiAiQzByZXNlbGxlciJ9",
    "message_id": 1234567891012131
  },
  "subscription": "projects/PROJECT/subscriptions/SUBSCRIPTION_NAME"
}

Ejemplo de objeto message.data después de la decodificación:

{
  "customer_id": "C0abcdef",
  "customer_domain_name": "domain.com",
  "event_type": "SUBSCRIPTION_CANCELLED",
  "sku_id": "Google-Apps-Unlimited",
  "subscription_id": "1234567",
  // Optional fields dependent on event_type
  "subscription_suspension_reasons": [],
  "subscription_cancellation_reason": "REASON"
}

Tipos de eventos

Tipos de eventos posibles:

NEW_SUBSCRIPTION_CREATED: Se creó una suscripción nueva.
SUBSCRIPTION_TRIAL_ENDED: Finalizó la prueba de una suscripción.
PRICE_PLAN_SWITCHED: El cliente cambió de un plan flexible a un plan anual. Este evento no se activa si el cliente cambia de un plan anual a un plan flexible como parte de una renovación.
COMMITMENT_CHANGED: Se aumentó o disminuyó el compromiso anual.
SUBSCRIPTION_RENEWED: Se renovó una suscripción anual.
SUBSCRIPTION_SUSPENDED: La suscripción está suspendida. Consulta subscription_suspension_reasons.
SUBSCRIPTION_SUSPENSION_REVOKED: Se revocó la suspensión.
SUBSCRIPTION_CANCELLED: Se canceló la suscripción. Consulta subscription_cancellation_reason. También puede detectar transferencias.
SUBSCRIPTION_CONVERTED: Se convirtió la suscripción. Ejemplos de casos:
- Convierte una suscripción directa en una suscripción de revendedor.
- Cambia la suscripción pagada a una oferta de período de gracia.
- Convertir una suscripción en línea a una suscripción sin conexión
SUBSCRIPTION_UPGRADE: Se actualizó el SKU de la suscripción. Ejemplo: Google Workspace Business Starter a Business Standard.
SUBSCRIPTION_DOWNGRADE: Se cambió a una versión inferior del SKU de suscripción. Ejemplo: Google Workspace Business Standard a Business Starter.
LICENSE_ASSIGNMENT_CHANGED: Se asignó o revocó la licencia. Se usa para hacer un seguimiento de los cambios en el recuento de asientos de las suscripciones flexibles.

Motivos de cancelación de la suscripción

El motivo de la cancelación se completa cuando event_type es SUBSCRIPTION_CANCELLED. Posibles motivos:

TRANSFERRED_OUT: El cliente se transfirió a la facturación directa o a otro revendedor.
PURCHASE_OF_SUBSUMING_SKU: El cliente actualizó a un SKU que anula otro. Ejemplo: Un cliente con Google Workspace Business Starter y Vault actualiza a Business Plus, que incluye Vault.
RESELLER_INITIATED: El revendedor canceló la suscripción.
OTHER: La suscripción se canceló por otro motivo.

Motivos de suspensión de la suscripción

El motivo de la suspensión se propaga cuando event_type es SUBSCRIPTION_SUSPENDED. Posibles motivos:

PENDING_TOS_ACCEPTANCE: El cliente no aceptó las Condiciones del Servicio de Google Workspace revendido.
RENEWAL_WITH_TYPE_CANCEL: Finalizó el compromiso del cliente y se canceló el servicio.
RESELLER_INITIATED: El revendedor suspendió manualmente la suscripción.
TRIAL_ENDED: La prueba del cliente venció sin que se seleccionara un plan que no sea de prueba.
OTHER: Se suspendió al cliente por un motivo interno de Google, como abuso.

Limitaciones de Pub/Sub

El orden de las notificaciones push no siempre es secuencial. Es posible que los mensajes se entreguen varias veces o que no se entreguen. Te recomendamos que uses reseller.subscriptions.get en las suscripciones modificadas para extraer el estado actual.