---
title: 패널 API로 외부에서 서버를 조작하기
description: "게임 패널 접속 중인 플레이어 목록 조회, 전체 공지, 킥·차단, 저장, 재시작과 같은 작업은 **게임 패널의 API**를 사용하여 외부 프로그램에서 실행하실 수 있습니다. 이 페이지에서는 API 키 발급부터 명령 실행 결과를 받는 방법까지 안내해 드립니다. 약 5분 소요업데이트 2026-08-13모든 요금제…"
url: "https://gss.bestnetllc.co.jp/ko/docs/%ed%8c%a8%eb%84%90-api%eb%a1%9c-%ec%99%b8%eb%b6%80%ec%97%90%ec%84%9c-%ec%84%9c%eb%b2%84%eb%a5%bc-%ec%a1%b0%ec%9e%91%ed%95%98%ea%b8%b0/"
updated: "2026-08-13"
category: 게임 패널
---

# 패널 API로 외부에서 서버를 조작하기

게임 패널

접속 중인 플레이어 목록 조회, 전체 공지, 킥·차단, 저장, 재시작과 같은 작업은 **게임 패널의 API**를 사용하여 외부 프로그램에서 실행하실 수 있습니다. 이 페이지에서는 API 키 발급부터 명령 실행 결과를 받는 방법까지 안내해 드립니다.

 약 5분 소요업데이트 2026-08-13모든 요금제

## 이 페이지에서 할 수 있는 것

게임 패널의 API(클라이언트 API)를 사용하면 다음과 같은 작업을 외부 프로그램이나 스크립트에서 자동화하실 수 있습니다.

- 접속 중인 플레이어 목록 조회
- 전체 공지 전송
- 플레이어 킥·차단
- 수동 저장
- 서버 시작·정지·재시작
- 가동 상태(CPU·메모리·디스크·통신량) 조회

API는 게임 종류와 관계없이 이용하실 수 있습니다. 게임별 명령어는 각 게임의 문서를 참조해 주세요.

## API 키 발급

1. 게임 패널에 로그인하신 뒤, 화면 우측 상단의 계정 메뉴에서 **「API Credentials(API 자격 증명)」**을 엽니다.
2. 용도를 알 수 있는 설명을 입력하고 생성합니다.
3. 표시된 키를 따로 보관합니다.

 API 키는 **생성 직후 한 번만 표시됩니다**. 화면을 닫으면 다시 표시할 수 없으므로 이 시점에 반드시 보관해 주세요. **「Allowed IPs(허용 IP)」**에 API를 실행할 단말이나 VPS의 고정 IP 주소를 입력해 두시면 해당 주소에서만 사용할 수 있게 됩니다. 비워 두면 어디에서나 사용할 수 있으므로, 고정 IP가 있으시다면 꼭 설정해 주세요.

API 키는 계정당 **최대 25개**까지 만드실 수 있습니다. 용도별로 나누어 만들고, 필요 없어진 키는 삭제해 주세요.

## 기본 사용법

기본 URL은 다음과 같습니다.

```
https://gsv.bestnetllc.co.jp/api/client
```

요청에는 다음 헤더를 함께 보냅니다.

```
Authorization: Bearer <API 키>
Accept: application/json
Content-Type: application/json   ← POST의 경우
```

**서버 식별자**는 패널에서 서버를 열었을 때의 URL `https://gsv.bestnetllc.co.jp/server/xxxxxxxx`의 **마지막 8자**입니다.

## 주요 엔드포인트

| 서버 목록 | `GET /api/client` |   |
| --- | --- | --- |
| 명령 전송 | `POST /api/client/servers/{id}/command` | 본문 `{"command":"..."}` / 성공 시 204 |
| 시작·정지·재시작 | `POST /api/client/servers/{id}/power` | 본문 `{"signal":"start"}` (stop / restart / kill) |
| 상태·리소스 | `GET /api/client/servers/{id}/resources` | 상태·CPU·메모리·디스크·통신량·가동 시간 |
| 콘솔 접속 정보 | `GET /api/client/servers/{id}/websocket` | 실행 결과를 읽을 때 사용(05 참조) |

명령을 전송하는 예:

```
curl -X POST "https://gsv.bestnetllc.co.jp/api/client/servers/xxxxxxxx/command" 
  -H "Authorization: Bearer ptlc_xxxxxxxxxxxxxxxxxxxxxxxxxxxx" 
  -H "Accept: application/json" 
  -H "Content-Type: application/json" 
  -d '{"command":"Info"}'
```

## 명령 실행 결과 받기

 `POST /command`는 **204 No Content**만 반환하며 **실행 결과는 응답 본문에 포함되지 않습니다**. 존재하지 않는 명령을 보내도 204가 반환됩니다. **204는 「명령이 콘솔에 전달되었다」는 의미이며, 성공을 보장하지 않습니다.**

실행 결과를 읽으시려면 콘솔(WebSocket)에 접속합니다.

1. `GET /api/client/servers/{id}/websocket`을 호출하면 접속 URL(`socket`)과 `token`이 반환됩니다.
2. 해당 `socket`에 WebSocket으로 접속합니다.
3. 접속 후 먼저 `{"event":"auth","args":["<token>"]}`을 전송합니다. `{"event":"auth success"}`가 오면 인증 완료입니다.
4. 이후 `{"event":"console output","args":["..."]}` 형태로 콘솔 출력이 전달됩니다.
5. 같은 연결에서 `{"event":"send command","args":["..."]}`를 보내실 수도 있습니다.

 전송과 수신을 하나의 연결로 처리할 수 있으므로 **5번 방법을 권장**합니다. RCON에 가장 가까운 사용 방식입니다. `token`의 유효 기간은 **10분**입니다. 장시간 연결하시는 경우에는 `websocket` 엔드포인트에서 `token`을 다시 받아 `{"event":"auth","args":["<새 token>"]}`을 다시 보내 주세요.

접속 대상은 패널 도메인이 아니라 서버가 가동 중인 노드의 호스트명(포트 8443)입니다. 정상적인 동작입니다.

## 제한 및 주의사항

- 요청 제한은 **1분당 256회**입니다. 계정 단위이므로 발신 IP를 변경해도 완화되지 않습니다.
- 서버가 **정지된 상태에서 명령을 보내면 오류**가 반환됩니다(`Server must be online in order to send commands.`).
- `command`가 비어 있으면 입력 오류(422)가 됩니다.
- 보내신 명령은 패널의 **활동 로그에 기록됩니다**.
- 서브 사용자가 이용하시는 경우 **「콘솔 조작」 권한**이 필요합니다.

## 보안에 대하여

- API 키는 **비밀번호와 동일하게** 취급해 주세요. GitHub·Discord·스크린샷 등에 포함하지 마십시오.
- **「Allowed IPs(허용 IP)」를 설정해 주세요.**
- 용도별로 키를 나누고, 필요 없어지면 삭제해 주세요. 만일 유출되더라도 삭제하면 즉시 무효가 됩니다.
- 권한이 없는 서버에는 접근하실 수 없습니다.

API 이용에 대해 궁금한 점이 있으시면 클라이언트 포털의 지원 티켓으로 편하게 문의해 주세요.
