# Report API Guide

{% hint style="info" %}
카카오 리포트 API는 **한국 표준시(UTC+9)**를 기준으로 데이터를 제공합니다.

리포트 등록 시, **한국 표준시(UTC+9)**를 기준으로 데이터 등록 필요합니다. 
{% endhint %}

### 1. 문서 버전 <a href="#id-kakao-dsp-api-1" id="id-kakao-dsp-api-1"></a>

| 날짜         | 버전  | 내용    |
| ---------- | --- | ----- |
| 2025-10-13 | 0.1 | 초안 작성 |

### 2. 개요 <a href="#id-kakao-dsp-api-2" id="id-kakao-dsp-api-2"></a>

**리포트 API 가이드 문서입니다.**

### 3. API <a href="#id-kakao-dsp-api-3.api" id="id-kakao-dsp-api-3.api"></a>

**Https 는 필수입니다.**

| domain                  |
| ----------------------- |
| <https://adx.kakao.com> |

#### &#x20;3.1 리포트 등록 API  <a href="#id-kakao-dsp-api-3.1-api" id="id-kakao-dsp-api-3.1-api"></a>

<mark style="color:purple;">**DSP가 DSP의 리포트를 카카오에 등록하기 위한 API 입니다.**</mark>

**3.1.1 리포트 등록 API**

<mark style="color:purple;">**DSP가 리포트를 등록(json)하는 API 입니다.**</mark>

{% hint style="info" %}
전월 정산마감 이후에는 전월 데이터 수정이 불가합니다. (예시 - 10월 정산마감 이후 10월 리포트 수정 불가)
{% endhint %}

\
**3.1.1.1 Request**

* Path : <mark style="color:$primary;">**POST**</mark>**&#x20;**<mark style="color:orange;">**/external/api/v1/dsp/report/json**</mark>
* Header

| name          | type   | required | value                 | description                       |
| ------------- | ------ | -------- | --------------------- | --------------------------------- |
| Authorization | string | true     | Bearer ${accessToken} | **accessToken은 카카오 담당자가 발급하여 전달** |
| Content-Type  | string | true     | application/json      | 서버로 전송하는 데이터 타입 명시                |
| Accept        | string | true     | application/json      | 서버로부터 받고자 하는 데이터 유형               |

* Request Parameter

| parameter | type   | required | sample value | description                                         |
| --------- | ------ | -------- | ------------ | --------------------------------------------------- |
| currency  | string | false    | KRW          | <p>통화 종류(KRW, USD)<br><strong>기본값은 KRW</strong></p> |

* Request Body

| parameter      | type   | required | sample value | description    |
| -------------- | ------ | -------- | ------------ | -------------- |
| \[].reportDate | string | true     | 2023-01-01   | 리포트 일자 (UTC+9) |
| \[].adunitId   | string | true     | 0Qv33        | 광고단위 아이디       |
| \[].cnt        | long   | true     | 1000         | 노출 카운트         |
| \[].sales      | double | true     | 1000.5       | 매출             |
| \[].click      | long   | false    | 100          | 클릭 카운트         |

\
**3.1.1.2 Response**

* Response Body

{% hint style="info" %}
정상 - 201(CREATED)
{% endhint %}

| column | type | name | description |
| ------ | ---- | ---- | ----------- |
| -      | -    | -    | -           |

{% hint style="info" %}
인증 실패 - 401(UNAUTHORIZED)
{% endhint %}

| column  | type   | name                             | description |
| ------- | ------ | -------------------------------- | ----------- |
| code    | string | UNAUTHORIZED                     | <p><br></p> |
| message | string | 인증실패                             | <p><br></p> |
| details | string | jwt token authentication failed! | <p><br></p> |

{% hint style="info" %}
에러 - 500(INTERNAL SERVER ERROR)
{% endhint %}

| column  | type   | name                  | description |
| ------- | ------ | --------------------- | ----------- |
| code    | string | INTERNAL SERVER ERROR | <p><br></p> |
| message | string | 서버에러                  | <p><br></p> |
| details | string | error...              | <p><br></p> |

**3.1.1.3 Example**

* Request

{% hint style="info" %}
currency = KRW 일 경우
{% endhint %}

```
curl --location 'https://adx.kakao.com/external/api/v1/dsp/report/json' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ${accessToken}' \
--data '[
   {
      "reportDate":"2024-01-01",
      "adunitId":"0Qv33",
      "cnt":"1000",
      "sales":"1000.0",
      "click":"100"
   },
   {
      "reportDate":"2024-01-01",
      "adunitId":"0Qv30",
      "cnt":"500",
      "sales":"700.0",
      "click":"70"
   }
]'
```

