게임플레이 파트너 가이드

테마 전환

CP별 리포트 API ​

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

리포트 설정값 필수 ​

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

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

관련 가이드: 광고 UX 가이드, 애드핏 설정

Endpoint ​

http
GET https://adfit-external-api.kakao.com/publisher/v3/report/channel/{channel}
항목값
환경Production 전용
인증API Key (Query Parameter)
Content-Typeapplication/json

API Key 발급 ​

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

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

Request ​

Path Parameters ​

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

Query Parameters ​

이름타입포맷설명
apikeystring—필수발급받은 API Key
fromDatestringyyyy-MM-dd 또는 yyyy-MM필수조회 시작일
toDatestringyyyy-MM-dd 또는 yyyy-MM필수조회 종료일
periodTypestringDAY 또는 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
  }
]

필드 상세 ​

필드타입설명계산식
reportDatestring조회 일자(yyyy-MM-dd) 또는 월(yyyy-MM)—
adunitIdstring광고단위 ID—
adunitNamestring광고단위명—
channelstring카카오에서 발급한 채널 ID—
cpstring파트너사가 설정한 게임 코드와 동일한 CPID—
adRequestCountlong광고 요청 수—
winCountlong광고 응답(낙찰) 수—
impressionCountlong렌더드 노출 수—
viewableImpressionCountlong노출 수—
clickCountlong클릭 수—
profitbigDecimal적립금 (원)—
fillRatedoubleFill Rate (%)impressionCount / adRequestCount × 100
vrdoubleViewable Rate (%)viewableImpressionCount / impressionCount × 100
ctrdoubleCTR (%)clickCount / viewableImpressionCount × 100
ecpmdoubleeCPMprofit / 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 기준)
정렬응답은 날짜 오름차순

참고 문서 ​