인벤토리 아이템 조회
기본 정보
인벤토리 시스템에 지급할 수 있는 아이템이 있는지 조회하는 API입니다.
호출주체
게임서버(s2s API)
도메인
각 환경별 도메인
인증 방식
X-Req-Pjid
X-Auth-Access-Key
HTTP 메소드
POST
Content-Type
application/x-www-form-urlencoded
참고 사항
게임 플레이에 영향을 주는 기능이 아니므로 비동기 처리를 하여 요청 실패가 게임이나 UX에 영향을 미치지 않도록 꼭 처리해주세요.
Request
HTTP Request end point
POST https://각 환경별 인벤토리시스템 도메인/inventory/api-game/v1/reward/item/listHTTP 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 으로 호출하면 됩니다.
pjid
String
O
프로젝트ID
1004
userType
String
O
userValue에 해당하는 ID 종류
IMID: HYBE IM의 id로 플랫폼 로그인 후 얻게되는 id, 정책상 기본적으로 인게임에서 유저가 보게되는 id value의 종류GAME_UID: 게임쪽에서 자체 정의한 유저ID
GAME_CHARACTER_ID: 게임쪽에서 자체 정의한 케릭터ID
기술PM 등으로 부터 사전에 협의된 값으로 호출 필요
IMID
userValue
String
O
userType에 해당하는 지급 대상 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
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
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
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에서 발생하는 에러코드는 하단에 별도로 설명합니다. (없을 경우 생략)
에러 코드 목록
SYSTEM_ERROR
500
빌링 시스템 내부에서 처리 불가한 예외 발생으로 에러
INVALID_PARAMETER
200
잘못된 파라미터로 요청
NOT_ALLOW_AUTH
200
권한이 없는 요청
인증 헤더 누락 등 권한없는 요청
Last updated