연동 절차 · 환경

계약부터 운영 전환까지의 순서와, 플랫폼이 발급하는 정보 · 오퍼레이터가 알려 줘야 하는 정보, 환경별 접속 주소를 정리합니다.

진행 순서

단계	하는 일	결과
1. 계약	제공 게임, 사용 통화, 운영 방식(`credit_mode`), 수수료를 정합니다.	계약 조건 확정
2. 오퍼레이터 정보 전달	아래 오퍼레이터가 알려 줄 정보를 전달합니다.	테스트 환경에 오퍼레이터 등록
3. 자격증명 수령	플랫폼이 발급하는 정보를 안전한 경로로 받습니다.	오퍼레이터 코드 · API 키 · 서명 비밀키
4. 테스트 환경 연동	지갑 콜백 4종 구현, `POST /launch` 로 게임 실행, 내역 API 연결	테스트 환경에서 실제 게임 플레이
5. 검수	플랫폼이 지갑 연결 시험(`balance` 호출)을 하고, 함께 정상 · 장애 시나리오를 점검합니다. 연동 체크리스트 참고	검수 통과
6. 운영 전환	운영 환경용 자격증명을 새로 받고, 운영 지갑 URL · 서버 IP 를 등록합니다.	운영 개시

협의 사항

일정, 담당자 연락 경로, 자격증명 전달 방법, 검수 범위는 계약 시 협의합니다.

플랫폼이 발급하는 정보

항목	형식	쓰는 곳
오퍼레이터 코드	소문자 · 숫자 · `_` · `-`, 2~32자 (예: `acme`)	모든 요청의 `X-Operator` 헤더. 지갑 콜백에도 같은 값이 실려 옵니다.
API 키	`ak_` + 40자리 hex (예: `ak_5c0f…`)	Operator API 요청의 `X-Api-Key` 헤더
서명 비밀키 (API secret)	64자리 hex 문자열	양방향 HMAC-SHA256 서명의 키. 문자열 그대로(hex 디코딩하지 않고) 키로 씁니다. 인증 · 서명 참고

API 키와 서명 비밀키는 발급 시점에 한 번만 평문으로 전달됩니다. 플랫폼은 API 키는 해시로, 비밀키는 암호화해 보관하므로 나중에 다시 보여 줄 수 없습니다. 잃어버렸으면 재발급을 요청하세요.
재발급하면 새 키 · 비밀키로 즉시 교체되고 이전 값은 바로 무효가 됩니다. 재발급 시각을 미리 맞춰 오퍼레이터 쪽 설정도 함께 바꾸세요.
테스트 환경과 운영 환경의 자격증명은 서로 다릅니다.
비밀키는 오퍼레이터 서버에만 두고 브라우저 · 앱 · 저장소에 넣지 마세요.

오퍼레이터가 알려 줄 정보

항목	형식	설명
지갑 콜백 기본 URL (`wallet_base_url`)	`https://` URL, 경로 포함 가능	플랫폼이 이 주소 뒤에 `/balance` · `/debit` · `/credit` · `/rollback` 을 붙여 `POST` 합니다. 예: `https://api.acme.example/games-wallet` → `https://api.acme.example/games-wallet/debit`. 끝의 `/` 는 무시되며, 쿼리 문자열은 넣지 마세요.
서버 IP 허용 목록 (`ip_allowlist`)	IP 또는 CIDR 목록 (예: `203.0.113.10`, `198.51.100.0/28`)	Operator API 를 호출할 오퍼레이터 서버의 공인 IP. 목록 밖에서 온 요청은 `403 IP_NOT_ALLOWED` 로 거절됩니다. 서버를 늘리거나 IP 가 바뀌면 미리 알려 주세요.
기본 복귀 URL (`default_return_url`)	`https://` URL	실행 요청에 `return_url` 이 없을 때 쓰는 값. 게임 화면의 "사이트로 돌아가기"가 이 주소로 이동하고, 게임 화면이 보내는 postMessage 의 대상 오리진도 이 주소의 오리진이 됩니다. 게임 실행 흐름 참고
임베드 도메인 (`embed_origins`)	스킴 + 호스트(+ 포트)만, 경로 없음 (예: `https://www.acme.example`)	게임 화면을 iframe 으로 넣을 사이트 도메인. 등록된 도메인만 iframe 으로 게임을 열 수 있습니다. 새 창으로만 연다면 필요 없습니다.
사용 통화	통화 코드 목록 (예: `PHP`, `USD`)	첫 번째가 기본 통화입니다. 플레이어 통화는 이 안에서만 쓸 수 있습니다. 쓸 수 있는 통화와 소수 자리는 `GET /currencies` 로 확인합니다.
제공 게임	게임 코드 목록	켤 게임. 게임 코드 참고
시간대	IANA 이름 (예: `Asia/Manila`)	관리용 화면 표시 시간대. 나중에 `PUT /settings` 로 바꿀 수 있습니다.
중복 게임 허용 여부	예 / 아니오 (기본: 아니오)	한 플레이어가 여러 테이블에 동시에 들어갈 수 있는지. 나중에 `PUT /settings` 의 `multi_table` 로 바꿀 수 있습니다.
기술 담당자 연락처	—	장애 · 대사 불일치 연락용