{% hint style="info" %}
currency = USD 일 경우
{% endhint %}

```
curl --location 'https://adx.kakao.com/external/api/v1/dsp/report/json?currency=USD' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ${accessToken}' \
--data '[
	{
		"reportDate":"2024-02-10",
		"adunitId":"0Qv33",
		"cnt":"1000",
		"sales":"1.2",
			"click":"100"
	},
	{
		"reportDate":"2024-02-10",
		"adunitId":"0Qv30",
		"cnt":"500",
		"sales":"0.7",
		"click":"70"
	}
]'
```

* Response

```
HTTP/2 201
date: Fri, 14 Jul 2023 02:26:53
content-length: 0
x-content-type-options: nosniff
x-xss-protection: 1; mode=block
cache-control: no-cache, no-store, max-age=0, must-revalidate
pragma: no-cache
expires: 0
strict-transport-security: max-age=15724800; includeSubDomains
x-frame-options: DENY
```

***

#### 3.2 리포트 조회 API  <a href="#id-kakao-dsp-api-3.2-api" id="id-kakao-dsp-api-3.2-api"></a>

<mark style="color:purple;">**DSP가 카카오에 등록한 DSP의 리포트를 조회하기 위한 API 입니다.**</mark>

**3.2.1 리포트 API**

<mark style="color:purple;">**DSP가 등록한 리포트 조회(json) API 입니다.**</mark>

**3.2.1.1 Request**

* Path : <mark style="color:$primary;">**GET**</mark> <mark style="color:orange;">**/external/api/v1/dsp/report**</mark>
* Header

| name          | type   | required | sample value          | description                       |
| ------------- | ------ | -------- | --------------------- | --------------------------------- |
| Authorization | string | true     | Bearer ${accessToken} | **accessToken은 카카오 담당자가 발급하여 전달** |
| Accept        | string | true     | application/json      | 서버로부터 받고자 하는 데이터 유형               |

* Request Parameter

| parameter | type   | required | sample value | description      |
| --------- | ------ | -------- | ------------ | ---------------- |
| start     | string | true     | 2023-01-01   | 조회 시작 일자 (UTC+9) |
| end       | string | true     | 2023-01-07   | 조회 종료 일자 (UTC+9) |

\
\
**3.2.1.2 Response**

* Response Body

{% hint style="info" %}
정상 - 200(OK) : KRW 예시
{% endhint %}

| column           | type   | sample value | description    |
| ---------------- | ------ | ------------ | -------------- |
| reportDate       | string | 2023-01-01   | 리포트 일자 (UTC+9) |
| dspId            | string | TEST\_DSP    | <p><br></p>    |
| adunitId         | string | 0Qv33        | 광고단위           |
| cnt              | long   | 100          | 노출 카운트         |
| sales            | double | 1000.0       | 매출(KRW)        |
| click            | long   | 10           | 클릭 카운트         |
| originalSales    | double | 1000.0       | 원본 매출          |
| originalCurrency | string | KRW          | 통화             |
| exhangeRate      | double | 1.0          | <p>환율<br></p>  |

{% hint style="info" %}
정상 - 200(OK) : USD 예시
{% endhint %}

| column           | type   | sample value | description                     |
| ---------------- | ------ | ------------ | ------------------------------- |
| reportDate       | string | 2023-01-01   | 리포트 일자 (UTC+9)                  |
| dspId            | string | TEST\_DSP    | <p><br></p>                     |
| adunitId         | string | 0Qv33        | 광고단위                            |
| cnt              | long   | 100          | 노출 카운트                          |
| sales            | double | 1353.6       | 매출(KRW)                         |
| click            | long   | 10           | 클릭 카운트                          |
| originalSales    | double | 1.0          | 원본 매출                           |
| originalCurrency | string | USD          | 원본 통화                           |
| exhangeRate      | double | 1353.6       | 환율 (하나은행, 리포트 일자 23:30 기준 고시환율) |

{% hint style="info" %}
인증 실패 - 401(UNAUTHORIZED)
{% endhint %}

| column  | type   | sample value                     | description |
| ------- | ------ | -------------------------------- | ----------- |
| code    | string | UNAUTHORIZED                     | <p><br></p> |
| message | string | 인증실패                             | <p><br></p> |
| details | string | jwt token authentication failed! | <p><br></p> |

