Quando os clientes escolhem um plano de preços para seu software, o Google cria um direito, que indica que o cliente comprou seu produto no Cloud Marketplace. Nesta seção, mostramos como criar e gerenciar direitos para seus clientes usando a API Partner Procurement.
Para mais detalhes sobre o gerenciamento de direitos, acesse a documentação de referência.
Antes de começar
- Configure o acesso à API Cloud Commerce Partner Procurement, conforme descrito em Integrar seu app.
Se você tiver ativado vários pedidos do mesmo produto, a
API Partner Procurement poderá enviar vários eventos com o tipo de evento
ENTITLEMENT_ACTIVE para o mesmo valor de ACCOUNT_ID, cada um com um
ENTITLEMENT_ID exclusivo que representa uma oferta diferente. Isso significa que você precisa
garantir que a lógica de processamento de eventos do app possa responder ao ENTITLEMENT_ID
em vez do ACCOUNT_ID ou do PRODUCT_ID.
É necessário garantir que a integração do front-end possa processar o novo objeto orders
incluído no payload do JWT. Para mais informações, consulte
Integrar o front-end do app.
Para mais informações sobre como ativar vários pedidos do mesmo produto, consulte Ativar vários pedidos do mesmo produto.
Aprovar um direito de acesso
Quando um cliente escolhe um plano de preços, o Cloud Marketplace cria um direito e envia a seguinte mensagem do Pub/Sub ao seu app:
{ "eventId": "...", "eventType": "ENTITLEMENT_CREATION_REQUESTED", "providerId": "YOUR_PARTNER_ID", "entitlement": { "id": "ENTITLEMENT_ID", "updateTime": "...", "newOfferDuration": "P2Y3M", // Contract duration for offer-based entitlements }, }
em que ENTITLEMENT_ID é um ID criado pelo Cloud Marketplace. Se a oferta tiver uma duração especificada, ela será informada em anos e meses. Se a oferta tiver uma data de término especificada, em vez de uma duração, o campo que indica a duração vai estar vazio.
No seu sistema, atualize a conta do usuário para refletir que ele comprou um plano. Em seguida, para aprovar o direito, faça uma solicitação HTTP POST à
API Partner Procurement e envie o ENTITLEMENT_ID que
você está aprovando:
POST v1/providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID:approve
Recusar um direito
Para rejeitar um direito, faça uma solicitação HTTP POST à
API Partner Procurement e use o método reject na sua solicitação:
POST v1/providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID:reject
Para informar um motivo para rejeitar o direito no corpo da solicitação, use o seguinte formato:
{ "reason": "..." }
Mudar um plano de direitos
Dependendo de como você configura seus planos de preços, seus clientes podem alterar o plano deles. Se um cliente selecionar um novo plano de preços, você receberá uma mensagem do Pub/Sub, no seguinte formato:
{ "eventId": "...", "eventType": "ENTITLEMENT_PLAN_CHANGE_REQUESTED", "providerId": "YOUR_PARTNER_ID", "entitlement": { "id": "ENTITLEMENT_ID", "newPlan": "ultimate", // New plan "updateTime": "...", "newOfferDuration": "P2Y3M", // Contract duration for the new offer, for offer-based entitlements "newProduct": "test-product.cloud.goog" "newOffer": "projects/1234567/services/test-product.cloud.goog/standardOffers/aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa" }, }
Se a oferta tiver uma duração especificada, ela será informada em anos e meses. Se a oferta tiver uma data de término especificada, em vez de uma duração, o campo que indica a duração vai estar vazio.
Para aprovar a alteração do plano, faça a seguinte solicitação HTTP POST
à API Partner Procurement:
POST v1/providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID:approvePlanChange
O corpo da solicitação precisa ter o plano que está sendo aprovado:
{
"pendingPlanName": PLAN_NAME
}
Depois que a alteração for aprovada, você receberá outra mensagem do Pub/Sub quando a alteração entrar em vigor. Na mensagem, o campo eventType muda para ENTITLEMENT_PLAN_CHANGED. Para verificar o status de um plano, faça a seguinte solicitação HTTP GET à API Partner Procurement.
GET v1/providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID
A resposta é semelhante à seguinte, com o campo state indicando
se o novo plano está ativo ou se a alteração do plano ainda está pendente:
{ "name": "providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID", "provider": "YOUR_PARTNER_ID", "account": "USER_ACCOUNT_ID", "product": "example-server", "plan": "pro", "state": "ENTITLEMENT_PENDING_PLAN_CHANGE", "newPendingPlan": "ultimate", ... }
Cancelar um direito
Se um usuário decidir cancelar um direito dele, você receberá uma notificação do Pub/Sub. De maneira similar à alteração de um plano, o cancelamento real pode entrar em vigor no final do ciclo de faturamento real.
A notificação está no seguinte formato:
{ "eventId": "...", // If the entitlement is canceled at the end of the month, // eventType is ENTITLEMENT_PENDING_CANCELLATION "eventType": "ENTITLEMENT_CANCELLED", "providerId": "YOUR_PARTNER_ID", "entitlement": { "id": "ENTITLEMENT_ID", "updateTime": "..." }, }
Excluir um direito
Se um usuário fizer uma solicitação direta ao suporte do Google ou sair da plataforma do Google, os direitos dele serão cancelados imediatamente, e os direitos e as contas serão excluídos após um período de carência de 60 dias. Para proteger a privacidade do usuário, exclua os dados dele dos seus servidores quando receber a notificação.
Quando os direitos são cancelados e a conta é excluída, você recebe notificações semelhantes às seguintes:
{ "eventId": "...", "eventType": "ENTITLEMENT_DELETED", "providerId": "YOUR_PARTNER_ID", "entitlement": { "id": "ENTITLEMENT_ID", "updateTime": "...", }, }
{ "eventId": "...", "eventType": "ACCOUNT_DELETED", "providerId": "YOUR_PARTNER_ID", "account": { "id": "USER_ACCOUNT_ID", "updateTime": "...", }, }
Lista de tipos de eventos para tarefas da conta
A seguir, é apresentada uma lista dos eventTypes que seu aplicativo pode receber em mensagens do Pub/Sub:
| eventType | Descrição |
|---|---|
| ACCOUNT_CREATION_REQUESTED | Obsoleto |
| ACCOUNT_ACTIVE | Indica que a conta do cliente foi criada. |
| ACCOUNT_DELETED | Indica que a conta do cliente foi excluída dos sistemas do Google Cloud. |
| ENTITLEMENT_CREATION_REQUESTED | Indica que um cliente selecionou um dos seus planos de preços. |
| ENTITLEMENT_OFFER_ACCEPTED | Indica que uma oferta foi aceita por um cliente. Inclui o horário de início programado da oferta, se houver. Esse evento é enviado para ofertas privadas e padrão (compras públicas). |
| ENTITLEMENT_ACTIVE | Indica que o plano escolhido de um cliente está ativo agora. |
| ENTITLEMENT_PLAN_CHANGE_REQUESTED | Indica que um cliente escolheu um novo plano. |
| ENTITLEMENT_PLAN_CHANGED | Indica que a alteração do plano de um cliente foi aprovada e as alterações entraram em vigor. |
| ENTITLEMENT_PLAN_CHANGE_CANCELLED | Indica o cancelamento da alteração do plano de um cliente devido à falta de aprovação ou ao retorno do cliente ao plano antigo. |
| ENTITLEMENT_PENDING_CANCELLATION | Indica o cancelamento do plano pelo cliente, pendente até o final do ciclo de faturamento. |
| ENTITLEMENT_CANCELLATION_REVERTED | Indica que o cancelamento pendente de um cliente foi revertido. Observe que os cancelamentos não podem ser revertidos após a finalização. |
| ENTITLEMENT_CANCELLED | Indica o cancelamento do plano de um cliente. |
| ENTITLEMENT_CANCELLING | Indica que o plano de um cliente está em processo de cancelamento. |
| ENTITLEMENT_RENEWED | Indica que o direito de um cliente foi renovado por outro período. Você não precisa fazer nada para concluir a renovação. |
| ENTITLEMENT_OFFER_ENDED | Indica que a oferta privada de um cliente terminou. Se o direito do cliente tiver sido cancelado, um evento ENTITLEMENT_CANCELLED separado será acionado. Se o direito do cliente ainda estiver ativo, o plano será revertido para o preço sem desconto. |
| ENTITLEMENT_DELETED | Indica que as informações sobre o plano de um cliente foram excluídas do Cloud Marketplace. |