인벤토리 아이템 조회

기본 정보

1. 인벤토리 시스템에 지급할 수 있는 아이템이 있는지 조회하는 API입니다.

항목	내용	비고
호출주체	게임서버(s2s API)
도메인	각 환경별 도메인
인증 방식	X-Req-Pjid X-Auth-Access-Key
HTTP 메소드	POST
Content-Type	application/x-www-form-urlencoded

참고 사항

1. 게임 플레이에 영향을 주는 기능이 아니므로 비동기 처리를 하여 요청 실패가 게임이나 UX에 영향을 미치지 않도록 꼭 처리해주세요.

Request

HTTP Request end point

POST https://각 환경별 인벤토리시스템 도메인/inventory/api-game/v1/reward/item/list

HTTP Request Header

• 아래의 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	O	프로젝트ID	1004
userType	String	O	userValue에 해당하는 ID 종류 IMID: HYBE IM의 id로 플랫폼 로그인 후 얻게되는 id, 정책상 기본적으로 인게임에서 유저가 보게되는 id value의 종류 GAME_UID: 게임쪽에서 자체 정의한 유저ID 기술PM 등으로 부터 사전에 협의된 값으로 호출 필요	IMID
userValue	String	O	상품을 받게될 유저ID 빌링/쿠폰 시스템에서 사용한 아이디와 동일 기술PM 등으로 부터 사전에 협의된 값으로 호출 필요	98HOE3C2JVE4ZGK6Q5QQ
serviceId	String	O	지급대상 게임서버 serviceId 기술PM 등으로 부터 사전에 협의된 값으로 호출 필요	10040100
serverId	String	X	지급대상 게임서버 ID 요청 키가 없을 경우 전체 조회 기술PM 등으로 부터 사전에 협의된 값으로 호출 필요	ASIA
provider	String	X	아이템을 지급한 주체 BILLING : 구매한 상품 아이템만 조회 COUPON : 사용한 쿠폰 아이템만 조회 요청 키가 없을 경우 전체 조회	COUPON
pageItemSize	Integer	O	한 페이지에 보여질 개수 허용 범위 : 10 ~ 20	10
pageNo	Integer	O	조회할 페이지 번호 허용 범위 : 1 ~ 10	1

Request sample - cURL

curl --location 'https://inven-api-dev.pub-dev.hybegames.io/inventory/api-game/v1/reward/item/list' \
--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' \
--data-urlencode 'pageItemSize=10' \
--data-urlencode 'pageNo=1'

Response

응답은 JSON형태로 전달됩니다.

Response property

key - 1depth	key - 2depth	data type	nullable	description	example
hasNext		boolean	X	다음 페이지 존재 유무	true
resultList			X 없으면 빈 배열	보상받을 수 있는 아이템 리스트
	rewardId	String(UUID)	X	보상 아이템 고유 아이디 동시성 이슈를 방지하기 위해 해당 값을 게임 지급 테이블에 Unique Index로 정의	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": true,
        "resultList": [
            {
                "rewardId": "889858d3-d2ac-4c7d-bff9-6362a14518b9",
                "pjid": "1201",
                "userType": "IMID",
                "userValue": "98HUE3C2JVE4XGK6Q3SN",
                "serviceId": "12010001",
                "serverId": "ASIA",
                "provider": "BILLING",
                "requesterCustomData": "PAID_PURCHASE",
                "expireAtUtcString": "2025-01-30T00:00:00Z",
                "billingPurchaseList": [
                    {
                        "boid": "120",
                        "payment": "PG",
                        "appstore": "BIFROST",
                        "os": "NONE",
                        "productId": "sku_id",
                        "quantity": 1,
                        "currency": "KRW",
                        "totalMicroPrice": 1200000000
                    }
                ],
                "couponRedeemList": []
            },
            {
                "rewardId": "6973a41f-075a-4a18-94f4-6a6062f560bf",
                "pjid": "1201",
                "userType": "IMID",
                "userValue": "98HUE3C2JVE4XGK6Q3SN",
                "serviceId": "12010001",
                "serverId": null,
                "provider": "COUPON",
                "requesterCustomData": null,
                "expireAtUtcString": "2025-12-01T00:00:00Z",
                "billingPurchaseList": [],
                "couponRedeemList": [
                    {
                        "couponId": "10126",
                        "itemId": "COSTUME_LAUNCHING_001",
                        "itemType": null,
                        "quantity": 1
                    }
                ]
            }
        ]
    }
}

에러 코드 정의

• 인벤토리 시스템 API와 통신이 성공했지만 여러가지 사유로 에러로 리턴해야하는 경우가 있습니다.

• 이때 resultCode 부분에 응답되는 공통 에러 코드를 정리해둔 목록입니다.

  • 게임쪽에서 HTTP 상태코드 200이 아닌 경우 처리가 어려워서 에러지만 http 200으로 리턴합니다.(단, 앞단 인프라 레벨 등에서 발생하는 에러는 불가)

  • 각 API에서 발생하는 에러코드는 하단에 별도로 설명합니다. (없을 경우 생략)

에러 코드 목록

에러 코드	Http Status	설명
SYSTEM_ERROR	500	빌링 시스템 내부에서 처리 불가한 예외 발생으로 에러
INVALID_PARAMETER	200	잘못된 파라미터로 요청
NOT_ALLOW_AUTH	200	권한이 없는 요청 인증 헤더 누락 등 권한없는 요청