API Voided Purchases

A API Voided Purchases do Google Play oferece uma lista de pedidos associados a compras anuladas por um usuário. Use as informações desta lista para implementar um sistema de revogação que impede que o usuário acesse os produtos desses pedidos.

Essa API se aplica a pedidos únicos no app e assinaturas de apps.

Uma compra pode ser anulada das seguintes maneiras:

• O usuário solicita um reembolso pelo pedido.
• O usuário cancela o pedido.
• Um pedido estornado.

• O desenvolvedor cancela ou reembolsa um pedido.

  Observação: apenas pedidos revogados serão exibidos na API Voided Purchases. Se um desenvolvedor reembolsar uma compra sem definir a opção de revogação, o pedido não será retornado pela API.

• O Google cancela ou reembolsa um pedido.

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

Observação: ao contrário de outras fontes de dados relacionadas a pedidos, a API Voided Purchases inclui compras estornadas por processadores de pagamentos. Portanto, é possível encontrar inconsistências entre as informações dessa API e as informações de outras fontes de dados relacionadas a pedidos.

Observação: a API Voided Purchases só retorna compras anuladas quando elas precisam ser revogadas. Os desenvolvedores podem usar essa API como uma indicação de quando realizar ações adicionais.

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:

• Configuração de clientes de acesso à API
• Adicionar usuários à conta de desenvolvedor e gerenciar permissões

Visualizar compras anuladas

Use o método GET para solicitar uma lista de compras anuladas. Na solicitação, inclua o nome do pacote totalmente qualificado do app, como com.google.android.apps.maps, e o 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 o início da Era Unix (link em inglês), da compra anulada mais antiga que você quer 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.

Observação: as compras anuladas na resposta são filtradas com base na hora em que determinado registro é visto como anulado pela API, não pelo valor de voidedTimeMillis retornado na resposta.

endTime

A hora, em milésimos de segundo, desde o início da Era Unix (link em inglês), da compra anulada mais recente que você quer ver na resposta. Por padrão, endTime é definido como a hora atual.

Observação: as compras anuladas na resposta são filtradas com base na hora em que determinado registro é entendido como anulado pela API, não pelo valor de voidedTimeMillis retornado na resposta.

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

Um token de continuação de uma resposta anterior, que permite ver mais resultados.

type

O tipo de compras anuladas que aparecem em cada resposta. Se definido como 0, apenas serão retornadas compras no app. Se ela for definida como 1, as compras anuladas no app e as assinaturas anuladas serão retornadas. O valor padrão é 0.

Observação: antes de solicitar o recebimento de compras de assinatura anuladas, é necessário usar o orderId na resposta, que identifica exclusivamente compras e assinaturas únicas. Caso contrário, você receberá vários pedidos de assinatura com o mesmo PurchaseToken.

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

{
  "tokenPagination": {
    "nextPageToken": "next_page_token"
  },
  "voidedPurchases": [
    {
      "kind": "androidpublisher#voidedPurchase",
      "purchaseToken": "some_purchase_token",
      "purchaseTimeMillis": "1468825200000",
      "voidedTimeMillis": "1469430000000",
      "orderId": "some_order_id",
      "voidedSource": "0",
      "voidedReason": "4"
    },
    {
      "kind": "androidpublisher#voidedPurchase",
      "purchaseToken": "some_other_purchase_token",
      "purchaseTimeMillis": "1468825100000",
      "voidedTimeMillis": "1470034800000",
      "orderId": "some_other_order_id",
      "voidedSource": "2",
      "voidedReason": "5"
    },
  ]
}

Cotas

A API Voided Purchases define as seguintes cotas por pacote:

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

Diretrizes para solicitações iniciais

Durante a 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 6.000.000 compras anuladas.
• Se uma resposta incluir um valor para nextPageToken, atribua esse valor ao parâmetro token durante sua próxima solicitação.

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.