Referencia del AIDL de Facturación Google Play

Advertencia: El AIDL ya no es compatible y se quitará en una versión futura. Para implementar las funciones de facturación de Google Play, usa la Biblioteca de Facturación Google Play.

En esta documentación, se proporciona información de referencia técnica para usar el AIDL de la Facturación Google Play.

Códigos de respuesta del servidor

En la siguiente tabla, se muestran todos los códigos de respuesta del servidor que se envían de Google Play a tu aplicación. Google Play envía el código de respuesta de manera síncrona como un valor entero mapeado a la clave RESPONSE_CODE en el Bundle de respuesta. Tu aplicación debe gestionar todos estos códigos de respuesta.

El 15 de junio de 2019 se dieron de baja las suscripciones por temporada. Google Play ahora muestra BILLING_RESPONSE_RESULT_DEVELOPER_ERROR para todas las compras nuevas de ese tipo.

Tabla 1. Resumen de códigos de respuesta para llamadas de AIDL de la Facturación Google Play

Código de respuesta	Valor	Descripción
`BILLING_RESPONSE_RESULT_OK`	0	Listo
`BILLING_RESPONSE_RESULT_USER_CANCELED`	1	El usuario presionó Atrás o Cancelar en un diálogo.
`BILLING_RESPONSE_RESULT_SERVICE_UNAVAILABLE`	2	No hay conexión de red.
`BILLING_RESPONSE_RESULT_BILLING_UNAVAILABLE`	3	La versión de AIDL de la Facturación Google Play no es compatible con el tipo solicitado.
`BILLING_RESPONSE_RESULT_ITEM_UNAVAILABLE`	4	El producto solicitado no está disponible para la compra.
`BILLING_RESPONSE_RESULT_DEVELOPER_ERROR`	5	Se proporcionaron argumentos no válidos a la API. Este error también puede indicar que no se firmó correctamente la aplicación, que no se la configuró de manera adecuada para la facturación o que no tiene los permisos necesarios en su manifiesto.
`BILLING_RESPONSE_RESULT_ERROR`	6	Error grave durante la acción de la API.
`BILLING_RESPONSE_RESULT_ITEM_ALREADY_OWNED`	7	No se concretó la compra porque ya se adquirió el artículo.
`BILLING_RESPONSE_RESULT_ITEM_NOT_OWNED`	8	No se concretó el consumo porque no se adquirió el artículo.

Referencia de AIDL de Facturación Google Play: Compatibilidad

En esta sección, se describen los métodos para obtener información sobre los tipos de compatibilidad de facturación disponibles para tu app.

Método isBillingSupported()

Este método indica lo siguiente:

Si la versión del AIDL es compatible con tu app.
Si Google Play admite la facturación en el país del usuario.
Si el sistema de facturación de Google Play está habilitado en el paquete de tu app.
Si tu app puede usar el tipo de artículo en cuestión con fines de facturación.

Tabla 2: Parámetros isBillingSupported()

Clave	Tipo	Descripción
`apiVersion`	`int`	El número de versión del AIDL de la Facturación Google Play que usa tu app.
`packageName`	`String`	Es el nombre del paquete de la app que invoca este método.
`type`	`String`	El valor debe ser `inapp` para un producto integrado en la aplicación o `subs` para suscripciones.

Este método está disponible en la versión 3 del AIDL de la Facturación Google Play y en versiones posteriores.

Método isBillingSupportedExtraParams()

Este método es idéntico a isBillingSupported(), excepto que puedes pasar un cuarto argumento (un objeto Bundle) que puede contener parámetros adicionales.

Tabla 3. Parámetros isBillingSupportedExtraParams()

Clave	Tipo	Descripción
`apiVersion`	`int`	El número de versión del AIDL de la Facturación Google Play que usa tu app.
`packageName`	`String`	Es el nombre del paquete de la app que invoca este método.
`type`	`String`	El valor debe ser `inapp` para un producto integrado en la aplicación o `subs` para suscripciones.
`extraParams`	`Bundle`	Un conjunto de parámetros adicionales que brinda más información sobre el tipo de sistema de facturación de Google Play que admite la app Este paquete puede contener una clave opcional llamada `vr` que posee un valor booleano. Este indicador especifica si esta app admite un flujo de compras de realidad virtual (RV).

