Notificações push

Esta página descreve como usar notificações push com a API Reseller.

Visão geral

A API Reseller usa a API Pub/Sub para enviar notificações push sobre eventos de assinatura do Google Workspace. Por exemplo, é possível configurar notificações push para receber avisos quando os status de assinatura do cliente mudarem.

Pré-requisitos

Ative a API Pub/Sub para seu projeto na nuvem do Google Cloud.
Conceda papéis do IAM do Pub/Sub à sua conta de serviço no projeto na nuvem. Recomendamos conceder o papel roles/pubsub.editor, mas você pode usar permissões mais específicas do Pub/Sub.

Criar um tópico

Para criar um tópico, registre-se na API Reseller usando o resellernotify.register método. Esse método 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.

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.

Exemplo de resposta:

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

Para autorizar mais contas de serviço, chame resellernotify.register novamente.

Revogar o acesso de uma conta de serviço

A API Reseller pode 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, configure como o aplicativo consome eventos de mudança. Escolha uma das opções a seguir:

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

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 na nuvem do Google
SUBSCRIPTION_NAME: um nome de identificação para sua assinatura
TOPIC_NAME: o tópico do Pub/Sub criado anteriormente
PUSH_NOTIFICATION_ENDPOINT: o endpoint do handler de notificação push

Uma resposta bem-sucedida retorna um código de status HTTP 200. 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 uma string JSON codificada em base64.

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

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 dependent on event_type
  "subscription_suspension_reasons": [],
  "subscription_cancellation_reason": "REASON"
}

Tipos de evento

Tipos de evento possíveis:

NEW_SUBSCRIPTION_CREATED: uma nova assinatura foi criada.
SUBSCRIPTION_TRIAL_ENDED: o período de teste de uma assinatura terminou.
PRICE_PLAN_SWITCHED: o cliente mudou de um plano flexível para um plano anual. Esse evento não é acionado se o cliente mudar de um plano anual para um plano 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 foi suspensa. Consulte subscription_suspension_reasons.
SUBSCRIPTION_SUSPENSION_REVOKED: a suspensão foi revogada.
SUBSCRIPTION_CANCELLED: a assinatura foi cancelada. Consulte subscription_cancellation_reason. Também é possível detectar transferências.
SUBSCRIPTION_CONVERTED: a assinatura foi convertida. Exemplos de casos:
- Converter uma assinatura direta em uma assinatura de revendedor.
- Converter uma assinatura paga em uma oferta de carência.
- Converter uma assinatura on-line em uma assinatura off-line.
SUBSCRIPTION_UPGRADE: a SKU da assinatura foi atualizada. Exemplo: do Google Workspace Business Starter para o Business Standard.
SUBSCRIPTION_DOWNGRADE: a SKU da assinatura foi rebaixada. Exemplo: do Google Workspace Business Standard para o Business Starter.
LICENSE_ASSIGNMENT_CHANGED: a licença foi atribuída ou revogada. Use para acompanhar as mudanças na contagem de licenças para assinaturas flexíveis.

Motivos de cancelamento de assinaturas

O motivo do cancelamento é preenchido quando event_type é SUBSCRIPTION_CANCELLED. Motivos possíveis:

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. Exemplo: um cliente com o Google Workspace Business Starter e o Vault faz upgrade para o Business Plus, que inclui o Vault.
RESELLER_INITIATED: o revendedor cancelou a assinatura.
OTHER: a assinatura foi cancelada por outro motivo.

Motivos da suspensão da assinatura

O motivo da suspensão é preenchido quando event_type é SUBSCRIPTION_SUSPENDED. Motivos possíveis:

PENDING_TOS_ACCEPTANCE: o cliente não aceitou os Termos de Serviço revendidos do Google Workspace.
RENEWAL_WITH_TYPE_CANCEL: o compromisso do cliente terminou e o serviço foi cancelado.
RESELLER_INITIATED: o revendedor suspendeu manualmente a assinatura.
TRIAL_ENDED: o período de teste do cliente expirou sem que ele selecionasse um plano não de teste.
OTHER: o cliente foi suspenso por um motivo interno do Google, como abuso.

Limitações do Pub/Sub

A ordem das notificações push nem sempre é sequencial. As mensagens podem ser entregues várias vezes ou não ser entregues. Recomendamos usar reseller.subscriptions.get em assinaturas alteradas para extrair o estado atual.