오퍼레이터 설정 · 알

오퍼레이터 단위 설정(시간대 · 중복 게임 · 관전 제한), 새 전용 테이블의 수수료 기본값, 라이브 카드 디자인, 선불 크레딧(알) 잔액 · 원장을 다룹니다. 주로 오퍼레이터 관리자 화면에서 씁니다.

메서드	경로	용도
GET	/operator/v1/settings	오퍼레이터 설정 조회
PUT	/operator/v1/settings	오퍼레이터 설정 변경
GET	/operator/v1/rake-defaults	수수료(레이크) 기본값 조회
PUT	/operator/v1/rake-defaults	수수료 기본값 저장 (기존 테이블 일괄 적용 선택)
GET	/operator/v1/card-design	라이브 카드 디자인 기본값 조회
PUT	/operator/v1/card-design	라이브 카드 디자인 기본값 저장
GET	/operator/v1/credit	알 잔액 · 원장

쓰기 요청(PUT)의 응답에는 X-Audit-Id 헤더로 감사 기록 번호가 실립니다. 이 번호로 나중에 변경을 되돌릴 수 있습니다. → 변경 이력(감사)

필드 검증 오류는 모두 다음 모양입니다. details.fields 에 잘못된 필드 이름이 담깁니다.

{ "error": { "code": "INVALID_REQUEST", "message": "invalid fields", "details": { "fields": ["watch_limit_sec"] } } }

GET /operator/v1/settings

오퍼레이터 설정을 조회합니다.

요청 예시

GET /operator/v1/settings HTTP/1.1
Host: {API_HOST}
X-Operator: acme
X-Api-Key: ak_live_…
X-Timestamp: 1760839200123
X-Nonce: 4a6c8e0b2d4f6a8c0e2b4d6f
X-Signature: 1f9b…

응답 예시

{
  "timezone": "Asia/Manila",
  "operator_timezone": "",
  "hq_timezone": "Asia/Manila",
  "currencies": ["PHP", "USD"],
  "multi_table": true,
  "watch_limit_sec": 600,
  "money_adjust": false
}

응답 필드

필드	타입	설명
timezone	string	관리 화면에 쓸 시간대(IANA 이름). operator_timezone 이 있으면 그 값, 비어 있으면 hq_timezone
operator_timezone	string	오퍼레이터가 정한 시간대. "" 이면 플랫폼 시간대를 따릅니다
hq_timezone	string	플랫폼(본사) 시간대
currencies	string[]	이 오퍼레이터가 쓸 수 있는 통화. 첫 번째가 기본 통화입니다. 본사가 정하며 이 API 로는 바꿀 수 없습니다
multi_table	bool	중복 게임 허용. false 면 플레이어는 한 번에 테이블 하나에만 들어갈 수 있습니다
watch_limit_sec	int	라이브 게임 관전 제한 시간(초). 베팅 · 착석 없이 이 시간 동안 보기만 하면 로비로 내보냅니다. 0 = 제한 없음
money_adjust	bool	본사가 이 오퍼레이터에게 "회원 머니 수동 지급 · 차감" 기능을 허용했는지. 읽기 전용이며 플랫폼 동작에는 영향이 없습니다(오퍼레이터 관리 화면에서 해당 기능을 보일지 판단하는 용도)

timezone 은 관리 화면 표시용 설정입니다. Operator API 응답 시각과 GGR 날짜 경계에는 영향을 주지 않습니다.

PUT /operator/v1/settings

보낸 항목만 바꿉니다. 셋 중 하나 이상을 보내야 합니다.

요청 필드

필드	타입	필수	설명
timezone	string	아니오	IANA 시간대 이름(예: Asia/Manila). "" 이면 플랫폼 시간대를 따릅니다. 앞뒤 공백은 지웁니다
multi_table	bool	아니오	중복 게임 허용
watch_limit_sec	int	아니오	0(제한 없음) 또는 30 ~ 3600

multi_table · watch_limit_sec 변경은 저장 즉시 새 입장부터 적용됩니다.

요청 예시

curl -X PUT {API_BASE}/operator/v1/settings \
  -H 'Content-Type: application/json; charset=utf-8' \
  -H 'X-Operator: acme' -H 'X-Api-Key: ak_live_…' \
  -H 'X-Timestamp: 1760839200123' -H 'X-Nonce: 0b2d4f6a8c0e2b4d6f8a0c2e' -H 'X-Signature: 6e3d…' \
  -d '{"multi_table":false,"watch_limit_sec":300}'

