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

기본 정보

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	권한이 없는 요청 인증 헤더 누락 등 권한없는 요청