Notificações push

Visão geral

A API Reseller usa a API Pub/Sub para enviar notificações push sobre diferentes eventos de assinatura do Google Workspace. Por exemplo, você pode configurar notificações push para receber notificações quando o status de assinatura dos seus clientes mudar.

Pré-requisitos

  • Ative a API Pub/Sub para seu projeto do Google Cloud.
  • Conceda papéis do IAM do Pub/Sub à sua conta de serviço no projeto do Cloud. Conceder o papel roles/pubsub.editor é um bom compromisso (fácil e não muito amplo), mas talvez seja melhor usar permissões do Pub/Sub mais específicas.

Criar um tópico

Para criar um tópico, você precisa se registrar na API Reseller usando o método resellernotify.register. O método resellernotify.register usa um endereço de e-mail da conta de serviço como parâmetro. Somente as contas de serviço autorizadas por esse método podem se inscrever no seu tópico recém-criado.

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

Uma resposta bem-sucedida retorna um código de status HTTP 200 e uma resposta JSON contendo o nome do seu tópico do Pub/Sub.

Veja a seguir um exemplo de resposta:

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

Para autorizar outras contas de serviço a usar seu tópico, chame resellernotify.register novamente.

Revogar o acesso de uma conta de serviço

A API Reseller também permite cancelar o registro de contas de serviço usando o endpoint resellernotify.unregister:

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

Assinar um tópico

Depois de criar o tópico do Pub/Sub, você precisa configurar como o aplicativo consome os eventos de mudança. Escolha uma das seguintes opções:

  • Assinatura push: você fornece um callback POST HTTP. O Pub/Sub usa esse callback para notificar seu aplicativo sobre novos eventos.
  • Assinatura de pull: o aplicativo faz uma chamada HTTP periodicamente para receber todas as mudanças na fila.

Confira a seguir um exemplo de solicitação para assinar um tópico:

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

Substitua:

  • PROJECT: o projeto do Google Cloud
  • SUBSCRIPTION_NAME: um nome de identificação para sua assinatura.
  • TOPIC_NAME: o tópico do Pub/Sub que você criou anteriormente.
  • PUSH_NOTIFICATION_ENDPOINT: o endpoint do gerenciador de notificações push.

Uma resposta bem-sucedida retorna um código de status HTTP 200. Confira a seguir um exemplo de resposta: 

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

Formatos de notificação

Confira a seguir um exemplo de notificação do Pub/Sub. Os dados da mensagem são transmitidos como uma string JSON codificada em base64.

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

Confira a seguir o exemplo de objeto message.data após a decodificação:

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

Tipos de evento

A lista a seguir contém todos os tipos de evento possíveis:

  • NEW_SUBSCRIPTION_CREATED: uma nova assinatura foi criada.
  • SUBSCRIPTION_TRIAL_ENDED: o teste de uma assinatura foi encerrado.
  • PRICE_PLAN_SWITCHED: o cliente converteu um plano flexível em anual. Esse evento não é acionado se o cliente mudar de um plano de compromisso para um flexível como parte de uma renovação.
  • COMMITMENT_CHANGED: o compromisso anual foi aumentado ou diminuído.
  • SUBSCRIPTION_RENEWED: uma assinatura anual foi renovada.
  • SUBSCRIPTION_SUSPENDED: a assinatura está suspensa. Consulte o campo subscription_suspension_reasons.
  • SUBSCRIPTION_SUSPENSION_REVOKED: a suspensão foi revogada para uma assinatura que já estava suspensa.
  • SUBSCRIPTION_CANCELLED: a assinatura foi cancelada. Consulte o campo subscription_cancellation_reason. Também pode ser usado para detectar transferências.

  • SUBSCRIPTION_CONVERTED: a assinatura foi convertida. Confira alguns exemplos de casos para esse evento:

    • Converta a assinatura direta em uma assinatura de revendedor.
    • Converter a assinatura paga em oferta de carência.
    • Converter a assinatura on-line em off-line.

  • SUBSCRIPTION_UPGRADE: a SKU da assinatura foi atualizada. Por exemplo, a assinatura foi atualizada do Google Workspace Business Starter para o Business Standard.

  • SUBSCRIPTION_DOWNGRADE: a SKU da assinatura foi rebaixada. Por exemplo, a assinatura foi rebaixada do Google Workspace Business Standard para Business Starter.

  • LICENSE_ASSIGNMENT_CHANGED: a licença foi atribuída ou revogada de um usuário. Você pode usar esse evento para acompanhar de forma reativa as mudanças na contagem de assentos para as assinaturas flexíveis.

Motivos para o cancelamento da assinatura

O motivo do cancelamento da assinatura é preenchido quando o event_type é SUBSCRIPTION_CANCELLED. Confira abaixo os possíveis motivos de cancelamento:

  • TRANSFERRED_OUT: o cliente foi transferido para o faturamento direto ou para outro revendedor.
  • PURCHASE_OF_SUBSUMING_SKU: o cliente fez upgrade para uma SKU que substitui outra. Por exemplo, se um cliente com o Google Workspace Business Starter e o Google Vault fizer upgrade para o Google Workspace Business Plus, a assinatura do Vault será absorvida porque está incluída no Google Workspace Business Plus.
  • RESELLER_INITIATED: o revendedor cancelou a assinatura.
  • OTHER: a assinatura foi cancelada por outro motivo que não está listado.

Motivos para a suspensão da assinatura

O motivo da suspensão da assinatura é preenchido quando o event_type é SUBSCRIPTION_SUSPENDED. Confira abaixo os possíveis motivos de suspensão:

  • PENDING_TOS_ACCEPTANCE: o cliente não fez login e aceitou os Termos de Serviço de revenda do Google Workspace.
  • RENEWAL_WITH_TYPE_CANCEL: o compromisso do cliente terminou e o serviço foi cancelado no final do período.
  • RESELLER_INITIATED: o revendedor suspendeu a assinatura manualmente.
  • TRIAL_ENDED: o teste do cliente expirou, e ele não selecionou um plano sem teste.
  • OTHER: o cliente foi suspenso por um motivo interno do Google, por exemplo, abuso.

Limitações do Pub/Sub

A ordem das notificações push não é garantida. As mensagens podem ser entregues várias vezes e, em situações extremas, nem mesmo entregues. Recomendamos o uso de reseller.subscriptions.get em todas as assinaturas alteradas para extrair o estado atual.