응답 예시

{
  "timezone": "Asia/Manila",
  "operator_timezone": "",
  "hq_timezone": "Asia/Manila",
  "multi_table": false,
  "watch_limit_sec": 300
}

응답 필드는 GET 과 같고 currencies · money_adjust 는 없습니다.

오류

HTTP	코드	details.fields	상황
400	INVALID_REQUEST	["timezone", "multi_table", "watch_limit_sec"]	본문이 JSON 이 아니거나, 필드 타입이 틀렸거나(예: "multi_table": "yes"), 세 필드가 모두 빠짐
400	INVALID_REQUEST	["watch_limit_sec"]	watch_limit_sec 이 0 이 아니면서 30 ~ 3600 밖
400	INVALID_REQUEST	["timezone"]	알 수 없는 시간대 이름
500	INTERNAL_ERROR	—	저장 실패

검증은 watch_limit_sec → timezone 순으로 하며 첫 오류에서 멈춥니다. 검증에 실패하면 아무것도 저장하지 않습니다.

GET /operator/v1/rake-defaults

수수료(레이크) 기본값을 조회합니다. 기본값은 새로 만드는 전용 테이블의 처음 값입니다. 이미 있는 테이블의 수수료는 테이블마다 테이블 설정으로 고칩니다.

응답 예시

{
  "rake_defaults": {
    "rake_bp": 500,
    "caps": { "PHP": 30000 },
    "no_flop_no_drop": true,
    "rake_floor": true
  },
  "currencies": ["PHP", "USD"],
  "max_rake_bp": 2000
}

응답 필드

필드	타입	설명
rake_defaults	object	저장된 기본값. 정하지 않은 항목은 필드가 없습니다(모두 없으면 {})
rake_defaults.rake_bp	int	레이크 비율(bp, 500 = 5%). 레이크가 있는 모든 게임에 쓰며, 스피드 홀덤은 앤티 레이크에도 같이 씁니다
rake_defaults.caps	object	통화 → 판당 최고 수수료(그 통화 최소 단위, 0 = 상한 없음). rake_bp 가 있을 때만 의미가 있습니다
rake_defaults.no_flop_no_drop	bool	플랍이 열리기 전에 끝난 핸드는 레이크를 떼지 않음 (홀덤 계열 — 텍사스 홀덤 · 오마하 · 라이브 홀덤)
rake_defaults.rake_floor	bool	한 판 레이크 합의 금액 1단위 미만을 버림 (예: ₱142.50 → ₱142). 레이크가 있는 모든 게임
currencies	string[]	caps 에 쓸 수 있는 통화(이 오퍼레이터 사용 통화)
max_rake_bp	int	rake_bp 상한 (2000 = 20%)

PUT /operator/v1/rake-defaults

수수료 기본값을 통째로 저장합니다. 보내지 않은 항목은 기본값에서 지워집니다(새 테이블은 그 항목을 복제 원본 테이블 값으로 따릅니다). 일부만 바꾸려면 먼저 GET 으로 받은 값에 고친 항목을 합쳐 보내세요.

요청 필드

필드	타입	필수	설명
rake_bp	int	아니오	0 ~ 2000
caps	object	아니오	{ "통화": 금액 }. 통화는 이 오퍼레이터 사용 통화만, 금액은 0 이상이고 금액 1단위(10^exponent)의 배수
no_flop_no_drop	bool	아니오	홀덤 계열 레이크 규칙
rake_floor	bool	아니오	소수점 버림
apply_all	bool	아니오	true 면 저장한 기본값 전부(비율 · 최고 수수료 · 노 플랍 노 드롭 · 소수점 버림)를 이 오퍼레이터의 기존 전용 테이블 전부에도 맞춥니다. 기본 false

기존 테이블에 반영되는 범위:

경우	기존 전용 테이블에 반영
apply_all: true	기본값 전부 (레이크가 있는 게임의 테이블. 엔진이 받지 않는 값은 그 테이블만 건너뜀)
apply_all 없음 · false, rake_floor 있음	rake_floor 만 전부 반영
apply_all 없음 · false, rake_floor 없음	반영 없음 (새 테이블에만 적용)

운영 중인 테이블에는 다음 판부터 적용됩니다. 공용 테이블에는 적용되지 않습니다.

요청 예시

