멤버십 API 정의서

개요

HYBE Game Platform Service(이하 IM Assemble) 멤버 서비스를 게임에서 연동하기 위한 S2S RESTful API 사용법에 대해서 설명합니다.

API 기본

Request

Request Parameter는 JSON 형식으로 Request Body에 포함하고, Content-Type: application/json 헤더를 포함하여 호출합니다.

Response

HTTP STATUS

API 요청 http status 정의

서버가 정상 처리를 한 경우 OK 로 나오고 정의된 에러 코드를 반환 합니다.

Status

HTTP Code

Description

200

api 정상 처리

정의된 오류 코드를 포함 하여 api 가 result data 를 보낸 경우

BAD_REQUST

400

전송되는 request parameter 에 문제가 있는 경우

필수 Parameter 누락
Parameter Type이 맞지 않음

UNAUTHORIZATION

401

NOT_FOUND

404

api 주소가 잘못 된 경우

Internal Server Error

500

서버에서 알수 없는 exception 이 발생

에러 처리가 되지 않은 오류 발생
- ex)
  - null data
  - db exception
  - logic exception

API Result Json 구조

http status ok(200) 일 경우에만 result json 을 보냅니다.

Json 예시

{
  "resultCode": "SUCCESS",
  "resultMessage": "success",
  "resultData": {
    ...
  }
}

ResultCode 구성 방식

성공

SUCCESS

실패

정의 된 에러 코드

서버 인증 정보

게임 서버 요청 확인을 위한 accessKey 를 header 에 포함하여 요청

Request Header

Header

Value

X-Auth-Access-Key

기술PM에게 전달 받은 ACCESS KEY

X-Req-Pjid

기술PM에게 전달 받은 Req Pjid

IM Assemble Endpoint 정보

Environment

Endpoint

https://api-qa.pub-dev.hybegames.io

prod

https://api.hybegames.com

로그인 및 가입

회원 로그인과 가입과 관련된 S2S API 명세

sdk login 으로 전달 받은 loginVerifyToken 으로 login 정보 확인과 게임 로그인을 완료 합니다.

로그인 토큰 검증의 성공 여부와 함, 정상/제재와 같은 유저 상태를 전달 합니다.
- state가 BLOCKED 인 유저는 로그인을 제한 해야 합니다.
- state가 PENALIZED 인 일부 게임 컨텐츠의 이용이 제한된 유저는 함께 전달되는 blocks 에서 상세 제재 정보에 따라 게임 컨텐츠의 이용을 제한 해야 합니다.

loginVerifyToken 은 최대 1시간 동안 유효 합니다.

로그인 과정에서 여러 번 호출 하는 것이 가능하지만, 재사용 목적으로 장기간 사용하는 토큰이 아닙니다.

Endpoint

url
- /member/api-game/v1/auth/login/verify
method
- POST

Request Body

Parameter

Type

Description

loginVerifyToken

string

sdk 로그인 후 받은 로그인 인증용 토큰

serviceId

string

service id

Response

Parameter

Type

Description

resultCode

string

SUCCESS : 성공

INVALID_LOGIN_VERIFY_TOKEN : login 인증 토큰 오류

LOGIN_VERIFY_EXPIRED : login 인증 토큰 만료

INVALID_SERVICE_ID : 유효 하지 않은 서비스 id

WITHDRAWAL_ACCOUNT : 탈퇴 대기 상태 유저

RELOGIN_REQUIRED : 로그인 데이터에 문제가 있어 다시 로그인 해야 되는 경우

INTERNAL_SERVER_ERROR : 서버 오류

resultMessage

string

resultData

LoginVerifyResult?

Nullable

result code SUCCESS 가 아닐 경우 null

LoginVerifyResult

Parameter

Type

Description

state

string

NORMAL (정상)

BLOCKED (게임 접속 제한)

PENALIZED (게임 컨텐츠 제한)

imId

string

im account 고유 ID

provider

Enum

로그인 인증 수단

GOOGLE
APPLE
STEAM
LINE
IM
TWITTER

Enum

client os Type

IOS
ANDROID
WIN64
WIN32
MACOS
LINUX

appStore

Enum

게임 설치 store

GOOGLE_PLAY
GOOGLE_PLAY_PC
APPLE_APP_STORE
STEAM
IM_LAUNCHER

blocks

List<UserBlockInfo>

제재 정보

connected

Boolean

service id 에 해당하는 게임 유저 연결 상태

UserBlockInfo

Parameter

Type

설명

blockId

int

제재 ID

reasonId

int

사유 ID

durationMinutes

int

제재 기간(분 단위)

blockedAt

Long

제재 적용 시간