{% hint style="info" %}
에러 - 500(INTERNAL SERVER ERROR)
{% endhint %}

| column  | type   | sample value          | description |
| ------- | ------ | --------------------- | ----------- |
| code    | string | INTERNAL SERVER ERROR | <p><br></p> |
| message | string | 서버에러                  | <p><br></p> |
| details | string | error...              | <p><br></p> |

\
\
**3.2.1.3 Example**

{% hint style="info" %}
currency = KRW 일경우
{% endhint %}

* Request&#x20;

```
curl --location 'https://adx.kakao.com/external/api/v1/dsp/report?start=2024-01-01&end=2024-01-01' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer ${accessToken}'

```

* Response

```
[
    {
        "reportDate": "2024-01-01",
        "dspId": "TEST_DSP",
        "adunitId": "0Qv33",
        "cnt": 1000,
        "click": 100,
        "sales": 1000.0,
        "originalSales": 1000.0,
        "originalCurrency": "KRW",
        "exchangeRate": 1.0
    },
    {
        "reportDate": "2024-01-01",
        "dspId": "TEST_DSP",
        "adunitId": "0Qv30",
        "cnt": 500,
        "click": 70,
        "sales": 700.0,
        "originalSales": 700.0,
        "originalCurrency": "KRW",
        "exchangeRate": 1.0
    }
]
```

{% hint style="info" %}
currency = USD 일경우
{% endhint %}

* Request

```
curl --location 'https://adx.kakao.com/external/api/v1/dsp/report?start=2024-02-10&end=2024-02-10' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer ${accessToken}'
```

* Response

```
[
    {
        "reportDate": "2024-02-10",
        "dspId": "TEST_DSP",
        "adunitId": "0Qv33",
        "cnt": 1000,
        "click": 100,
        "sales": 1598.4,
        "originalSales": 1.2,
        "originalCurrency": "USD",
        "exchangeRate": 1332.0
    },
    {
        "reportDate": "2024-02-10",
        "dspId": "TEST_DSP",
        "adunitId": "0Qv30",
        "cnt": 500,
        "click": 70,
        "sales": 932.4,
        "originalSales": 0.7,
        "originalCurrency": "USD",
        "exchangeRate": 1332.0
    }
]
```

***

\
**3.2.2 Report  CSV Download API**

<mark style="color:purple;">**DSP가 카카오에 등록한 리포트를 CSV 다운로드하는 API 입니다.**</mark>

\
**3.2.2.1 Request**

* Path : <mark style="color:$primary;">**GET**</mark> <mark style="color:orange;">**/external/api/v1/dsp/report/csv**</mark>
* Header

| name          | type   | required | sample value          | description                       |
| ------------- | ------ | -------- | --------------------- | --------------------------------- |
| Authorization | string | true     | Bearer ${accessToken} | **accessToken은 카카오 담당자가 발급하여 전달** |

* Request Parameter

| parameter | type   | required | sample value | description      |
| --------- | ------ | -------- | ------------ | ---------------- |
| start     | string | true     | 2023-01-01   | 조회 시작 일자 (UTC+9) |
| end       | string | true     | 2023-01-07   | 조회 종료 일자 (UTC+9) |

\
**3.2.2.2 Response**

* Response Body

{% hint style="info" %}
정상 - 200(OK) : KRW 예시 CSV File Download
{% endhint %}

| column           | type   | sample value | description    |
| ---------------- | ------ | ------------ | -------------- |
| reportDate       | string | 2023-01-01   | 리포트 일자 (UTC+9) |
| dspId            | string | TEST\_DSP    | <p><br></p>    |
| adunitId         | string | 0Qv33        | 광고단위           |
| cnt              | long   | 100          | 노출 카운트         |
| sales            | double | 1000.0       | 매출(KRW)        |
| click            | long   | 10           | 클릭 카운트         |
| originalSales    | double | 1000.0       | 원본 매출          |
| originalCurrency | string | KRW          | 원본 통화          |
| exhangeRate      | double | 1.0          | 환율             |

{% hint style="info" %}
정상 - 200(OK) : USD 예시 CSV File Download
{% endhint %}