curl -X PUT {API_BASE}/operator/v1/rake-defaults \
  -H 'Content-Type: application/json; charset=utf-8' \
  -H 'X-Operator: acme' -H 'X-Api-Key: ak_live_…' \
  -H 'X-Timestamp: 1760839200123' -H 'X-Nonce: 8c0e2b4d6f8a0c2e4b6d8f0a' -H 'X-Signature: 2a7f…' \
  -d '{"rake_bp":500,"caps":{"PHP":30000},"no_flop_no_drop":true,"rake_floor":true,"apply_all":false}'

응답 예시

{
  "rake_defaults": { "rake_bp": 500, "caps": { "PHP": 30000 }, "no_flop_no_drop": true, "rake_floor": true },
  "floor_tables": 4,
  "applied_tables": 0
}

필드	타입	설명
rake_defaults	object	저장된 기본값
floor_tables	int	rake_floor 를 반영해 실제로 바뀐 테이블 수 (이미 같은 값이던 테이블은 세지 않음)
applied_tables	int	apply_all 로 실제로 바뀐 테이블 수

오류

HTTP	코드	상황
400	INVALID_REQUEST (details 없음, message invalid json)	본문이 JSON 이 아니거나 필드 타입이 틀림
400	INVALID_REQUEST (details.fields)	rake_bp 가 0 ~ 2000 밖 → "rake_bp", 사용하지 않는 통화 · 음수 · 1단위 배수가 아닌 상한 → "caps.<통화>" (예: "caps.USD"). 여러 개면 모두 담깁니다
500	INTERNAL_ERROR	저장 실패

GET /operator/v1/card-design

라이브 홀덤 · 스피드 홀덤(live_holdem, live_speed_holdem 계열) 카드의 앞면 · 뒷면 · 뒷면 색상 기본값을 조회합니다. 이 기본값은 이 오퍼레이터 플레이어가 보는 카드에 쓰이며 공용 테이블에도 적용됩니다(같은 공용 테이블이라도 오퍼레이터마다 다르게 보일 수 있습니다). 전용 테이블은 테이블마다 따로 정할 수 있습니다. → 테이블

응답 예시

{
  "card_design": { "back": "rlive", "back_color": "red" },
  "default": { "face": "texas", "back": "texas", "back_color": "blue" },
  "options": {
    "face": ["texas", "studio"],
    "back": ["texas", "rlive"],
    "back_color": ["blue", "red", "black"]
  }
}

응답 필드

필드	타입	설명
card_design	object	오퍼레이터 기본값 {face?, back?, back_color?}. 비운 항목은 필드가 없고 default 를 따릅니다
default	object	플랫폼 기본값
options	object	항목별로 고를 수 있는 값

항목	값
face (앞면)	texas — 디자인 1(텍사스 홀덤 카드 그림) · studio — 디자인 2(큰 숫자 + 무늬)
back (뒷면)	texas — 디자인 1 · rlive — 디자인 2(격자 무늬, 색상 선택 가능)
back_color (뒷면 색상)	blue · red · black — 뒷면이 rlive 일 때만 쓰입니다

카드 디자인은 테이블 값 → 오퍼레이터 기본값 → 플랫폼 기본값 순으로 정해집니다. 바꾼 값은 플레이어가 다음에 테이블에 들어올 때부터 보입니다.

PUT /operator/v1/card-design

기본값을 통째로 저장합니다. 보내지 않거나 "" 로 보낸 항목은 플랫폼 기본값을 따릅니다.

요청 필드

필드	타입	필수	설명
face	string	아니오	texas · studio · ""
back	string	아니오	texas · rlive · ""
back_color	string	아니오	blue · red · black · ""

요청 예시

curl -X PUT {API_BASE}/operator/v1/card-design \
  -H 'Content-Type: application/json; charset=utf-8' \
  -H 'X-Operator: acme' -H 'X-Api-Key: ak_live_…' \
  -H 'X-Timestamp: 1760839200123' -H 'X-Nonce: 6f8a0c2e4b6d8f0a2c4e6b8d' -H 'X-Signature: 9d0c…' \
  -d '{"face":"studio","back":"rlive","back_color":"black"}'

응답 예시

{ "card_design": { "face": "studio", "back": "rlive", "back_color": "black" } }

오류

HTTP	코드	상황
400	INVALID_REQUEST (details 없음, message invalid json)	본문이 JSON 이 아님
400	INVALID_REQUEST (details.fields)	고를 수 없는 값 → "face" · "back" · "back_color" 중 해당 필드
500	INTERNAL_ERROR	저장 실패

GET /operator/v1/credit