expireAt

Long

제재 만료 시간

permanent

Boolean

영구제재 유무

영구 제재 : true
일반 제재 : false

metadata

String

게임사 전달 데이터

게임사에서 제재 시 설정한 값

Response Example

{
  "resultCode": "SUCCESS",
  "resultMessage": "success",
  "resultData": {
    "state": "BLOCKED",
    "imId": "aaaa-aaaa-aaaa-aaaa-aaaa",
    "provider": "GOOGLE",
    "os": "ANDROID",
    "appStore": "GOOGLE_PLAY",
    "blocks": [
      {
        "blockId": 1,
        "reasonId": 1,
        "durationHour": 3,
        "blockedAt": 1611110101,
        "expireAt": 1611110101,
        "permanent": false,
        "metadata": "{\"field\": \"testvalue\"}"
      },
      ...
    ],
    "connected": false
  }
}

Get Info (멤버십 정보 조회)

imId 를 이용한 계정 정보 확인

Endpoint

url
- /member/api-game/v1/user/info
method
- GET

Request Parameter

Parameter

Type

Description

imId

string

sdk 로그인 후 받은 IMID

Response

Parameter

Type

Description

Parameter

Type

desc

resultCode

string

SUCCESS : 성공

NO_ACCOUNT: 회원 정보 없음

INTERNAL_SERVER_ERROR : 서버 오류

resultMessage

string

resultData

GetAccountResult?

Nullable

result code SUCCESS 가 아닐 경우 null

GetAccountResult

Parameter

Type

Description

state

string

NORMAL(정상)

BLOCKED(게임 접속 제한)

PENALIZED (게임 컨텐츠 제한)

WITHDRAWAN (탈퇴)

imId

string

im account 고유 ID

blocks

List<UserBlockInfo>

제재 정보

BLOCKED 일 경우 게임 접속 제한 데이터만 전달 드립니다.

PENALIZED 일 경우 컨텐츠 제한 데이터만 전달 드립니다.

providers

List<String>

로그인 수단 List

GOOGLE
APPLE
STEAM
LINE
IM
TWITTER

UserBlockInfo

Parameter

Type

Description

Parameter

Type

설명

blockId

int

제재 ID

reasonId

int

사유 ID

durationMinutes

int

제재 기간(분 단위)

blockedAt

Long

제재 적용 시간

expireAt

Long

제재 만료 시간

permanent

Boolean

영구제재 유무

영구 제재 : true
일반 제재 : false

metadata

String

게임사 전달 데이터

게임사에서 제재 시 설정한 값

Response Example

{
  "resultCode": "SUCCESS",
  "resultMessage": "success",
  "resultData": {
    "state": "NORMAL",
    "imId": "aaaabbbb-ccccddd-fffccc-tttggg",
    "provider": "GOOGLE",
    "blocks": [
      {
        "blockId": 1,
        "reasonId": 1,
        "durationMinutes": 3,
        "blockedAt": 1611110101,
        "expireAt": 1611110101,
      },
      ...
    ]
  }
}

Connect User (게임 신규 가입 유저의 IM Assemble 계정 연동)

IM Assemble 계정 연동

로그인 이후 게임 User 생성 후 기타 서비스 이용을 위해 필수 연동 필요

Endpoint

url
- /member/api-game/v1/user/connect
method
- POST

Request Body

Parameter

Type

Description

imId

string

im account 고유 ID

serviceId

string

기술PM에게 전달 받은 SERVICE ID

userId

string

게임사 계정 고유 ID

Request Parameter

{
  "imId": "aaaa"
  "userId": "aaabbcc",
  "serviceId": "10060000"
}

Response

Parameter

Type

Description

resultCode

string

SUCCESS : 성공

NO_ACCOUNT: 회원 정보 없음

NOT_ALLOWED_SERVICE : 유효 하지 않은 service id

ALREADY_CONNECTED_USER : 이미 imId 와 연결된 user id

EXIST_SERVICE_USER : SERVICE 에 USER 가 존재

INTERNAL_SERVER_ERROR : 서버 오류

resultMessage

string

{
  "resultCode": "SUCCESS",
  "resultMessage": "success"
}

제재

게임 이용 제한을 위한 제재 연동 API

IM Assemble의 제재 기능은 유저 별 제재 상태와 이력을 관리 하는 것을 목표로 설계 되었습니다.

제재 상태와 이력 일원화 관리
- IM Assemble 통합 관리툴을 통해 제재 상태와 이력을 조회하고 접속 제한을 처벌 할 수 있습니다.
- 제재를 통해 게임 혹은 GMTool에서 제재를 처벌/해제 할 수 있습니다.
기간제 제재 시작/종료 관리
- 유저 제재 정보 갱신 API 제작 가이드를 통해 제재 정보가 변경되면 게임서버에 알려드립니다.

