본문으로 건너뛰기

인벤토리 아이템 조회

기본 정보​

  1. 인벤토리 시스템에 지급할 수 있는 아이템이 있는지 조회하는 API입니다.
항목내용비고
호출주체게임서버(s2s API)
도메인각 환경별 도메인
인증 방식

X-Req-Pjid

X-Auth-Access-Key

HTTP 메소드POST
Content-Typeapplication/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 으로 호출하면 됩니다.
keydata typerequireddescriptionexample
pjidString O프로젝트ID1004
userTypeStringO

userValue에 해당하는 ID 종류

  • IMID: HYBE IM의 id로 플랫폼 로그인 후 얻게되는 id, 정책상 기본적으로 인게임에서 유저가 보게되는 id value의 종류
  • GAME_UID: 게임쪽에서 자체 정의한 유저ID
  • GAME_CHARACTER_ID: 게임쪽에서 자체 정의한 케릭터ID

기술PM 등으로 부터 사전에 협의된 값으로 호출 필요

IMID
userValueStringO

userType에 해당하는 지급 대상 ID

  • 빌링/쿠폰 시스템에서 사용한 아이디와 동일

기술PM 등으로 부터 사전에 협의된 값으로 호출 필요

98HOE3C2JVE4ZGK6Q5QQ
serviceIdStringO지급대상 게임서버 serviceId
기술PM 등으로 부터 사전에 협의된 값으로 호출 필요		10040100
serverIdStringX

지급대상 게임서버 ID

  • 요청 키가 없을 경우 전체 조회

기술PM 등으로 부터 사전에 협의된 값으로 호출 필요

ASIA
providerStringX

아이템을 지급한 주체

  • BILLING : 구매한 상품 아이템만 조회
  • COUPON : 사용한 쿠폰 아이템만 조회
  • 요청 키가 없을 경우 전체 조회
COUPON
pageItemSizeIntegerO

한 페이지에 보여질 개수

  • 허용 범위 : 10 ~ 20
10
pageNoIntegerO

조회할 페이지 번호

  • 허용 범위 : 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 - 1depthkey - 2depthdata typenullabledescriptionexample
hasNext booleanX다음 페이지 존재 유무true
resultList

X

없으면 빈 배열

보상받을 수 있는 아이템 리스트
rewardIdString(UUID)X

보상 아이템 고유 아이디

  • 동시성 이슈를 방지하기 위해 해당 값을 게임 지급 테이블에 Unique Index로 정의
889858d3-d2ac-4c7d-bff9-6362a14518b9
pjidStringX프로젝트 ID1201
userTypeStringXuserValue에 해당하는 ID 종류IMID
userValueStringX

상품을 받게될 유저ID

  • 아이템을 지급한 Provider(빌링/쿠폰) 연동에 사용한 유저ID
98HOE3C2JVE4ZGK6Q5QQ
serviceIdStringX지급대상 게임서버 serviceId12010001
serverIdStringO

지급대상 게임서버 ID

  • 구분하지 않을 경우 null일 수 있음
ASIA
providerStringX

아이템을 지급한 주체

  • BILLING
  • COUPON
BILLING
requesterCustomDataStringO

지급 요청자(게임)가 아이템 등록시 전달했던 커스텀 데이터

  • 없을 경우 null일 수 있음
PAID_PURCHASE
expireAtUtcStringStringX

아이템 만료일

  • 만료일이 지난 아이템은 목록에서 제외
2025-01-30T00:00:00Z
billingPurchaseListList

X

없으면 빈 배열

빌링 구매 아이템 상세 정보

  • provider가 BILLING일 경우에만 존재
  • 아래 표 참고
couponRedeemListList

X

없으면 빈 배열

쿠폰 사용 아이템 상세 정보 - 참고

  • provider가 COUPON일 경우에만 존재
  • 아래 표 참고

Response property - billingPurchaseList

key - 1depthdata typenullabledescriptionexample
boidStringX빌링 시스템에서 생성한 고유 아이디120
paymentStringX

결제가 진행된 스토어 또는 서비스

  • 돈을 지급한 행위가 발생한 스토어
PG
appstoreStringX

구매가 이뤄지는 상점 스토어

  • 개발사 입장에서는 배포한 스토어
BIFROST
osStringX

구매한 디바이스의 OS 종류

  • 주의: 외부 결제 등 OS를 알 수 없는 경우 NONE일 수 있음
NONE
productIdStringX상품IDgoogle_1201_item_001
quantityIntegerX지급 상품 개수1
currencyStringX구매 금액의 통화KRW
totalMicroPriceLongX

구매 금액 micro단위 (해당 상품의 금액과 quantity값을 고려해서 합산)

  • 사용측의 부동 소수점 오차등을 방지하기 위해서 micro단위 사용

1200000000

Response property - couponRedeemList

key - 1depthdata typenullabledescriptionexample
couponIdStringX쿠폰 시스템에서 생성한 고유 아이디
itemIdStringX지급할 아이템 고유 아이디COSTUME_LAUNCHING_001
itemTypeStringO

아이템 종류

  • 사용하지 않을 시 null일 수 있음
quantityIntegerX지급할 아이템 갯수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_ERROR500빌링 시스템 내부에서 처리 불가한 예외 발생으로 에러
INVALID_PARAMETER200잘못된 파라미터로 요청
NOT_ALLOW_AUTH200

권한이 없는 요청

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