운영 목적의 예약상태 아이템 조회

기본 정보

  1. 예약상태로 남아있는 아이템 목록 조회 API입니다.

    1. 일반적인 흐름이 아닌 어떤 이유로 예약상태로 남아있어 이후 시퀀스를 진행하지 못한 경우에 대처할 수 있습니다.

      1. 상황에 맞게 다음 시퀀스를 호출하세요.

      2. 아이템 만료일은 예약 시점 기준으로 판단합니다. 즉, 만료일 이전에 예약한 아이템은 만료일이 지난 후에도 다음 시퀀스 진행 가능

    2. 유저 서비스 로직이 아닌 운영툴 등에서만 사용하세요.

항목
내용
비고

호출주체

게임서버(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

권한이 없는 요청

  • 인증 헤더 누락 등 권한없는 요청

Last updated