선불 크레딧(알) 잔액과 원장을 조회합니다. 운영 방식(mode) 확인에도 씁니다(limit=1 로 가볍게 호출).

알방식(prepaid) 오퍼레이터는 베팅 debit 을 지갑에 보내기 전에 그 금액만큼 알이 차감되고, 알이 모자라면 지갑을 부르지 않고 베팅 · 착석이 거절됩니다. 독립운영(independent)은 알을 쓰지 않습니다. → 운영 방식

쿼리 파라미터

파라미터	타입	필수	설명
limit	정수	아니오	원장 행 수. 기본 50, 최대 500
offset	정수	아니오	건너뛸 행 수 (기본 0)
kind	manual	아니오	manual 이면 본사 수동 처리(charge · withdraw · adjust)만. 다른 값은 무시하고 전체를 돌려줍니다

요청 예시

GET /operator/v1/credit?limit=50&offset=0 HTTP/1.1
Host: {API_HOST}
X-Operator: acme
X-Api-Key: ak_live_…
X-Timestamp: 1760839200123
X-Nonce: 3e5b7d9f1a3c5e7b9d1f3a5c
X-Signature: 7b2e…

응답 예시

{
  "mode": "prepaid",
  "balance": 99998701,
  "warn_below": 10000000,
  "currency": "PHP",
  "entries": [
    { "id": 812, "kind": "credit", "amount": 15896, "balance_after": 99998701, "tx_id": "tx_5c0e9a7d3b1f5e2a8c4d6b0f9e1a3c5d", "memo": null, "created_at": "2026-10-18T14:20:41.07Z" },
    { "id": 811, "kind": "debit", "amount": -6000, "balance_after": 99982805, "tx_id": "tx_0199f3b0ab3c7d118e2f3a4b5c6d7e8f", "memo": null, "created_at": "2026-10-18T14:20:11.4Z" },
    { "id": 790, "kind": "charge", "amount": 50000000, "balance_after": 99988805, "tx_id": null, "memo": "10월 충전", "created_at": "2026-10-18T09:00:00Z" }
  ]
}

응답 필드

필드	타입	설명
mode	string	운영 방식 prepaid(알방식) · independent(독립운영)
balance	int64	지금 알 잔액 (최소 단위)
warn_below	int64	본사가 정한 경고 기준. 잔액이 이보다 낮아지면 충전이 필요하다는 신호로 쓰세요 (0 = 기준 없음)
currency	string	알 금액의 통화 — 이 오퍼레이터의 기본 통화(GET /settings 의 currencies[0])
entries[]	array	원장, 최신순(id 내림차순)
entries[].id	int64	원장 행 번호
entries[].kind	string	아래 표
entries[].amount	int64	잔액 변화량. 차감은 음수, 증가는 양수
entries[].balance_after	int64	이 행 반영 뒤 잔액
entries[].tx_id	string | null	관련 지갑 거래 ID. 본사 수동 처리는 null
entries[].memo	string | null	본사 수동 처리 메모
entries[].created_at	시각	기록 시각

kind

값	부호	뜻	tx_id
charge	+	본사 충전	null
withdraw	−	본사 회수	null
adjust	±	본사 조정	null
debit	−	베팅 · 바이인 debit 전 차감	그 debit
debit_failed	+	debit 이 거절돼 차감분을 되돌림	원 debit
rollback	+	debit 이 취소(rollback)돼 차감분을 되돌림	원 debit (rollback 거래의 ID 가 아님)
credit	+	당첨 · 캐시아웃 credit 이 성공해 그만큼 더함 (금액 0 인 credit 은 기록하지 않음)	그 credit

• 같은 지갑 거래가 같은 종류로 두 번 반영되지 않습니다. 한 debit 은 debit 1행, 되돌림은 debit_failed 또는 rollback 중 1행만 생깁니다.
• 알이 모자라 거절된 debit 은 차감 자체가 없으므로 원장에 남지 않습니다(플랫폼 거래 원장에는 failed 로 남습니다). → GET /transactions
• 페이지 넘기기는 offset 방식입니다. 조회 중 새 행이 생기면 다음 페이지와 겹칠 수 있으니 id 로 중복을 걸러 주세요.

오류

HTTP	코드	상황
500	INTERNAL_ERROR	일시적인 서버 오류

협의 사항

알 충전 · 회수 방법과 경고 기준(warn_below)은 계약 시 협의합니다. 이 API 로는 조회만 할 수 있습니다.