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 CloudSUBSCRIPTION_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 camposubscription_suspension_reasons
.SUBSCRIPTION_SUSPENSION_REVOKED
: a suspensão de uma assinatura suspensa foi revogada.SUBSCRIPTION_CANCELLED
: a assinatura foi cancelada. Consulte o camposubscription_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.