| column           | type   | sample value | description    |
| ---------------- | ------ | ------------ | -------------- |
| reportDate       | string | 2023-01-01   | 리포트 일자 (UTC+9) |
| dspId            | string | TEST\_DSP    | <p><br></p>    |
| adunitId         | string | 0Qv33        | 광고단위           |
| cnt              | long   | 100          | 노출 카운트         |
| sales            | double | 1000.0       | 매출(KRW)        |
| click            | long   | 10           | 클릭 카운트         |
| originalSales    | double | 100.5        | 원본 매출          |
| originalCurrency | string | USD          | 원본 통화          |
| exhangeRate      | double | 1398.8       | 환율             |

{% hint style="info" %}
인증 실패 - 401(UNAUTHORIZED)
{% endhint %}

| column  | type   | sample value                     | description |
| ------- | ------ | -------------------------------- | ----------- |
| code    | string | UNAUTHORIZED                     | <p><br></p> |
| message | string | 인증실패                             | <p><br></p> |
| details | string | jwt token authentication failed! | <p><br></p> |

{% hint style="info" %}
에러 - 500(INTERNAL SERVER ERROR)
{% endhint %}

| column  | type   | sample value          | description |
| ------- | ------ | --------------------- | ----------- |
| code    | string | INTERNAL SERVER ERROR | <p><br></p> |
| message | string | 서버에러                  | <p><br></p> |
| details | string | error...              | <p><br></p> |

\
**3.2.2.3 Example**

* Request

```
curl --location 'https://adx.kakao.com/external/api/v1/dsp/report/csv?start=2024-01-01&end=2024-01-01' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer ${accessToken}'
```

