인벤토리 아이템 사용 확인

기본 정보

1. 예약을 성공한 아이템에 대해서 게임 서버에서는 유저에게 아이템을 지급합니다.

2. 이 문서는 아이템 지급을 성공한 경우 인벤토리 시스템에 최종 사용 완료로 처리하기 위한 문서입니다.

항목	내용	비고
호출주체	게임서버(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/confirm

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	아이템 지급을 성공한 아이템의 rewardId 링크 한번 요청에 최대 20개 지원	c42ec5c3-5bcf-4e39-b7ed-4a9bdcf1be8e

Request sample - cURL

curl --location 'https://inven-api-dev.pub-dev.hybegames.io/inventory/api-game/v1/reward/item/confirm' \
--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": [
"713e0bbc-eb73-46b7-9d1e-6b57db8775d2",
"bf1042c3-f301-4906-95fc-e22e0a346c34"
    ]
}'

Response

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

Response property

key	data type	nullable	description	example
rewardId	String	X	처리한 rewardId	c42ec5c3-5bcf-4e39-b7ed-4a9bdcf1be8e
confirmedResultCode	String	X	확인 결과 코드 해당 코드로 게임 로직 처리	SUCCESS
confirmedResultMessage	String	X	확인 결과 메시지 게임에서 참고용 메시지로 유저에게 노출 x

confirmedResultCode 정의 표

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

Response sample

application/json;charset=UTF-8
{
  "resultCode": "SUCCESS",
  "resultMessage": "request success",
  "resultData": [
    {
      "rewardId": "c42ec5c3-5bcf-4e39-b7ed-4a9bdcf1be8e",
      "confirmedResultCode": "SUCCESS",
      "confirmedResultMessage": ""
    },
    {
      "rewardId": "5f4d0c9e-71f9-4bc4-afb8-294b4b535c3b",
      "confirmedResultCode": "FAIL_STATUS_NOT_RESERVED",
      "confirmedResultMessage": "status is not Reserved. db.status: READY"
    }
  ]
}

공통 에러 코드 정의

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

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

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

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

에러 코드 목록

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