지급 대상 정보 조회 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 | 서버 에러 |