Notificações push

Visão geral

A API Revendedor usa a API Pub/Sub para entregar notificações push sobre diferentes eventos de assinatura do Google Workspace. Por exemplo, é possível configurar notificações push para receber avisos 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 à conta de serviço no projeto do Cloud. Conceder o papel roles/pubsub.editor é um bom comprometimento (fácil e não muito amplo), mas é recomendável usar permissões do Pub/Sub mais específicas.

Criar um tópico

Para criar um tópico, você precisa se registrar na API Revendedor usando o método resellernotify.register. O método resellernotify.register usa um endereço de e-mail de conta de serviço como parâmetro. Somente contas de serviço autorizadas por esse método podem se inscrever no 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 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 para revendedores 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"
}

Inscrever-se em um tópico

Depois de criar o tópico do Pub/Sub, é preciso configurar como o aplicativo consome os eventos de alteração. Escolha uma das seguintes opções:

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

Veja 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 da 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. Veja 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

Veja 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 da assinatura terminou.
  • PRICE_PLAN_SWITCHED: o cliente mudou de um plano flexível para um anual. Este evento não será acionado se o cliente converter um plano de compromisso em um flexível como parte de uma renovação.
  • COMMITMENT_CHANGED: o compromisso anual foi aumentado ou reduzido.
  • SUBSCRIPTION_RENEWED: uma assinatura anual foi renovada.
  • SUBSCRIPTION_SUSPENDED: a assinatura foi suspensa. Consulte o campo subscription_suspension_reasons.
  • SUBSCRIPTION_SUSPENSION_REVOKED: a suspensão de uma assinatura suspensa foi revogada.
  • 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:

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

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

  • SUBSCRIPTION_DOWNGRADE: foi feito downgrade da SKU da assinatura. Por exemplo, fizemos o downgrade da assinatura do Google Workspace Business Standard para o Business Starter.

  • LICENSE_ASSIGNMENT_CHANGED: a licença foi atribuída ou revogada a um usuário. É possível usar esse evento para rastrear de forma reativa as alterações na contagem de licenças em assinaturas flexíveis.

Motivos do cancelamento da assinatura

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

  • TRANSFERRED_OUT: o cliente foi transferido para 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á suspensa porque está incluída no Google Workspace Business Plus.
  • RESELLER_INITIATED: o revendedor cancelou a assinatura.
  • OTHER: a assinatura foi cancelada por algum motivo diferente do listado.

Motivos da suspensão da assinatura

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

  • PENDING_TOS_ACCEPTANCE: o cliente não fez login e não 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 ao final da vigência.
  • RESELLER_INITIATED: o revendedor suspendeu a assinatura manualmente.
  • TRIAL_ENDED: o teste do cliente expirou, e o cliente não selecionou um plano que não seja de teste.
  • OTHER: o cliente está suspenso por um motivo interno do Google, por exemplo, por 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 nunca. Recomendamos o uso de reseller.subscriptions.get em todas as assinaturas modificadas para extrair o estado atual.