> ## Documentation Index
> Fetch the complete documentation index at: https://guide.daro.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Report API

> DARO Report API를 사용하여 앱의 광고 성과 데이터를 외부에서 직접 조회할 수 있습니다. 앱, 광고 단위, 광고 포맷, 국가, 플랫폼 등 다양한 기준으로 데이터를 그룹핑하여 조회할 수 있습니다.

## 소개

DARO Report API는 고객사가 DARO 대시보드 외부에서 프로그래밍 방식으로 광고 성과 데이터를 조회할 수 있는 REST API입니다. 이 API를 통해 수익, 노출, 클릭 등 주요 지표를 다양한 기준으로 그룹핑하여 조회할 수 있습니다.

## 인증

Report API를 사용하려면 먼저 Access Token을 발급받아야 합니다.

### 1. Secret Key 확인

[DARO 대시보드](https://dashboard.daro.so/service/account)에서 발급된 `report_secret_key`를 확인합니다.

<Note>
  `report_secret_key`가 아직 발급되지 않은 경우, 계정 담당자에게 문의해 주세요.
</Note>

### 2. Access Token 발급

```
POST https://api.daro.so/report/v1/auth
```

**요청 본문:**

```json theme={null}
{
  "secretKey": "YOUR_REPORT_SECRET_KEY"
}
```

**응답:**

```json theme={null}
{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "expiresAt": "2025-01-01T01:00:00Z"
}
```

| 필드          | 타입     | 설명                |
| ----------- | ------ | ----------------- |
| accessToken | String | API 요청에 사용할 인증 토큰 |
| expiresAt   | String | 토큰 만료 시간          |

### 3. API 요청 시 토큰 사용

발급받은 `accessToken`을 HTTP 헤더에 포함하여 API를 호출합니다.

```
Authorization: Bearer {accessToken}
```

**요청 예시:**

```bash theme={null}
curl -X POST "https://api.daro.so/report/v1/auth" \
  -H "Content-Type: application/json" \
  -d '{"secretKey": "YOUR_REPORT_SECRET_KEY"}'
```

<Warning>
  `accessToken`은 `expiresAt`에 명시된 시간이 지나면 만료됩니다. 만료된 경우 `/report/v1/auth` 엔드포인트를 통해 새로운 토큰을 발급받아야 합니다.
</Warning>

## API 정책

### 인증 및 권한 관리

Secret Key는 안전하게 관리해야 하며 타인과 공유해서는 안 됩니다.

### 요청 제한

기본 요청 한도는 분당 100회입니다. 더 높은 요청량이 필요할 경우 DARO 비즈니스팀에 문의하세요.

## 리포트 조회

```
GET https://api.daro.so/report/v1/metrics
```

## 요청 파라미터

모든 파라미터는 쿼리스트링으로 전달합니다.

| 파라미터             | 타입     | 설명                                                        | 예시                                     |     |
| ---------------- | ------ | --------------------------------------------------------- | -------------------------------------- | --- |
| from *(필수)*      | String | 조회 시작 날짜 (`YYYY-MM-DD`)                                   | `2025-01-01`                           |     |
| to *(필수)*        | String | 조회 종료 날짜 (`YYYY-MM-DD`). `from` 이후 날짜여야 하며, 조회 기간은 최대 90일 | `2025-01-31`                           |     |
| group\_by *(필수)* | String | 데이터 그룹핑 기준 (콤마로 복수 지정 가능)                                 | `app,ad_format`                        |     |
| app              | String | 특정 앱으로 필터링                                                | `your_app_key`                         |     |
| ad\_unit\_id     | String | 특정 광고 단위로 필터링                                             | `fa1c6d2f-5016-467d-b54c-672299c7db4c` |     |
| ad\_format       | String | 광고 포맷으로 필터링                                               | `banner`                               |     |
| country          | String | 국가 코드로 필터링                                                | `KR`                                   |     |
| platform         | String | 플랫폼으로 필터링                                                 | `android`                              |     |
| page\_size       | Int    | 페이지당 항목 수 (기본값: 10, 최대: 1000)                             | `20`                                   |     |
| page\_number     | Int    |                                                           | 페이지 번호 (기본값: 1)                        | `1` |

### group\_by 사용 가능한 값

| 값          | 설명         |
| ---------- | ---------- |
| app        | 앱별 그룹핑     |
| ad\_unit   | 광고 단위별 그룹핑 |
| ad\_format | 광고 포맷별 그룹핑 |
| country    | 국가별 그룹핑    |
| platform   | 플랫폼별 그룹핑   |

## 요청 예시

```bash theme={null}
curl -X GET "https://api.daro.so/report/v1/metrics?from=2025-01-01&to=2025-01-31&group_by=app,ad_format&page_size=20&page_number=1" \
  -H "Authorization: Bearer {accessToken}"
```

## 응답

### 응답 필드

| 필드             | 타입     | 설명                                       |
| -------------- | ------ | ---------------------------------------- |
| date           | String | 날짜                                       |
| appKey         | String | 앱 키 (`group_by`에 `app` 포함 시 반환)          |
| appName        | String | 앱 이름 (`group_by`에 `app` 포함 시 반환)         |
| adUnitName     | String | 광고 단위 이름 (`group_by`에 `ad_unit` 포함 시 반환) |
| adFormat       | String | 광고 포맷 (`group_by`에 `ad_format` 포함 시 반환)  |
| country        | String | 국가 코드 (`group_by`에 `country` 포함 시 반환)    |
| platform       | String | 플랫폼 (`group_by`에 `platform` 포함 시 반환)     |
| revenue        | Float  | 수익 (USD)                                 |
| adRequest      | Int    | 광고 요청 수                                  |
| matchedRequest | Int    | 매칭된 요청 수                                 |
| impression     | Int    | 노출 수                                     |
| click          | Int    | 클릭 수                                     |
| matchRate      | Float  | 매칭률 (matchedRequest / adRequest)         |
| showRate       | Float  | 노출률 (impression / matchedRequest)        |
| ctr            | Float  | 클릭률 (click / impression)                 |
| ecpm           | Float  | eCPM (revenue / impression \* 1000)      |

### 응답 예시

```json theme={null}
{
  "data": [
    {
      "date": "2025-01-01",
      "appKey": "your_app_key",
      "appName": "My App",
      "adFormat": "banner",
      "revenue": 123.45,
      "adRequest": 10000,
      "matchedRequest": 8500,
      "impression": 8000,
      "click": 160,
      "matchRate": 0.85,
      "showRate": 0.9412,
      "ctr": 0.02,
      "ecpm": 15.43
    },
    {
      "date": "2025-01-02",
      "appKey": "your_app_key",
      "appName": "My App",
      "adFormat": "interstitial",
      "revenue": 130.20,
      "adRequest": 11000,
      "matchedRequest": 9200,
      "impression": 8700,
      "click": 174,
      "matchRate": 0.8364,
      "showRate": 0.9457,
      "ctr": 0.02,
      "ecpm": 14.97
    }
  ],
  "page_size": 20,
  "page_number": 1,
  "total_count": 31
}
```

<Warning>
  `group_by`에 포함되지 않은 차원의 필드는 응답에서 생략됩니다. 예를 들어 `group_by=app`으로 요청하면 `adUnitName`, `adFormat`, `country` 등의 필드는 응답에 포함되지 않습니다.
</Warning>