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

# collections.mp.microsoft.com/v8.0/collections/consume

> 게임 서비스에서 사용자의 잔액에서 스토어 관리 및 개발자 관리 소모품이 사용되었음을 보고하는 Microsoft Store v8 Collections consume API입니다.

Consume API를 사용하여 다음 Microsoft Store 소모품 유형을 관리할 수 있습니다.

* **스토어 관리 소모품:** 소비된 수량을 보고하고 지정된 사용자의 현재 수량 잔액에서 제거합니다.
  사용자는 서비스에서 소비되거나 이행된 것으로 보고할 필요 없이 스토어 관리 소모품을 반복적으로 재구매할 수 있습니다.
  자세한 내용은 [스토어 관리 소비 요청](#store-managed-consume-request)을 참조하세요.

* **개발자 관리 소모품:** 지정된 사용자에 대해 소모품 제품을 이행된 것으로 보고합니다.
  사용자가 개발자 관리 소모품 제품을 재구매하기 전에 앱 또는 서비스는 해당 사용자에 대해 소모품 제품을 이행된 것으로 보고해야 합니다.
  자세한 내용은 [개발자 관리 소비 요청](#developer-managed-consume-request)을 참조하세요.

## `trackingId`를 사용하여 이행 완료 유효성 검사

`trackingId`는 재시도에 안전한 이행 유효성 검사를 제공합니다.
서비스가 확인 응답을 받지 못하면 동일한 요청 본문을 다시 보냅니다.
서비스는 이전 요청을 인식하고 재시도를 확인 검사로 처리합니다.

API에 대한 각 요청에는 고유한 `trackingId`가 있어야 합니다.
원래 요청이 성공하지 못했거나 응답을 받지 못한 경우, 요청을 재시도하면 서비스가 요청된 트랜잭션을 완료합니다.
이전 요청에서 이행이 완료된 경우, API는 요청을 인식하고 확인 응답을 보냅니다.
이 경우 API는 사용자의 잔액에서 두 번째로 이행하거나 차감하지 않습니다.
대신 API는 항목이 사용자의 남은 잔액과 함께 소비된 것처럼 성공으로 응답합니다.

따라서 요청이 이행되었다는 확인 응답을 받을 때까지 각 요청의 값과 `trackingId`를 서버 또는 로그에 캐시하세요.
예제는 [Game Service 샘플](https://aka.ms/gdkdl)을 참조하세요.

요청에 `includeOrderIds` 매개 변수가 있는 경우, 소모품의 제품 유형에 따라 다음 동작이 예상됩니다.

| 소모품 유형 | 첫 번째 소비 요청 동작                  | 재시도 소비 요청 동작                                  |
| ------ | ------------------------------ | --------------------------------------------- |
| 스토어 관리 | 요청을 이행하는 데 사용된 OrderIds가 반환됩니다 | 요청을 이행하는 데 사용된 동일한 OrderIds가 반환됩니다            |
| 개발자 관리 | 요청을 이행하는 데 사용된 OrderIds가 반환됩니다 | 이 제품 유형에는 이 데이터가 추적되지 않으므로 OrderID가 반환되지 않습니다 |

개발자 관리 소모품을 사용하는 경우 재시도 요청에서 주문 ID를 가져올 수 없습니다.

## 필수 구성 요소

[서비스 간 API의 필수 구성 요소](https://learn.microsoft.com/reference/service-to-service-nav#prerequisites-for-service-to-service-apis)를 검토하세요.

이 API는 Microsoft Entra ID 및 위임된 인증 X-token 인증 유형을 모두 지원합니다.

<Info>**개발자 관리 소모품에 대한 샌드박스 제한:** 개발 샌드박스(RETAIL이 아닌)에서 개발자 관리 소모품 제품을 소비할 때 사용자 저장소 ID 또는 Microsoft Entra ID를 사용한 인증은 지원되지 않습니다. 샌드박스 환경에서는 개발자 관리 소모품 제품을 성공적으로 소비하려면 위임된 권한 부여 XSTS 토큰을 사용해야 합니다. 이 제한은 스토어 관리 소모품이나 RETAIL 샌드박스에는 적용되지 않습니다.</Info>

파트너 센터에서 제품 구성을 게시하지 않으면 호출이 성공하지만 결과가 반환되지 않을 수 있습니다.

### 사용자 저장소 ID 인증 오류 코드

| Code | Error        | Inner error code           | Description                                                                                                          |
| ---- | ------------ | -------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| 401  | Unauthorized | AuthenticationTokenInvalid | Microsoft Entra ID 액세스 토큰이 잘못되었습니다. 어떤 경우에는 `ServiceError`의 세부 정보에 토큰이 만료되었거나 `appid` 클레임이 누락된 경우와 같은 자세한 정보가 포함됩니다. |
| 401  | Unauthorized | PartnerAadTicketRequired   | Microsoft Entra ID 액세스 토큰이 권한 부여 헤더에서 서비스에 전달되지 않았습니다.                                                               |
| 401  | Unauthorized | InconsistentClientId       | 요청 본문의 Microsoft Store ID 키에 있는 `clientId` 클레임과 권한 부여 헤더의 Microsoft Entra ID 액세스 토큰에 있는 `appid` 클레임이 일치하지 않습니다.      |

### X-token 인증 사용 시 오류 코드

| Code | Error        | Inner error code   | Description                                                                                          |
| ---- | ------------ | ------------------ | ---------------------------------------------------------------------------------------------------- |
| 401  | Unauthorized | Expired Token      | X-token이 만료되었으며 호출을 완료하려면 새 토큰이 필요합니다.                                                               |
| 403  | Unauthorized | Invalid Token      | 사용된 토큰은 이 엔드포인트에서 인증할 권한이 없습니다. 토큰이 잘못된 샌드박스 또는 신뢰 당사자용일 수 있습니다.                                     |
| 429  | Throttled    | Too frequent calls | 지정된 호출 제한 내에서 사용자에 대해 서비스가 너무 많이 호출되었습니다. 서비스가 이 사용자에 대해 다른 호출을 서비스에 언제 수행할 수 있는지에 대한 정보는 응답을 참조하세요. |

## 요청

### 요청 구문

| Method | Request URI                                                     |
| ------ | --------------------------------------------------------------- |
| `POST` | `https://collections.mp.microsoft.com/v8.0/collections/consume` |

### 요청 헤더

| Header           | Type     | Description                                                                 |
| ---------------- | -------- | --------------------------------------------------------------------------- |
| `Authorization`  | `string` | 필수. 사용 중인 인증 유형에 따라 위임된 권한 부여 X-token 또는 Microsoft Entra ID 액세스 토큰 중 하나입니다. |
| `Signature`      | `string` | X-token으로 인증할 때 필수입니다. 사용자 저장소 ID 인증에는 필요하지 않습니다.                           |
| `User-Agent`     | `string` | 선택 사항이지만 권장됩니다. 로깅 및 조사를 위해 서비스를 식별하는 데 도움이 됩니다.                            |
| `Host`           | `string` | 값 `collections.mp.microsoft.com`으로 설정해야 합니다.                                |
| `Content-Length` | `number` | 요청 본문의 길이입니다.                                                               |
| `Content-Type`   | `string` | 요청 및 응답 형식을 지정합니다. 현재 지원되는 유일한 값은 `application/json`입니다.                    |

### 요청 본문

| Parameter         | Type           | Description                                                                                                                                                                                                                                                        | Required            |
| ----------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------- |
| `beneficiary`     | `UserIdentity` | 이 항목이 소비되는 사용자입니다. 자세한 내용은 [Microsoft Entra ID 및 사용자 저장소 ID로 인증](https://learn.microsoft.com/reference/xstore-authenticating-your-service#authenticating-with-microsoft-entra-id-and-user-store-ids)을 참조하세요. X-token 인증에는 필요하지 않습니다.                               | 사용자 저장소 ID 인증에만 해당  |
| `trackingId`      | `guid`         | 중복 검사를 위해 개발자가 제공한 고유한 `trackingId`입니다. GUID는 각 요청에 대해 고유해야 합니다. 자세한 내용은 [trackingId를 사용하여 이행 완료 유효성 검사](#using-trackingid-to-validate-fulfillment-completion)를 참조하세요.                                                                                             | 예                   |
| `productId`       | `string`       | 요청에 대한 소모품의 `productId`입니다. 파트너 센터 또는 [서비스에서 사용자의 제품 및 자격 쿼리](/reference/microsoft-store-apis/xstore-v9-query-for-products)를 통해 얻을 수 있습니다.                                                                                                                         | 예                   |
| `removeQuantity`  | `int`          | 사용자의 현재 잔액에서 소비할 수량입니다.                                                                                                                                                                                                                                            | 스토어 관리 소모품에만 적용됩니다. |
| `includeOrderIds` | `bool`         | 소비 요청을 이행하는 데 사용된 주문의 OrderIds 및 LineItemIds를 포함합니다. 이 값은 [Clawback 이벤트 서비스](https://learn.microsoft.com/reference/xstore-managing-refunds-and-chargebacks) 결과와 함께 사용하여 게임 서비스에서 환불된 소비 트랜잭션을 식별할 수 있습니다.                                                          | 아니요                 |
| `sbx`             | `string`       | UserStoreIds로 인증할 때 결과의 범위를 지정할 샌드박스를 지정하는 선택적 값입니다. 이 값이 없는 기본값은 RETAIL 샌드박스입니다. X-Token 인증은 샌드박스가 X-Token 내에 지정되므로 이 값이 필요하지 않습니다. **참고:** 개발자 관리 소모품의 경우, 개발 샌드박스를 대상으로 하는 `sbx` 매개 변수를 사용한 사용자 저장소 ID 인증은 지원되지 않습니다. 개발자 관리 소모품의 샌드박스 테스트에는 XSTS 토큰 인증을 사용하세요. | 아니요                 |

### 소비 요청 예제

다음 예제에서는 인증에 사용자 저장소 ID를 사용하며 요청 JSON 본문에 beneficiary 개체가 필요합니다.

#### 스토어 관리 소비 요청

```syntax theme={null}
POST https://collections.mp.microsoft.com/v8.0/collections/consume HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1...
Host: collections.mp.microsoft.com
Content-Type: application/json

{
    "beneficiary" : {
        "localTicketReference": "testReference",
        "identityValue": "eyJ0eXAiOiJ...",
        "identityType": "b2b"
    },
    "productId": "9N0297GK108W",
    "trackingId": "1b3afaa8-8644-40e9-9073-266a3bb8804f",
    "removeQuantity": 1,
    "sandbox": "XDKS.1",
    "includeOrderIds": true
}
```

#### 개발자 관리 소비 요청

<Note>다음 예제에서는 사용자 저장소 ID 인증을 사용합니다. 그러나 이 인증 방법은 개발 샌드박스의 개발자 관리 소모품에는 작동하지 않습니다. 샌드박스 환경에서 테스트하는 경우 XSTS 토큰 인증을 대신 사용하세요. 자세한 내용은 [위임된 인증 XSTS 토큰을 통한 인증](https://learn.microsoft.com/reference/xstore-authenticating-your-service#authenticating-with-delegated-authentication-x-tokens)을 참조하세요.</Note>

```syntax theme={null}
POST https://collections.mp.microsoft.com/v8.0/collections/consume HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1...
Content-Type: application/json
Host: collections.md.mp.microsoft.com

{
    "beneficiary" : {
        "localTicketReference" : "testReference",
        "identityValue": "eyJ0eXAiOiJ...",
        "identityType": "b2b"
    },
    "productId" : "9NBLGGH5WVP6",
    "trackingId" : "08a14c7c-1892-49fc-9135-190ca4f10490",
    "sbx" : "XDKS.1",
    "includeOrderIds": true
}
```

## 응답

### 응답 본문

| Parameter           | Type                            | Description                                                                                                                         | Required |
| ------------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `itemId`            | string                          | 사용자가 소유한 다른 항목과 컬렉션 항목을 구별하는 ID입니다. 이 ID는 제품별로 고유합니다.                                                                               | 예        |
| `productId`         | `string`                        | Microsoft Store 카탈로그 내에서 제품의 스토어 ID라고도 합니다. 제품에 대한 스토어 ID의 예는 9NBLGGH42CFD입니다.                                                      | 예        |
| `trackingId`        | `GUID`                          | 소비 요청을 위해 호출자가 제공한 고유한 `trackingId`입니다.                                                                                             | 예        |
| `newQuantity`       | `int`                           | 이 소모품 제품에 대한 사용자 잔액의 남은 수량입니다. 개발자 관리 소모품의 경우 값은 0입니다.                                                                              | 예        |
| `orderTransactions` | `List<ConsumeOrderTransaction>` | 요청을 이행하는 데 사용된 주문을 나타내는 ConsumeOrderTransaction 개체의 배열입니다. 요청에서 `includeOrderIds` 매개 변수가 true로 설정된 경우에만 반환됩니다. 자세한 내용은 다음 표를 참조하세요. | 아니요      |

`ConsumeOrderTransaction` 개체에는 다음 매개 변수가 포함됩니다.

| Parameter          | Type   | Description                                                                                                     | Required |
| ------------------ | ------ | --------------------------------------------------------------------------------------------------------------- | -------- |
| `orderId`          | `GUID` | 소비 요청의 전체 또는 일부를 이행하는 데 사용된 사용자의 구매 주문 ID입니다.                                                                   | 예        |
| `orderLineItemId`  | `GUID` | 사용자가 수행한 구매 주문 내 소모품이 있었던 라인 항목의 ID입니다. OrderID당 여러 LineItemId가 있을 수 있기 때문에 이 ID는 OrderId보다 소모품 구매에 대해 더 고유합니다. | 예        |
| `quantityConsumed` | `int`  | 이 특정 OrderId / LineItemId로 이행된 요청의 수량입니다.                                                                       | 예        |

### 소비 응답 예제

```syntax theme={null}
HTTP/1.1 200 OK
Date: Sat, 04 Sep 2021 01:59:13 GMT
Content-Type: application/json; charset=utf-8
Server: Kestrel
Content-Length: 140
MS-CorrelationId: c7ed3826-c332-4394-af7e-32800e492695
MS-RequestId: 0702fbcf-01ec-4591-995e-13b92149df4d
MS-CV: rJGMXgDq8E2A1EmX.0
X-Content-Type-Options: nosniff
MS-ServerId: 6

{
    "newQuantity": 0,
    "itemId": "c95fef434d1241d6bdb09090b130b6f4",
    "trackingId": "1b3afaa8-8644-40e9-9073-266a3bb8804f",
    "productId": "9N0297GK108W",
    "orderTransactions": [
        {
            "orderId": "8060a406-85c8-4d01-a105-ff11725499c9",
            "orderLineItemId": "cb054aa0-7392-4cc6-af06-53b285e39259",
            "quantityConsumed": 1
        }
    ]
}
```

## 관련 문서

[서비스에서 제품 관리](https://learn.microsoft.com/reference/service-to-service-nav)

[Microsoft Store API로 서비스 인증](https://learn.microsoft.com/reference/xstore-authenticating-your-service)

[publisherQuery(Collections v9)를 사용하여 사용자의 제품 및 자격 쿼리](/reference/microsoft-store-apis/xstore-v9-query-for-products)

[서비스에서 소모품 제품 관리](https://learn.microsoft.com/reference/xstore-managing-consumables-and-refunds)

[서비스에서 환불 및 지불 거절 관리](https://learn.microsoft.com/reference/xstore-managing-refunds-and-chargebacks)


## Related topics

- [Microsoft Store 서비스 API](/ko/reference/microsoft-store-apis/xstore-nav.md)
- [서비스에서 소모품 제품 관리](/ko/publishing/xstore-commerce/xstore-managing-consumables.md)
- [collections.mp.microsoft.com/v9.0/collections/publisherQuery](/ko/reference/microsoft-store-apis/xstore-v9-query-for-products.md)
- [Microsoft Store v8 Collections b2bLicensePreview API](/ko/reference/microsoft-store-apis/xstore-v8-query-for-products.md)
- [purchase.mp.microsoft.com/v8.0/b2b/orders/query](/ko/reference/microsoft-store-apis/xstore-v8-clawbackv1.md)