---
url: https://developers.webzenk.kr/api/server.md
---
# 개발사 서버 API

개발사 서버에서 **Server Secret**으로 서명해 호출해요. 서명 방식은 [앱 서명](./#서명-만들기)과 같고 키만 달라요. App Secret으로는 호출할 수 없고, 브라우저(CORS)에서도 호출할 수 없어요.

| | 경로 | 설명 |
|---|---|---|
| GET | `/v1/server/metrics/daily` | 일별 KPI |
| GET | `/v1/server/metrics/retention` | 리텐션 |
| GET | `/v1/server/metrics/events` | 이벤트 일 집계 |
| GET | `/v1/server/purchases` | 상태별 결제 목록 (환불 회수) |
| GET | `/v1/server/players/{id}` | 유저 조회 |
| POST | `/v1/server/players/{id}/ban` | 제재 |
| POST | `/v1/server/players/{id}/unban` | 제재 해제 |

## 지표

모든 지표 API는 `?from=YYYY-MM-DD&to=YYYY-MM-DD` (기본 최근 7일, 최대 92일, 게임 시간대 날짜)를 받고 `{ "from", "to", "items": [ … ] }`를 돌려줘요.

GET `/v1/server/metrics/daily`

```json
{
  "date": "2026-11-18", "dau": 1520, "nru": 210, "purchases": 48, "payers": 41, "pur": 0.027,
  "refunds": 1, "ad_rewards": 930, "ad_viewers": 402, "events": 18820,
  "revenue": [ { "currency": "KRW", "gross": 612000, "refund": 12000, "net": 600000, "purchases": 47, "arpdau": 394.7368 } ],
  "updated_at": 1795055466
}
```

* `pur` 결제율(결제자/DAU), `revenue`는 **통화별** (환산 안 함), 테스트 결제 제외. Google Play 금액은 앱이 보낸 표시 가격 기준.
* 매시간 오늘·어제를 다시 계산해요(최대 1시간 지연).

GET `/v1/server/metrics/retention` → `{ "cohort": "2026-11-01", "cohort_size": 210, "d1": 0.41, "d3": 0.27, "d7": 0.18, … }`

GET `/v1/server/metrics/events?name=stage_clear` → `{ "date", "name", "count", "users" }` (`name` 생략 시 전체)

## 결제 목록 (환불 회수)

GET `/v1/server/purchases?status=refunded&since=<epoch>&limit=100`

```json
{ "items": [ { "purchase_id": "5012", "player_id": "1024", "product_id": "gem_100", "status": "refunded",
               "refunded_at": 1795059000, "refund_reason": "…", "…": "결제 기록 필드" } ],
  "next_since": 1795059000 }
```

* `status`: `refunded`(기본) · `verified` · `consumed` · `pending`
* 다음 호출은 `since=next_since`. 경계 건이 다시 올 수 있으니 `purchase_id`로 중복을 거르세요. → [환불 처리](/guide/refunds)

## 유저

GET `/v1/server/players/{id}` → [내 정보](./auth#내-정보)와 같은 형식

POST `/v1/server/players/{id}/ban` — `{ "reason": "결제 어뷰징" }` → 로그인·토큰 갱신 차단 + 세션 종료 (이미 받은 Access Token은 최대 1시간 유효)

POST `/v1/server/players/{id}/unban` → 제재 해제
