본문으로 건너뛰기

인벤토리 아이템 예약하기

기본 정보​

  1. 조회 API에서 획득한 rewardId를 이용하여 아이템을 지급받기 위해 예약하는 API입니다. 참고 - 전체 시퀀스
  2. 해당 예약 API 호출을 성공하는 경우 해당 아이템은 이후 조회 API에서 노출되지 않습니다.
    1. 유저에게 해당 아이템을 지급하고 결과에 따라 아래 두 API중 하나를 호출해야 합니다.
      1. 지급을 성공한 경우 인벤토리 아이템 사용 확인 API를 호출 - 아이템 사용 확인
      2. 지급을 실패한 경우 인벤토리 아이템 사용 취소 API를 호출 - 아이템 사용 취소 혹은 아이템 사용 취소 및 영구 제외
항목내용비고
호출주체게임서버(s2s API)
도메인각 환경별 도메인
인증 방식

X-Req-Pjid

X-Auth-Access-Key

HTTP 메소드POST
Content-Typeapplication/json

Request​

HTTP Request end point​

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

HTTP Request Header​

  • 아래의 HTTP Header들을 API 요청에 포함시켜야합니다.
이름값비고
X-Req-Pjid프로젝트ID기술 PM 등에게 전달받은 프로젝트ID
X-Auth-Access-Key인증용 키기술 PM 등에게 전달받은 해당 게임용 인증 키

HTTP Request Parameter​

  • 아래 파라미터들을 Content-Type: application/json 으로 호출하면 됩니다.
keydata typerequireddescriptionexample
pjidStringO 프로젝트ID1004
userTypeStringO

userValue에 해당하는 ID 종류

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

userType에 해당하는 지급 대상 ID

  • 빌링/쿠폰 시템에서 사용한 아이디와 동일
98HOE3C2JVE4ZGK6Q5QQ
rewardIdListList<String>O

조회 API에서 응답으로 받은 rewardId 링크

  • 한번 요청에 최대 20개 지원
80b37193-6b5e-4fb6-8b60-2d3074c98cf11

Request sample - cURL​

curl --location 'https://inven-api-dev.pub-dev.hybegames.io/inventory/api-game/v1/reward/item/reserve' \
--header 'X-Req-Pjid: 1201' \
--header 'X-Auth-Access-Key: test-auth-key' \
--header 'Content-Type: application/json' \
--data '{
    "pjid": "1201",
    "userType": "IMID",
    "userValue": "98HUE3C2JVE4XGK6Q3SN",
    "rewardIdList": [
"d3875013-92f8-47df-a593-35a9ed2bc2ab",
"c7ec9a5c-7680-49af-b866-00d01267f8f4",
"d6d650e4-801c-4b4c-ab55-3e87fbe0cb7d"
    ]
}'

Response​

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

Response property​

keydata typenullabledescriptionexample
rewardIdStringX예약을 진행한 rewardId80b37193-6b5e-4fb6-8b60-2d3074c98cf11
reservedResultCodeStringX

예약 결과 코드

  • 해당 코드로 게임 로직 처리
SUCCESS
reservedResultMessageStringX

예약 결과 메시지

  • 게임에서 참고용 메시지로 유저에게 노출 x

reservedResultCode 정의 표

코드설명처리 방향
SUCCESS예약 성공유저에게 아이템 지급 진행
FAIL_NOT_FOUND요청한 rewardId가 존재하지 않음요청 데이터 확인
FAIL_EXPIRED요청한 rewardId의 만료일 경과조회 API로 최신 목록을 조회
FAIL_MISS_MATCH_USER_TYPE디비 아이템 보상 정보와 요청한 userType이 일치하지 않음요청 데이터 확인
FAIL_MISS_MATCH_USER_VALUE디비 아이템 보상 정보와 요청한 userValue가 일치하지 않음요청 데이터 확인
FAIL_STATUS_NOT_READY디비 아이템 보상 정보의 상태가 예약할 수 없는 상태조회 API로 최신 목록을 조회
FAIL_INTERNAL_ERROR서버 오류요청 정보로 기술PM 에게 문의해주세요.

Response sample​

application/json;charset=UTF-8
{
  "resultCode": "SUCCESS",
  "resultMessage": "request success",
  "resultData": [
    {
      "rewardId": "80b37193-6b5e-4fb6-8b60-2d3074c98cf11",
      "reservedResultCode": "FAIL_NOT_FOUND", // 아이디가 없을 경우 
      "reservedResultMessage": "rewardId is not found."
    },
    {
      "rewardId": "566988f2-106a-4982-a4ac-8c567fa5db39",
      "reservedResultCode": "FAIL_STATUS_NOT_READY", // 예약할 수 있는 상태가 아닌 경우
      "reservedResultMessage": "status is not Ready. db.status: RESERVED"
    },
    {
      "rewardId": "1d950816-7ad6-4908-94e3-5de307191913",
      "reservedResultCode": "SUCCESS", // 예약 성공
      "reservedResultMessage": ""
    }
  ]
}

공통 에러 코드 정의​

  • 인벤토리 시스템 API와 통신이 성공했지만 여러가지 사유로 에러로 리턴해야하는 경우가 있습니다.
  • 이때 resultCode 부분에 응답되는 공통 에러 코드를 정리해둔 목록입니다.
    • 게임쪽에서 HTTP 상태코드 200이 아닌 경우 처리가 어려워서 에러지만 http 200으로 리턴합니다.(단, 앞단 인프라 레벨 등에서 발생하는 에러는 불가)
    • 각 API에서 발생하는 에러코드는 하단에 별도로 설명합니다. (없을 경우 생략)

에러 코드 목록

에러 코드Http Status설명
SYSTEM_ERROR500빌링 시스템 내부에서 처리 불가한 예외 발생으로 에러
INVALID_PARAMETER200잘못된 파라미터로 요청
NOT_ALLOW_AUTH200

권한이 없는 요청

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