* Response\
  [샘플](https://wiki.daumkakao.com/download/attachments/1932318155/2023-07-14T11_08_51.966064_TEST_DSP_Sales_Report.csv?version=1\&modificationDate=1761702467000\&api=v2)\
  \ <br>

***

**3.2.3 카카오 리포트 API**

<mark style="color:purple;">**카카오 리포트 조회(json) API 입니다.**</mark>

{% hint style="info" %}
Kakao Report는 2023/09/01 부터의 데이터만 조회 가능합니다.&#x20;

한 번에 조회 가능한 기간은 최대 7일 입니다.
{% endhint %}

\
**3.2.3.1 Request**

* Path : <mark style="color:$primary;">**GET**</mark> <mark style="color:orange;">**/external/api/v1/dsp/report/kakao**</mark>
* Header

| name          | type   | required | sample value          | description                       |
| ------------- | ------ | -------- | --------------------- | --------------------------------- |
| Authorization | string | true     | Bearer ${accessToken} | **accessToken은 카카오 담당자가 발급하여 전달** |
| Accept        | string | true     | application/json      | 서버로부터 받고자 하는 데이터 유형               |

* Request Parameter

| parameter | type   | required | sample value | description      |
| --------- | ------ | -------- | ------------ | ---------------- |
| start     | string | true     | 2023-09-01   | 조회 시작 일자 (UTC+9) |
| end       | string | true     | 2023-09-07   | 조회 종료 일자 (UTC+9) |

<br>

**3.2.3.2 Response**

* Response Body

{% hint style="info" %}
정상 - 200(OK)
{% endhint %}

| column     | type   | sample value | description    |
| ---------- | ------ | ------------ | -------------- |
| reportDate | string | 2023-01-01   | 리포트 일자 (UTC+9) |
| dspId      | string | TEST\_DSP    | <p><br></p>    |
| adunitId   | string | 0Qv33        | 광고단위           |
| cnt        | long   | 100          | 노출 카운트         |
| sales      | double | 1000.0       | 매출(KRW)        |
| click      | long   | 10           | 클릭 카운트         |

{% hint style="info" %}
인증 실패 - 401(UNAUTHORIZED)
{% endhint %}

| column  | type   | sample value                     | description |
| ------- | ------ | -------------------------------- | ----------- |
| code    | string | UNAUTHORIZED                     | <p><br></p> |
| message | string | 인증실패                             | <p><br></p> |
| details | string | jwt token authentication failed! | <p><br></p> |

{% hint style="info" %}
에러 - 500(INTERNAL SERVER ERROR)
{% endhint %}

| column  | type   | sample value          | description |
| ------- | ------ | --------------------- | ----------- |
| code    | string | INTERNAL SERVER ERROR | <p><br></p> |
| message | string | 서버에러                  | <p><br></p> |
| details | string | error...              | <p><br></p> |

\
\
**3.2.3.3 Example**

* Request

```
curl 'https://adx.kakao.com/external/api/v1/dsp/report/kakao?start=2023-07-08&end=2023-07-13' -i -X GET \
-H 'Authorization: Bearer ${accessToken}'
```

* Response

```
[
   {
      "reportDate":"2023-07-13",
      "dspId":"TEST_DSP",
      "adunitId":"0Qv33",
      "cnt":100,
      "sales":2000.0,
      "click":10
    },
   {
      "reportDate":"2023-07-12",
      "dspId":"TEST_DSP",
      "adunitId":"0Qv33",
      "cnt":100,
      "sales":2000.0,
      "click":10 
   },
   {
      "reportDate":"2023-07-11",
      "dspId":"TEST_DSP",
      "adunitId":"0Qv33",
      "cnt":100,
      "sales":2000.0,
       "click":10
   },
   {
      "reportDate":"2023-07-10",
      "dspId":"TEST_DSP",
      "adunitId":"0Qv33",
      "cnt":100,
      "sales":2000.0,
      "click":10 
   },
   {
      "reportDate":"2023-07-09",
      "dspId":"TEST_DSP",
      "adunitId":"0Qv33",
      "cnt":100,
      "sales":2000.0,
      "click":10
   },
   {
      "reportDate":"2023-07-08",
      "dspId":"TEST_DSP",
      "adunitId":"0Qv33",
      "cnt":100,
      "sales":2000.0,
      "click":10 
  }
]
```

***

**3.2.4 카카오 리포트  CSV Download API**

<mark style="color:purple;">**카카오 리포트를 CSV 다운로드하는 API 입니다.**</mark>

{% hint style="info" %}
Kakao Report는 2023/09/01 부터의 데이터만 조회 가능합니다.&#x20;

한 번에 조회 가능한 기간은 최대 7일 입니다.
{% endhint %}

\
**3.2.4.1 Request**

* Path : <mark style="color:$primary;">**GET**</mark> <mark style="color:orange;">**/external/api/v1/dsp/report/kakao/csv**</mark>
* Header

| name          | type   | required | sample value          | description                       |
| ------------- | ------ | -------- | --------------------- | --------------------------------- |
| Authorization | string | true     | Bearer ${accessToken} | **accessToken은 카카오 담당자가 발급하여 전달** |

* Request Parameter

| parameter | type   | required | sample value | description      |
| --------- | ------ | -------- | ------------ | ---------------- |
| start     | string | true     | 2023-01-01   | 조회 시작 일자 (UTC+9) |
| end       | string | true     | 2023-01-07   | 조회 종료 일자 (UTC+9) |

\
**3.2.4.2 Response**

* Response Body

{% hint style="info" %}
정상 - 200(OK) CSV File Download
{% endhint %}

| column     | type   | sample value | description    |
| ---------- | ------ | ------------ | -------------- |
| reportDate | string | 2023-01-01   | 리포트 일자 (UTC+9) |
| dspId      | string | TEST\_DSP    | <p><br></p>    |
| adunitId   | string | 0Qv33        | 광고단위           |
| cnt        | long   | 100          | 노출 카운트         |
| sales      | double | 1000.0       | 매출             |
| click      | long   | 10           | 클릭 카운트         |

{% hint style="info" %}
인증 실패 - 401(UNAUTHORIZED)
{% endhint %}

| column  | type   | sample value                     | description |
| ------- | ------ | -------------------------------- | ----------- |
| code    | string | UNAUTHORIZED                     | <p><br></p> |
| message | string | 인증실패                             | <p><br></p> |
| details | string | jwt token authentication failed! | <p><br></p> |

{% hint style="info" %}
에러 - 500(INTERNAL SERVER ERROR)
{% endhint %}

| column  | type   | sample value          | description |
| ------- | ------ | --------------------- | ----------- |
| code    | string | INTERNAL SERVER ERROR | <p><br></p> |
| message | string | 서버에러                  | <p><br></p> |
| details | string | error...              | <p><br></p> |

\
\
**3.2.4.3 Example**

* Request

```
curl 'https://adx.kakao.com/external/api/v1/dsp/report/kakao/csv?start=2023-07-08&end=2023-07-13' -i -X GET \
    -H 'Authorization: Bearer ${accessToken}'
```

* Response\
  [샘플](https://wiki.daumkakao.com/download/attachments/1932318155/2023-07-14T11_08_51.966064_TEST_DSP_Sales_Report.csv?version=1\&modificationDate=1761702467000\&api=v2)


---

# Agent Instructions: 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:

```
GET https://kakaobusiness.gitbook.io/main/partner/kakaoadx_rtb/report.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.