> For the complete documentation index, see [llms.txt](https://adpopcornssp.gitbook.io/offerwall/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://adpopcornssp.gitbook.io/offerwall/advertiser/report-api.md).

# 리포트 API 연동

## 광고주 리포트 API 연동 <a href="#report-api" id="report-api"></a>

애드팝콘 광고주의 리포트 정보를 조회할 수 있는 API를 안내해요.&#x20;

파트너스 페이지에서 발급받은 accessToken을 이용해 조회해요.

***

### 사전 준비 <a href="#prerequisites" id="prerequisites"></a>

#### Access Token 발급 (필수)

Open API를 사용하려면 accessToken을 발급받아야 해요.&#x20;

파트너스 페이지의 리포트 API 설정 메뉴에서 토큰 활성화 시 발급 가능하며, 회사 당 1개만 발급할 수 있어요.

#### White IP 등록 (권장)

리포트 정보를 요청하는 서버의 IP를 등록해야 해요.&#x20;

등록된 IP에서만 접근이 허용되며, 등록하지 않을 경우 모든 IP에서 접근이 가능해요.

> 복수의 IP를 등록할 때는 콤마(,)로 구분해 주세요. (예: 1.123.4.5, 128.0.0.1)

***

### 제공 API <a href="#api-list" id="api-list"></a>

| API                  | 설명                          | 최대 조회 기간 |
| -------------------- | --------------------------- | -------- |
| 일반 캠페인 기간별 조회        | 일반 캠페인의 기간별 클릭/완료 지표 조회     | 45일      |
| 일반 캠페인 시간별 조회        | 일반 캠페인의 특정 날짜/시간별 지표 조회     | 45일      |
| CPM 캠페인 기간별 조회       | CPM 캠페인의 기간별 노출/클릭/소진 예산 조회 | 45일      |
| CPM 캠페인 그룹 기간별 조회    | CPM 캠페인 그룹별 기간 리포트 조회       | 45일      |
| CPM 캠페인 그룹 소재 기간별 조회 | CPM 캠페인 그룹의 소재별 기간 리포트 조회   | 45일      |

***

### 1. 일반 캠페인 기간별 조회 API <a href="#campaign-report" id="campaign-report"></a>

#### API URL

```
GET https://reward-report.adpopcorn.com/v1/Campaign/Report?accessToken={accessToken}&startDate=yyyy-MM-dd&endDate=yyyy-MM-dd
```

#### Method

GET

#### Content-Type

application/json

#### 파라미터

| 파라미터        | 설명               | 필수 |
| ----------- | ---------------- | -- |
| accessToken | 발급받은 토큰          | 필수 |
| startDate   | 시작일 (yyyy-MM-dd) | 필수 |
| endDate     | 종료일 (yyyy-MM-dd) | 필수 |

> 조회 기간은 최대 45일이에요.

#### 응답

| 필드        | 자료형                   | 설명          |
| --------- | --------------------- | ----------- |
| Result    | int                   | 조회 결과       |
| ResultMsg | String                | 결과 메시지      |
| Data      | List\<ReportModel>    | 일반 리포트 리스트  |
| CPMData   | List\<CPMReportModel> | CPM 리포트 리스트 |

#### ReportModel

| 필드                     | 자료형    | 설명                     |
| ---------------------- | ------ | ---------------------- |
| campaignKey            | String | 캠페인 키                  |
| campaignName           | String | 캠페인 이름                 |
| totalComplete          | Int    | 기간 내 전체 완료자 수          |
| totalClick             | long   | 기간 내 전체 참여자 수          |
| externalCampaignKey    | String | 조회된 캠페인의 외부 업체 키 값(옵션) |
| dailyReport            | List   | 일별 리포트 리스트             |
| dailyReport.reportDate | String | 리포트 날짜 (yyyyMMdd)      |
| dailyReport.click      | long   | 해당 일자 참여자 수            |
| dailyReport.complete   | long   | 해당 일자 완료자 수            |

#### 응답 예시

```json
{
    "Result": true,
    "ResultCode": 1,
    "ResultMsg": "조회에 성공하였습니다.",
    "Data": [
        {
            "campaignKey": "1234567",
            "campaignName": "캠페인 이름",
            "totalComplete": 73,
            "totalClick": 479,
            "externalCampaignKey": null,
            "dailyReport": [
                {
                    "reportDate": "20240321",
                    "click": 140,
                    "complete": 13
                },
                {
                    "reportDate": "20240322",
                    "click": 100,
                    "complete": 25
                },
                {
                    "reportDate": "20240323",
                    "click": 95,
                    "complete": 12
                },
                {
                    "reportDate": "20240324",
                    "click": 88,
                    "complete": 10
                },
                {
                    "reportDate": "20240325",
                    "click": 56,
                    "complete": 13
                }
            ]
        }
    ]
}
```

***

### 2. 일반 캠페인 시간별 조회 API <a href="#campaign-hourly-report" id="campaign-hourly-report"></a>

#### API URL

```
GET https://reward-report.adpopcorn.com/v1/Campaign/Report/Hourly?accessToken={accessToken}&reportDate={yyyyMMdd}&hour={HH}
```

#### Method

GET

#### Content-Type

application/json

#### 파라미터

| 파라미터        | 설명                 | 필수 |
| ----------- | ------------------ | -- |
| accessToken | 발급받은 토큰            | 필수 |
| reportDate  | 조회 날짜 (yyyyMMdd)   | 필수 |
| hour        | 조회 시간 (HH, 00\~23) | 필수 |

> 조회 기간은 최대 45일이에요.

#### 응답

| 필드        | 자료형                      | 설명         |
| --------- | ------------------------ | ---------- |
| Result    | int                      | 조회 결과      |
| ResultMsg | String                   | 결과 메시지     |
| Data      | List\<HourlyReportModel> | 리포트 정보 리스트 |

#### HourlyReportModel

| 필드                  | 자료형    | 설명                     |
| ------------------- | ------ | ---------------------- |
| reportDate          | String | 리포트 날짜 (yyyyMMdd)      |
| reportHour          | String | 리포트 시간 (HH)            |
| campaignKey         | String | 캠페인 키                  |
| campaignName        | String | 캠페인 이름                 |
| complete            | long   | 완료자 수                  |
| click               | long   | 참여자 수                  |
| externalCampaignKey | String | 조회된 캠페인의 외부 업체 키 값(옵션) |

#### 응답 예시

```json
{
    "Result": true,
    "ResultCode": 1,
    "ResultMsg": "조회에 성공하였습니다.",
    "Data": [
        {
            "reportDate": "20240805",
            "reportHour": "12",
            "campaignKey": "1704143714",
            "campaignName": "[WEB_CPL] 채널S 유튜브 구독",
            "complete": 160,
            "click": 339,
            "externalCampaignKey": null
        }
    ]
}
```

***

### 3. CPM 캠페인 기간별 조회 API <a href="#cpm-campaign-report" id="cpm-campaign-report"></a>

#### API URL

```
GET https://reward-report.adpopcorn.com/v1/CPMCampaign/Report?accessToken={accessToken}&startDate=yyyy-MM-dd&endDate=yyyy-MM-dd
```

#### Method

GET

#### Content-Type

application/json

#### 파라미터

| 파라미터        | 설명               | 필수 |
| ----------- | ---------------- | -- |
| accessToken | 발급받은 토큰          | 필수 |
| startDate   | 시작일 (yyyy-MM-dd) | 필수 |
| endDate     | 종료일 (yyyy-MM-dd) | 필수 |

> 조회 기간은 최대 45일이에요.

#### 응답

| 필드        | 자료형                   | 설명         |
| --------- | --------------------- | ---------- |
| Result    | int                   | 조회 결과      |
| ResultMsg | String                | 결과 메시지     |
| Data      | List\<CPMReportModel> | 리포트 정보 리스트 |

#### CPMReportModel

| 필드                      | 자료형    | 설명                     |
| ----------------------- | ------ | ---------------------- |
| campaignKey             | String | 캠페인 키                  |
| campaignName            | String | 캠페인 이름                 |
| totalImp                | long   | 기간 내 전체 노출 수           |
| totalClick              | long   | 기간 내 전체 클릭 수           |
| totalCtr                | double | 기간 내 CTR               |
| totalSpentBudget        | long   | 기간 내 소진 예산             |
| externalCampaignKey     | String | 조회된 캠페인의 외부 업체 키 값(옵션) |
| dailyReport             | List   | 일별 리포트 리스트             |
| dailyReport.reportDate  | String | 리포트 날짜 (yyyyMMdd)      |
| dailyReport.imp         | long   | 노출 수                   |
| dailyReport.click       | long   | 클릭 수                   |
| dailyReport.ctr         | long   | 클릭률                    |
| dailyReport.spentBudget | long   | 소진 예산                  |

#### 응답 예시

```json
{
    "Result": true,
    "ResultCode": 1,
    "ResultMsg": "조회에 성공하였습니다.",
    "Data": [
        {
            "campaignKey": "1234567",
            "campaignName": "캠페인 이름",
            "totalImp": 73,
            "totalClick": 479,
            "totalCtr": 0.1,
            "totalSpentBudget": 10000,
            "externalCampaignKey": null,
            "dailyReport": [
                {
                    "reportDate": "20240321",
                    "imp": 140,
                    "click": 13,
                    "ctr": 0.1,
                    "spentBudget": 100
                },
                {
                    "reportDate": "20240322",
                    "imp": 100,
                    "click": 25,
                    "ctr": 0.1,
                    "spentBudget": 100
                }
            ]
        }
    ]
}
```

***

### 4. CPM 캠페인 그룹 기간별 조회 API <a href="#cpm-campaign-group-report" id="cpm-campaign-group-report"></a>

#### API URL

```
GET https://reward-report.adpopcorn.com/v1/CPMCampaign/Report/Group?accessToken={accessToken}&startDate=yyyy-MM-dd&endDate=yyyy-MM-dd&campaignKey={campaignKey}
```

#### Method

GET

#### Content-Type

application/json

#### 파라미터

| 파라미터        | 설명               | 필수 |
| ----------- | ---------------- | -- |
| accessToken | 발급받은 토큰          | 필수 |
| startDate   | 시작일 (yyyy-MM-dd) | 필수 |
| endDate     | 종료일 (yyyy-MM-dd) | 필수 |
| campaignKey | 캠페인 키            | 필수 |

> 조회 기간은 최대 45일이에요.

#### 응답

| 필드        | 자료형                        | 설명         |
| --------- | -------------------------- | ---------- |
| Result    | int                        | 조회 결과      |
| ResultMsg | String                     | 결과 메시지     |
| Data      | List\<CPMGroupReportModel> | 리포트 정보 리스트 |

#### CPMGroupReportModel

| 필드                      | 자료형    | 설명                |
| ----------------------- | ------ | ----------------- |
| groupKey                | String | 그룹 키              |
| groupName               | String | 그룹 이름             |
| totalImp                | long   | 기간 내 전체 노출 수      |
| totalClick              | long   | 기간 내 전체 클릭 수      |
| totalCtr                | double | 기간 내 CTR          |
| totalSpentBudget        | long   | 기간 내 소진 예산        |
| dailyReport             | List   | 일별 리포트 리스트        |
| dailyReport.reportDate  | String | 리포트 날짜 (yyyyMMdd) |
| dailyReport.imp         | long   | 노출 수              |
| dailyReport.click       | long   | 클릭 수              |
| dailyReport.ctr         | long   | CTR               |
| dailyReport.spentBudget | long   | 소진 예산             |

#### 응답 예시

```json
{
    "Result": true,
    "ResultCode": 1,
    "ResultMsg": "조회에 성공하였습니다.",
    "Data": [
        {
            "groupKey": "1234567",
            "groupName": "그룹 이름",
            "totalImp": 73,
            "totalClick": 479,
            "totalCtr": 0.1,
            "totalSpentBudget": 10000,
            "dailyReport": [
                {
                    "reportDate": "20240321",
                    "imp": 140,
                    "click": 13,
                    "ctr": 0.1,
                    "spentBudget": 100
                },
                {
                    "reportDate": "20240322",
                    "imp": 100,
                    "click": 25,
                    "ctr": 0.1,
                    "spentBudget": 100
                }
            ]
        }
    ]
}
```

***

### 5. CPM 캠페인 그룹 소재 기간별 조회 API <a href="#cpm-campaign-creative-report" id="cpm-campaign-creative-report"></a>

#### API URL

```
GET https://reward-report.adpopcorn.com/v1/CPMCampaign/Report/Creative?accessToken={accessToken}&startDate=yyyy-MM-dd&endDate=yyyy-MM-dd&groupKey={groupKey}
```

#### Method

GET

#### Content-Type

application/json

#### 파라미터

| 파라미터        | 설명               | 필수 |
| ----------- | ---------------- | -- |
| accessToken | 발급받은 토큰          | 필수 |
| startDate   | 시작일 (yyyy-MM-dd) | 필수 |
| endDate     | 종료일 (yyyy-MM-dd) | 필수 |
| groupKey    | 그룹 키             | 필수 |

> 조회 기간은 최대 45일이에요.

#### 응답

| 필드        | 자료형                                | 설명         |
| --------- | ---------------------------------- | ---------- |
| Result    | int                                | 조회 결과      |
| ResultMsg | String                             | 결과 메시지     |
| Data      | List\<CPMGroupCreativeReportModel> | 리포트 정보 리스트 |

#### CPMGroupCreativeReportModel

| 필드                      | 자료형    | 설명                |
| ----------------------- | ------ | ----------------- |
| creativeId              | String | 소재 ID             |
| creativeName            | String | 소재 이름             |
| totalImp                | long   | 기간 내 전체 노출 수      |
| totalClick              | long   | 기간 내 전체 클릭 수      |
| totalCtr                | double | 기간 내 CTR          |
| totalSpentBudget        | long   | 기간 내 소진 예산        |
| dailyReport             | List   | 일별 리포트 리스트        |
| dailyReport.reportDate  | String | 리포트 날짜 (yyyyMMdd) |
| dailyReport.imp         | long   | 노출 수              |
| dailyReport.click       | long   | 클릭 수              |
| dailyReport.ctr         | long   | CTR               |
| dailyReport.spentBudget | long   | 소진 예산             |

#### 응답 예시

```json
{
    "Result": true,
    "ResultCode": 1,
    "ResultMsg": "조회에 성공하였습니다.",
    "Data": [
        {
            "creativeId": "1234567",
            "creativeName": "소재 이름",
            "totalImp": 73,
            "totalClick": 479,
            "totalCtr": 0.1,
            "totalSpentBudget": 10000,
            "dailyReport": [
                {
                    "reportDate": "20240321",
                    "imp": 140,
                    "click": 13,
                    "ctr": 0.1,
                    "spentBudget": 100
                },
                {
                    "reportDate": "20240322",
                    "imp": 100,
                    "click": 25,
                    "ctr": 0.1,
                    "spentBudget": 100
                }
            ]
        }
    ]
}
```

***

### 관련 가이드 <a href="#related-guides" id="related-guides"></a>

* 파트너스 운영 관리 → [**\[파트너스 운영 관리\]**](/offerwall/advertiser/partners-page/operation.md)
* 기술 문의: <reward@adpopcorn.com>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://adpopcornssp.gitbook.io/offerwall/advertiser/report-api.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.