운영 목적의 예약상태 아이템 조회
기본 정보
- 예약상태로 남아있는 아이템 목록 조회 API입니다.
- 일반적인 흐름이 아닌 어떤 이유로 예약상태로 남아있어 이후 시퀀스를 진행하지 못한 경우에 대처할 수 있습니다.
- 상황에 맞게 다음 시퀀스를 호출하세요.
- 아이템 만료일은 예약 시점 기준으로 판단합니다. 즉, 만료일 이전에 예약한 아이템은 만료일이 지난 후에도 다음 시퀀스 진행 가능
- 유저 서비스 로직이 아닌** 운영툴 등에서만 사용하세요.**
- 일반적인 흐름이 아닌 어떤 이유로 예약상태로 남아있어 이후 시퀀스를 진행하지 못한 경우에 대처할 수 있습니다.
| 항목 | 내용 | 비고 |
|---|---|---|
| 호출주체 | 게임서버(s2s API) | |
| 도메인 | 각 환경별 도메인 | |
| 인증 방식 | X-Req-Pjid, X-Auth-Access-Key | |
| HTTP 메소드 | POST | |
| Content-Type | application/x-www-form-urlencoded |
Request
HTTP Request end point
POST https://각 환경별 인벤토리시스템 도메인/inventory/api-game/v1/operational/reward/list/reserved
- 아래의 HTTP Header들을 API 요청에 포함시켜야합니다.
| 이름 | 값 | 비고 |
|---|---|---|
| X-Req-Pjid | 프로젝트ID | 기술 PM 등에게 전달받은 프로젝트ID |
| X-Auth-Access-Key | 인증용 키 | 기술 PM 등에게 전달받은 해당 게임용 인증 키 |
HTTP Request Parameter
- 아래 파라미터들을 Content-Type: application/x-www-form-urlencoded 으로 호출하면 됩니다.
| key | data type | required | description | example |
|---|---|---|---|---|
| pjid | String | 프로젝트ID | 1004 | |
| userType | String | O | userValue에 해당하는 ID 종류: IMID (HYBE IM의 id로 플랫폼 로그인 후 얻게되는 id, 정책상 기본적으로 인게임에서 유저가 보게되는 id value의 종류), GAME_UID (게임쪽에서 자체 정의한 유저ID), GAME_CHARACTER_ID (게임쪽에서 자체 정의한 케릭터ID) | IMID |
| userValue | String | O | userType에 해당하는 지급 대상 ID (빌링/쿠폰 시스템에서 사용한 아이디와 동일) | 98HOE3C2JVE4ZGK6Q5QQ |
| serviceId | String | O | 지급대상 게임서버 serviceId | 10040100 |
| pageItemSize | Integer | X | 한 페이지에 보여질 갯수 (기본값: 20, 허용 범위: 10~50) | 20 |
| pageNo | Integer | X | 조회할 페이지 번호 (기본값: 1, 허용 범위: 1~5) | 1 |
Request sample - cURL
curl --location 'https://inven-api-dev.pub-dev.hybegames.io/inventory/api-game/v1/operational/reward/list/reserved' \
--header 'X-Req-Pjid: 1201' \
--header 'X-Auth-Access-Key: test-auth-key' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'pjid=1201' \
--data-urlencode 'userType=IMID' \
--data-urlencode 'userValue=98HUE3C2JVE4XGK6Q3SN' \
--data-urlencode 'serviceId=12010001'
Response
응답은 JSON형태로 전달됩니다.
Response property
| key - 1depth | key - 2depth | data type | nullable | description | example |
|---|---|---|---|---|---|
| hasNext | boolean | X | 다음 페이지 존재 유무 | true | |
| resultList | X (없으면 빈 배열) | 보상받을 수 있는 아이템 리스트 | |||
| rewardId | String(UUID) | X | 보상 아이템 고유 아이디 | 889858d3-d2ac-4c7d-bff9-6362a14518b9 | |
| pjid | String | X | 프로젝트 ID | 1201 | |
| userType | String | X | userValue에 해당하는 ID 종류 | IMID | |
| userValue | String | X | 상품을 받게될 유저ID (아이템을 지급한 Provider(빌링/쿠폰) 연동에 사용한 유저ID) | 98HOE3C2JVE4ZGK6Q5QQ | |
| serviceId | String | X | 지급대상 게임서버 serviceId | 12010001 | |
| serverId | String | O | 지급대상 게임서버 ID (구분하지 않을 경우 null일 수 있음) | ASIA | |
| provider | String | X | 아이템을 지급한 주체 (BILLING, COUPON) | BILLING | |
| requesterCustomData | String | O | 지급 요청자(게임)가 아이템 등록시 전달했던 커스텀 데이터 (없을 경우 null일 수 있음) | PAID_PURCHASE | |
| expireAtUtcString | String | X | 아이템 만료일 (만료일이 지난 아이템은 목록에서 제외) | 2025-01-30T00:00:00Z | |
| billingPurchaseList | List | X (없으면 빈 배열) | 빌링 구매 아이템 상세 정보 (provider가 BILLING일 경우에만 존재, 아래 표 참고) | ||
| couponRedeemList | List | X (없으면 빈 배열) | 쿠폰 사용 아이템 상세 정보 (provider가 COUPON일 경우에만 존재, 아래 표 참고) |
Response property - billingPurchaseList
| key - 1depth | data type | nullable | description | example |
|---|---|---|---|---|
| boid | String | X | 빌링 시스템에서 생성한 고유 아이디 | 120 |
| payment | String | X | 결제가 진행된 스토어 또는 서비스 (돈을 지급한 행위가 발생한 스토어) | PG |
| appstore | String | X | 구매가 이뤄지는 상점 스토어 (개발사 입장에서는 배포한 스토어) | BIFROST |
| os | String | X | 구매한 디바이스의 OS 종류 (주의: 외부 결제 등 OS를 알 수 없는 경우 NONE일 수 있음) | NONE |
| productId | String | X | 상품ID | google_1201_item_001 |
| quantity | Integer | X | 지급 상품 개수 | 1 |
| currency | String | X | 구매 금액의 통화 | KRW |
| totalMicroPrice | Long | X | 구매 금액 micro단위 (해당 상품의 금액과 quantity값을 고려해서 합산, 사용측의 부동 소수점 오차등을 방지하기 위해서 micro단위 사용) | 1200000000 |
Response property - couponRedeemList
| key - 1depth | data type | nullable | description | example |
|---|---|---|---|---|
| couponId | String | X | 쿠폰 시스템에서 생성한 고유 아이디 | |
| itemId | String | X | 지급할 아이템 고유 아이디 | COSTUME_LAUNCHING_001 |
| itemType | String | O | 아이템 종류 (사용하지 않을 시 null일 수 있음) | |
| quantity | Integer | X | 지급할 아이템 갯수 | 1 |
Success sample
application/json;charset=UTF-8
{
"resultCode": "SUCCESS",
"resultMessage": "request success",
"resultData": {
"hasNext": false,
"resultList": [
{
"rewardId": "c7ec9a5c-7680-49af-b866-00d01267f8f4",
"pjid": "1201",
"userType": "IMID",
"userValue": "98HUE3C2JVE4XGK6Q3SN",
"serviceId": "12010001",
"serverId": "12010001",
"provider": "COUPON",
"requesterCustomData": null,
"expireAtUtcString": "2025-12-01T09:00:00Z",
"billingPurchaseList": [],
"couponRedeemList": [
{
"couponId": "9",
"itemId": "COSTUME_LAUNCHING_001",
"itemType": null,
"quantity": 1
}
]
},
{
"rewardId": "d6d650e4-801c-4b4c-ab55-3e87fbe0cb7d",
"pjid": "1201",
"userType": "IMID",
"userValue": "98HUE3C2JVE4XGK6Q3SN",
"serviceId": "12010001",
"serverId": "ASIA",
"provider": "BILLING",
"requesterCustomData": "PAID_PURCHASE",
"expireAtUtcString": "2025-12-01T00:00:00Z",
"billingPurchaseList": [
{
"boid": "3055",
"payment": "PG",
"appstore": "BIFROST",
"os": "NONE",
"productId": "sku_id",
"quantity": 1,
"currency": "KRW",
"totalMicroPrice": 1200000000
}
],
"couponRedeemList": []
},
{
"rewardId": "3ff73830-3625-4df8-8e4f-35706610b136",
"pjid": "1201",
"userType": "IMID",
"userValue": "98HUE3C2JVE4XGK6Q3SN",
"serviceId": "12010001",
"serverId": "ASIA",
"provider": "COUPON",
"requesterCustomData": null,
"expireAtUtcString": "2025-12-01T00:00:00Z",
"billingPurchaseList": [],
"couponRedeemList": [
{
"couponId": "32",
"itemId": "COSTUME_LAUNCHING_010",
"itemType": null,
"quantity": 1
}
]
},
{
"rewardId": "d3875013-92f8-47df-a593-35a9ed2bc2ab",
"pjid": "1201",
"userType": "IMID",
"userValue": "98HUE3C2JVE4XGK6Q3SN",
"serviceId": "12010001",
"serverId": "ASIA",
"provider": "BILLING",
"requesterCustomData": "billing_custom",
"expireAtUtcString": "2025-04-20T00:00:00Z",
"billingPurchaseList": [
{
"boid": "150",
"payment": "PG",
"appstore": "BIFROST",
"os": "NONE",
"productId": "sku_id",
"quantity": 1,
"currency": "KRW",
"totalMicroPrice": 1200000000
}
],
"couponRedeemList": []
}
]
}
}
에러 코드 정의
- 인벤토리 시스템 API와 통신이 성공했지만 여러가지 사유로 에러로 리턴해야하는 경우가 있습니다.
- 이때 resultCode 부분에 응답되는 공통 에러 코드를 정리해둔 목록입니다.
- 게임쪽에서 HTTP 상태코드 200이 아닌 경우 처리가 어려워서 에러지만 http 200으로 리턴합니다.(단, 앞단 인프라 레벨 등에서 발생하는 에러는 불가)
- 각 API에서 발생하는 에러코드는 하단에 별도로 설명합니다. (없을 경우 생략)
에러 코드 목록
| 에러 코드 | Http Status | 설명 |
|---|---|---|
| SYSTEM_ERROR | 500 | 빌링 시스템 내부에서 처리 불가한 예외 발생으로 에러 |
| INVALID_PARAMETER | 200 | 잘못된 파라미터로 요청 |
| NOT_ALLOW_AUTH | 200 | 권한이 없는 요청
|