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

# Transações idempotentes e padrões de repetição no Economy v2

> Use IdempotencyId nas gravações de inventário do PlayFab Economy v2 para repetir com segurança após falhas de rede e evitar compras ou concessões duplicadas.

<Info>
  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).
</Info>

Falhas de rede, tempos limite e solicitações duplicadas são inevitáveis em jogos ao vivo. O Economy v2 fornece o **IdempotencyId** para evitar transações duplicadas. Esse recurso garante que uma operação seja processada apenas uma vez, mesmo que a mesma solicitação seja enviada várias vezes.

Para controle de simultaneidade otimista (garantir que uma gravação só seja bem-sucedida se o inventário não tiver sido alterado desde a sua última leitura), consulte [ETags e controle de simultaneidade](/pt-BR/services/playfab/economy-monetization/economy-v2/tutorials/etags-and-concurrency-control).

## Pré-requisitos

* Uma [conta de desenvolvedor do PlayFab](https://developer.playfab.com/en-us/sign-up).
* Um título criado no [Game Manager](https://developer.playfab.com/).
* Pelo menos um item de catálogo publicado e uma moeda virtual.

## Como funciona

Quando você inclui um `IdempotencyId` em uma solicitação de gravação de inventário, o PlayFab armazena esse ID por **14 dias**. Se outra solicitação chegar com o mesmo `IdempotencyId`, o PlayFab retornará o resultado da solicitação original sem processar a operação novamente.

## APIs compatíveis

O `IdempotencyId` é compatível com todas as APIs de gravação de inventário:

* [AddInventoryItems](https://learn.microsoft.com/en-us/rest/api/playfab/economy/inventory/add-inventory-items)
* [SubtractInventoryItems](https://learn.microsoft.com/en-us/rest/api/playfab/economy/inventory/subtract-inventory-items)
* [PurchaseInventoryItems](https://learn.microsoft.com/en-us/rest/api/playfab/economy/inventory/purchase-inventory-items)
* [TransferInventoryItems](https://learn.microsoft.com/en-us/rest/api/playfab/economy/inventory/transfer-inventory-items)
* [DeleteInventoryItems](https://learn.microsoft.com/en-us/rest/api/playfab/economy/inventory/delete-inventory-items)
* [UpdateInventoryItems](https://learn.microsoft.com/en-us/rest/api/playfab/economy/inventory/update-inventory-items)
* [ExecuteInventoryOperations](https://learn.microsoft.com/en-us/rest/api/playfab/economy/inventory/execute-inventory-operations)

## Exemplo: compra segura com repetição

Neste cenário, um jogador compra uma Espada Laser. O cliente gera um `IdempotencyId` exclusivo (por exemplo, um GUID) antes de enviar a solicitação:

```json theme={null}
{
    "Entity": {
        "Type": "title_player_account",
        "Id": "{{PlayerID}}"
    },
    "Item": {
        "Id": "{{LaserSwordID}}"
    },
    "Amount": 1,
    "PriceAmounts": [
        {
            "ItemId": "{{DiamondCurrencyID}}",
            "Amount": 5
        }
    ],
    "IdempotencyId": "b7e3f1a2-9c4d-4e8f-a1b2-3c4d5e6f7a8b"
}
```

Se o cliente não receber uma resposta (por exemplo, por tempo limite de rede), ele poderá repetir com segurança exatamente a mesma solicitação com o mesmo `IdempotencyId`. O PlayFab reconhece a duplicata e retorna o resultado original. O jogador é cobrado apenas uma vez.

## Práticas recomendadas

* **Gere um ID exclusivo por operação lógica**: use um GUID ou UUID. Não reutilize o mesmo ID para operações diferentes.
* **Gere o ID no lado do cliente antes da primeira tentativa**: essa prática garante que todas as repetições usem o mesmo ID.
* **Não altere o corpo da solicitação entre as repetições**: usar o mesmo `IdempotencyId` com um corpo de solicitação diferente causa um erro de conflito.
* **Os IDs expiram após 14 dias**: depois disso, o mesmo ID pode ser usado novamente para uma nova operação.

## As APIs de resgate são automaticamente idempotentes

As APIs de resgate de marketplace (`RedeemAppleAppStoreInventoryItems`, `RedeemGooglePlayInventoryItems`, `RedeemMicrosoftStoreInventoryItems`, `RedeemSteamInventoryItems`) não exigem um `IdempotencyId`. Elas são inerentemente idempotentes. Cada recibo ou token de marketplace só pode ser resgatado uma vez. Uma segunda chamada com o mesmo recibo retorna sucesso, mas não concede nada.

## Cenários comuns

| Cenário | Abordagem recomendada |
| - | - |
| Compra no lado do cliente (o jogador compra um item) | Gere um GUID antes da primeira tentativa e repita com o mesmo ID em caso de tempo limite. |
| Concessão de recompensa no lado do servidor (conclusão de missão) | Use um ID determinístico derivado da missão e do jogador (por exemplo, `questId-playerId`) para evitar concessões em dobro. |
| Resgate de marketplace | Nenhum `IdempotencyId` necessário: as APIs de resgate são automaticamente idempotentes. |

## Confira também

* [ETags e controle de simultaneidade](/pt-BR/services/playfab/economy-monetization/economy-v2/tutorials/etags-and-concurrency-control)
* [Visão geral do inventário](/pt-BR/services/playfab/economy-monetization/economy-v2/inventory#idempotency)
* [Prevenção de fraudes](/pt-BR/services/playfab/economy-monetization/economy-v2/fraud-prevention)
* [ExecuteInventoryOperations](https://learn.microsoft.com/en-us/rest/api/playfab/economy/inventory/execute-inventory-operations)


## Related topics

- [ETags e controle de simultaneidade no Economy v2](/pt-BR/services/playfab/economy-monetization/economy-v2/tutorials/etags-and-concurrency-control.md)
- [Tabelas de drop e saque aleatório no Economy v2](/pt-BR/services/playfab/economy-monetization/economy-v2/tutorials/drop-tables-and-randomized-loot.md)
- [Prevenção contra fraudes, resgate e validação de recibos](/pt-BR/services/playfab/economy-monetization/economy-v2/fraud-prevention/index.md)
- [Visão geral do Economy v2](/pt-BR/services/playfab/economy-monetization/economy-v2/overview.md)
- [Perguntas frequentes sobre o Economy versão 2 (V2)](/pt-BR/services/playfab/economy-monetization/economy-v2/faq.md)