API de Voided Purchases

La API de Google Play Voided Purchases proporciona una lista de pedidos asociados con las compras que anuló un usuario. Puedes usar la información de esta lista a fin de implementar un sistema de revocación para evitar que un usuario acceda a los productos de esos pedidos.

Esta API se aplica a suscripciones de apps y pedidos únicos realizados directo desde apps.

Una compra se puede anular de las siguientes maneras:

  • Si el usuario solicita un reembolso por el pedido
  • Si el usuario cancela el pedido
  • Si se realiza la devolución del cargo del pedido
  • Si el desarrollador cancela o reembolsa el pedido

  • Si Google cancela o reembolsa el pedido

Si usas esta API, estarás creando una experiencia más equilibrada y justa para todos los usuarios de tu app, especialmente si se trata de un juego.

Cómo obtener acceso

Si quieres trabajar con la API de Voided Purchases, debes tener permiso para ver información financiera. La autorización se brinda mediante el cliente OAuth o una cuenta de servicio. Si usas esta última opción, habilita el permiso "Ver informes financieros" en la cuenta correspondiente.

Si deseas obtener más información sobre cómo obtener acceso autorizado a las APIs de Google Play Developer, consulta las siguientes guías:

Cómo ver las compras anuladas

Usa el método GET para solicitar una lista de compras anuladas. En tu solicitud, incluye el nombre del paquete de tu app que cumple con los requisitos (como com.google.android.apps.maps) y el token de autorización que recibiste cuando obtuviste acceso a la API.

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

También puedes incluir los siguientes parámetros opcionales en la solicitud:

startTime

Indica el tiempo (en milisegundos desde la época Unix) de la compra anulada más antigua que quieras ver en la respuesta. De forma predeterminada, el parámetro startTime está configurado en los últimos 30 días.

La API solo muestra compras anuladas que se hayan realizado durante los últimos 30 días. Las compras que se hayan anulado antes no se incluyen en la respuesta, independientemente del valor que proporciones para startTime.

endTime

Indica el tiempo (en milisegundos desde la época Unix) de la compra anulada más reciente que quieras ver en la respuesta. De forma predeterminada, el parámetro endTime está configurado en la hora actual.

maxResults
Indica la cantidad máxima de compras anuladas que aparecen en cada respuesta. De forma predeterminada, este valor es 1,000. Ten en cuenta que ese número también es el valor máximo para este parámetro.
token
Indica un token de continuación de una respuesta anterior que permite ver más resultados.
type

Indica el tipo de compras anuladas que aparecen en cada respuesta. Si se establece en 0, solo se mostrarán las compras anuladas que se realizaron directo desde la aplicación. Si se establece en 1, se mostrarán las compras directas desde la aplicación y las de suscripciones que se anularon. El valor predeterminado es 0.

includeQuantityBasedPartialRefund

Indica si se incluirán compras anuladas de reembolsos parciales basados en la cantidad, los cuales se aplican únicamente a las compras de cantidades múltiples. Si es true, es posible que se devuelvan compras anuladas adicionales con voidedQuantity, que indica la cantidad de un reembolso parcial basado en la cantidad. El valor predeterminado es false.

La respuesta es una cadena JSON que contiene una lista de compras anuladas. Si la cantidad de resultados es mayor que el número especificado en el parámetro de solicitud maxResults, la respuesta incluirá un valor nextPageToken, que puedes pasar a una solicitud posterior para ver más resultados. El primer resultado de la lista muestra la compra anulada más antigua.

{
  "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"
    },
  ]
}

Cuotas

La API de Voided Purchases establece las siguientes cuotas por paquete:

  • 6,000 consultas por día (el día comienza y termina a la medianoche, hora del Pacífico)
  • 30 consultas en cualquier período de 30 segundos

Lineamientos para las solicitudes iniciales

En la solicitud inicial a la API, es posible que quieras recuperar todos los datos disponibles de tu app. Aunque es poco probable, este proceso podría agotar la cuota diaria. Para obtener datos de compras anuladas de una forma más segura y consistente, sigue estas prácticas recomendadas:

  • Usa el valor predeterminado para el parámetro maxResults. De esta forma, si usas toda la cuota de consultas disponible para un día, podrás recuperar los detalles de 6,000,000 compras anuladas.
  • Si una respuesta incluye un valor para nextPageToken, asigna este valor al parámetro token durante la próxima solicitud.

Prácticas recomendadas

Cuando uses esta API en tu app, recuerda que existen varios motivos para anular una compra y que no hay una única solución que funcione en todos los casos. Cuando diseñes tus políticas y estrategias de revocación, ten en cuenta a los usuarios. Para ello, implementa estas recomendaciones:

  • Usa esta API como elemento de estrategia integral para abordar el comportamiento no deseado. Por lo general, revocar el acceso a los productos integrados en la aplicación es más efectivo cuando esta acción se combina con una app que tiene precios razonables para compras directas, un diseño que desalienta el comportamiento no deseado, una base de usuarios sólida cuya cultura rechaza dicho comportamiento y canales de asistencia receptivos y eficientes para los usuarios.
  • Administra tu política de revocación de manera uniforme para garantizar equidad para todos los usuarios.
  • A la hora de abordar el comportamiento no deseado, considera crear una política por etapas. Por ejemplo, comienza con advertencias integradas en la aplicación para las primeras infracciones y, a medida que el comportamiento no deseado continúe, intensifica las medidas que tomes. Como último recurso, prohíbele al usuario interactuar con la app.
  • Cuando agregues una política de revocación, y cada vez que la actualices, usa los canales de comunicación de la app para informar a los usuarios sobre los cambios. Asegúrate de que tengan tiempo para comprender claramente estos cambios antes de que se apliquen.
  • Sé transparente con los usuarios y avísales siempre que tomes medidas rigurosas, como revocar su acceso a un producto integrado en la aplicación. Permite que reclamen ante tus decisiones y asegúrate de que las disputas se resuelvan de manera justa.
  • Supervisa los formularios de comentarios y foros de la comunidad para comprender qué impulsa a los usuarios a comportarse de formas no deseadas y cómo llevan a cabo dicho comportamiento. Actúa en función de estos datos como primera línea de defensa.