본문으로 건너뛰기

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

기본 정보​

  1. 예약을 성공한 아이템에 대해서 게임 서버에서는 유저에게 아이템을 지급합니다.
  2. 이 문서는 아이템 지급을 실패한 경우 인벤토리 시스템에 취소(영구 제외) 처리하기 위한 문서입니다.
    1. 영구 제외 취소 처리를 하면 **해당 아이템은 사용하지 않았더라도 **조회 목록에 노출되지 않습니다.
    2. 아이템 지급 처리 시점에 서비스 운영상 등으로 유저에게 아이템을 지급하지 않는 경우 사용하세요.
항목내용비고
호출주체게임서버(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/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 으로 호출하면 됩니다.
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

취소 처리할 아이템의 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​

keydata typenullabledescriptionexample
rewardIdStringX처리한 rewardIdc42ec5c3-5bcf-4e39-b7ed-4a9bdcf1be8e
canceledResultCodeStringX

취소 결과 코드

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

취소 결과 메시지

  • 게임에서 참고용 메시지로 유저에게 노출 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_ERROR500빌링 시스템 내부에서 처리 불가한 예외 발생으로 에러
INVALID_PARAMETER200잘못된 파라미터로 요청
NOT_ALLOW_AUTH200

권한이 없는 요청

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