Operator API 전체 목록
Operator API 는 오퍼레이터 서버가 플랫폼을 호출하는 서버 간 API 입니다. 게임 실행 URL 발급, 게임 · 테이블 조회, 내역 조회, 플레이어 강제 종료와 오퍼레이터 관리 화면용 설정 기능을 제공합니다.
베이스 URL
{API_BASE}/operator/v1{API_BASE} 는 환경별 API 주소입니다(테스트 · 운영 주소는 연동 절차 · 환경). 이 문서의 경로는 모두 베이스 URL 기준입니다. 예를 들어 POST /launch 는 POST {API_BASE}/operator/v1/launch 입니다.
인증 요약
모든 엔드포인트는 같은 서명 규칙을 씁니다. 자세한 내용은 인증 · 서명을 보세요.
| 헤더 | 필수 | 내용 |
|---|---|---|
X-Operator | 필수 | 오퍼레이터 코드 (예: acme) |
X-Api-Key | 권장 | 발급받은 API 키 (ak_…). 보내면 검증합니다. |
X-Timestamp | 필수 | 요청 시각, Unix 밀리초. 플랫폼 시각과 ±5분 안이어야 합니다. |
X-Nonce | 필수 | 요청마다 새 랜덤 문자열(1~128자). 5분 안에 같은 값을 다시 쓰면 거절됩니다. |
X-Signature | 필수 | hex(HMAC-SHA256(api_secret, 서명문)), 소문자 16진수 |
X-Operator-Admin | 선택 | 관리 화면에서 조작한 관리자 아이디(^[A-Za-z0-9_.@-]{1,40}$). 변경 이력에 조작자로 남습니다. 서명 대상이 아니며 권한과 무관합니다. |
서명문 = X-Timestamp + "\n" + X-Nonce + "\n" + METHOD + "\n" + 경로와 쿼리 + "\n" + 본문 원문- 요청 본문은 JSON(
Content-Type: application/json; charset=utf-8)입니다.GET은 본문 없이 빈 문자열로 서명합니다. - 본문은 최대 64KB 까지 읽습니다(
PUT /lobby-banners만 768KB). 넘으면 잘린 본문으로 서명을 검증하므로INVALID_SIGNATURE로 실패합니다. - 속도 제한은 오퍼레이터당 초당 200건입니다. 넘으면
429 RATE_LIMITED입니다. - 오류 응답은
{"error": {"code", "message", "details?"}}모양입니다. 공통 오류 코드는 오류 코드를 보세요. - 쓰기 요청(
GET이 아닌 요청,POST /launch제외)의 응답에는X-Audit-Id헤더가 붙습니다. 이 번호로 변경 이력을 조회하거나 되돌릴 수 있습니다.
구분
| 구분 | 뜻 |
|---|---|
| 필수 | 모든 오퍼레이터가 연동해야 하는 엔드포인트 |
| 권장 | 사이트 화면 · 운영 대사에 쓰도록 권장하는 엔드포인트 |
| 관리 화면용 | 오퍼레이터 관리자 화면(백오피스)에서 설정 · 운영을 직접 하려는 경우에 쓰는 엔드포인트. 쓰지 않으면 본사가 기본값으로 운영합니다. |
제약 칸의 표기는 다음과 같습니다.
- 독립운영만: 운영 방식이
independent인 오퍼레이터만 쓸 수 있습니다.prepaid오퍼레이터는403입니다(연동 개요 · 운영 방식). - 전용 테이블만: 이 오퍼레이터가 만든 전용 테이블에만 쓸 수 있습니다. 공용 테이블은
403 TABLE_NOT_OWNED입니다.
게임 실행
| 메서드 | 경로 | 설명 | 구분 | 제약 | 문서 |
|---|---|---|---|---|---|
POST | /launch | 플레이어 게임 실행 URL 발급 | 필수 | 게임 실행 |
게임 · 로비 · 통화
| 메서드 | 경로 | 설명 | 구분 | 제약 | 문서 |
|---|---|---|---|---|---|
GET | /games | 켜진 게임 목록 · 사이트 베팅 한도 · 로비 출력 | 필수 | 게임 · 로비 · 통화 | |
GET | /currencies | 통화 표 (코드 · 소수 자리 · 기호) | 필수 | 게임 · 로비 · 통화 | |
PUT | /games/{game_code}/bet-limits | 게임별 · 통화별 사이트 베팅 한도 | 관리 화면용 | 게임 · 로비 · 통화 | |
PUT | /games/{game_code}/lobby | 게임 로비의 메뉴 · 테이블 출력, 배너 | 관리 화면용 | 게임 · 로비 · 통화 | |
PUT | /lobby-banners | 로비 배너 그림 올리기 | 관리 화면용 | 본문 768KB | 게임 · 로비 · 통화 |
테이블
| 메서드 | 경로 | 설명 | 구분 | 제약 | 문서 |
|---|---|---|---|---|---|
GET | /tables | 테이블 현황 (공용 + 자기 전용) | 권장 | 테이블 | |
POST | /tables | 전용 테이블 만들기 | 관리 화면용 | 독립운영만 | 테이블 |
PATCH | /tables/{table_id} | 이름 · 정렬 순서 바꾸기 | 관리 화면용 | 전용 테이블만 | 테이블 |
POST | /tables/{table_id}/close | 테이블 닫기 | 관리 화면용 | 전용 테이블만 | 테이블 |
PUT | /tables/{table_id}/settings | 통화별 한도 · 레이크 | 관리 화면용 | 전용 테이블만 | 테이블 |
PUT | /tables/{table_id}/currency | 운영 통화 바꾸기 | 관리 화면용 | 전용 테이블만, 착석자 없을 때 | 테이블 |
PUT | /tables/{table_id}/live | 딜링 방식 · 일시정지 | 관리 화면용 | 전용 테이블만, 라이브 홀덤 · 스피드 홀덤 | 테이블 |
PUT | /tables/{table_id}/timers | 배팅 · 차례 시간 | 관리 화면용 | 전용 테이블만 | 테이블 |
PUT | /tables/{table_id}/rake-rule | 레이크 규칙 (노 플랍 노 드롭 · 소수점 버림) | 관리 화면용 | 전용 테이블만, 레이크 있는 게임 | 테이블 |
PUT | /tables/{table_id}/card-design | 테이블 카드 디자인 | 관리 화면용 | 전용 테이블만, 라이브 홀덤 · 스피드 홀덤 | 테이블 |
플레이어
| 메서드 | 경로 | 설명 | 구분 | 제약 | 문서 |
|---|---|---|---|---|---|
POST | /players/{external_id}/logout | 세션 강제 종료 · 차단 · 차단 해제 | 필수 | 플레이어 | |
GET | /players/online | 지금 접속 중인 플레이어 | 권장 | 플레이어 |
라운드 · 거래 · 리포트
| 메서드 | 경로 | 설명 | 구분 | 제약 | 문서 |
|---|---|---|---|---|---|
GET | /rounds | 라운드(플레이어 × 판) 내역 | 권장 | 라운드 · 거래 · 리포트 | |
GET | /rounds/{round_id} | 라운드 상세 (카드 · 머니 · 진행 기록) | 권장 | 라운드 · 거래 · 리포트 | |
GET | /sessions/{session_id} | 테이블 세션(착석 1회) 상세 | 관리 화면용 | 라운드 · 거래 · 리포트 | |
GET | /transactions | 지갑 거래 원장 (대사용) | 필수 | 라운드 · 거래 · 리포트 | |
GET | /reports/ggr | 일 · 게임별 GGR 집계 | 권장 | 라운드 · 거래 · 리포트 |
오퍼레이터 설정 · 알
| 메서드 | 경로 | 설명 | 구분 | 제약 | 문서 |
|---|---|---|---|---|---|
GET | /credit | 운영 방식 · 알 잔액 · 알 원장 | 권장 | 알 원장은 prepaid 만 의미 있음 | 오퍼레이터 설정 · 알 |
GET | /settings | 시간대 · 통화 · 중복 게임 허용 등 | 관리 화면용 | 오퍼레이터 설정 · 알 | |
PUT | /settings | 시간대 · 중복 게임 허용 · 관전 시간 제한 바꾸기 | 관리 화면용 | 오퍼레이터 설정 · 알 | |
GET | /rake-defaults | 수수료(레이크) 기본값 | 관리 화면용 | 오퍼레이터 설정 · 알 | |
PUT | /rake-defaults | 수수료 기본값 바꾸기 | 관리 화면용 | 오퍼레이터 설정 · 알 | |
GET | /card-design | 카드 디자인 기본값 · 선택지 | 관리 화면용 | 오퍼레이터 설정 · 알 | |
PUT | /card-design | 카드 디자인 기본값 바꾸기 | 관리 화면용 | 오퍼레이터 설정 · 알 |
딜러
라이브 테이블을 직접 운영하는 오퍼레이터만 의미가 있습니다.
| 메서드 | 경로 | 설명 | 구분 | 제약 | 문서 |
|---|---|---|---|---|---|
GET | /dealers | 딜러 목록 | 관리 화면용 | 딜러 | |
POST | /dealers | 딜러 등록 | 관리 화면용 | 딜러 | |
PATCH | /dealers/{dealer_id} | 딜러 정보 · 상태 바꾸기 | 관리 화면용 | 딜러 | |
POST | /dealers/{dealer_id}/badge | 사원증 코드 발급 | 관리 화면용 | 딜러 | |
DELETE | /dealers/{dealer_id}/badge | 사원증 코드 폐기 | 관리 화면용 | 딜러 | |
PUT | /dealers/{dealer_id}/photo | 딜러 사진 올리기 | 관리 화면용 | 본문 64KB | 딜러 |
DELETE | /dealers/{dealer_id}/photo | 딜러 사진 지우기 | 관리 화면용 | 딜러 | |
GET | /dealer-devices | 딜러툴 단말 현황 | 관리 화면용 | 딜러 | |
GET | /dealer-tool | 딜러툴 최신 설치본 정보 | 관리 화면용 | 딜러 | |
GET | /dealer-card-log | 딜러 카드 입력 기록 | 관리 화면용 | 독립운영만 | 딜러 |
프라이빗 테이블
| 메서드 | 경로 | 설명 | 구분 | 제약 | 문서 |
|---|---|---|---|---|---|
GET | /private-tables | 프라이빗 예약 목록 | 관리 화면용 | 독립운영만 | 프라이빗 테이블 |
POST | /private-tables | 프라이빗 예약 만들기 | 관리 화면용 | 독립운영만, 전용 라이브 홀덤 | 프라이빗 테이블 |
DELETE | /private-tables/{private_id} | 프라이빗 예약 취소 | 관리 화면용 | 독립운영만 | 프라이빗 테이블 |
변경 이력(감사)
| 메서드 | 경로 | 설명 | 구분 | 제약 | 문서 |
|---|---|---|---|---|---|
GET | /audit | 이 오퍼레이터가 남긴 변경 이력 | 관리 화면용 | 변경 이력(감사) | |
POST | /audit/{audit_id}/restore | 변경 되돌리기 | 관리 화면용 | 변경 이력(감사) |
처음 연동할 때
최소 연동은 아래 순서면 충분합니다.
GET /currencies·GET /games로 통화 소수 자리와 켜진 게임을 받아 사이트에 게임 메뉴를 만듭니다.- 플레이어가 게임을 누르면
POST /launch로 실행 URL 을 받아 새 창 또는 iframe 으로 엽니다. - 지갑 콜백 4종(balance · debit · credit · rollback)을 구현합니다.
- 플레이어 탈퇴 · 차단 · 자기 배제 때
POST /players/{external_id}/logout을 부릅니다. - 정기적으로
GET /transactions로 자기 지갑 원장과 대사합니다.
사이트에서 테이블을 직접 골라 들어가게 하려면 GET /tables 를, 플레이어에게 베팅 내역을 보여 주려면 GET /rounds 를 더합니다.