유저별 제재에 따른 게임 내 알림이나 컨텐츠 제약 사항은 게임에서 직접 구현 하셔야 합니다.

게임 내 컨텐츠 제재(페널티)는 게임의 특성에 따라 다양한 요소가 필요 할 수 있으며, 컨텐츠, 자원소비, 구매 제재항목과 제재을 참고하여 게임 내 페널티 종류 별 제재 ID를 정의 하시고 공유 주시면 됩니다.

제재ID는 동일 제재 중복 처벌을 막기 위한 제재의 소분류를 구별하는 키 입니다.
사유ID는 게임 내 유저에게 노출 하는 메시지의 다국어 처리 등을 위해 사용하는 값이며, 게임에서 임의대로 지정이 가능합니다.

제재 요청

Endpoint

url
- /member/api-game/v1/user/block
method
- POST

Request

Parameter

Type

Description

imId

string

sdk 로그인 후 받은 hybe im 계정 id

blockId

int

제재 id

durationMinutes

int

제재 기간(분 단위)

reasonId

int

사유 id

metadata

String

게임사 제재 정보

게임사 GM 툴 이용 시 전달 되는 데이터 저장

플랫폼 환경 제재 시는 공백 저장

permanent

boolean

영구제재 유무

50년 강제 적용

memo

string?

제재 내역 admin tool 조회 용도 메모(선택)

Response

Parameter

Type

Description

resultCode

string

SUCCESS : 성공

NO_ACCOUNT: 회원 정보 없음

INVALID_BLOCK_ID : 유효하지 않은 제재 id

INVALID_REASON_ID : 유효하지 않은 사유 id

실제 구현 중 에러코드가 추가 될 수 있습니다.

INTERNAL_SERVER_ERROR : 서버 오류

resultMessage

string

resultData

List<BlockResponse>

BlockResponse

Parameter

Type

Description

sendGameServerResults

BlockSendGameServerResponse

게임 서버 api 호출 결과

BlockSendGameServerResponse

Parameter

Type

Description

serviceId

String

success

Boolean

게임 서버 요청 성공 여부

Response Example

{
    "resultCode": "SUCCESS",
    "resultMessage": "success",
    "resultData": {
        "sendGameServerResults": [
            {"serviceId": "10040000", "success": true},
            {"serviceId": "10040010", "success": false},
        ]
    }
}

제재 ID

제재 ID는 플랫폼과 협의하여 추가 가능

유형

구분

우선순위

설명

게임 접속 제한

운영 정책 상 게임 이용 제한 ℹ️ 게임 접속 제한의 경우만 우선 순위가 적용 됩니다.

101

게임 접속 제한

임시 제재

임시 접속 제재

10001

게임 컨텐츠 제한

채팅 이용 제한

999

10101

게임 컨텐츠 제한

컨텐츠 이용 제한(던전 류)

10102

게임 컨텐츠 제한

자원 소비 제한(재화,아이템류 소모 제한)

10103

게임 컨텐츠 제한

자원 변화 제한(아이템 상태 변화 불가-구매/강화/돌파 등 제한)

제재 사유 ID

게임 내 표시(주로 게임 내 다국어 키와 매칭됩니다.) 와 GMTool 표시 등의 목적으로 제재 사유를 정의 합니다.

제재 사유 ID 와 제재 ID 는 1:1 관계가 아닙니다.

동일한 제재 유형에 다른 사유가 유저에게 노출 되어야 하거나, 다른 제재에 동일한 유저 사유가 노출 되어야 하는 경우 등 처벌되는 제재의 유형과 유저에게 노출 되는 사유가 다를 수 있는 점을 확인 하시고, 제재의 종류에 따라 유연하게 구성 할 수 있는 점 참고 바랍니다.

구분

연관 제재 ID

게임 운영 방해

작명 정책 위반

현금 거래

사행성 조장

사칭·사기

결제 프로세스 악용

데이터 변조·해킹

비인가 프로그램 사용 및 제작·유포·판매·공유·홍보

비인가 프로그램 사용 시도 의심

다수 계정 및 집단적인 비정상 플레이 패턴 감지

게임 오류 사용

게임 오류 악용 및 비정상 플레이 전파·유포

명의·계정·결제 도용

개인정보 유출 및 권리 침해

서비스 담당자 인권 침해 및 운영 방해

101

운영자 임시 접속 제한

인벤토리 변경 등의 사유로 일시 접속 제한

10001

채팅 이용 제한

