Voided Purchases API

A Voided Purchases API do Google Play oferece uma lista de pedidos no aplicativo associados a compras anuladas pelo usuário. É possível usar as informações dessa lista para implementar um sistema de revogação que impeça o usuário de acessar produtos a partir desses pedidos no aplicativo.

Essa API se aplica a compras. Para assinaturas, veja Notificações do desenvolvedor em tempo real.

Para anular uma compra, o usuário pode:

  • solicitar um reembolso pelo pedido;
  • cancelar o pedido;
  • optar pelo estorno do pedido.

Ao usar essa API, você ajuda a criar uma experiência mais equilibrada e justa para todos os usuários do seu app, principalmente se ele for um app de jogo.

Conseguir acesso

Para trabalhar com a Voided Purchases API, é preciso ter permissão para ver informações financeiras. Conceda a autorização usando um cliente OAuth ou uma conta de serviço. Se você estiver usando uma conta de serviço, ative a permissão "Ver relatórios financeiros" nessa conta.

Para saber mais sobre como ter acesso autorizado a Google Play Developer APIs, consulte os seguintes guias:

Visualizar compras anuladas

Use o método GET para solicitar uma lista de compras anuladas associadas a pedidos no aplicativo. Na solicitação, inclua o nome do pacote totalmente qualificado do app, por exemplo, com.google.android.apps.maps, além do token de autorização que você recebeu ao conseguir acesso à API.

GET https://www.googleapis.com/androidpublisher/v3/applications/
your_package_name/purchases/voidedpurchases?access_token=your_auth_token

Também é possível incluir os seguintes parâmetros na sua solicitação, sendo que todos eles são opcionais:

startTime

A hora em milésimos de segundo, desde a época do Unix, da compra anulada mais antiga de um produto no aplicativo que você queira ver na resposta. Por padrão, startTime é definido como 30 dias atrás.

A API só exibe as compras anuladas que ocorreram nos últimos 30 dias. Compras anuladas anteriores a esse período não são incluídas na resposta, independentemente do valor definido para startTime.

endTime

A hora em milésimos de segundo, desde a época do Unix, da compra anulada mais recente de um produto no aplicativo que você queira ver na resposta. Por padrão, endTime é definido como a hora atual.

maxResults
O número máximo de compras anuladas exibidas em cada resposta. Por padrão, esse valor é 1.000. O valor máximo desse parâmetro também é 1.000.
token
Token de continuação de uma resposta anterior, que permite ver mais resultados.

A resposta é uma string JSON que contém uma lista de compras anuladas relacionadas a pedidos no aplicativo. Se o número de resultados for maior que o número especificado no parâmetro maxResults da solicitação, a resposta incluirá um valor nextPageToken, que pode ser passado para uma solicitação subsequente para exibir mais resultados. O primeiro resultado na lista mostra a compra anulada mais antiga de um produto no aplicativo.

{
  "tokenPagination": {
    "nextPageToken": "next_page_token"
  },
  "voidedPurchases": [
    {
      "kind": "androidpublisher#voidedPurchase",
      "purchaseToken": "some_purchase_token",
      "purchaseTimeMillis": "1468825200000",
      "voidedTimeMillis": "1469430000000"
    },
    {
      "kind": "androidpublisher#voidedPurchase",
      "purchaseToken": "some_other_purchase_token",
      "purchaseTimeMillis": "1468825100000",
      "voidedTimeMillis": "1470034800000"
    },
  ]
}

Cotas

A Voided Purchases API define as seguintes cotas por pacote:

  • 500 consultas por dia. O dia começa e termina à meia-noite do Horário do Pacífico.
  • 30 consultas durante qualquer período de 30 segundos.

Diretrizes para solicitações iniciais

Durante sua solicitação de API inicial, é possível buscar todos os dados disponíveis do seu app. Embora seja improvável, esse processo pode esgotar sua cota diária. Para receber dados de compras anuladas de uma forma mais segura e consistente, siga estas práticas recomendadas:

  • Use o valor padrão para o parâmetro maxResults. Assim, se você usar toda a cota de consultas de um dia, poderá recuperar os detalhes de 100.000 compras anuladas.
  • Se uma resposta incluir um valor para nextPageToken, atribua esse valor ao parâmetro token durante sua próxima solicitação.
  • Não faça muitas tentativas com valores de parâmetros opcionais de solicitação, uma vez que as solicitações inválidas também são contabilizadas em cada cota.

Práticas recomendadas

Ao determinar como usar essa API no seu app, lembre-se de que há muitos motivos para se anular uma compra e que não há uma solução única que funcione para todos os casos. Pense nos usuários ao desenvolver suas políticas e estratégias de revogação. Para isso, utilize estas práticas recomendadas:

  • Use essa API como um dos vários elementos de uma estratégia abrangente para lidar com comportamentos inadequados. A revogação de acesso a produtos no aplicativo costuma ser mais eficiente em combinação com um app que tenha preços razoáveis para compras no aplicativo, com um design de app que desmotive comportamentos inadequados, com uma base de usuários sólida que tenha uma cultura que rejeite esses comportamentos e com canais de suporte ao usuário responsivos e eficientes.
  • Administre sua política de revogação de maneira uniforme para garantir igualdade a todos os usuários.
  • Crie uma política dividida em etapas para lidar com comportamentos inadequados. Por exemplo, comece com avisos no aplicativo para as primeiras ofensas, depois intensifique suas respostas à medida que o comportamento inadequado do usuário continuar. Como último recurso, é possível impedir toda a interação do usuário com seu app.
  • Ao introduzir uma política de revogação e sempre que atualizá-la, use os canais de comunicação do seu app para informar os usuários sobre as alterações. Permita que os usuários tenham tempo para entender claramente essas alterações antes que elas entrem em vigor no seu app.
  • Seja transparente com os usuários e informe-os sempre que você tomar uma medida, por exemplo, revogar o acesso deles a um produto no aplicativo. O ideal é que os usuários possam contestar suas decisões, e que essas contestações sejam tratadas de forma justa.
  • Monitore formulários de feedback e fóruns da comunidade para entender o que leva os usuários a se comportarem de maneiras inadequadas e como eles desenvolvem esses comportamentos. Aja com base nesses insights como primeira linha de defesa.