지급 대상 정보 조회 API
지급 대상 정보 조회 API는 웹 상점에 접속한 사용자의 앱 서버, 채널, 캐릭터 정보를 불러오기 위한 API입니다. 하이브 서버에서 앱으로 지급 대상 정보 조회 API를 요청하면, 앱에서 하이브 서버로 응답값을 반환합니다.
개요¶
웹 상점을 이용할 때, 웹 상점에서 구매하기 UI를 구현하려면 아래와 같이 접속한 사용자의 앱 서버, 채널, 캐릭터 정보가 필요합니다.
이 API 사용을 포함한 전체 과정을 요약하면 아래와 같습니다.
- 앱: API 엔드포인트를 구성해 앱 서버 URL을 준비
- 앱: 하이브 콘솔 하이브 콘솔 > 커뮤니티 & 웹 상점 > 웹 상점 > 웹 상점 설정 > 지급 대상 정보에서 하이브 서버에 전달할 지급 대상 정보 API URL을 등록
- 하이브 서버: 앱에서 등록한 지급 대상 정보 API URL로 POST API 요청, 응답값으로 데이터 수령
- 하이브 서버: 수령한 앱 서버, 채널, 캐릭터 정보를 프론트엔드로 전송
- 웹 상점 프론트엔드: 웹 상점 구매하기 UI에서 드롭다운 메뉴를 노출
API 엔드포인트 구성(앱 서버 URL)¶
하이브 콘솔 > 커뮤니티 & 웹 상점 > 웹 상점 > 웹 상점 설정 > 지급 대상 정보에 API 엔드포인트를 등록합니다.
API 엔드포인트는 요청을 받을 때 요청 매개변수에 있는 사용자 정보(cs_code)를 받고, 응답으로 앱 서버, 채널, 캐릭터 정보를 전달해야 합니다. API 엔드포인트는 하이브 콘솔(상용, 샌드박스)에 대응해 아래 예시와 같이 구성합니다.
| 콘솔 환경 | API 엔드포인트 |
|---|---|
| 상용 | https://{URL}/webstore-profile |
| 샌드박스 | https://{URL}/webstore-profile |
API 요청(하이브 서버 → 앱 서버) 구성¶
하이브 서버에서 앱 서버로 보내는 POST 요청 정보입니다. 앱 서버 리스트, 서버에 포함된 채널, 그리고 캐릭터 목록을 응답으로 받습니다.
| API 정보 | 설명 |
|---|---|
| Method | POST |
| Response Format | JSON |
| Content-type | application/json |
다음은 Request Body 정보입니다.
| 명칭 | 타입 | 필수 여부 (필수: O, 옵션: X) | 설명 |
|---|---|---|---|
| cs_code | Integer | O | 사용자 고유 식별자(Player ID) |
다음은 Request Body 예시입니다.
API 응답(앱 서버 → 하이브 서버) 구성¶
응답 성공 시, 앱 서버에서 하이브 서버로 전달해야 하는 응답값 정보입니다. 상품별로 캐릭터 레벨에 따른 구매 제한 기능을 위해, 하이브 콘솔 인앱 정보에서 캐릭터를 선택하지 않았더라도 캐릭터 레벨 정보를 전달해야 합니다. 캐릭터를 미선택한 경우, 배열(data.channels.characters)에 캐릭터가 여러 개 있다면 배열 첫 번째 원소에 해당하는 캐릭터의 레벨을 사용합니다.
| 명칭 | 타입 | 필수 여부(필수: O, 옵션: X) | 설명 |
|---|---|---|---|
| result_code | Integer | O | 결과 코드 |
| result_message | String | O | 결과 메시지 |
| cs_code | Integer | O | 사용자 고유 식별자(Player ID) |
| data | Array | O | 서버 리스트(사용자 정보 없을 경우 응답 값: "[ ]") |
| data.server_id | String | O | 서버 고유 식별자 |
| data.server_name | String | O | 서버의 이름 |
| data.channels | Array | O | 서버에 포함된 채널 리스트 |
| data.channels.channel_id | String | O | 채널 고유 식별자(채널 미사용 시 응답 값: "0") |
| data.channels.channel_name | String | O | 채널의 이름(채널 미사용 시 응답 값: "-") |
| data.channels.characters | Array | O | 채널에 포함된 캐릭터 리스트 |
| data.channels.characters.character_id | String | O | 캐릭터 고유 식별자(캐릭터 미사용 시 응답 값: "-") |
| data.channels.characters.character_name | String | O | 캐릭터의 이름(캐릭터 미사용 시 응답 값: "-") |
| data.channels.characters.character_level | String | O | 캐릭터의 레벨(캐릭터 레벨이 없는 경우 응답값: "0") |
다음은 응답 성공 시 응답값 예시입니다.
// 1. 하이브 콘솔에서 서버, 채널, 캐릭터 선택 시
{
"result_code": 200,
"result_message": "success",
"cs_code": 100001234,
"data": [
{
"server_id": "1",
"server_name": "Server 1",
"channels": [{
"channel_id": "1",
"channel_name": "Channel 1",
"characters": [{
"character_id": "A",
"character_name": "Character A",
"character_level": "99"
},
{
"character_id": "B",
"character_name": "Character B",
"character_level": "10"
}
]
}]
}
]
}
// 2. 하이브 콘솔에서 서버, 캐릭터 선택 시
{
"result_code": 200,
"result_message": "success",
"cs_code": 100001234,
"data": [
{
"server_id": "2",
"server_name": "Server 2",
"channels": [{
"channel_id": "0",
"channel_name": "-",
"characters": [{
"character_id": "C",
"character_name": "Character C",
"character_level": "11"
},
{
"character_id": "D",
"character_name": "Character E",
"character_level": "12"
}
]
}]
}
]
}
// 3. 하이브 콘솔에서 서버, 채널 선택 시
{
"result_code": 200,
"result_message": "success",
"cs_code": 100001234,
"data": [
{
"server_id": "3",
"server_name": "Server 3",
"channels": [{
"channel_id": "2",
"channel_name": "Channel 2",
"characters": [{
"character_id": "-",
"character_name": "-",
"character_level": "99"
}]
}]
}
]
}
// 4. 하이브 콘솔에서 서버만 선택 시
{
"result_code": 200,
"result_message": "success",
"cs_code": 100001234,
"data": [
{
"server_id": "4",
"server_name": "Server 4",
"channels": [{
"channel_id": "0",
"channel_name": "-",
"characters": [{
"character_id": "-",
"character_name": "-",
"character_level": "99"
}]
}]
}
]
}
// 5. 하이브 콘솔에서 서버, 채널, 캐릭터 선택 시 - 채널이 여러 개인 경우
{
"result_code": 200,
"result_message": "success",
"cs_code": 100001234,
"data": [
{
"server_id": "1",
"server_name": "Server 1",
"channels": [
{
"channel_id": "1",
"channel_name": "Channel 1",
"characters": [
{
"character_id": "A",
"character_name": "Character A",
"character_level": "99"
}, {
"character_id": "B",
"character_name": "Character B",
"character_level": "10"
}
]
}, {
"channel_id": "2",
"channel_name": "Channel 2",
"characters": [
{
"character_id": "A2",
"character_name": "Character A2",
"character_level": "99"
}, {
"character_id": "B2",
"character_name": "Character B2",
"character_level": "10"
}
]
}
]
}
]
}
다음은 응답 코드(result_code) 정의입니다.
| 코드 | 설명 |
|---|---|
| 200 | 성공 |
| 204 | 사용자에 대한 정보 없음 |
| 500 | 서버 에러 |