---
url: /api-sdk/ads/cp-report.md
description: 채널별 CP(Content Provider) 보고서를 조회하는 애드핏 External API
---

# CP별 리포트 API

채널별 CP(Content Provider) 보고서를 조회하는 애드핏 External API입니다. 퍼블리셔가 API Key 인증으로 채널별 일간·월간 보고서 데이터를 조회할 수 있습니다.

## 리포트 설정값 

게임별 광고 지표를 정확하게 조회하려면 CPID와 채널 ID를 아래 기준으로 설정해야 합니다.

| 값 | 설정 기준 |
| --- | --- |
| **CPID** | 게임플레이 파트너센터에 등록한 게임 코드와 **동일한 값**을 입력합니다.메타데이터 API로 게임을 등록했던 파트너사는 그 `code` 값을 그대로 유지합니다. |
| **채널 ID** | 카카오에서 발급한 값을 사용합니다.발급값 확인이 필요한 경우 카카오 담당자에게 문의하세요. |

> **관련 가이드**: [광고 UX 가이드](/docs/ads/ux-guideline), [애드핏 설정](/docs/ads/iaa-options)

## Endpoint

```http
GET https://adfit-external-api.kakao.com/publisher/v3/report/channel/{channel}
```

| 항목 | 값 |
| --- | --- |
| 환경 | Production 전용 |
| 인증 | API Key (Query Parameter) |
| Content-Type | `application/json` |

## API Key 발급

애드핏 프론트(`https://adfit.kakao.com`)에 로그인한 뒤 **보고서 > API 키 관리** 메뉴에서 발급받습니다. 메뉴가 보이지 않는 경우 애드핏에 문의합니다.

* API Key는 퍼블리셔별로 발급됩니다
* 일일 요청 제한: **200회**

## Request

### Path Parameters

| 이름 | 타입 | 설명 |
| --- | --- | --- |
| `channel` | `string` | 필수채널 ID.카카오에서 파트너사별로 발급하는 값 |

### Query Parameters

| 이름 | 타입 | 포맷 | 설명 |
| --- | --- | --- | --- |
| `apikey` | `string` | — | 필수발급받은 API Key |
| `fromDate` | `string` | `yyyy-MM-dd` 또는 `yyyy-MM` | 필수조회 시작일 |
| `toDate` | `string` | `yyyy-MM-dd` 또는 `yyyy-MM` | 필수조회 종료일 |
| `periodType` | `string` | `DAY` 또는 `MONTH` (대소문자 무관) | 기본값 `DAY`조회 단위 |

### 예시

```bash
# 일간 조회 (기본)
curl -X GET "https://adfit-external-api.kakao.com/publisher/v3/report/channel/채널명\
?apikey=YOUR_API_KEY&fromDate=2026-01-01&toDate=2026-01-31"

# 월간 조회
curl -X GET "https://adfit-external-api.kakao.com/publisher/v3/report/channel/채널명\
?apikey=YOUR_API_KEY&fromDate=2026-01&toDate=2026-06&periodType=MONTH"
```

## Response

### 성공 (`200 OK`)

응답은 리포트 항목 배열이며 날짜 오름차순으로 정렬됩니다.

```json
[
  {
    "reportDate": "2025-01-02",
    "adunitId": "05d24",
    "adunitName": "광고단위명",
    "channel": "카카오에서 발급한 채널 ID",
    "cp": "파트너사가 설정한 게임 코드와 동일한 CPID",
    "adRequestCount": 0,
    "winCount": 0,
    "impressionCount": 1,
    "viewableImpressionCount": 0,
    "clickCount": 0,
    "profit": 0,
    "fillRate": 0,
    "vr": 0,
    "ctr": 0,
    "ecpm": 0
  }
]
```

### 필드 상세

| 필드 | 타입 | 설명 | 계산식 |
| --- | --- | --- | --- |
| `reportDate` | `string` | 조회 일자(`yyyy-MM-dd`) 또는 월(`yyyy-MM`) | — |
| `adunitId` | `string` | 광고단위 ID | — |
| `adunitName` | `string` | 광고단위명 | — |
| `channel` | `string` | 카카오에서 발급한 채널 ID | — |
| `cp` | `string` | 파트너사가 설정한 게임 코드와 동일한 CPID | — |
| `adRequestCount` | `long` | 광고 요청 수 | — |
| `winCount` | `long` | 광고 응답(낙찰) 수 | — |
| `impressionCount` | `long` | 렌더드 노출 수 | — |
| `viewableImpressionCount` | `long` | 노출 수 | — |
| `clickCount` | `long` | 클릭 수 | — |
| `profit` | `bigDecimal` | 적립금 (원) | — |
| `fillRate` | `double` | Fill Rate (%) | `impressionCount / adRequestCount × 100` |
| `vr` | `double` | Viewable Rate (%) | `viewableImpressionCount / impressionCount × 100` |
| `ctr` | `double` | CTR (%) | `clickCount / viewableImpressionCount × 100` |
| `ecpm` | `double` | eCPM | `profit / viewableImpressionCount × 1000` |

모든 필드는 항상 응답에 포함됩니다. 데이터가 없는 경우 숫자 필드는 `0`, 비율 필드는 `0.0`으로 반환됩니다.

## 에러

에러 발생 시 아래 형식으로 응답합니다.

```json
{
  "message": "에러 메시지",
  "details": null,
  "code": "ERROR_CODE"
}
```

### 주요 에러 케이스

| HTTP | 메시지 | 원인 |
| --- | --- | --- |
| `400` | 파라미터 형식이 잘못되었습니다. 사용 가능한 값: `yyyy-MM-dd`, `yyyy-MM` | 날짜 포맷 오류 |
| `400` | 허용된 조회 기간을 초과하였습니다. (일: 90일, 월: 12개월) | 조회 기간 초과 |
| `400` | 허용되지 않은 기간 유형입니다. | `periodType` 값 오류 |
| `401` | — | API Key 인증 실패 |
| `403` | — | 권한 없음 또는 IP 차단 |

## 제약 조건

| 항목 | 제한 |
| --- | --- |
| 일간 조회 기간 | 최대 90일 (`periodType=DAY`) |
| 월간 조회 기간 | 최대 12개월, 365일 (`periodType=MONTH`) |
| 날짜 순서 | `fromDate ≤ toDate` |
| 일일 요청 수 | 200회 (퍼블리셔 API Key 기준) |
| 정렬 | 응답은 날짜 오름차순 |

## 참고 문서

* [애드핏 광고 SDK](/api-sdk/sdk/adfit)
* [애드핏 설정](/docs/ads/iaa-options)
* 기술 문의: [카카오디벨로퍼스 데브톡](https://devtalk.kakao.com/c/game-play/353)