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

# Canje con el marketplace de Microsoft Store

> Cree complementos de Microsoft Store, vincúlelos a agrupaciones de PlayFab y canjee compras de XBOX y Windows con RedeemMicrosoftStoreInventoryItems.

# Configuración de PlayFab y Microsoft Store para habilitar compras

En este tutorial se muestra cómo:

* Crear un producto que se pueda comprar en Microsoft Store
* Asignarlo a una agrupación de PlayFab
* Canjear los artículos comprados en el inventario de un jugador mediante la API [RedeemMicrosoftStoreInventoryItems](https://learn.microsoft.com/en-us/rest/api/playfab/economy/inventory/redeem-microsoft-store-inventory-items)

## Requisitos previos

1. Un título en el [Game Manager](https://developer.playfab.com/) de PlayFab.
2. Una [integración existente entre el título seleccionado y Microsoft Store](/services/playfab/economy-monetization/economy-v2/marketplace/marketplace-integrations/microsoft), que incluya:
   * El complemento **XBOX Network** instalado y configurado en Game Manager.
   * El **Product Group**, el **Dev Studio** y el **Business Partner ID** configurados en Partner Center.
3. Una cuenta de [Partner Center](https://partner.microsoft.com/) con acceso a su aplicación.
4. Una aplicación ya creada en Partner Center.
5. El jugador que llama a la API de canje debe estar autenticado en PlayFab con una identidad de XBOX Live (por ejemplo, mediante `LoginWithXbox`). Los jugadores autenticados con otros tipos de identidad (como CustomID o correo electrónico) no tienen el contexto de XBOX necesario para este flujo.

## Paso 1: Crear el complemento en Partner Center

Si no creó un complemento en Partner Center como parte de la [configuración de la integración con el marketplace](/services/playfab/economy-monetization/economy-v2/marketplace/marketplace-integrations/microsoft#step-1-create-your-add-on-in-partner-center), siga estos pasos:

1. Inicie sesión en [Partner Center](https://partner.microsoft.com/) y vaya a su aplicación.
2. En **Add-ons**, seleccione **Create a new add-on**.
3. Seleccione el tipo de producto adecuado:
   * **Developer-managed consumable** para artículos que se pueden volver a comprar (moneda, paquetes consumibles).
   * **Durable** para compras únicas (DLC, pases de temporada, desbloqueos cosméticos).
4. Complete la configuración del complemento (precios, descripciones, etc.) y envíelo.
5. Después de crear el complemento, anote el **Store ID**, la cadena alfanumérica (por ejemplo, `9NBLGGH42CFD`) que se muestra en Partner Center. Use este valor para la asignación de marketplace en PlayFab, **no** el Product ID definido por el desarrollador ni el nombre del complemento.

<Info>
  **Los consumibles administrados por la Tienda no se admiten.** Solo los consumibles administrados por el desarrollador (Developer-managed consumables) y los duraderos (Durables) funcionan con la API `RedeemMicrosoftStoreInventoryItems`. Es posible que Partner Center muestre una advertencia que sugiera que los consumibles administrados por el desarrollador no se admiten en XBOX. Esta advertencia no se aplica cuando se usa el flujo de canje de PlayFab. Para obtener más información, consulte [Elección del tipo de producto adecuado](https://learn.microsoft.com/en-us/gaming/gdk/docs/store/commerce/getting-started/xstore-choosing-the-right-product-type).
</Info>

6. Publique el complemento en el sandbox o entorno en el que tenga previsto realizar las pruebas.

## Paso 2: Crear una agrupación en Game Manager

<Note>
  Antes de crear una agrupación en **Game Manager**, cree y publique en su catálogo los artículos que desee agregar a la agrupación. Si necesita orientación sobre cómo crear un artículo, consulte [este paso](/services/playfab/economy-monetization/economy-v2/tutorials/craftingGame/crafting-game-game-manager#step-4---create-your-first-item).
</Note>

Para habilitar una asignación de marketplace entre **Game Manager** y **Microsoft Store**, debe crear una **agrupación** (Bundle) en Game Manager. Una agrupación puede contener varios artículos con distintas cantidades, y PlayFab los agrega al inventario del jugador una vez canjeados. Siga estos pasos:

1. Vaya a [Game Manager](https://developer.playfab.com/) y navegue hasta su **título**.
2. En el menú de navegación izquierdo, elija **Engage** > **Economy**.
3. Seleccione la pestaña **Bundles**.
4. Seleccione **New bundle**.
5. Agregue a la **agrupación** la información que desee, como artículos y precios.
6. Desplácese hasta el final de la página y seleccione **Save and publish** si quiere que los jugadores puedan canjearla de inmediato. Seleccione **Save as draft** si quiere publicarla en una fecha posterior.

### Agregar artículos a la agrupación

Una agrupación por sí sola no concede ningún artículo a un jugador. Primero debe vincularle artículos. Una vez canjeada, la agrupación concede esos artículos al jugador específico.

Para agregar artículos a su agrupación:

1. Vaya a la sección **Items** en modo de edición.
2. Seleccione **Add**. Aparece una ventana que muestra todos los artículos de su catálogo.
3. Busque el artículo deseado y seleccione **Add** junto a él.
4. Seleccione el botón **Add** en la parte inferior.

## Paso 3: Habilitar la asignación de marketplace

Para garantizar que, cuando un jugador compre un producto en Microsoft Store, este se asocie y asigne correctamente en Game Manager, debe configurar la **Marketplace Mapping** en su agrupación.

1. Navegue hasta su agrupación en modo de edición.
2. Desplácese hacia abajo hasta la sección **Marketplace Mapping**.
3. En la lista desplegable **Marketplace**, seleccione **MicrosoftStore** (distingue mayúsculas de minúsculas; debe ser exactamente `MicrosoftStore`).
4. Para el **Marketplace ID**, use el **Store ID** exacto de Partner Center (por ejemplo, `9NBLGGH42CFD`). **No** use el Product ID definido por el desarrollador.
5. Seleccione el **+** en el lado derecho de esa fila y elija **Save** para guardar los cambios.

<Info>
  La agrupación debe estar **publicada** (no dejarse como borrador) para que se pueda asociar durante el canje. La API de canje no detecta artículos de catálogo sin publicar.
</Info>

Para obtener más información sobre los identificadores alternativos, consulte [Identificadores alternativos](/services/playfab/economy-monetization/economy-v2/catalog/content-types-tags-and-properties#alternate-ids).

## Paso 4: Autenticar al jugador

Antes de realizar una llamada de canje, debe asegurarse de que el jugador esté correctamente autenticado. Para escenarios de XBOX y Microsoft Store, use [LoginWithXbox](https://learn.microsoft.com/en-us/rest/api/playfab/client/authentication/login-with-xbox) para autenticar al jugador con PlayFab.

Tras una llamada correcta a `LoginWithXbox`, PlayFab devuelve un `EntityToken` que debe usar en los encabezados de la llamada de canje con la clave `X-EntityToken`.

## Paso 5: Adquirir el token de XBOX

La API `RedeemMicrosoftStoreInventoryItems` requiere un token de XBOX válido en el parámetro `XboxToken`. Este token es independiente del `EntityToken` que se usa para la autenticación.

* Si usa la **API de C del GDK**, use:

  ```cpp theme={null}
  XUserGetTokenAndSignatureAsync  // with method "POST", URL "https://playfabapi.com/", and empty body ""
  ```

Los tres parámetros (método, dirección URL y cuerpo) deben proporcionarse exactamente como se muestra. Un token obtenido de forma incorrecta hace que la consulta a la API de colecciones de Microsoft Store falle de forma silenciosa y no devuelva ningún artículo.

## Paso 6: Realizar una compra

El jugador debe comprar el complemento en Microsoft Store antes de que usted pueda canjearlo a través de PlayFab. Esta compra se puede realizar mediante la interfaz de XBOX o de la Tienda de Windows.

<Note>
  Si está realizando pruebas en un entorno de sandbox, asegúrese de que la cuenta del jugador y el complemento estén publicados en el mismo sandbox. El jugador debe tener una **compra sin canjear** en su cuenta para que la API de canje encuentre artículos que canjear.
</Note>

## Paso 7: Canjear la compra

Con el jugador autenticado, el token de XBOX adquirido y una compra completada, ya puede llamar a la API [RedeemMicrosoftStoreInventoryItems](https://learn.microsoft.com/en-us/rest/api/playfab/economy/inventory/redeem-microsoft-store-inventory-items).

Incluya el `EntityToken` como encabezado `X-EntityToken` y proporcione el token de XBOX en el cuerpo de la solicitud:

```json theme={null}
{
    "XboxToken": "{Your Xbox token from GetTokenAndSignatureAsync}"
}
```

### Funcionamiento del canje

Cuando se realiza la llamada a `RedeemMicrosoftStoreInventoryItems`, PlayFab usa el token de XBOX para consultar en la API de colecciones de Microsoft Store las compras sin canjear asociadas a la cuenta del jugador. A continuación, asocia esas compras con los **Store IDs** configurados en las asignaciones de marketplace de sus agrupaciones de PlayFab y concede los artículos correspondientes.

Una respuesta correcta incluye un código de estado `200` junto con la respuesta [RedeemMicrosoftStoreInventoryItemsResponse](https://learn.microsoft.com/en-us/rest/api/playfab/economy/inventory/redeem-microsoft-store-inventory-items), que contiene:

* **Succeeded**: una lista de los artículos canjeados correctamente.
* **Failed**: una lista de los artículos cuyo canje falló.
* **TransactionIds**: identificadores de cada transacción de canje.

Cada acción de canje desencadena un evento correspondiente en el historial de transacciones del jugador, que se puede recuperar en la pestaña **Transaction History (V2)** de la página de información general del jugador en [Game Manager](https://developer.playfab.com/).

Junto con el registro en el historial de transacciones del jugador, también se desencadena y registra un evento de **PlayStream** `items_redeemed`. Puede acceder a estos registros de su título en la página **Data**, en la sección **Analyze** de la barra de navegación izquierda de [Game Manager](https://developer.playfab.com/).

### Cumplimiento de consumibles administrados por el desarrollador

Si el producto canjeado es un **consumible administrado por el desarrollador**, PlayFab lo notifica automáticamente como **cumplido** (consumido) ante Microsoft Store en su nombre después de un canje correcto. El paso de cumplimiento es necesario para que el jugador pueda volver a comprar el mismo consumible. Si el consumible no aparece como cumplido después de un canje correcto, reintente la llamada a `RedeemMicrosoftStoreInventoryItems`. Si el problema persiste, escale al equipo de PlayFab a través de su canal de soporte. Los duraderos no requieren cumplimiento porque son compras únicas. Para obtener más información, consulte [Administración de consumibles y reembolsos](https://learn.microsoft.com/en-us/gaming/gdk/docs/store/commerce/service-to-service/xstore-managing-consumables-and-refunds).

## Solución de problemas

Si la llamada de canje devuelve `200` pero las tres matrices (`Succeeded`, `Failed`, `TransactionIds`) están vacías, la API de colecciones de Microsoft Store no encuentra ningún artículo coincidente. Este resultado suele indicar un problema de configuración. Consulte la [sección de solución de problemas](/services/playfab/economy-monetization/economy-v2/marketplace/marketplace-integrations/microsoft#troubleshooting) de la guía de integración de Microsoft Store para ver una lista completa de causas comunes y sus resoluciones.

Si la API devuelve un error HTTP (como 400), compruebe la respuesta de error en busca de códigos como `InvalidCatalogItemConfiguration`, `InvalidXboxLiveToken` o `AccountNotLinked`.

## Consulte también

* [Integración con el marketplace de Microsoft Store](/services/playfab/economy-monetization/economy-v2/marketplace/marketplace-integrations/microsoft)
* [Referencia de la API RedeemMicrosoftStoreInventoryItems](https://learn.microsoft.com/en-us/rest/api/playfab/economy/inventory/redeem-microsoft-store-inventory-items)
* [Inicio rápido de prevención de fraude](/services/playfab/economy-monetization/economy-v2/fraud-prevention/quickstart)
* [Configuración del complemento XBOX Live](/services/playfab/identity/player-identity/platform-specific-authentication/xbox-live-add-on)
* [Cómo integrar correctamente una aplicación de Apple en Game Manager](/services/playfab/economy-monetization/economy-v2/marketplace/marketplace-integrations/apple)
* [Cómo integrar correctamente una aplicación de Google en Game Manager](/services/playfab/economy-monetization/economy-v2/marketplace/marketplace-integrations/google)


## Related topics

- [Canje de marketplace: Información general](/es/services/playfab/economy-monetization/economy-v2/marketplace/marketplace-redemption/overview.md)
- [Canje con el marketplace de Steam](/es/services/playfab/economy-monetization/economy-v2/marketplace/marketplace-redemption/steam.md)
- [Canje con el marketplace de Google](/es/services/playfab/economy-monetization/economy-v2/marketplace/marketplace-redemption/google.md)
- [Canjear compras desde la aplicación del App Store de Apple](/es/services/playfab/economy-monetization/economy-v2/marketplace/marketplace-redemption/apple.md)
- [Guía de inicio rápido de prevención de fraude](/es/services/playfab/economy-monetization/economy-v2/fraud-prevention/quickstart.md)