공통 규약

모든 Operator API 와 지갑 콜백에 공통으로 적용되는 형식 · 단위 · 제한을 정리합니다.

베이스 URL · 버전

{API_BASE}/operator/v1/...

{API_BASE} 는 환경마다 다릅니다(연동 절차 · 환경).
버전은 경로의 v1 로 표시합니다.
응답에는 필드가 추가될 수 있습니다. 모르는 필드는 무시하도록 구현하세요.
모든 요청은 서명해야 합니다.

요청 · 응답 형식

본문은 JSON, 문자 인코딩은 UTF-8 입니다. 요청에 Content-Type: application/json; charset=utf-8 를 붙이세요.
쿼리 값은 퍼센트 인코딩해서 보냅니다. 서명도 인코딩한 문자열 그대로 합니다(인증 · 서명).
성공 응답은 200(조회 · 수정), 201(생성), 204(본문 없음) 중 하나입니다. 엔드포인트별로 정해져 있습니다.
관리 설정을 바꾸는 쓰기 요청(게임 실행 POST /launch 제외)은 응답 헤더 X-Audit-Id 에 변경 기록 번호(정수)를 돌려줍니다. 이 번호로 변경 이력을 조회하거나 되돌릴 수 있습니다.

선택 헤더 `X-Operator-Admin`

오퍼레이터 관리 화면에서 관리자가 한 조작을 API 로 보낼 때, 그 관리자 아이디를 X-Operator-Admin 헤더에 실을 수 있습니다(영문 · 숫자 · _ . @ -, 1~40자). 변경 이력의 조작자가 operator:<오퍼레이터 코드>/<아이디> 로 남습니다. 권한에는 영향이 없고 서명 대상도 아닙니다.

금액

금액은 모두 정수이고, 통화의 최소 단위입니다. 소수(부동소수점)는 쓰지 않습니다.
통화별 소수 자리(exponent)는 GET /currencies 로 확인합니다. 최소 단위 금액 = 표시 금액 × 10^exponent 입니다.

통화	`exponent`	표시 금액	API 금액
`PHP`	2	₱50.00	`5000`
`USD`	2	$12.34	`1234`
`KRW`	0	₩10,000	`10000`

오퍼레이터 지갑도 같은 최소 단위로 잔액(balance)을 돌려줘야 합니다.
베팅 한도 · 테이블 한도처럼 오퍼레이터가 정하는 한도 값은 1 단위(10^exponent)의 배수만 받습니다. 예: PHP 는 100(₱1) 단위.
금액은 64비트 정수입니다. 저장 컬럼은 BIGINT 같은 64비트 정수형을 쓰고, JavaScript 의 Number 로 다룰 때는 안전 정수 범위(2⁵³−1)를 넘지 않는지 유의하세요.

시각

위치	형식	예
`POST /launch` 응답 `expires_at`, 지갑 콜백 본문 `created_at`	UTC, 밀리초 3자리 고정	`2026-10-19T03:21:07.512Z`
그 밖의 응답 시각	RFC 3339. 소수 초 자릿수가 가변이고, 시간대 오프셋이 `Z` 가 아닐 수 있습니다	`2026-10-19T02:10:00.123456Z`, `2026-10-19T11:57:40.1+08:00`
헤더 `X-Timestamp`	Unix epoch 밀리초	`1760000000000`

응답 시각은 문자열 비교하지 말고, RFC 3339 파서로 읽어 오프셋까지 해석하세요.

기간 쿼리 `from` · `to`

내역 · 리포트 조회의 기간 파라미터는 공통 규칙을 따릅니다.

규칙	내용
형식	RFC 3339(`2026-10-01T00:00:00+08:00`) 또는 날짜(`2026-10-01`, UTC 0시로 해석)
구간	`[from, to)` — `from` 포함, `to` 제외
기본값	`to` 가 없으면 지금(UTC), `from` 이 없으면 `to` 의 24시간 전

형식이 틀리면 기본값으로 바뀝니다

from · to 를 해석하지 못하면 오류 없이 기본값이 쓰입니다. 오프셋의 + 를 인코딩하지 않으면(+08:00 → 공백) 해석에 실패하므로 %2B08%3A00 처럼 인코딩하세요. 결과 기간이 예상과 다르면 먼저 인코딩을 확인하세요.

ID

