Quando os clientes escolhem um plano de preços para o seu software, a Google cria um direito, que indica que o cliente comprou o seu produto no Cloud Marketplace. Esta secção revê como criar e gerir autorizações para os seus clientes através da API Partner Procurement.
Para mais detalhes sobre a gestão de concessões, visite a documentação de referência.
Antes de começar
- Configure o acesso à API Cloud Commerce Partner Procurement, conforme descrito em Integre a sua app.
Se ativou várias encomendas do mesmo produto, a API Partner Procurement pode 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. Isto significa que tem de garantir que a lógica de processamento de eventos da sua app pode responder ao ENTITLEMENT_ID em vez do ACCOUNT_ID ou do PRODUCT_ID.
Tem de garantir que a integração do frontend consegue processar o novo objeto orders
incluído no payload JWT. Para mais informações, consulte o artigo
Integre o frontend da sua app.
Para mais informações sobre como ativar várias encomendas do mesmo produto, consulte o artigo Ative várias encomendas do mesmo produto.
Aprove um direito de utilização
Quando um cliente escolhe um plano de preços, o Cloud Marketplace cria uma autorização e envia a seguinte mensagem do Pub/Sub para a sua 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, essa duração é indicada em anos e meses. Se a oferta tiver uma data de conclusão especificada, em vez de uma duração, o campo que indica a duração está vazio.
No seu sistema, atualize a conta do utilizador para refletir que este comprou um plano. Em seguida, para aprovar a concessão, faça um pedido HTTP POST à API Partner Procurement e envie o ENTITLEMENT_ID que está a aprovar:
POST v1/providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID:approve
Rejeite um direito de utilização
Para rejeitar uma concessão, faça um pedido HTTP POST à API Partner Procurement e use o método reject no seu pedido:
POST v1/providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID:reject
Para indicar um motivo para rejeitar a concessão no corpo do pedido, use o seguinte formato:
{ "reason": "..." }
Altere um plano de concessão
Consoante a forma como configura os seus planos de preços, os clientes podem alterar o respetivo plano. Se um cliente selecionar um novo plano de preços, recebe 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, essa duração é indicada em anos e meses. Se a oferta tiver uma data de conclusão especificada, em vez de uma duração, o campo que indica a duração está vazio.
Para aprovar a alteração do plano, faça o seguinte pedido HTTP POST à API Partner Procurement:
POST v1/providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID:approvePlanChange
O corpo do pedido tem de ter o plano que está a ser aprovado:
{
"pendingPlanName": PLAN_NAME
}
Após a aprovação da alteração, recebe outra mensagem do Pub/Sub
quando a alteração entrar em vigor. Na mensagem, o campo eventType é alterado para ENTITLEMENT_PLAN_CHANGED. Para verificar o estado de um plano, faça o seguinte pedido HTTP GETà API Partner Procurement.
GET v1/providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID
A resposta é semelhante à seguinte, com o campo state a indicar 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", ... }
Cancele um direito de utilização
Se um utilizador decidir cancelar a respetiva autorização, recebe uma notificação do Pub/Sub. Tal como acontece com a alteração de um plano, o cancelamento real pode entrar em vigor no final do ciclo de faturação atual.
A notificação tem o 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": "..." }, }
Elimine um direito de utilização
Se um utilizador fizer um pedido direto ao apoio técnico da Google ou sair da plataforma Google, as respetivas concessões são canceladas imediatamente, e as contas e concessões são eliminadas após um período de tolerância de 60 dias. Para proteger a privacidade do utilizador, tem de eliminar os respetivos dados dos seus servidores quando receber uma notificação.
Quando as concessões são canceladas e a conta é eliminada, 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
Segue-se uma lista dos eventTypes que a sua app pode receber em mensagens do Pub/Sub:
| eventType | Descrição |
|---|---|
| ACCOUNT_CREATION_REQUESTED | Descontinuado |
| ACCOUNT_ACTIVE | Indica que a conta do cliente foi criada. |
| ACCOUNT_DELETED | Indica que a conta do cliente foi eliminada dos Google Cloud sistemas. |
| ENTITLEMENT_CREATION_REQUESTED | Indica que um cliente selecionou um dos seus planos de preços. |
| ENTITLEMENT_OFFER_ACCEPTED | Indica que uma oferta foi aceite por um cliente. Inclui a hora de início agendada da oferta, se existir. Este evento é enviado para ofertas privadas e ofertas padrão (compras públicas). |
| ENTITLEMENT_ACTIVE | Indica que o plano escolhido por um cliente está agora ativo. |
| 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 que as alterações entraram em vigor. |
| ENTITLEMENT_PLAN_CHANGE_CANCELLED | Indica que a alteração do plano de um cliente foi cancelada, quer porque não foi aprovada, quer porque o cliente voltou ao plano antigo. |
| ENTITLEMENT_PENDING_CANCELLATION | Indica que um cliente cancelou o respetivo plano e que o cancelamento está pendente até ao final do ciclo de faturação. |
| ENTITLEMENT_CANCELLATION_REVERTED | Indica que o cancelamento pendente de um cliente foi revertido. Tenha em atenção que não é possível reverter os cancelamentos depois de serem definitivos. |
| ENTITLEMENT_CANCELLED | Indica que o plano de um cliente foi cancelado. |
| ENTITLEMENT_CANCELLING | Indica que o plano de um cliente está em processo de cancelamento. |
| ENTITLEMENT_RENEWED | Indica que a autorização de um cliente foi renovada por outro período. Não tem de fazer nada para concluir a renovação. |
| ENTITLEMENT_OFFER_ENDED | Indica que a oferta privada de um cliente terminou. Se a autorização do cliente tiver sido cancelada, é acionado um evento ENTITLEMENT_CANCELLED separado. Se a autorização do cliente ainda estiver ativa, o respetivo plano reverte para os preços sem desconto. |
| ENTITLEMENT_DELETED | Indica que as informações sobre o plano de um cliente foram eliminadas do Cloud Marketplace. |