> 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>