무료 아이템 지급 API 제작 가이드 (Deprecated)

쿠폰 등 무료 아이템 지급은 인벤토리 API 정의서 를 이용합니다.

해당 API는 인벤토리 연동이 불가능하거나, 특수한 목적으로 사용하는 API로, 제작이 필요한 경우 기술PM을 통해 제작 요청 드립니다.

해당 문서는 가이드이고 이후 추가 요청된 요구 사항 등을 감안해서 API 가이드를 작성 해 주셔야 합니다.

개요

게임플랫폼의 통합 쿠폰 시스템은 쿠폰의 발급과 사용(Redeem), 그리고 동일 쿠폰 유저 별 사용 회수 제한 등을 관리 합니다.

정상적인 쿠폰을 사용하였을 때, 쿠폰 시스템이 게임 아이템을 지급 하기 위해 게임 개발팀은 아이템 지급 API를 제공 해 주셔야 합니다.

Request와 Response 명세는 보편적인 시스템 구성과 도메인 규칙을 준수하기 위해 작성 된 가이드 입니다.

서비스 특성상 불필요한 정보는 제외 될 수 있으며, 명세의 변경이 필요한 부분은 협의가 가능합니다.

Request

HTTP Request end point에 대한 가이드

• /api/ingame/item/coupon_21315 형태의 API URL을 정의

  • 특정 고정된 랜덤 스트링은 혹시 모르는 보안 사고를 막기 위해서 임의로 정해서 사용 추천

  • 해당 url 포맷은 예제이고 어떤 url 포맷이어도 상관 없습니다.

POST https://각 환경별 게임서버 도메인/api/ingame/item/{특정한 고정된 랜덤 스트링}

HTTP Request Parameter

• Content-Type: application/json

• Content-Type: application/json 으로 요청됩니다.

key(1 depth)	key(2 depth)	type	required	설명	예
pjid		String(20)	Y	프로젝트ID	1004
serverId		String(20)	N	지급대상 게임서버 ID	ASIA_SERVER, 10040100 등
transactionId		String(20)	N	쿠폰 사용 트렌젝션 ID	02d530c1-bacd-4375-8498-32ae2dda2514
giveUser		json object	Y	상품을 지급해야하는 유저정보 데이터
	idType	String(10)	Y	ID종류	IMID, GAME_UID
	idValue	String(50)	Y	ID의 값
giveProductList		json array list		지급해야하는 상품 리스트
	itemId			아이템 ID	1234567
	quantity			지급 상품 개수	1

<key 상세 설명>

• pjid: 동일 게임이라면 서비스ID가 여러개일 수 있지만 프로젝트ID는 같습니다.

• serverId: 게임서버를 구분하지 않는 게임의 경우 null 일 수 있음

• transactionId: 쿠폰 사용 트렌젝션 ID

  • 주의: 게임서버에서는 해당 값을 기준으로 중복지급 방지 처리 필수 구현 하셔야 합니다.

    • 게임 서버간 통신 중에 API응답 지연 등으로 재 처리 요청될 수 있습니다.

    • 게임쪽에서는 boid 기준으로 유니크 인덱스 생성등을 통한 방어를 추천합니다.

• giveUser: 아이템을 지급해야하는 유저정보 데이터

  • idType

    • 여러 형태의 ID종류를 지원하기 위해서 type으로 구분하고 있습니다. (일반적으로 IMID를 기본으로 합니다.)

      • IMID: HYBE IM의 id로 플랫폼 로그인 후 얻게되는 id, 정책상 기본적으로 인게임에서 유저가 보게되는 id value의 종류

      • GAME_UID: 게임쪽에서 자체 정의한 유저ID

  • idValue: 게임에서는 해당 유저 id에게 상품을 지급

• giveProductList: 현재 1개의 상품만 판매하는 형태로 사용 중이지만 특정 결제 수단에서 여러 건의 상품 구매 기능이 존재해서 확장성을 위해서 리스트 형태로 준비 되었습니다.

  • itemId: 아이템 ID - 게임 내 우편으로 지급 될 아이템 ID

  • quantity: 지급 아이템 개수

Request Sample JSON

{
    "transactionId": "02d530c1-bacd-4375-8498-32ae2dda2514",
    "pjid": "9001",
    "serverId": "ASIA_SERVER",
    "giveUser": {
        "idType": "IMID",
        "idValue": "aaaabbbb-ccccddd-fffccc-tttggg"
    },
    "giveItemList": [
        {
            "itemId": "1234567",
            "quantity": 1
        },
        {
            "itemId": "test_1234",
            "quantity": 1
        }
    ]
}

