Report API Guide

카카오 AD Exchange와 RTB 연동한 DSP에게 제공하는 리포트 API 가이드입니다.

1. 문서 버전

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

2. 개요

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

3. API

Https 는 필수입니다.

domain
https://adx.kakao.com

3.1 리포트 등록 API

DSP가 DSP의 리포트를 카카오에 등록하기 위한 API 입니다.

3.1.1 리포트 등록 API

DSP가 리포트를 등록(json)하는 API 입니다.

전월 정산마감 이후에는 전월 데이터 수정이 불가합니다. (예시 - 10월 정산마감 이후 10월 리포트 수정 불가)

3.1.1.1 Request

• Path : POST /external/api/v1/dsp/report/json

• 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	통화 종류(KRW, USD) 기본값은 KRW

• Request Body

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

3.1.1.2 Response

• Response Body

정상 - 201(CREATED)

column	type	name	description
-	-	-	-

인증 실패 - 401(UNAUTHORIZED)

column	type	name	description
code	string	UNAUTHORIZED
message	string	인증실패
details	string	jwt token authentication failed!

에러 - 500(INTERNAL SERVER ERROR)

column	type	name	description
code	string	INTERNAL SERVER ERROR
message	string	서버에러
details	string	error...

3.1.1.3 Example

• Request

currency = KRW 일 경우

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"
   }
]'

currency = USD 일 경우

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

DSP가 카카오에 등록한 DSP의 리포트를 조회하기 위한 API 입니다.

3.2.1 리포트 API

DSP가 등록한 리포트 조회(json) API 입니다.

3.2.1.1 Request

• Path : GET /external/api/v1/dsp/report

• 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	조회 시작 일자
end	string	true	2023-01-07	조회 종료 일자

3.2.1.2 Response

• Response Body

정상 - 200(OK) : KRW 예시

column	type	sample value	description
reportDate	string	2023-01-01	리포트 일자
dspId	string	TEST_DSP
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	환율

정상 - 200(OK) : USD 예시

column	type	sample value	description
reportDate	string	2023-01-01	리포트 일자
dspId	string	TEST_DSP
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 기준 고시환율)

인증 실패 - 401(UNAUTHORIZED)

column	type	sample value	description
code	string	UNAUTHORIZED
message	string	인증실패
details	string	jwt token authentication failed!

에러 - 500(INTERNAL SERVER ERROR)

column	type	sample value	description
code	string	INTERNAL SERVER ERROR
message	string	서버에러
details	string	error...

3.2.1.3 Example

currency = KRW 일경우

• Request

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

currency = USD 일경우

• 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

DSP가 카카오에 등록한 리포트를 CSV 다운로드하는 API 입니다.

3.2.2.1 Request

• Path : GET /external/api/v1/dsp/report/csv

• 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	조회 시작 일자
end	string	true	2023-01-07	조회 종료 일자

3.2.2.2 Response

• Response Body

정상 - 200(OK) : KRW 예시 CSV File Download

column	type	sample value	description
reportDate	string	2023-01-01	리포트 일자
dspId	string	TEST_DSP
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	환율

정상 - 200(OK) : USD 예시 CSV File Download

column	type	sample value	description
reportDate	string	2023-01-01	리포트 일자
dspId	string	TEST_DSP
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	환율

인증 실패 - 401(UNAUTHORIZED)

column	type	sample value	description
code	string	UNAUTHORIZED
message	string	인증실패
details	string	jwt token authentication failed!

에러 - 500(INTERNAL SERVER ERROR)

column	type	sample value	description
code	string	INTERNAL SERVER ERROR
message	string	서버에러
details	string	error...

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

---

3.2.3 카카오 리포트 API

카카오 리포트 조회(json) API 입니다.

Kakao Report는 2023/09/01 부터의 데이터만 조회 가능합니다.

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

3.2.3.1 Request

• Path : GET /external/api/v1/dsp/report/kakao

• 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	조회 시작 일자
end	string	true	2023-09-07	조회 종료 일자

3.2.3.2 Response

• Response Body

정상 - 200(OK)

column	type	sample value	description
reportDate	string	2023-01-01	리포트 일자
dspId	string	TEST_DSP
adunitId	string	0Qv33	광고단위
cnt	long	100	노출 카운트
sales	double	1000.0	매출(KRW)
click	long	10	클릭 카운트

인증 실패 - 401(UNAUTHORIZED)

column	type	sample value	description
code	string	UNAUTHORIZED
message	string	인증실패
details	string	jwt token authentication failed!

에러 - 500(INTERNAL SERVER ERROR)

column	type	sample value	description
code	string	INTERNAL SERVER ERROR
message	string	서버에러
details	string	error...

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

카카오 리포트를 CSV 다운로드하는 API 입니다.

Kakao Report는 2023/09/01 부터의 데이터만 조회 가능합니다.

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

3.2.4.1 Request

• Path : GET /external/api/v1/dsp/report/kakao/csv

• 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	조회 시작 일자
end	string	true	2023-01-07	조회 종료 일자

3.2.4.2 Response

• Response Body

정상 - 200(OK) CSV File Download

column	type	sample value	description
reportDate	string	2023-01-01	리포트 일자
dspId	string	TEST_DSP
adunitId	string	0Qv33	광고단위
cnt	long	100	노출 카운트
sales	double	1000.0	매출
click	long	10	클릭 카운트

인증 실패 - 401(UNAUTHORIZED)

column	type	sample value	description
code	string	UNAUTHORIZED
message	string	인증실패
details	string	jwt token authentication failed!

에러 - 500(INTERNAL SERVER ERROR)

column	type	sample value	description
code	string	INTERNAL SERVER ERROR
message	string	서버에러
details	string	error...

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