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

  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, estarás creando 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 pueden reembolsarse con el motivo de que el desarrollador nunca las procesó y, por lo tanto, podrían no existir en los registros del desarrollador.

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 configurar el acceso de clientes a la API
• 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 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.

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 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.

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 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.

Nota: Para solicitar la recepción de compras de suscripciones anuladas, 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 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

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 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.