인벤토리 아이템 예약하기

기본 정보

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-Type	application/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 으로 호출하면 됩니다.

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 GAME_CHARACTER_ID: 게임쪽에서 자체 정의한 케릭터ID	IMID
userValue	String	O	userType에 해당하는 지급 대상 ID 빌링/쿠폰 시템에서 사용한 아이디와 동일	98HOE3C2JVE4ZGK6Q5QQ
rewardIdList	List<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

key	data type	nullable	description	example
rewardId	String	X	예약을 진행한 rewardId	80b37193-6b5e-4fb6-8b60-2d3074c98cf11
reservedResultCode	String	X	예약 결과 코드 해당 코드로 게임 로직 처리	SUCCESS
reservedResultMessage	String	X	예약 결과 메시지 게임에서 참고용 메시지로 유저에게 노출 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_ERROR	500	빌링 시스템 내부에서 처리 불가한 예외 발생으로 에러
INVALID_PARAMETER	200	잘못된 파라미터로 요청
NOT_ALLOW_AUTH	200	권한이 없는 요청 인증 헤더 누락 등 권한없는 요청