지갑 URL 은 HTTPS 로

지갑 콜백에는 플레이어 ID 와 금액이 실립니다. 공개 인터넷을 거치는 지갑 URL 은 반드시 HTTPS 로 준비하세요. 서명이 위변조는 막지만 내용을 암호화하지는 않습니다.

협의 사항

지갑 콜백을 보내는 플랫폼 서버의 발신 IP(오퍼레이터 방화벽 허용용)는 환경별로 계약 시 안내합니다.

환경별 주소

실제 주소는 연동할 때 환경별로 발급하며 이 문서에 싣지 않습니다. 주소는 바뀔 수 있고, 바뀔 때는 미리 알려 드립니다. 이 문서에서는 아래 자리표시로 적습니다.

자리표시	뜻	형식
`{API_HOST}`	Operator API 호스트	호스트 이름만 (스킴 · 경로 없이)
`{API_BASE}`	Operator API 오리진	`https://{API_HOST}` — Operator API 베이스 URL 은 `{API_BASE}/operator/v1`
`{GAME_ORIGIN}`	게임 화면 오리진 (`launch_url`)	`https://` + 호스트

환경	`{API_BASE}`	`{GAME_ORIGIN}`
테스트	연동 시 제공	연동 시 제공
운영	운영 전환 시 제공	운영 전환 시 제공

게임 화면 오리진은 POST /launch 가 돌려주는 launch_url 의 오리진입니다. 게임 화면이 보내는 postMessage 를 받을 때 event.origin 을 이 값과 비교하세요(게임 실행 흐름).
환경마다 자격증명과 등록 정보(지갑 URL · IP 허용 목록 등)가 따로 있습니다. 운영 전환 때 환경 주소만 바꾸지 말고 자격증명도 운영용으로 바꾸세요.
플레이어 브라우저는 게임 화면 오리진과 같은 계열의 API · WebSocket 주소로 직접 접속합니다. 라이브 게임은 영상 수신에 UDP 를 쓰므로, 플레이어 네트워크에서 외부로 나가는 UDP 가 막혀 있으면 영상이 늦게 뜨거나 끊길 수 있습니다.

검수 때 플랫폼이 하는 일

지갑 연결 시험: 플랫폼이 등록된 wallet_base_url 로 서명된 balance 를 한 번 보냅니다. 존재하는 플레이어면 OK, 없는 플레이어면 PLAYER_NOT_FOUND 가 HTTP 200 으로 오면 주소 · 서명 검증이 정상입니다. 서명 검증 실패(INVALID_SIGNATURE)나 HTTP 오류가 오면 인증 · 서명을 다시 확인하세요.
시나리오 점검: 정상 베팅 · 정산, 잔액 부족, 지갑 지연 · 오류 시 rollback, credit 재시도, 강제 종료, 대사(GET /transactions)를 함께 확인합니다. 항목은 연동 체크리스트를 보세요.

연동 절차 · 환경 ​

진행 순서 ​

플랫폼이 발급하는 정보 ​

오퍼레이터가 알려 줄 정보 ​

환경별 주소 ​