10101

아레나 이용 제한

10201

재화(1) 사용 제한

10202

재화(2) 사용 제한

10203

재화(3) 사용 제한

10204

재화(4) 사용 제한

10205

아이템 사용 제한

제재 해제 요청

Endpoint

url
- /member/api-game/v1/user/unblock
method
- POST

Request Body

Parameter

Type

Description

imId

string

sdk 로그인 후 받은 IMID

blockId

int

제재 id

memo

string?

제재 내역 admin tool 조회 용도 메모(선택)

Response

Parameter

Type

Description

resultCode

string

SUCCESS : 성공

NO_ACCOUNT: 회원 정보 없음

NO_BLOCK : 제재 id 에 해당하는 제재가 설정 되어 있지 않음

INVALID_BLOCK_ID : 유효하지 않은 제재 id

INVALID_REASON_ID : 유효하지 않은 사유 id

실제 구현 중 에러코드가 추가 될 수 있습니다.

INTERNAL_SERVER_ERROR : 서버 오류

resultMessage

string

resultData

UnBlockResponse

UnBlockResponse

Parameter

Type

Description

sendGameServerResults

List<UnBlockSendGameServerResponse>

게임 서버 api 호출 결과

UnBlockSendGameServerResponse

Parameter

Type

Description

serviceId

String

success

Boolean

게임 서버 요청 성공 여부

Response Example

{
    "resultCode": "SUCCESS",
    "resultMessage": "success",
    "resultData": {
        "sendGameServerResults": [
            {"serviceId": "10040000", "success": true},
            {"serviceId": "10040010", "success": false},
        ]
    }
}

부가 기능

게임 계정 재연동

한번의 API호출로 기존 게임 계정을 연동 해제하고 새 게임 계정 ID로 연동시키는 API입니다. 연동 해제부터 연동까지 진행하여 리세마라 편의를 위해 제공됩니다.

Endpoint

url
- /member/api-game/v1/user/reconnect
method
- POST

Request Body

Parameter

Type

Required

Description

Example

imId

String

IM 플랫폼 IMID

JESAMVAPSWLQ8YH2RFS8

serviceId

String

서비스 ID

10080020

disconnectUserId

String

연동 해제할 기존 게임 계정 고유 ID

검증 목적으로 기존 게임 계정 고유 ID를 받습니다.

472fabbc-fa02-4876-a56b-c335cbe78aab

connectUserId

String

새로 연동할 게임 계정 고유 ID

로직상 연동 해제에 성공하면 이 ID로 새롭게 연동시킵니다.

co2fabbc-fp1k-1116-c92b-c335cbe7887h

Request Parameter 상세 설명

imId: IM 플랫폼에서 관리하는 서비스별 유저에게 부여된 ID입니다.
serviceId: 게임에 부여된 서비스 ID입니다.
disconnectUserId: 연동을 해제할 게임 계정 고유 ID입니다. 기존에 이 ID로 연동된 것이 맞는지 검증하기 위한 목적으로 받습니다.
connectUserId: 새로 연동할 게임 계정 고유 ID입니다. 새로 연동할 ID이므로 이 ID로 이미 계정이 존재한다면 유효하지 않은 요청으로 간주하여 API호출이 실패합니다.

Request Body Sample JSON

{
    "imId": "JESAMVAPSWLQ8YH2RFS8", 
    "serviceId": "10080020", 
    "disconnectUserId": "472fabbc-fa02-4876-a56b-c335cbe78aab",  
    "connectUserId": "co2fabbc-fp1k-1116-c92b-c335cbe7887h"     
}

CURL Sample

curl --location 'http://{플랫폼 도메인}/member/api-game/v1/user/reconnect' \
--header 'X-Auth-Access-Key: {accessKey}' \
--header 'X-Req-Pjid: {프로젝트ID}' \
--header 'Content-Type: application/json' \
--data '

{
    "imId": "JESAMVAPSWLQ8YH2RFS8", 
    "serviceId": "10080020", 
    "disconnectUserId": "472fabbc-fa02-4876-a56b-c335cbe78aab",  
    "connectUserId": "co2fabbc-fp1k-1116-c92b-c335cbe7887h"     
}'

Response

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

Success case

성공일 경우 resultCode에 SUCCESS로 드립니다. 추가적인 데이터(resultData등)는 별도로 제공하지 않습니다. 따라서 resultData필드는 불필요하여 null값으로 제공됩니다.

Success case sample

{
    "resultCode": "SUCCESS",
    "resultMessage": "success",
    "resultData": null
}

Error case

