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

# Economy v2의 멱등성 트랜잭션 및 재시도 패턴

> PlayFab Economy v2 인벤토리 쓰기에 IdempotencyId를 사용해 네트워크 오류 후 안전하게 재시도하고 중복 구매 또는 부여를 방지합니다.

<Info>
  Economy v2는 이제 정식 출시(GA)되었습니다. 지원 및 피드백은 [PlayFab 포럼](https://community.playfab.com)을 참조하세요.
</Info>

라이브 게임에서는 네트워크 오류, 시간 초과, 중복 요청이 필연적입니다. Economy v2는 중복 트랜잭션을 방지하기 위해 **IdempotencyId**를 제공합니다. 이 기능은 동일한 요청이 여러 번 전송되더라도 작업이 한 번만 처리되도록 보장합니다.

낙관적 동시성 제어(마지막으로 읽은 이후 인벤토리가 변경되지 않은 경우에만 쓰기가 성공하도록 보장)에 대해서는 [ETag 및 동시성 제어](/services/playfab/economy-monetization/economy-v2/tutorials/etags-and-concurrency-control)를 참조하세요.

## 필수 구성 요소

* [PlayFab 개발자 계정](https://developer.playfab.com/en-us/sign-up).
* [Game Manager](https://developer.playfab.com/)에서 만든 타이틀.
* 게시된 카탈로그 아이템과 가상 화폐가 각각 하나 이상 있어야 합니다.

## 작동 방식

인벤토리 쓰기 요청에 `IdempotencyId`를 포함하면 PlayFab은 해당 ID를 **14일 동안** 저장합니다. 동일한 `IdempotencyId`로 다른 요청이 도착하면 PlayFab은 작업을 다시 처리하지 않고 원래 요청의 결과를 반환합니다.

## 지원되는 API

`IdempotencyId`는 모든 인벤토리 쓰기 API에서 지원됩니다.

* [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)

## 예제: 재시도가 있는 안전한 구매

이 시나리오에서 플레이어는 Laser Sword를 구매합니다. 클라이언트는 요청을 보내기 전에 고유한 `IdempotencyId`(예: GUID)를 생성합니다.

```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"
}
```

클라이언트가 응답을 받지 못하면(예: 네트워크 시간 초과) 동일한 `IdempotencyId`로 정확히 동일한 요청을 안전하게 재시도할 수 있습니다. PlayFab은 중복을 인식하고 원래 결과를 반환합니다. 플레이어는 한 번만 청구됩니다.

## 모범 사례

* **논리적 작업당 고유한 ID 생성** — GUID 또는 UUID를 사용하세요. 서로 다른 작업에 동일한 ID를 재사용하지 마세요.
* **첫 번째 시도 전에 클라이언트 측에서 ID 생성** — 이 방법은 모든 재시도가 동일한 ID를 사용하도록 보장합니다.
* **재시도 사이에 요청 본문을 변경하지 마세요** — 동일한 `IdempotencyId`를 다른 요청 본문과 함께 사용하면 충돌 오류가 발생합니다.
* **ID는 14일 후에 만료됩니다** — 이후에는 새 작업에 대해 동일한 ID를 다시 사용할 수 있습니다.

## Redeem API는 자동으로 멱등적입니다

마켓플레이스 상환 API(`RedeemAppleAppStoreInventoryItems`, `RedeemGooglePlayInventoryItems`, `RedeemMicrosoftStoreInventoryItems`, `RedeemSteamInventoryItems`)에는 `IdempotencyId`가 필요하지 않습니다. 본질적으로 멱등적입니다. 각 마켓플레이스 영수증 또는 토큰은 한 번만 상환할 수 있습니다. 동일한 영수증으로 두 번째 호출하면 성공이 반환되지만 아무것도 부여되지 않습니다.

## 일반적인 시나리오

| 시나리오                     | 권장 접근 방식                                                              |
| ------------------------ | --------------------------------------------------------------------- |
| 클라이언트 측 구매(플레이어가 아이템 구매) | 첫 번째 시도 전에 GUID를 생성하고, 시간 초과 시 동일한 ID로 재시도합니다.                        |
| 서버 측 보상 부여(퀘스트 완료)       | 이중 부여를 방지하기 위해 퀘스트와 플레이어(예: `questId-playerId`)에서 파생된 결정론적 ID를 사용합니다. |
| 마켓플레이스 상환                | `IdempotencyId`가 필요하지 않습니다. 상환 API는 자동으로 멱등적입니다.                      |

## 참고 항목

* [ETag 및 동시성 제어](/services/playfab/economy-monetization/economy-v2/tutorials/etags-and-concurrency-control)
* [인벤토리 개요](/services/playfab/economy-monetization/economy-v2/inventory#idempotency)
* [사기 방지](/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

- [Economy v2에서의 ETag 및 동시성 제어](/ko/services/playfab/economy-monetization/economy-v2/tutorials/etags-and-concurrency-control.md)
- [Economy v2의 드롭 테이블 및 무작위 루트](/ko/services/playfab/economy-monetization/economy-v2/tutorials/drop-tables-and-randomized-loot.md)
- [사기 방지, 상환, 영수증 검증](/ko/services/playfab/economy-monetization/economy-v2/fraud-prevention/index.md)
- [Economy v2 개요](/ko/services/playfab/economy-monetization/economy-v2/overview.md)
- [트랜잭션 이력](/ko/services/playfab/economy-monetization/economy-v2/inventory/transaction-history.md)