> ## 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. # APIs de Inventory do PlayFab > Visão geral das APIs de Inventory do PlayFab Economy v2 para gerenciar inventários de jogadores, conceder itens, acompanhar saldos de moeda e ler pilhas. # Inventory O Economy v2 agora está em disponibilidade geral. Para obter suporte e enviar comentários, acesse o [Fórum do PlayFab](https://community.playfab.com). As APIs de Inventory do PlayFab oferecem a capacidade de gerenciar e armazenar os inventários dos seus jogadores e os dados de inventário. Recursos como Pilhas e Coleções oferecem flexibilidade na estruturação dos inventários dos jogadores e permitem que esse sistema funcione com qualquer jogo ## Gerenciando inventários de jogadores As APIs a seguir são usadas para ajudar a adicionar, remover, atualizar e excluir itens no inventário de um jogador. O limite atual é de 10000 itens, e você receberá um erro se ultrapassar esse valor. ### Obtendo o inventário de um jogador #### Game Manager 1. No [Game Manager](/pt-BR/services/playfab/live-service-management/gamemanager), navegue até `Players` 2. Selecione o jogador que você deseja visualizar ou crie um `New Player` e, em seguida, vá para `Inventory (V2)` #### API Você pode usar a `GetInventoryItems` para obter o inventário do jogador. Os jogadores estão limitados a acessar e manipular apenas o próprio inventário. Entidades de título podem passar um parâmetro `Entity` para indicar qual inventário de jogador desejam acessar. Um exemplo de solicitação `GetInventoryItems`: ```json theme={null} { "Entity": { "Type": "title_player_account", "Id": "ABCD12345678" }, "CollectionId": "main_character", "Count": 15, "ContinuationToken": "abc=" } ``` *** Mais informações sobre como usar `CollectionId` e ter vários inventários por jogador podem ser encontradas [aqui](/pt-BR/services/playfab/economy-monetization/economy-v2/inventory/collections). ##### Tokens de continuação O campo `ContinuationToken` retornado por uma resposta de pesquisa pode ser passado para uma solicitação de inventário para paginar por várias contagens de resultados. ### Adicionar itens de inventário A API `AddInventoryItems` é usada para adicionar itens diretamente ao inventário de um jogador específico. Ela recebe os parâmetros `EntityId`, `ItemId` e `Amount` e adiciona o item fornecido ao inventário de um jogador Um exemplo de solicitação `AddInventoryItems`: ```json theme={null} { "Entity": { "Type": "title_player_account", "Id": "ABCD12345678" }, "Item": { "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b", }, "Amount": 10, } ``` ### Subtrair itens de inventário A API `SubtractInventoryItems` é usada para reduzir diretamente um item no inventário de um jogador em uma quantidade específica. Ela recebe os parâmetros `EntityId`, `ItemId` e `Amount` e remove a quantidade fornecida do item. Essa API gerará um erro se você tentar remover mais do que a quantidade disponível no momento. Um exemplo de solicitação `SubtractInventoryItems`: ```json theme={null} { "Entity": { "Type": "title_player_account", "Id": "ABCD12345678" }, "Item": { "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b", }, "Amount": 10, } ``` ### Atualizar itens de inventário A API `UpdateInventoryItems` é usada para definir diretamente um item no inventário de um jogador com uma quantidade específica. Ela recebe os parâmetros `EntityId`, `ItemId` e `Amount` e define a quantidade fornecida do item. Essa API pode ser usada tanto para aumentar quanto para reduzir a quantidade de um item, além de adicionar itens ao inventário de um jogador caso o item não exista. Um exemplo de solicitação `UpdateInventoryItems`: ```json theme={null} { "Entity": { "Type": "title_player_account", "Id": "ABCD12345678" }, "Item": { "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b", "Amount": 10 } } ``` ### Excluir itens de inventário A API `DeleteInventoryItems` é usada para excluir uma pilha inteira de itens do inventário de um jogador. Um exemplo de solicitação `DeleteInventoryItems`: ```json theme={null} { "Entity": { "Type": "title_player_account", "Id": "ABCD12345678" }, "Item": { "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b", }, } ``` ### Comprar itens de inventário A API `PurchaseInventoryItems` usa o preço do item definido no catálogo, deduz o custo do inventário do jogador e o troca pela quantidade desejada do item. Você deve especificar o `Item` que deseja comprar e a `Amount` do item que deseja comprar. Há alguns parâmetros principais específicos da API `PurchaseInventoryItems`: * `PriceAmounts` é uma lista de itens e quantidades que são preços **por item** do item. Esses preços devem corresponder a um valor configurado no Catálogo ou na Loja especificada. * `StoreId` é um parâmetro opcional da Loja da qual o item será comprado. Mais informações sobre Lojas podem ser encontradas [aqui](/pt-BR/services/playfab/economy-monetization/economy-v2/catalog/stores) Um exemplo de solicitação `PurchaseInventoryItems`: ```json theme={null} { "Entity": { "Type": "title_player_account", "Id": "ABCD12345678" }, "Item": { "Id": "LaserSword", }, "Amount": 10, "PriceAmounts": [ { "ItemId": "0b440353-bdbc-48d8-8873-f0988c1f9d8b", "Amount": 5 } ], } ``` A API `PurchaseInventoryItems` é usada para compras com moedas virtuais. Para compras com dinheiro real por meio de marketplaces externos (Apple App Store, Google Play, Steam, Microsoft Store), use as APIs de resgate correspondentes (como `RedeemAppleAppStoreInventoryItems`, `RedeemGooglePlayInventoryItems`, `RedeemSteamInventoryItems` ou `RedeemMicrosoftStoreInventoryItems`). Essas APIs validam o recibo de compra com o marketplace e concedem os itens ao inventário do jogador. Para obter mais informações, consulte [Resgate no marketplace](/pt-BR/services/playfab/economy-monetization/economy-v2/marketplace/marketplace-redemption/overview). #### Pacotes Quando um pacote é comprado (via `PurchaseInventoryItems` ou uma API de resgate de marketplace), o pacote é **desempacotado automaticamente** no inventário do jogador. Os itens individuais referenciados em `ItemReferences` do pacote são concedidos diretamente; o pacote em si não aparece como um item no inventário do jogador. Por exemplo, comprar um pacote contendo 2x Laser Sword e 2x Laser Gun concede esses itens individualmente. O custo em moeda virtual definido em `PriceOptions` do pacote é deduzido do inventário do jogador como parte da transação. Pacotes vinculados a produtos de marketplace via `AlternateIds` seguem o mesmo comportamento de desempacotamento quando resgatados. Para obter mais informações sobre como criar pacotes, consulte [Pacotes](/pt-BR/services/playfab/economy-monetization/economy-v2/catalog/bundles). ### Transferir itens de inventário A API `TransferInventoryItems` pode ser usada de três maneiras diferentes. 1. Para transferir itens entre jogadores (por exemplo, o Jogador A dá três maçãs ao Jogador B) 2. Para transferir itens entre as coleções de inventário de um único jogador (por exemplo, o Jogador A move sua espada longa do inventário do personagem Mago para o inventário do personagem Guerreiro) 3. Para transferir itens dentro do inventário de um único jogador para criar, remover e manipular Pilhas de itens (por exemplo, o Jogador A divide sua Pilha de 10 moedas de ouro em duas pilhas de três e sete moedas de ouro) Os parâmetros `GivingItem` e `Amount` são usados para representar a quantidade e o item que está sendo transferido. O `ReceivingItem` representa o destino do item na conta do jogador que recebe. Os parâmetros `GivingItem` e `ReceivingItem` são objetos `InventoryItemReference` que contêm o `Id` do item e o `StackId`. Tanto `GivingItem` quanto `ReceivingItem` podem estar vazios para lidar com transferências em que uma entidade não está transferindo itens. A menos que especificado, todos os itens são definidos como `default` para o `StackId` quando adicionados/transferidos para o inventário de um jogador. #### 1. Transferência entre jogadores Para uma transferência entre jogadores, `GivingEntity` e `ReceivingEntity` devem ser especificados, representando o jogador que transfere os itens e o jogador que recebe os itens, respectivamente. Um exemplo de solicitação `TransferInventoryItems` entre jogadores: ```json theme={null} { "GivingEntity": { "Type": "title_player_account", "Id": "DEFG98765432" }, "ReceivingEntity": { "Type": "title_player_account", "Id": "ABCD12345678" }, "GivingItem": { "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b", }, "ReceivingItem": { "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b", }, "Amount": 1 } ``` #### 2. Transferência entre coleções Para uma transferência entre coleções, `GivingCollectionId` e `ReceivingCollectionId` devem ser definidos, representando a ID da coleção de inventário de origem e de destino da transferência, respectivamente. Um exemplo de solicitação `TransferInventoryItems` entre coleções: ```json theme={null} { "GivingEntity": { "Type": "title_player_account", "Id": "ABCD12345678" }, "ReceivingEntity": { "Type": "title_player_account", "Id": "ABCD12345678" }, "GivingCollectionId": "default", "ReceivingCollectionId": "main_character", "GivingItem": { "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b", }, "ReceivingItem": { "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b", }, "Amount": 10 } ``` A solicitação acima transfere 10 unidades do item da coleção `default` do jogador para a coleção `main_character`. Mais informações sobre coleções podem ser encontradas [aqui](/pt-BR/services/playfab/economy-monetization/economy-v2/inventory/collections). #### 3. Transferência entre pilhas Para uma transferência entre pilhas, o `StackId` de `GivingItem` e de `ReceivingItem` da solicitação deve ser especificado. Um exemplo de solicitação `TransferInventoryItems` entre pilhas: ```json theme={null} { "GivingEntity": { "Type": "title_player_account", "Id": "ABCD12345678" }, "ReceivingEntity": { "Type": "title_player_account", "Id": "ABCD12345678" }, "GivingItem": { "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b", "StackId": "default", }, "ReceivingItem": { "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b", "StackId": "MyNewStack", }, "Amount": 10 } ``` A solicitação acima transfere 10 unidades do item da pilha `default` do jogador para a pilha `MyNewStack`. Mais informações sobre pilhas podem ser encontradas [aqui](/pt-BR/services/playfab/economy-monetization/economy-v2/inventory/stacks). ### API ExecuteInventoryOperations Você pode usar a API `ExecuteInventoryOperations` para agrupar várias operações de inventário em uma única solicitação. As operações ocorrem na ordem especificada na solicitação e, se uma operação não puder ser executada, todo o conjunto de operações será cancelado. A `ExecuteInventoryOperations` recebe um parâmetro `Operation` que é uma lista de operações. Pode haver no máximo **50 operações** na lista `Operation`, mas os tipos de operação podem se repetir (por exemplo, 10 operações Add são válidas). Também há um limite de **300 itens** que podem ser modificados/adicionados em uma única solicitação. Por exemplo, adicionar um pacote com 50 itens conta como 50 itens modificados. Os tipos de operação válidos são: * Add * Subtract * Update * Purchase * Transfer\* * Delete \*Somente transferências em uma única coleção são compatíveis dentro de um lote. Um exemplo de solicitação `ExecuteInventoryOperations`: ```json theme={null} { "Entity": { "Type": "title_player_account", "Id": "ABCD12345678" }, "Operations": [ { "Update": { "Item" { "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b", "Amount": 10 } } }, { "Subtract": { "Item" { "Id": "0b440353-bdbc-48d8-8873-f0988c1f9d8b", }, "Amount": 5 } } ] } ``` ### Idempotência Ao chamar as APIs de Inventory, você pode passar uma `IdempotencyId` que pode ser usada em situações em que chamadas repetitivas estão sendo feitas para fins de fallback ou redundância. Se várias chamadas de API tiverem a mesma `IdempotencyId`, o sistema garantirá que apenas uma dessas solicitações seja processada. Por exemplo, a seguinte solicitação de API `PurchaseItem` pode ser chamada várias vezes, mas como todas as solicitações têm a mesma `IdempotencyId`, apenas uma única compra será feita para o inventário desse jogador. ```json theme={null} { "Entity": { "Type": "title_player_account", "Id": "ABCD12345678" }, "Item": { "Id": "LaserSword", }, "Amount": 10, "PriceAmounts": [ { "ItemId": "0b440353-bdbc-48d8-8873-f0988c1f9d8b", "Amount": 5 } ], "IdempotencyId": "ABC123" } ``` As `IdempotencyId` são armazenadas e aplicadas por 14 dias; depois disso, a ID pode ser usada novamente. Usar a mesma `IdempotencyId` para tipos de solicitação diferentes causará um conflito e gerará um erro. ### ETags e controle de simultaneidade As APIs de gravação de inventário oferecem suporte ao controle de simultaneidade otimista por meio de ETags e cabeçalhos HTTP. Para obter todos os detalhes, consulte [ETags de inventário](/pt-BR/services/playfab/economy-monetization/economy-v2/inventory/etags). ### Propriedades de exibição As Propriedades de exibição são propriedades de item personalizadas que podem ser adicionadas a itens e pilhas de itens nos inventários dos jogadores. Essas propriedades podem ser adicionadas pelas operações `AddInventoryItems`, `PurchaseInventoryItems`, `TransferInventoryItems` e `UpdateInventoryItems`. #### Adicionando propriedades a novas pilhas/itens Para as APIs `AddInventoryItems`, `PurchaseInventoryItems` e `TransferInventoryItems`, as Propriedades de exibição **só** podem ser adicionadas quando uma nova pilha é criada. Para definir Propriedades de exibição para novos itens, o parâmetro `NewStackValues` deve ser definido na solicitação de API. Um exemplo de solicitação `AddInventoryItems` com `NewStackValues`: ```json theme={null} { "Entity": { "Type": "title_player_account", "Id": "ABCD12345678" }, "Item": { "Id": "20a645ce-a3bf-4fcb-8e67-36aa7bf0331d", "StackId": "NewStack" }, "Amount": 15, "NewStackValues": { "DisplayProperties": { "DifficultyRating":5, "IsMagic": true, "Rarity": "Legendary" } } } ``` Mais informações sobre pilhas podem ser encontradas [aqui](/pt-BR/services/playfab/economy-monetization/economy-v2/inventory/stacks). #### Atualizando propriedades de pilhas/itens existentes Para atualizar as Propriedades de exibição em itens existentes, a API `UpdateInventoryItems` pode ser usada para modificar as propriedades diretamente. Um exemplo de solicitação `UpdateInventoryItems` com `DisplayProperties`: ```json theme={null} { "Entity": { "Type": "title_player_account", "Id": "ABCD12345678" }, "Item": { "Id": "20a645ce-a3bf-4fcb-8e67-36aa7bf0331d", "StackId": "NewStack", "Amount": 15, "DisplayProperties": { "DifficultyRating":5, "IsMagic": false, "Rarity": "Epic" } } } ``` ## Related topics - [PFInventoryInventoryItem](/pt-BR/services/playfab/api-references/c/pfinventorytypes/structs/pfinventoryinventoryitem.md) - [PFInventoryRedeemSteamInventoryItemsAsync](/pt-BR/services/playfab/api-references/c/pfinventory/functions/pfinventoryredeemsteaminventoryitemsasync.md) - [PFInventoryInventoryItemReference](/pt-BR/services/playfab/api-references/c/pfinventorytypes/structs/pfinventoryinventoryitemreference.md) - [PFInventorySubtractInventoryItemsOperation](/pt-BR/services/playfab/api-references/c/pfinventorytypes/structs/pfinventorysubtractinventoryitemsoperation.md) - [PFInventoryTransferInventoryItemsAsync](/pt-BR/services/playfab/api-references/c/pfinventory/functions/pfinventorytransferinventoryitemsasync.md)