멤버십 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
OK	200	api 정상 처리 정의된 오류 코드를 포함 하여 api 가 result data 를 보낸 경우
BAD_REQUST	400	전송되는 request parameter 에 문제가 있는 경우 필수 Parameter 누락 Parameter Type이 맞지 않음
UNAUTHORIZATION	401	login token authrization 처리 실패
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
qa	https://api-qa.pub-dev.hybegames.io
prod	https://api.hybegames.com

로그인 및 가입

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

Login Verify (로그인 토큰 검증)

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	login verify 결과 데이터 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
os	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	login verify 결과 데이터 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는 플랫폼과 협의하여 추가 가능

ID	유형	구분	우선순위	설명
1	게임 접속 제한	게임 접속 제한	1	운영 정책 상 게임 이용 제한 ℹ️ 게임 접속 제한의 경우만 우선 순위가 적용 됩니다.
101	게임 접속 제한	임시 제재	2	임시 접속 제재
10001	게임 컨텐츠 제한	채팅 이용 제한	999
10101	게임 컨텐츠 제한	컨텐츠 이용 제한(던전 류)
10102	게임 컨텐츠 제한	자원 소비 제한(재화,아이템류 소모 제한)
10103	게임 컨텐츠 제한	자원 변화 제한(아이템 상태 변화 불가-구매/강화/돌파 등 제한)

제재 사유 ID

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

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

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

ID	구분	연관 제재 ID
1	게임 운영 방해	1
2	작명 정책 위반
3	현금 거래
4	사행성 조장
5	사칭·사기
6	결제 프로세스 악용
7	데이터 변조·해킹
8	비인가 프로그램 사용 및 제작·유포·판매·공유·홍보
9	비인가 프로그램 사용 시도 의심
10	다수 계정 및 집단적인 비정상 플레이 패턴 감지
11	게임 오류 사용
12	게임 오류 악용 및 비정상 플레이 전파·유포
13	명의·계정·결제 도용
14	개인정보 유출 및 권리 침해
15	서비스 담당자 인권 침해 및 운영 방해
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	Y	IM 플랫폼 IMID	JESAMVAPSWLQ8YH2RFS8
serviceId	String	Y	서비스 ID	10080020
disconnectUserId	String	Y	연동 해제할 기존 게임 계정 고유 ID 검증 목적으로 기존 게임 계정 고유 ID를 받습니다.	472fabbc-fa02-4876-a56b-c335cbe78aab
connectUserId	String	Y	새로 연동할 게임 계정 고유 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
QA	별도 요청

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