Este método está disponible en la versión 7 del AIDL de la Facturación Google Play y en versiones posteriores.

Referencia del AIDL de Facturación Google Play: Detalles

El AIDL de la Facturación Google Play se define en el archivo IInAppBillingService.aidl, que se incluye en la versión 3 del ejemplo de aplicación.

Método getSkuDetails()

Usa el método getSkuDetails() con el fin de obtener detalles del producto para una lista correspondiente de ID de productos.

Tabla 4. Parámetros GetSkuDetails()

Clave	Tipo	Descripción
`apiVersion`	`int`	El número de versión del AIDL de la Facturación Google Play que usa tu app.
`packageName`	`String`	El nombre del paquete de la app que invoca este método.
`type`	`String`	Es el tipo de artículo integrado en la app ("inapp" para compras únicas y "subs" para suscripciones).
`skusBundle`	`Bundle`	Es el paquete que contiene una `StringArrayList` de SKU con la clave `ITEM_ID_LIST`.

Si el método getSkuDetails() tiene éxito, Google Play envía un Bundle como respuesta. Los resultados de la consulta se almacenan en el Bundle dentro de una ArrayList de String mapeada a la clave DETAILS_LIST. Cada string de la lista contiene los detalles del producto correspondiente a un único producto en formato JSON. Los campos de la string JSON con los detalles del producto están resumidos en la tabla 5.

Tabla 5. Descripción de los campos JSON con los detalles del producto que se muestran a partir de una solicitud getSkuDetails()

Clave	Descripción
`productId`	Es el ID del producto.
`type`	El valor debe ser `inapp` para un producto integrado en la aplicación o `subs` para suscripciones.
`price`	Es el precio del artículo con formato, incluido su símbolo de moneda. El precio no incluye impuestos.
`price_amount_micros`	Es el precio en microunidades, donde 1,000,000 microunidades equivalen a una unidad de moneda. Por ejemplo, si `price` es `"€7.99"`, entonces `price_amount_micros` debe expresarse `"7990000"`. Este valor representa el precio localizado y redondeado para una moneda en particular.
`price_currency_code`	Es el código de moneda ISO 4217 de `price`. Por ejemplo, si `price` está especificado en libras esterlinas, entonces `price_currency_code` es `"GBP"`.
`title`	Título del producto.
`description`	Descripción del producto.
`subscriptionPeriod`	Período de suscripción especificado en formato ISO 8601. Por ejemplo, `P1W` equivale a una semana, `P1M` a un mes, `P3M` a tres meses, `P6M` a seis meses y `P1Y` a un año. Nota: Solo se muestra para suscripciones.
`freeTrialPeriod`	Período de prueba configurado en Google Play Console, especificado en formato ISO 8601. Por ejemplo, `P7D` equivale a siete días. Para obtener más información acerca de los criterios de elegibilidad, consulta Suscripciones integradas en la aplicación. Nota: Solo se muestra para las suscripciones que tienen configurado un período de prueba.
`introductoryPrice`	Es el precio de lanzamiento de una suscripción con formato, incluido su símbolo de moneda, como `€3.99`. No incluye impuestos. Nota: Solo se muestra para las suscripciones que tienen configurado un período de lanzamiento.
`introductoryPriceAmountMicros`	Es el precio de lanzamiento en microunidades. La moneda es la misma que `price_currency_code`. Nota: Solo se muestra para las suscripciones que tienen configurado un período de lanzamiento.
`introductoryPricePeriod`	El período de facturación del precio de lanzamiento, que se especifica en formato ISO 8601. Nota: Solo se muestra para las suscripciones que tienen configurado un período de lanzamiento.
`introductoryPriceCycles`	La cantidad de períodos de facturación de la suscripción en los que el usuario recibirá un precio de lanzamiento (por ejemplo, 3). Nota: Solo se muestra para las suscripciones que tienen configurado un período de lanzamiento.

Método getBuyIntent()

Este método muestra un valor entero del código de respuesta mapeado a la clave RESPONSE_CODE y un objeto PendingIntent a fin de iniciar el flujo de compra para la suscripción integrada en la aplicación mapeado a la clave BUY_INTENT, como se describe en Cómo implementar la Facturación Google Play. Cuando recibe el PendingIntent, Google Play envía un Intent de respuesta con los datos de esa orden de compra. En la tabla 6, se resumen los datos que se muestran en el Intent de respuesta.

