---
url: https://developers.webzenk.kr/api/ads.md
---
# 보상형 광고

| | 경로 | 인증 | 설명 |
|---|---|---|---|
| POST | `/v1/ads/sessions` | 유저 | 보상 세션 발급 |
| GET | `/v1/ads/sessions/{id}` | 유저 | 세션 상태 |
| POST | `/v1/ads/sessions/{id}/claim` | 유저 | 지급 완료 보고 |
| GET | `/v1/ads/unclaimed` | 유저 | 콜백은 왔지만 지급 보고가 없는 보상 — **로그인 직후 호출** |
| POST | `/v1/ads/claim` | 유저 | 위 목록의 지급 완료 보고 |

흐름과 MAX 설정은 [보상형 광고 가이드](/guide/ads)를 먼저 보세요. 웹에서는 쓸 수 없습니다(`WEB_NOT_SUPPORTED`).

## 세션 발급

POST `/v1/ads/sessions` — `{ "placement": "daily_chest" }` (생략 시 `default`, 1~64자 `[A-Za-z0-9_.-]`)

```json
{ "session_id": "9f1c…", "placement": "daily_chest", "custom_data": "9f1c…", "expires_in": 3600, "remaining_today": 19 }
```

`custom_data`를 그대로 `MaxSdk.ShowRewardedAd(adUnitId, placement, customData)`에 넣습니다.
하루 한도를 넘었으면 `429 AD_DAILY_CAP` — 광고를 띄우지 마세요.

## 상태 확인

GET `/v1/ads/sessions/{id}`

```json
{ "reward_id": "771", "session_id": "9f1c…", "placement": "daily_chest", "status": "rewarded",
  "reject_reason": null, "amount": "10", "currency": "gold", "rewarded_at": 1795055500, "claimed_at": null }
```

`status`: `pending` · `rewarded` · `claimed` · `rejected` · `expired`

## 지급 완료 보고

POST `/v1/ads/sessions/{id}/claim` → 세션 상태 (`claimed`). `rewarded`가 아니면 `409 AD_NOT_REWARDED`.

GET `/v1/ads/unclaimed` → `{ "items": [ 보상 … ] }`
POST `/v1/ads/claim` — `{ "reward_ids": ["771"] }` → `{ "items": [ { "reward_id": "771", "status": "claimed" } ] }`