ID	형식	예
플레이어	`pl_` + 32자리 소문자 hex	`pl_0192f3a1c4e87b2c9d0e1f2a3b4c5d6e`
테이블	`tbl_` + 32자리 hex	`tbl_0192f3a1c4e87b2c9d0e1f2a3b4c5d70`
라운드	`rnd_` + 32자리 hex	`rnd_0192f3a1c4e87b2c9d0e1f2a3b4c5d71`
테이블 세션	`tss_` + 32자리 hex	`tss_0192f3a1c4e87b2c9d0e1f2a3b4c5d72`
지갑 거래	`tx_` + 32자리 hex	`tx_0192f3a1c4e87b2c9d0e1f2a3b4c5d6e`
프라이빗 예약	`prv_` + 32자리 hex	`prv_0192f3a1c4e87b2c9d0e1f2a3b4c5d73`
딜러	접두어 없는 UUID 문자열	`0192f3a1-c4e8-7b2c-9d0e-1f2a3b4c5d74`
변경 이력	정수	`812`

ID 는 불투명한 문자열로 다루세요. 형식을 파싱하거나 정렬 기준으로 쓰지 마세요(일부 ID 는 시간순이 아닙니다).
저장할 때는 64자까지 담을 수 있게 하세요.
플레이어 external_id 는 오퍼레이터가 정하는 값(1~64바이트)이며 플랫폼은 그대로 돌려줍니다.

페이징

목록 API 는 엔드포인트에 따라 두 방식 중 하나를 씁니다.

방식	쓰는 곳	요청	응답
커서	`GET /rounds`, `GET /transactions`	`limit`, `cursor`	`next_cursor` — 다음 페이지 요청의 `cursor` 로 그대로 넘깁니다. 더 없으면 `null`
오프셋	`GET /credit`	`limit`, `offset`	(다음 페이지 여부 없음 — 받은 행 수가 `limit` 보다 적으면 끝)
오프셋	`GET /dealer-card-log`	`limit`, `offset`	`has_more`
페이지 번호	`GET /audit`	`limit`, `page`(1부터)	`has_more`

limit 기본값은 100, 최대 500 입니다(GET /credit 은 기본 50). 500 보다 크면 500 으로 줄입니다.
커서 페이징은 다음 페이지를 요청할 때 첫 요청과 같은 필터 · 정렬 파라미터를 함께 보내야 합니다. 커서 값의 형식에 기대지 마세요.

오류 응답

Operator API 는 오류를 HTTP 상태 코드와 아래 본문으로 알립니다.

json

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "invalid fields",
    "details": { "fields": ["player.nickname"] }
  }
}

필드	타입	설명
`error.code`	string	기계가 읽는 오류 코드. 분기는 이 값으로 하세요.
`error.message`	string	사람이 읽는 짧은 설명(영문). 바뀔 수 있으므로 분기에 쓰지 마세요.
`error.details`	object	일부 오류에만 있습니다. 입력 필드 오류는 `details.fields` 에 잘못된 필드 이름 목록이 옵니다.

오류 코드 전체는 오류 코드를 보세요.

지갑 콜백은 다릅니다

지갑 콜백 응답은 오류도 HTTP 200 + 본문 status 로 돌려줘야 합니다. 지갑 콜백 개요를 보세요.

요청 크기 · 속도 제한

항목	값	넘으면
요청 본문	64KB (`PUT /lobby-banners` 만 768KB)	상한까지만 읽고 서명을 검증하므로 `401 INVALID_SIGNATURE`
요청 수	오퍼레이터당 초당 200건 (1초 단위 고정 창, 모든 엔드포인트 합산)	`429 RATE_LIMITED`

429 를 받으면 잠시 기다렸다가 다시 보내세요. 다시 보낼 때는 타임스탬프 · nonce · 서명을 새로 만듭니다.
목록을 한꺼번에 모을 때는 limit=500 으로 페이지 수를 줄이세요.

멱등성

조회(GET) 는 몇 번을 보내도 안전합니다.
Operator API 쓰기 요청에는 멱등 키가 없습니다. 같은 요청을 다시 보내면 다시 처리됩니다. 예를 들어 POST /launch 는 호출할 때마다 새 실행 토큰을, POST /tables 는 호출할 때마다 새 테이블을 만듭니다. 쓰기 요청이 타임아웃되면 조회 API 로 결과를 먼저 확인한 뒤 다시 보내세요. 설정을 통째로 덮어쓰는 PUT 은 같은 값으로 다시 보내도 결과가 같습니다.
지갑 콜백은 tx_id 로 멱등이어야 합니다. 플랫폼은 같은 거래를 같은 tx_id 와 같은 본문으로 재시도하므로, 오퍼레이터는 이미 처리한 tx_id 에 대해 처음과 같은 응답을 돌려줘야 합니다. 지갑 콜백 개요를 보세요.

공통 규약 ​

베이스 URL · 버전 ​

요청 · 응답 형식 ​

선택 헤더 X-Operator-Admin ​

금액 ​

시각 ​

기간 쿼리 from · to ​

ID ​

페이징 ​

오류 응답 ​

요청 크기 · 속도 제한 ​

멱등성 ​