Nota: En lugar de utilizar este método, te recomendamos usar getBuyIntentExtraParams(), que incluye funciones adicionales.

Tabla 6. Datos de respuesta de una solicitud de compra de Google Play

Clave	Descripción
`RESPONSE_CODE`	El valor es `0` si la compra se realiza correctamente. De lo contrario, se produce un error.
`INAPP_PURCHASE_DATA`	Es una string en formato JSON que contiene detalles de la orden de compra. Consulta la tabla 7 para obtener una descripción de los campos JSON.
`INAPP_DATA_SIGNATURE`	String que contiene la firma de los datos de compra firmados con la clave privada del desarrollador. La firma de datos usa el esquema RSASSA-PKCS1-v1_5.

La tabla 7 describe los campos JSON que se muestran en los datos de respuesta para una orden de compra.

Tabla 7. Descripciones de los campos JSON de INAPP_PURCHASE_DATA

Campo	Descripción
`autoRenewing`	Indica si la suscripción se renueva automáticamente. Si el valor es `true`, la suscripción se encuentra activa y se renovará automáticamente en la siguiente fecha de facturación. Si el valor es `false`, indica que el usuario canceló la suscripción. El usuario tiene acceso al contenido de la suscripción hasta la siguiente fecha de facturación y perderá el acceso en esa fecha, a menos que vuelva a habilitar la renovación automática (o renueve la suscripción manualmente, como se describe en Renovación manual). Si ofreces un período de gracia, este valor continuará siendo `true` para todas las suscripciones mientras no venza ese período. La siguiente fecha de facturación se extiende dinámicamente cada día hasta el final del período de gracia o hasta que el usuario fije su forma de pago.
`orderId`	Es el identificador de pedido único de la transacción. Este identificador corresponde al ID de pedido de Google Payments.
`packageName`	Es el paquete de la aplicación desde el que se originó la compra.
`productId`	Es el identificador de producto del artículo. Todos los artículos poseen un ID de producto que debes especificar en la lista de productos de la aplicación de Google Play Console.
`purchaseTime`	Es la hora (expresada en milisegundos) en que se compró el producto a partir de la época ("epoch"; es decir, desde el 1 de enero de 1970).
`purchaseState`	Es el estado de compra del pedido. Siempre muestra `0` (compras).
`developerPayload`	Es la string especificada por el desarrollador que contiene información adicional sobre un pedido. Puedes especificar un valor para este campo cuando haces una solicitud `getBuyIntent`.
`purchaseToken`	Es el token que identifica una compra de manera única para un par específico de artículo y usuario.

Método consumePurchase()

Compra correspondiente al token específico. Como resultado, se quitará este artículo de todas las respuestas posteriores de getPurchases() y se podrá volver a comprar los artículos del mismo SKU.

Tabla 8. Parámetros consumePurchase()

Clave	Tipo	Descripción
`apiVersion`	`int`	El número de versión del AIDL de la Facturación Google Play que usa tu app.
`packageName`	`String`	El nombre del paquete de la app que invoca este método.
`purchaseToken`	`String`	Es el token en el archivo JSON de información que identifica la compra que se consumirá.

Este método muestra un RESULT_OK(0) de consumo exitoso y los códigos de respuesta correspondientes en caso de fallas.

Método getBuyIntentToReplaceSkus()

Este método se usa para actualizar una suscripción o para pasarla a una versión anterior. El método es similar a getBuyIntent(), con la excepción de que toma una lista con un SKU ya comprado que debe reemplazarse por el SKU que se comprará. Cuando el usuario completa la compra, Google Play intercambia el SKU anterior y acredita al usuario el valor no usado del tiempo de su suscripción de manera prorrateada. Google Play adjudica este crédito a la nueva suscripción y no comienza a emitir facturación para el usuario por la nueva suscripción hasta que se haya consumido el crédito.

Nota: En lugar de utilizar este método, te recomendamos usar getBuyIntentExtraParams(), que incluye funciones adicionales.

Se agregó este método con la versión 5 del AIDL de la Facturación Google Play. Para verificar que se informe el método, envía una solicitud isBillingSupported del AIDL.

Nota: Solo puedes usar este método para compras de suscripciones. Si el parámetro type que se pasa no es "subs", el método mostrará BILLING_RESPONSE_RESULT_DEVELOPER_ERROR. Además, es posible que los SKU transmitidos no incluyan SKU para suscripciones temporales.

