본문으로 건너뛰기
한국어 번역 진행 중한국어 문서를 완성하는 동안 일부 가이드와 API 설명은 아직 영어로 표시될 수 있습니다.

플레이어 관리

사용 사례​

이 엔드포인트들을 사용하여 브랜드에 등록된 플레이어를 조회하고 모니터링합니다. 플레이어는 게임 프로바이더를 통해 최초 인증할 때 플랫폼에서 자동으로 생성되며, 이 API를 통해 직접 생성하지 않습니다. 플레이어 관리 엔드포인트를 통해 다음 작업을 수행할 수 있습니다:

  • 팀 전체의 모든 플레이어를 조회하거나, 브랜드 또는 사용자명으로 필터링합니다.
  • 특정 플레이어의 프로필 및 현재 월렛(Wallet) 잔액을 조회합니다.
  • 플레이어의 전체 거래 내역(차감, 입금, 롤백)을 확인합니다.

전체 흐름​

단계 1 -- 플레이어 목록 조회​

GET /api/player/list

페이지네이션된 플레이어 목록을 반환합니다. 브랜드별 필터링 또는 사용자명 검색이 가능합니다.

쿼리 파라미터:

파라미터타입기본값제약 조건설명
pageinteger1>= 1페이지 번호
sizeinteger201--100페이지당 항목 수
brand_idinteger--선택 사항특정 브랜드로 필터링
usernamestring--선택 사항사용자명으로 대소문자 구분 없는 부분 일치 검색

요청 예시 -- 브랜드 42의 모든 플레이어:

GET /api/player/list?page=1&size=20&brand_id=42

요청 예시 -- 사용자명으로 검색:

GET /api/player/list?page=1&size=50&username=john

응답:

{
  "total": 1250,
  "page": 1,
  "page_size": 20,
  "items": [
    {
      "id": 8801,
      "team_id": 7,
      "brand_id": 42,
      "username": "johndoe",
      "nickname": "John",
      "currency": "KRW",
      "status": 1,
      "created_at": "2026-03-15T12:00:00Z",
      "updated_at": "2026-03-15T12:00:00Z"
    },
    {
      "id": 8802,
      "team_id": 7,
      "brand_id": 42,
      "username": "johnsmith",
      "nickname": null,
      "currency": "KRW",
      "status": 1,
      "created_at": "2026-03-16T08:30:00Z",
      "updated_at": "2026-03-16T08:30:00Z"
    }
  ]
}

참고: 응답 본문의 필드명은 page_size이지만, 이를 제어하는 쿼리 파라미터는 size입니다. 이 규칙은 모든 플레이어 및 베팅 엔드포인트에서 일관되게 적용됩니다.

단계 2 -- 플레이어 상세 조회​

GET /api/player/{player_id}

단일 플레이어의 전체 프로필 정보와 현재 월렛 잔액을 반환합니다.

경로 파라미터: player_id -- 플레이어의 숫자 ID.

응답:

{
  "id": 8801,
  "team_id": 7,
  "brand_id": 42,
  "username": "johndoe",
  "nickname": "John",
  "currency": "KRW",
  "status": 1,
  "created_at": "2026-03-15T12:00:00Z",
  "updated_at": "2026-04-01T18:22:00Z",
  "wallet_balance": "45200.00",
  "wallet_frozen": "0.00"
}
필드설명
wallet_balance현재 사용 가능 잔액. 월렛 기록이 아직 없는 플레이어의 경우 null입니다.
wallet_frozen진행 중인 게임 라운드에서 보류 중인 금액. 월렛 기록이 없으면 null입니다.
status1 = 활성, 0 = 비활성

해당 플레이어가 존재하지 않거나 다른 팀에 속한 경우 404 Not Found가 반환됩니다.

단계 3 -- 플레이어 거래 내역 조회​

GET /api/player/{player_id}/transactions

플레이어의 페이지네이션된 거래 내역을 반환합니다. 각 거래는 월렛 이벤트를 나타내며, 차감(Debit, 베팅 진행), 입금(Credit, 당첨금 지급) 또는 롤백(Rollback, 베팅 취소)으로 구분됩니다.

경로 파라미터: player_id -- 플레이어의 숫자 ID.

쿼리 파라미터:

파라미터타입기본값제약 조건설명
pageinteger1>= 1페이지 번호
sizeinteger201--100페이지당 항목 수

요청 예시:

GET /api/player/8801/transactions?page=1&size=20

응답:

{
  "total": 342,
  "page": 1,
  "page_size": 20,
  "items": [
    {
      "id": 55001,
      "team_id": 7,
      "brand_id": 42,
      "player_id": 8801,
      "type": "debit",
      "amount": "10000.00",
      "balance_before": "55200.00",
      "balance_after": "45200.00",
      "ref_id": "txn_abc123",
      "memo": "Bet placed - round_id: rnd_9988",
      "created_at": "2026-04-06T10:15:00Z"
    },
    {
      "id": 55000,
      "team_id": 7,
      "brand_id": 42,
      "player_id": 8801,
      "type": "credit",
      "amount": "25000.00",
      "balance_before": "30200.00",
      "balance_after": "55200.00",
      "ref_id": "txn_xyz789",
      "memo": null,
      "created_at": "2026-04-06T10:12:00Z"
    }
  ]
}
필드설명
type거래 유형: "debit", "credit" 또는 "rollback"
amount거래 금액 (항상 양수)
balance_before해당 거래 직전의 월렛 잔액
balance_after해당 거래 직후의 월렛 잔액
ref_id게임 프로바이더가 제공한 외부 참조 ID (있는 경우)
memo거래에 첨부된 메모 (있는 경우)

결과는 최신 순으로 정렬됩니다 (id 기준 내림차순).

주요 참고 사항​

  • 이 API를 통해 플레이어를 생성할 수 없습니다. 플레이어는 브랜드의 인증 정보를 사용하여 게임 프로바이더를 통해 최초 연결할 때 자동으로 등록됩니다.
  • **size 파라미터(page_size 아님)**가 모든 플레이어 및 거래 목록 엔드포인트에서 페이지네이션에 사용됩니다. 최대값은 100입니다.
  • wallet_balance 및 wallet_frozen은 null일 수 있습니다. 등록되었지만 아직 월렛 거래를 수행하지 않은 플레이어의 경우입니다.
  • 팀 간 격리가 적용됩니다. 자신의 팀에 속한 플레이어만 접근할 수 있습니다. 다른 팀의 플레이어 ID에 접근하려고 하면 404 Not Found가 반환됩니다.
  • 거래 내역은 추가 전용이며 최신 순으로 정렬됩니다. page와 size를 사용하여 이전 기록을 조회할 수 있습니다.