재연동 실패인 경우 HTTP 상태 코드는 200이지만, resultCode에 에러에 대한 코드를 전달드립니다. 이때 에러에 대한 상세 사유는 resultMessage필드를 참고하시면됩니다.

Error인 경우 에러 코드 정의

Error code

Description

NO_ACCOUNT

전달받은 IMID에 대한 플랫폼 계정이 존재하지 않는 경우

ALREADY_CONNECTED_USER

연동하려는 게임 계정 ID(connectUserId)가 이미 존재하는 경우 - 이미 연동된 게임 계정 ID에 대해 한번 더 연동할 수는 없으므로 유효하지 않은 요청으로 간주하여 실패합니다.

NOT_ALLOWED_SERVICE

유효하지 않은 서비스ID를 전달한 경우 - 플랫폼에서 관리하는 프로젝트 설정에서 전달받은 프로젝트 ID 내(헤더 X-Req-Pjid 필드)에 정의된 서비스ID(serviceId)가 존재하지 않는 경우이므로 유효하지 않은 요청으로 간주하여 실패합니다.

NO_PROJECT_ACCOUNT

플랫폼 내에 해당 프로젝트(pjId)의 계정이 존재하지 않는 경우

WITHDRAWN_PROJECT_ACCOUNT

서비스 이용동의 철회 처리 중인 계정인 경우 - 이용동의 철회 상태에서는 해당 요청을 처리할 수 없습니다.

WITHDRAWN_ACCOUNT

계정 탈퇴 처리 중인 계정인 경우 - 계정 탈퇴 상태에서는 해당 요청을 처리할 수 없습니다.

NO_CONNECTED_SERVICE

전달받은 서비스ID가 기존 계정에 정보가 없는 경우 - 이 경우 전달받은 서비스 ID(serviceId)값이 플랫폼 계정에 존재하지 않기 때문에 유효하지 않은 요청이므로 연결 해제를 진행할 수 없습니다.

INVALID_PARAMETER

연동 해제할 게임 계정 고유 ID가 기존에 해당 계정(imId)의 게임 계정 고유 ID와 일치 하지 않는 경우 - 이 경우 잘못된 게임 계정 고유 ID를 해제하려는 시도이므로 유효하지 않은 요청으로 간주하여 연결 해제를 진행할 수 없습니다.

COMMON_INTERNAL_SERVER_ERROR

플랫폼 서버 내에서 서버 오류로 연동 해제 및 재연동에 실패한 경우

Error case sample

{
    "resultCode": "ALREADY_CONNECTED_USER",
    "resultMessage": "already connected user",
    "resultData": null
}

테스트 지원 기능

QA 환경에서만 사용할 수 있는 테스트 지원 기능 입니다.

Game Account ID 연결 해제

게임 계정을 즉시 연결 해제 합니다. 연결 해제 후 로그인 하시면 신규 IMID가 발급되며 게임에서 신규 가입이 진행 됩니다.

연결 해제 된 이전 IMID 로 복구 할 수 없습니다.
게임 이용 중인 유저를 즉시 연결 해제를 하는 경우 플랫폼 연동 기능이 비정상적으로 동작 할 수 있습니다.

Endpoint

url
- /member/api-game/v1/dev/user/disconnect
method
- POST

환경 정보

env

accessKey

별도 요청

Request Body

필드

type

desc

imId

string

im account 고유 ID

serviceId

string

service id

Response

필드

타입

desc

resultCode

String

SUCCESS : 성공

NO_ACCOUNT: 회원 정보 없음

NOT_ALLOWED_SERVICE : 유효 하지 않은 service id

INTERNAL_SERVER_ERROR : 서버 오류

NOT_ALLOWED_SERVICE: 허용되지 않는 요청 환경

resultMessage

String

resultData

null

Previous환경 설정 Next빌링 API 정의서

Last updated 1 month ago

개요

API 기본

Request

Response

HTTP STATUS

API Result Json 구조

ResultCode 구성 방식

서버 인증 정보

IM Assemble Endpoint 정보

로그인 및 가입

Login Verify (로그인 토큰 검증)

Endpoint

Request Body

Response

Response Example

Get Info (멤버십 정보 조회)

Endpoint

Request Parameter

Response

Response Example

Connect User (게임 신규 가입 유저의 IM Assemble 계정 연동)

Endpoint

Request Body

Request Parameter

Response

제재

제재 요청

Endpoint

Request

Response

Response Example

제재 ID

제재 사유 ID

제재 해제 요청

Endpoint

Request Body

Response

Response Example

부가 기능

게임 계정 재연동

Endpoint

Request Body

Response

테스트 지원 기능

Game Account ID 연결 해제

Endpoint

환경 정보

Request Body

Response