API de Voided Purchases

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

Esta API se aplica a suscripciones de apps y pedidos únicos desde las 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

  Nota: En la API de Voided Purchases, solo se mostrarán los pedidos revocados. Si un desarrollador reembolsa una compra sin configurar la opción de revocación, la API no mostrará el pedido.

• Si Google cancela o reembolsa el pedido

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

Nota: A diferencia de otras fuentes de datos relacionadas con pedidos, la API de Voided Purchases incluye las compras devueltas por procesadores de pagos. Por lo tanto, es posible que veas incoherencias entre la información que proporciona esta API y la que proviene de otras fuentes de datos relacionadas con pedidos.

Nota: La API de Voided Purchases muestra las compras anuladas solo cuando deben revocarse. Los desarrolladores pueden usar esta API como un indicador para saber cuándo deben tomar medidas adicionales. Sin embargo, algunas compras podrían reembolsarse debido a que el desarrollador nunca las procesó y, por lo tanto, podrían no existir en sus registros.

Cómo obtener acceso

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

Para 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 configurar Clientes de acceso a APIs
• Cómo agregar usuarios a la cuenta de desarrollador y administrar permisos

Cómo ver las compras anuladas

Usa el método GET para solicitar una lista de compras anuladas. En tu solicitud, incluye el nombre de paquete completamente calificado de tu app (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 el tiempo Unix) de la compra anulada más antigua que quieras ver en la respuesta. De forma predeterminada, el parámetro startTime está configurado en 30 días atrás.

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.

Nota: Las compras anuladas incluidas en la respuesta se filtran de acuerdo al momento en el que la API detecta como anulado un registro determinado, no por el valor de voidedTimeMillis que se muestra en la respuesta.

endTime

Indica la marca de tiempo (en milisegundos desde el tiempo 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.

Nota: Las compras anuladas incluidas en la respuesta se filtran de acuerdo al momento en el que la API detecta como anulado un registro determinado, no por el valor de voidedTimeMillis que se muestra en la respuesta.

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 el valor máximo de este parámetro también es 1,000.

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 desde la app. Si se establece en 1, se mostrarán las compras anuladas de suscripciones y las que se realizaron desde apps. El valor predeterminado es 0.

Nota: Para solicitar recibir compras anuladas de suscripciones, debes usar orderId en la respuesta, ya que identifica de forma exclusiva las suscripciones y compras únicas. De lo contrario, recibirás múltiples pedidos de suscripción con el mismo PurchaseToken.

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.

Nota: Cuando se reembolsa la cantidad total restante de una compra, la compra anulada correspondiente no tendrá voidedQuantity, que funciona como un indicador de que se reembolsó la compra por completo. Por ejemplo, si una compra de cantidad 10 se reembolsa 3 veces con cantidades 2, 3 y 5, habrá 3 compras anuladas. Las primeras dos compras anuladas tendrán un valor de voidedQuantity de 2 y 3, mientras que la tercera compra anulada no tendrá un valor de voidedQuantity.

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 coherente, 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 de 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

Nota: Además de usar esta API, los desarrolladores deben realizar la integración con las notificaciones para desarrolladores en tiempo real (RTDN). Con las RTDN, se recibirán notificaciones de Google cada vez que haya un cambio en el derecho de un usuario dentro de la app, lo que incluye cuando un usuario anule una compra.

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 uno de muchos elementos de una estrategia integral para abordar comportamientos no deseados. Por lo general, revocar el acceso a los productos integrados en la aplicación es más eficaz en una app que tiene precios razonables para las compras directas desde ella, un diseño que desalienta el comportamiento no deseado, una base de usuarios sólida cuya cultura rechaza este tipo de comportamiento y canales de asistencia al usuario receptivos y eficientes.
• 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 en la app para las primeras infracciones y, a medida que el comportamiento no deseado continúe, intensifica las medidas que tomes. Como último recurso, impide que el usuario interactúe 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, como la decisión de revocar su acceso a un producto integrado en la aplicación. Es conveniente que los usuarios puedan iniciar reclamos ante tus decisiones, y asegúrate de que estos 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.