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 os status de assinatura dos clientes mudam.

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 em fila.

Confira a seguir um exemplo de solicitação para se inscrever em 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 algum motivo diferente dos listados.

Motivos para suspensão de assinaturas

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 fim 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.