Este método muestra un valor entero del código de respuesta mapeado a la clave RESPONSE_CODE y un objeto PendingIntent a fin de iniciar el flujo de compra para la suscripción integrada en la aplicación mapeado a la clave BUY_INTENT. Cuando recibe el PendingIntent, Google Play envía un Intent de respuesta con los datos de esa orden de compra. Los datos que se muestran en el Intent de respuesta se resumen en la tabla 9.

Tabla 9. Datos de respuesta de una solicitud de compra con la versión 5 del AIDL de la Facturación Google Play

Clave	Descripción
`RESPONSE_CODE`	El valor es `0` si la compra se realiza correctamente. Si esta falla, contiene un código de error.
`INAPP_PURCHASE_DATA`	Una string en formato JSON que contiene detalles de la orden de compra. Consulta la tabla 6 para obtener una descripción de los campos JSON.
`INAPP_DATA_SIGNATURE`	Es una string que contiene la firma de los datos de compra que el desarrollador firmó con su clave privada. La firma de datos usa el esquema RSASSA-PKCS1-v1_5.

Método getBuyIntentExtraParams()

Este método inicia una solicitud de compra. Es una variante del método getBuyIntent() que incluye un parámetro extraParams adicional. Este parámetro es un Bundle de claves y valores opcionales que afectan la operación del método, como se muestra en la tabla 10.

Tabla 10. Parámetros getBuyIntentExtraParams() adicionales

Clave	Tipo	Descripción
`skusToReplace`	`List<String>`	Es una lista opcional con exactamente un SKU que corresponde al que el usuario tiene al momento de pasar a otro con más beneficios o más básico. Transmite este campo si la compra actualiza una suscripción existente o cambia a un plan inferior. El SKU especificado se reemplaza con el SKU que está comprando el usuario. Google Play reemplaza el SKU especificado al comienzo del siguiente ciclo de facturación.
`replaceSkusProration`	`boolean`	Especifica si el usuario debe recibir una compensación por el período de suscripción sin usar de los SKU en los que realizan una actualización o pasan a una versión anterior. Si configuras este campo como verdadero, Google Play intercambia los SKU anteriores y acredita al usuario el valor no usado del tiempo de su suscripción de manera prorrateada. Google Play adjudica este crédito a la nueva suscripción y no comienza a emitir facturación para el usuario por la nueva suscripción hasta que se haya consumido el crédito. Si configuras este campo como falso, el usuario no recibirá ningún crédito por el tiempo de suscripción no usado y la fecha de recurrencia no se cambiará. El valor predeterminado es verdadero. Se ignora si no pasas un `skusToReplace`.
`accountId`	`String`	Es una string ofuscada opcional que está asociada de forma exclusiva con la cuenta del usuario en tu app. Si pasas este valor, Google Play podrá usarlo para detectar actividad irregular, como muchos dispositivos que realizan compras desde la misma cuenta en un período de tiempo corto. Este campo es similar a `developerId`, ya que representa a un solo usuario. Sin embargo, ten en cuenta que si tienes varias apps, el mismo usuario puede tener diferentes `accountId` para cada app, mientras que `developerId` debería identificar a un solo usuario de manera única en todas tus apps. No uses el ID de desarrollador de Google Play Console ni el ID de Google para este campo. Además, este campo no debe incluir el ID del usuario en Cleartext. Te recomendamos usar un hash unidireccional para generar una string a partir del ID del usuario y que almacenes la string con hash en este campo.
`developerId`	`String`	Es una string oculta opcional que se asocia de manera única con la cuenta del usuario en todas tus apps. Este campo es similar a `accountId`, ya que representa a un solo usuario. Sin embargo, debería ser el mismo en todas tus apps para el mismo usuario, mientras que `accountId` puede ser único por app, incluso para el mismo usuario. No uses el ID de desarrollador de Google Play Console ni el ID de Google para este campo. Además, este campo no debe incluir el ID del usuario en Cleartext. Te recomendamos usar un hash unidireccional para generar una string a partir del ID del usuario y que almacenes la string con hash en este campo.
`vr`	`boolean`	Especifica si el intent proporcionado representa el comienzo de un flujo de compra de realidad virtual (RV). Nota: Para que este parámetro adicional tenga un efecto en tu app, debes usar la versión 7 del AIDL de la Facturación Google Play o una API más reciente.

