> ## Documentation Index > Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt > Use this file to discover all available pages before exploring further. # Administración de productos consumibles desde su servicio > Describe cómo crear un sistema sólido que administre los consumibles en el servicio de su juego, incluida la administración de los reembolsos de artículos consumidos por parte de los usuarios. Para economías basadas en consumibles, use un servicio back-end de confianza para validar y administrar las transacciones. Las llamadas de servicio a servicio son más seguras y confiables que la entrega administrada por el cliente, que puede verse afectada por manipulaciones o pérdidas de red. Este artículo muestra cómo administrar consumibles y conciliar reembolsos para reducir el fraude y la pérdida de ingresos. Para administrar productos consumibles y gestionar reembolsos, llame a las siguientes API de Microsoft Store desde su servicio. Consulte las páginas de documentación para obtener detalles sobre cómo realizar las llamadas y analizar los resultados. | API de Microsoft Store | Función | | --------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [collections.mp.microsoft.com/v8.0/collections/consume](/reference/microsoft-store-apis/xstore-v8-consume) | Consumir o entregar un producto consumible que posee el usuario. | | [purchase.mp.microsoft.com/v8.0/b2b/orders/query](/reference/microsoft-store-apis/xstore-v8-clawbackv1) | Pedidos de compra: informa de las compras de consumibles realizadas por el usuario en los últimos 90 días. | | [purchase.mp.microsoft.com/v8.0/b2b/clawback/sastoken](/reference/microsoft-store-apis/xstore-v8-clawbackv2-sastoken) | Proporciona un token SAS que se usa para consultar la cola de mensajes del servicio de eventos de Clawback en busca de eventos de reembolso relacionados con sus productos. | **Limitación del sandbox:** al consumir productos consumibles administrados por el desarrollador en un sandbox de desarrollo, solo se admite la autenticación con tokens XSTS. La autenticación con User Store ID o Microsoft Entra ID no funciona para las llamadas de consumo de consumibles administrados por el desarrollador en entornos de sandbox. Planifique sus pruebas en consecuencia. Para obtener más información, consulte la [sección Requisitos previos de la API Consume](/reference/microsoft-store-apis/xstore-v8-consume#prerequisites). ## Uso de la biblioteca .NET Microsoft.StoreServices y del ejemplo Para ayudar a ilustrar los principios y flujos descritos en este artículo, revise el ejemplo de Microsoft.StoreServices, que proporciona: * Uso de la biblioteca Microsoft.StoreServices para administrar la autenticación y realizar las llamadas a los servicios de Microsoft Store. * Lógica de ejemplo para administrar productos consumibles, hacer el seguimiento de las solicitudes de consumo pendientes, conciliar compras reembolsadas, renovar User Store ID expirados y mucho más. * Una guía de configuración que incluye los pasos de este artículo sobre cómo configurar su Microsoft Entra ID para este método de autenticación. * [Microsoft.StoreServices (GitHub)](https://github.com/microsoft/Microsoft-Store-Services) * [Ejemplo de Microsoft.StoreServices (GitHub)](https://github.com/microsoft/Microsoft-Store-Services-Sample) ## Administración de consumibles ### Esquema recomendado de un servicio de administración de consumibles Use un único flujo de servidor para validar la propiedad, entregar el uso y conciliar los reembolsos. El esquema siguiente mantiene estas responsabilidades explícitas y seguras frente a reintentos. | Fase | Acción del servicio | | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | Recepción de solicitudes | Recibir las solicitudes del cliente para usar o comprar artículos con moneda consumible. | | Autenticación | Autenticarse en las API de servicio de Microsoft Store. | | Comprobaciones de saldo | Validar el saldo del usuario para los productos consumibles desde la Store. | | Entrega | Consumir o entregar la cantidad requerida del saldo del usuario. | | Seguridad frente a reintentos | Hacer el seguimiento de las solicitudes de consumo pendientes y reintentar de forma segura cuando se pierdan respuestas. | | Concesión de saldo | Otorgar el saldo del producto comprado a la cuenta del usuario. | | Registro de transacciones | Mantener una base de datos de seguimiento de las transacciones de consumo y concesión relacionadas con el usuario. | | Respuesta al cliente | Devolver los resultados de la transacción o los artículos otorgados al cliente del juego. | | Conciliación | Procesar las transacciones de consumibles reembolsadas y aplicar acciones correctivas. | ### Administración del saldo del usuario en su servicio frente a Microsoft Store Los productos consumibles administrados por la Store se pueden administrar completamente en el servicio de su juego consumiendo cualquier saldo distinto de cero de Microsoft Store. Como alternativa, el saldo de consumibles del usuario se puede administrar a través de Microsoft Store, consumiendo cantidad únicamente cuando se usa para artículos del juego. Los productos consumibles administrados por el desarrollador, sin embargo, requieren administración en un servicio de juego. Consulte [Elección del tipo de producto correcto](/publishing/xstore-commerce/xstore-choosing-product-type) para obtener más información sobre los consumibles administrados por el desarrollador frente a los administrados por Microsoft Store. El enfoque más común es hacer el seguimiento del saldo de moneda efectivo del usuario en su servicio. En este diseño, su servicio consulta los saldos de consumibles distintos de cero, los consume y abona la moneda del juego equivalente en la cuenta del usuario. Este flujo reduce las llamadas repetidas a las API de la Store después de la entrega, simplifica la gestión del saldo entre plataformas y proporciona a los equipos de soporte un sistema central para los ajustes de saldo. Configuración típica: configure cada nivel de moneda como un consumible administrado por la Store independiente que otorga una cantidad de `1` por compra y, a continuación, asigne cada producto a su valor en el juego. Ejemplo: un consumible de "500 monedas" aumenta la cantidad en la Store a `1`; después del consumo, la cantidad en la Store vuelve a `0` y su servicio abona 500 monedas. Los consumibles administrados por la Store pueden otorgar el valor completo directamente a la cantidad de la Store en la compra (por ejemplo, 500 por compra). En ese modelo, la Store hace el seguimiento del crecimiento del saldo y su servicio deduce cantidad cuando los usuarios gastan moneda en el juego. Sin embargo, colocar todos los niveles como SKU bajo un único identificador de producto limita características como los precios promocionales específicos de cada nivel y los tokens de canje 5x5. Consulte [Procedimientos recomendados para ofrecer moneda del juego](/publishing/xstore-commerce/xstore-consumables#best-practices-for-offering-in-game-currency). ### Uso de TrackingIds como sistema redundante para la validación de consumos Incluya un `TrackingId` en cada solicitud de consumo. Si se pierde una respuesta, reintente con el mismo `TrackingId`, usuario, `productId` y cantidad para confirmar si el consumo original se realizó correctamente. Esta solicitud de reintento evita concesiones dobles y, al mismo tiempo, permite reintentos seguros. El flujo siguiente muestra un patrón de consumo seguro frente a reintentos. El producto A (500 monedas del juego) es un consumible configurado para otorgar una cantidad de 1 en la Store. 1. El usuario compra el producto A y ahora tiene una cantidad de `1` para el producto al llamar al servicio de consulta. 2. El servicio del juego consulta el saldo de consumibles del usuario mediante la API de consulta de Microsoft Store y ve que el saldo del usuario es `1`. 3. El servicio del juego genera un TrackingID, crea una solicitud de consumo para consumir una unidad del producto y agrega la información de la solicitud a una lista de transacciones pendientes. 4. El servicio del juego envía la solicitud a la API de consumo de Microsoft Store. 5. El servicio del juego no obtiene respuesta de la API de consumo (pérdida de paquetes de red, interrupción del servicio, corte de energía, etc.). En este punto, el servicio no puede confirmar si la transacción se completó. Consultar el inventario por sí solo puede ser ambiguo si el usuario volvió a comprar durante la interrupción. Use la lista de transacciones pendientes y reintente con los mismos valores de la solicitud. 6. El servicio del juego determina cuándo debe reintentar la solicitud de consumo. 7. El servicio del juego vuelve a crear la solicitud de consumo con el mismo usuario, ProductId, TrackingId y cantidad. 8. El servicio del juego envía la solicitud a la API de consumo de Microsoft Store. 9. El servicio del juego recibe una respuesta que indica que la solicitud se realizó correctamente y que el nuevo saldo del usuario es "0". 10. El servicio del juego agrega 500 monedas al saldo de moneda del usuario del que se hace el seguimiento en el servidor. 11. El servicio del juego quita la solicitud de consumo de la lista de transacciones pendientes, ya que el artículo se consumió y verificó, y al usuario se le otorgó la moneda del juego correcta en el servicio. ### Comportamiento de la API de consumo de Microsoft Store al verificar solicitudes de transacción anteriores Si llega una solicitud con valores diferentes, la API la trata como una nueva solicitud de consumo. Si la API detecta un reintento con el mismo `TrackingId`, usuario, cantidad y `productId`, no consume una segunda vez. En su lugar, devuelve una respuesta correcta con el saldo restante actual. Debido a este comportamiento, reproducir una solicitud que agotó el tiempo de espera es seguro siempre que los valores de la solicitud sean idénticos. Si usa autenticación X-Token con la API de consumo, puede actualizar y obtener un nuevo X-Token siempre que el nuevo X-Token sea para el mismo usuario de XBOX que la solicitud anterior. ### Mitigación del fraude por devoluciones y reembolsos de consumibles con el servicio de eventos de Clawback Para ayudar a prevenir abusos y devoluciones o reembolsos fraudulentos de productos consumibles, su servicio debe usar el servicio de eventos de Clawback. Clawback permite a su servicio recibir eventos cuando un producto consumible se devuelve o se reembolsa. Su servicio debe quitar el valor agregado de la cuenta del usuario para ese consumible. Para tomar medidas sobre los eventos de Clawback, asegúrese de usar la opción `"includeOrderIds": TRUE` en su solicitud de consumo a [collections.mp.microsoft.com/v8.0/collections/consume](/reference/microsoft-store-apis/xstore-v8-consume). Su servicio debe almacenar los datos de las transacciones de consumo de las respuestas de la API mediante las variables siguientes: | Variable | Origen | Descripción | | ----------------- | ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Key / Unique ID` | \[OrderID]:\[LineItemID]:\[ProductID]:\[TrackingId] | Incluya `ProductID` porque los lotes pueden reutilizar el mismo `OrderID` y `LineItemID` en productos diferentes. Si su consumible otorga una cantidad mayor que `1`, incluya `TrackingId` para distinguir las operaciones de consumo individuales. | | `ProductId` | ProductId de la solicitud de consumo | Dado que el mismo orderID y orderLineItemID pueden compartirse entre distintos productos otorgados mediante la compra de un lote, también debe hacer el seguimiento del ProductID del artículo consumido. | | `UserId` | UserId que usa su sistema para identificar al usuario al que se otorga el valor del consumible | Los eventos de Clawback no proporcionan userIds, por lo que debe hacer el seguimiento del usuario que recibe el contenido dentro de su sistema para tomar medidas de conciliación. | | `OrderID` | orderTransactions -> orderId (al usar "includeOrderIds": true en la solicitud /consume) | Identificador del pedido de compra del usuario usado para satisfacer toda la solicitud de consumo o parte de ella. Ejemplo: identificador relacionado con la compra de todo el carro de la compra. | | `LineItemID` | orderTransactions -> orderLineItemId (al usar "includeOrderIds": true en la solicitud /consume) | Identificador que representa un producto único dentro del pedido de compra del usuario usado para satisfacer la solicitud de consumo. Ejemplo: identificador relacionado con un artículo único dentro del carro de la compra durante la compra. | | `Qty` | orderTransactions -> quantityConsumed (al usar "includeOrderIds": true en la solicitud /consume) | Cantidad de la solicitud satisfecha por este OrderId / LineItemId específico. Nota: debe ser 1 en la configuración estándar de consumibles, pero puede ser mayor que 1 si su consumible está configurado para otorgar una cantidad mayor que 1 en cada compra. | | `Status` | Estado actual de la transacción de consumo dentro de su sistema para su propio seguimiento | Resulta útil para poder marcar cuándo una transacción de consumo se concilia con un evento de Clawback. También es necesario para los contracargos y las reversiones de contracargos. Por ejemplo, si un artículo se revoca debido a la conciliación de un evento de contracargo, puede deshacer la acción más adelante si se produce una reversión del contracargo (ChargebackReversal). | Configure esta base de datos de seguimiento pronto, preferiblemente antes de la incorporación a la cola de Clawback. Los datos tempranos le proporcionan transacciones históricas para futuras conciliaciones y una línea base limpia para medir los efectos del procesamiento de Clawback. Para obtener más información, consulte [Administración de reembolsos y contracargos desde su servicio](/publishing/xstore-commerce/xstore-managing-refunds). ## Consulte también [Información general sobre comercio](/publishing/xstore-commerce/xstore-commerce-overview) [Ecosistemas basados en consumibles](/publishing/xstore-commerce/xstore-consumables) [Administración de reembolsos y contracargos desde su servicio](/publishing/xstore-commerce/xstore-managing-refunds) [API de servicio de Microsoft Store](/reference/microsoft-store-apis/index) [Biblioteca Microsoft.StoreServices (GitHub)](https://github.com/microsoft/Microsoft-Store-Services) [Ejemplo de Microsoft.StoreServices (GitHub)](https://github.com/microsoft/Microsoft-Store-Services-Sample) ## Related topics - [Ecosistemas basados en consumibles](/es/publishing/xstore-commerce/xstore-consumables.md) - [purchase.mp.microsoft.com/v8.0/b2b/orders/query](/es/reference/microsoft-store-apis/xstore-v8-clawbackv1.md) - [collections.mp.microsoft.com/v8.0/collections/consume](/es/reference/microsoft-store-apis/xstore-v8-consume.md) - [collections.mp.microsoft.com/v9.0/collections/publisherQuery](/es/reference/microsoft-store-apis/xstore-v9-query-for-products.md) - [API b2bLicensePreview de Collections v8 de Microsoft Store](/es/reference/microsoft-store-apis/xstore-v8-query-for-products.md)