Response

• Content-Type: application/json;charset=UTF-8

Response property

• 지급 성공일 때는 resultCode에 SUCCESS로 입력 후 아래 추가 데이터를 resultData 필드에 추가해서 응답

key	data type	description	example
giveCompletedAtUnixTS	Long	요청된 상품지급이 완료된 일시의 Unix Timestamp	1704872037
playerId	String(50)	실제 상품을 지급받은 playerId

<key 상세 설명>

• giveCompletedAtUnixTS: 요청된 상품지급이 완료된 일시의 Unix Timestamp

  • 게임쪽에서 일반적으로 사용이 편하신 Unix Timestamp로 전달을 추천 합니다.

  • 빌링 시스템에서 UTC 0 타임존으로 파싱해서 사용합니다.

  • 실제 게임에서 지급된 시간이 최소 오차로 필요하기에 응답 받아야합니다. (예. 월 변경이 발생했을 때 한도제한 로직)

• playerId: 실제 상품을 지급받은 playerId

  • 지급 API 호출은 imid로 요청되기 때문에 실제 상품을 지급받은 게임쪽의 playerId 응답이 필요합니다.

  • 게임의 유저 스콥에 따라서 imid값이 될 수도 있습니다.

• 지급 성공일 때는 resultCode에 SUCCESS로 입력 후 아래 추가 데이터를 resultData 필드에 추가해서 응답

Success sample

{
    "resultCode": "SUCCESS",
    "resultMessage": "request success",
    "resultData": {
        "giveCompletedAtUnixTS": 1704872037,
        "playerId" : "abcdef"
    }
}

Error Sample

• 지급 실패인 경우 HTTP 상태 코드는 200이지만 resultCode에 정의된 에러코드와 함께 참고할 수 있는 메시지를 resultMessage로 응답해주시면 됩니다.

• 게임쪽에서는 HTTP 상태 코드 관리에 어려운 경우가 많으셔서 상태코드는 200으로 처리해주시면 됩니다.{ "resultCode": "INVALID_USER", "resultMessage": "not exist userId." }

• 중복 지급 요청으로 에러인 경우 → ALREADY_GIVED_ITEM와 함께 이전에 지급했던 정보를 응답{ "resultCode": "ALREADY_GIVED_ITEM", "resultMessage": "already gived item '12345'. transactionId: '02d530c1-bacd-4375-8498-32ae2dda2514'", "resultData": { "giveCompletedAtUnixTS": 1706585356, "playerId" : "abcdef" } }

Error인 경우의 에러 코드 정의

• 아래의 에러 코드는 필수로 생각되는 에러 코드이며 추가되어야 할 에러코드가 있다면 공유 후 추가 가능

에러코드	비고
INVALID_PARAMETER	잘못된 파라미터로 API요청 시스템에서의 요청 파라미터가 잘못된 경우
INVALID_USER	잘못된 게임 유저 - 지급 해야 할 유저ID가 게임 내에 존재하지 않거나 제재 중인 경우 등 valid하지 않은 유저에게 상품 지급이 요청된 경우 에러코드 - 참고할 수 있는 상세 내용은 resultMessage에 전달해주시면 운영/디버깅에 좋습니다.
NOT_ALLOW_AUTH	API 사용 권한이 없는 경우 - 인증 정보가 잘못된 등 API 사용할 수 없는 요청인 경우
ALREADY_GIVED_PRODUCT	이미 지급 완료된 구매 건에 대해서 재 지급 요청 transactionId 기준으로 지급 여부를 판단하시면 됩니다. 아이템 지급하기 전에 transactionId로 꼭 중복 지급 여부를 체크하시기 바랍니다. (transactionId로 유니크 인덱스를 설정하실 수 있다면 추천) 게임 서버의 타임아웃 등의 이유로 쿠폰 시스템에서 지급 실패로 판단 한 경우, 쿠폰 시스템에서는 유저가 쿠폰을 사용(사용 인증) 한 상태로 전환 되어 게임 서버가 정상일 때 다시 아이템 지급을 요청 할 수 있습니다. 이 때 게임에서 이미 지급 된 경우라면 해당 에러 코드로 리턴하고 resultData의 giveCompletedAtUnixTS 필드에 지급 되었던 일시를 추가해주시면 됩니다.

# 파라미터 오류로 판별된 응답 json 샘플
{ 
    "resultCode": "INVALID_PARAMETER",
    "resultMessage": "duplicated reqeust. Check your 'reqId' or duplicated request data."
}