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 entregar notificaciones push sobre Google Workspace eventos de suscripción. Por ejemplo, puedes configurar notificaciones push para recibir avisos cuando cambien los estados de suscripción de los clientes.

Requisitos previos

Crea un tema

Para crear un tema, regístrate en la API de Reseller con el resellernotify.register método. Este método toma una dirección de correo electrónico de la 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 del 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.

Revoca el acceso para una cuenta de servicio

La API de Reseller puede anular el registro de las 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"
}

Suscríbete a un tema

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

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

Solicitud de ejemplo 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

El siguiente es 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: Se suspendió la suscripción. 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:
    • Convertir una suscripción directa en una suscripción de distribuidor
    • Convertir una suscripción pagada en una oferta de período de gracia
    • Convertir una suscripción en línea en 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 el SKU de la 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 puestos para las suscripciones flexibles.

Motivos de cancelación de las suscripciones

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

  • TRANSFERRED_OUT: El cliente se transfirió a la facturación directa o a otro distribuidor.
  • 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 distribuidor canceló la suscripción.
  • OTHER: La suscripción se canceló por otro motivo.

Motivos de suspensión de las suscripciones

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 revendidas.
  • RENEWAL_WITH_TYPE_CANCEL: Finalizó el compromiso del cliente y se canceló el servicio.
  • RESELLER_INITIATED: El distribuidor suspendió manualmente la suscripción.
  • TRIAL_ENDED: Venció la prueba del cliente sin que se seleccionara un plan que no sea de prueba.
  • OTHER: El cliente se suspende por un motivo interno de Google, como el 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.