Este método está disponible en la versión 6 del AIDL de la Facturación Google Play y en versiones posteriores.

Método getPurchases()

Este método muestra los productos actuales no consumidos que posee el usuario, incluidos los artículos comprados y los adquiridos mediante el canje de un código promocional. En la tabla 11, se indican los datos de respuesta que se muestran en el Bundle.

Tabla 11. Datos de respuesta de una solicitud getPurchases

Clave	Descripción
`RESPONSE_CODE`	Si la solicitud se realiza correctamente, el valor es `0`. De lo contrario, se produce un error.
`INAPP_PURCHASE_ITEM_LIST`	Es un objeto `StringArrayList` que contiene la lista de productIds de las compras de esta app.
`INAPP_PURCHASE_DATA_LIST`	Es un objeto `StringArrayList` que contiene los detalles de las compras de esta app. Consulta la tabla 13 para ver la lista de información detallada que se almacena en cada elemento de la lista.
`INAPP_DATA_SIGNATURE_LIST`	Es un objeto `StringArrayList` que contiene las firmas de las compras de esta app.
`INAPP_CONTINUATION_TOKEN`	Es una string que contiene un token de continuación para obtener el siguiente conjunto de productos integrados en la aplicación que posee el usuario. Solo lo establece el servicio de Google Play si la cantidad de productos que posee el usuario es muy grande. Cuando la respuesta contiene un token de continuación, debes hacer otra llamada a `getPurchases` y pasar el token de continuación que recibiste. La llamada de `getPurchases` subsiguiente muestra más compras y, posiblemente, otro token de continuación.

Método getPurchaseHistory()

Este método muestra la compra más reciente que hizo el usuario para cada SKU, incluso si esa compra venció, se canceló o se consumió. En la tabla 12, se indican los datos de respuesta que se muestran en el Bundle:

Tabla 12. Datos de respuesta de una solicitud getPurchaseHistory

Clave	Descripción
`RESPONSE_CODE`	Si se realiza la solicitud correctamente, el valor es `0`. De lo contrario, se produce un error.
`INAPP_PURCHASE_ITEM_LIST`	Es un objeto `StringArrayList` que contiene la lista de productIds de las compras de esta app.
`INAPP_PURCHASE_DATA_LIST`	Es un objeto `StringArrayList` que contiene los detalles de las compras recientes de esta app. Consulta la tabla 6 para ver la lista de información detallada que se almacena en cada `INAPP_PURCHASE_DATA` de la lista.
`INAPP_DATA_SIGNATURE_LIST`	Es un objeto `StringArrayList` que contiene las firmas de las compras de esta app.
`INAPP_CONTINUATION_TOKEN`	Es una string que contiene un token de continuación para obtener el siguiente conjunto de productos integrados en la aplicación que posee el usuario. Solo lo establece el servicio de Google Play si la cantidad de productos que posee el usuario es muy grande. Cuando la respuesta contiene un token de continuación, debes hacer otra llamada a `getPurchases` y pasar el token de continuación que recibiste. La llamada de `getPurchases` subsiguiente muestra más compras y, posiblemente, otro token de continuación.

Tabla 13: Descripciones de los campos JSON del historial de compras que muestra getPurchaseHistory()

Campo	Descripción
`productId`	Es el identificador de producto del artículo. Todos los artículos poseen un ID de producto que debes especificar en la lista de productos de la aplicación de Google Play Console.
`purchaseTime`	Es la hora (expresada en milisegundos) en que se compró el producto a partir de la época ("epoch"; es decir, desde el 1 de enero de 1970).
`developerPayload`	Es la string especificada por el desarrollador que contiene información adicional sobre un pedido. Puedes especificar un valor para este campo cuando haces una solicitud `getBuyIntent`.
`purchaseToken`	Es el token que identifica una compra de manera única para un par específico de artículo y usuario.

Nota: El método getPurchaseHistory() tiene una sobrecarga superior a getPurchases(), ya que requiere una llamada al servidor de Google Play. Debes usar getPurchases() si realmente no necesitas acceder al historial de compras del usuario.

Este método está disponible en la versión 6 del AIDL de la Facturación Google Play y en versiones posteriores.