인벤토리 아이템 사용 취소 및 영구 제외

기본 정보

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

2. 이 문서는 아이템 지급을 실패한 경우 인벤토리 시스템에 취소(영구 제외) 처리하기 위한 문서입니다.

   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/cancel/drop

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	IMID
userValue	String	O	상품을 받게될 유저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/cancel/drop' \
--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": [
"fe0fa75c-7b36-495b-8aaf-c494ff49878c",
"bf1042c3-f301-4906-95fc-e22e0a346c34"
    ]
}'

Response

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

Response property

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

canceledResultCode 정의 표

코드	설명	처리 방향
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",
      "canceledResultCode": "FAIL_STATUS_NOT_RESERVED",
      "canceledResultMessage": "status is not Reserved. db.status: DONE"
    },
    {
      "rewardId": "5f4d0c9e-71f9-4bc4-afb8-294b4b535c3b",
      "canceledResultCode": "SUCCESS",
      "canceledResultMessage": ""
    }
  ]
}

공통 에러 코드 정의

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

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

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

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

에러 코드 목록

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