Kakao Developers

페이지 이동경로

문서>
카카오모먼트>
광고 만들기: 광고계정

카카오모먼트

광고 만들기: 광고계정

이 문서는 광고 만들기: 광고계정 API 사용법을 안내합니다.

광고계정 목록 보기

기본 정보

GET /openapi/v4/adAccounts HTTP/1.1
Host: apis.moment.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}

광고계정 목록을 조회합니다.

액세스 토큰(Access token)을 헤더에 담아 GET으로 요청하고, 성공 시 응답 바디에 JSON 객체로 광고계정들의 정보 배열을 받습니다.

Request

Header

Name	Type	Description	Required
Authorization	`String`	액세스 토큰 Bearer ${ACCESS_TOKEN} 형식으로 전달	O

Parameter

Name	Type	Description	Required
config	`Array`	광고계정 상태, 복수 상태(기본값 : [ON, OFF]) enum{ON, OFF, DEL}	X

Response

Name	Type	Description
content	`AdAccount[]`	광고계정 정보 목록

AdAccount

Name	Type	Description
id	`Long`	광고계정 번호
name	`String`	광고계정명
memberType	`String<MemberType>`	멤버타입 MASTER(마스터 권한), MEMBER(멤버 권한) 중 하나
config	`String<Config>`	광고계정 상태
businessAccount	`BusinessAccount`	비즈니스계정 정보 소속된 비즈니스계정이 없는 경우 응답에서 제외

Sample

Request

curl -X GET "https://apis.moment.kakao.com/openapi/v4/adAccounts?config=ON,OFF,DEL" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}"

Response

{
  "content": [
    {
      "id": 1111,
      "name": "카카오모먼트_광고계정1",
      "memberType": "MASTER",
      "config": "ON"
    },
    {
      "id": 1112,
      "name": "카카오모먼트_광고계정2",
      "memberType": "MEMBER",
      "config": "OFF"
    }
  ]
}

광고계정 보기

기본 정보

GET /openapi/v4/adAccount HTTP/1.1
Host: apis.moment.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}

특정 광고계정의 상세 정보를 조회합니다. 광고계정은 사업자 광고계정, 개인 광고계정 두 가지 종류가 있습니다.

광고계정	광고계정 소유 사업자 정보	광고계정 사업자 정보
사업자 광고계정 (광고주 생성)	O	O
사업자 광고계정 (대행사 생성)	O	Optional
개인 광고계정	X	X

광고계정의 게재와 관련된 상태는 광고계정 상태(config), 관리자정지 여부(isAdminStop), 잔액부족 여부(isOutOfBalance) 조합으로 만들어집니다.

광고계정의 게재와 관련된 현재 상태	광고계정 상태	관리자정지 여부	잔액부족 여부
운영중	ON	false	false
잔액부족	ON	false	true
관리자정지	ON	true	false
관리자정지, 잔액부족	ON	true	true
사용자OFF	OFF	false	false
사용자OFF, 잔액부족	OFF	false	true
사용자OFF, 관리자정지	OFF	true	false
사용자OFF, 잔액부족, 관리자정지	OFF	true	true
삭제됨	DEL	-	-

액세스 토큰(Access token)과 광고계정 ID(adAccountId)를 헤더에 담아 GET으로 요청하고, 성공 시 응답 바디에 JSON 객체로 광고계정 상세 정보를 받습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.

이 API는 사용자 계정, 앱 ID마다 1초에 한 번씩 요청 가능하도록 제한되어 있습니다.

Request

Header

Name	Type	Description	Required
Authorization	`String`	액세스 토큰 Bearer ${ACCESS_TOKEN} 형식으로 전달	O
adAccountId	`Long`	광고계정 ID	O

Response

Name	Type	Description
id	`Long`	광고계정 번호
name	`String`	광고계정명
ownerCompany	`Company`	광고계정 소유 사업자 정보
advertiser	`Company`	광고주 사업자 정보
type	`String`	광고계정 유형 BUSINESS(사업자 광고계정), INDIVIDUAL(개인 광고계정) 중 하나
config	`String`	광고계정 상태 ON, OFF, DEL(삭제) 중 하나
businessAccount	`BusinessAccount`	비즈니스계정 정보 소속된 비즈니스계정이 없는 경우 응답에서 제외
isAdminStop	`Boolean`	관리자 정지 여부
isOutOfBalance	`Boolean`	잔액부족 여부
statusDescription	`String`	광고계정의 게재와 관련된 현재 상태

Sample

Request

curl -X GET "https://apis.moment.kakao.com/openapi/v4/adAccounts/${adAccountId}" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "adAccountId: ${adAccountId}"

Response: 성공

{
  "id": 1111,
  "name": "카카오모먼트_광고계정",
  "ownerCompany": {
    "businessRegistrationNumber": "120-81-47521",
    "name": "주식회사 카카오"
  },
  "advertiser": {
    "businessRegistrationNumber": "120-81-47521",
    "name": "주식회사 카카오"
  },
  "type": "BUSINESS",
  "businessAccount": {
        "businessId": 12345,
        "businessName": "카카오"
     },
  "config":"ON",
  "isAdminStop": false,
  "isOutOfBalance": false,
  "statusDescription": "운영중"
}

Response: 실패

{
    "code": -813,
    "msg": "KakaoMomentException",
    "extras": {
        "detailCode": 21006,
        "detailMsg": "존재하지 않는 광고계정입니다."
    }
}

실시간 잔액 보기

기본 정보

GET /openapi/v4/adAccounts/balance HTTP/1.1
Host: apis.moment.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}

광고계정의 실시간 잔액을 조회합니다.

액세스 토큰(Access token)과 광고계정 ID(adAccountId)를 헤더에 담아 GET으로 요청하고, 성공 시 응답 바디에 JSON 객체로 잔액 정보를 받습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.

Request

Header

Name	Type	Description	Required
Authorization	`String`	액세스 토큰 Bearer ${ACCESS_TOKEN} 형식으로 전달	O
adAccountId	`Long`	광고계정 ID	O

Parameter

없음

Response

Name	Type	Description
id	`Long`	광고계정 번호
cash	`Long`	유상캐시
freeCash	`Long`	무상캐시

Sample

Request

curl -X GET "https://apis.moment.kakao.com/openapi/v4/adAccounts/balance" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "adAccountId: ${adAccountId}"

Response: 성공

{
  "id": 1111,
  "cash": 5000000,
  "freeCash": 100000
}

Response: 실패

{
    "code": -813,
    "msg": "KakaoMomentException",
    "extras": {
        "detailCode": 21006,
        "detailMsg": "존재하지 않는 광고계정입니다."
    }
}

영업권 보기

기본 정보

GET /openapi/v4/adAccounts/bizRight HTTP/1.1
Host: apis.moment.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}

광고계정 영업권을 조회합니다.

조회 대상의 액세스 토큰(Access token)과 광고계정 ID(adAccountId)를 헤더에 담아 GET으로 요청하고, 성공 시 응답 바디에 JSON 객체로 영업권 정보를 받습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.

Request

Header

Name	Type	Description	Required
Authorization	`String`	액세스 토큰 Bearer ${ACCESS_TOKEN} 형식으로 전달	O
adAccountId	`Long`	광고계정 ID	O

Parameter

Response

Name	Type	Description
id	`Long`	광고계정 번호
bizRightCompanyName	`String`	영업권을 가진 사업자명

Sample

Request

curl -X GET "https://apis.moment.kakao.com/openapi/v4/adAccounts/bizRight" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "AdAccountId: ${adAccountId}"

Response: 성공

{
  "id": 1111,
  "bizRightCompanyName": "주식회사 카카오"
}

Response: 실패

{
    "code": -813,
    "msg": "KakaoMomentException",
    "extras": {
        "detailCode": 21006,
        "detailMsg": "존재하지 않는 광고계정입니다."
    }
}

카카오톡 채널 프로필 목록 보기

기본 정보

GET /openapi/v4/adAccounts/channel/profiles HTTP/1.1
Host: apis.moment.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}

사용자의 카카오톡 채널 프로필 목록을 조회합니다. 응답의 각 id 값을 캠페인 생성 시 이용할 수 있습니다.

액세스 토큰(Access token)과 광고계정 ID(adAccountId)를 헤더에 담아 GET으로 요청하며, 요청이 성공하면 응답 바디(Body)에 JSON 객체로 사용자의 카카오톡 채널 프로필 정보 목록을 받습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.

Request

Header

Name	Type	Description	Required
Authorization	`String`	액세스 토큰 Bearer ${ACCESS_TOKEN} 형식으로 전달	O
adAccountId	`Long`	광고계정 ID	O

Parameter

없음

Response

Name	Type	Description
-	`ChannelProfile[]`	카카오톡 채널 프로필 정보 목록

ChannelProfile

Name	Type	Description
id	`String`	카카오톡 채널 프로필 ID
name	`String`	카카오톡 채널 이름
searchId	`String`	검색용 ID(UUID)

Sample

Request

curl -X GET "https://apis.moment.kakao.com/openapi/v4/adAccounts/channel/profiles" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "adAccountId: ${adAccountId}"

Response

[
  {
    "id": "_ZQxd",
    "name": "카카오채널",
    "searchId": "카카오채널"
  },
  {
    "id": "_Xxju",
    "name": "카카오채널2",
    "searchId": "카카오채널2"
  }
]

픽셀 & SDK 목록 보기

기본 정보

GET /openapi/v4/adAccounts/trackers HTTP/1.1
Host: apis.moment.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}

유형, 목표에 따른 권한있는 픽셀 & SDK 목록을 조회합니다. 응답의 각 id 값을 캠페인 생성 시 이용할 수 있습니다.

액세스 토큰(Access token)과 광고계정 ID(adAccountId)를 헤더에 담아 GET으로 요청하며, 성공 시 응답 바디(Body)에 JSON 객체로 트래커 정보를 받습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.

픽셀 & SDK란?

광고주의 웹사이트 또는 앱에 설치하여, 광고 클릭을 통한 유입과 무관하게 이벤트별 로그를 수집해 아래와 같은 목적으로 사용할 수 있습니다.
- 광고 클릭을 통한 유입을 분리하여 보고서용으로 사용 - 이벤트별로 리타겟팅(Re-Targeting)에 사용 - 광고효율(예: ctr, cvr)등을 높이는 기반 자료로 사용

Request

Header

Name	Type	Description	Required
Authorization	`String`	액세스 토큰 Bearer ${ACCESS_TOKEN} 형식으로 전달	O
adAccountId	`Long`	광고계정 ID	O

Parameter

Name	Type	Description	Required
campaignType	`String`	캠페인 유형 정보 `CampaignType` 중 하나	X
goal	`String`	목표 정보 `Goal` 중 하나	X

Response

Name	Type	Description
-	`PixelAndSdkInfo[]`	픽셀 & SDK 정보 목록

PixelAndSdkInfo

Name	Type	Description
id	`String`	픽셀 & SDK 번호
name	`String`	픽셀 & SDK 이름

Sample

Request

curl -X GET "https://apis.moment.kakao.com/openapi/v4/adAccounts/tracker?campaignType=TALK_BIZ_BOARD&goal=VISITING" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "adAccountId: ${adAccountId}"

Response

[
  {
    "id": "1",
    "name": "트래커1"
  },
  {
    "id": "2",
    "name": "트래커2"
  }
]

광고계정 생성하기

기본 정보

POST /openapi/v4/adAccounts HTTP/1.1
Host: apis.moment.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}

새로운 광고계정을 생성합니다. 광고계정 생성은 사업자 계정에 한하여 가능하며, 광고주 및 대행사 계정을 생성할 수 있습니다.

액세스 토큰(Access token)을 헤더에 담아 POST로 요청하며, 성공 시 생성된 광고계정 정보를 받습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.

이 API는 사용자 계정마다 1초에 한 번씩 요청 가능하도록 제한되어 있습니다.

Request

Header

Name	Type	Description	Required
Authorization	`String`	액세스 토큰 Bearer ${ACCESS_TOKEN} 형식으로 전달	O

Parameter

Name	Type	Description	Required
name	`String`	생성할 광고계정 이름	O
ownerCompanyId	`Long`	광고계정 소유 사업자 번호 사업자 정보 보기를 통해 조회한 ID 값 대행사 사용자는 대행사 사업자 번호	O
advertiserCompanyId	`Long`	광고주 사업자 번호 사업자 정보 보기를 통해 조회한 ID 값	O*

* 광고주 사업자인 경우, advertiserCompanyId는 필수 파라미터 아님

Response

Name	Type	Description
id	`Long`	광고계정 번호
name	`String`	광고계정명
ownerCompany	`Company`	광고계정 소유 사업자 정보
advertiser	`Company`	광고주 사업자 정보
type	`String`	광고계정 유형 BUSINESS(사업자 광고계정)
config	`String`	광고계정 상태 ON, OFF, DEL(삭제) 중 하나
isAdminStop	`Boolean`	관리자 정지 여부
isOutOfBalance	`Boolean`	잔액부족 여부
statusDescription	`String`	광고계정의 게재와 관련된 현재 상태

Sample

Request

curl -X POST "https://apis.moment.kakao.com/openapi/v4/adAccounts" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "Content-Type: application/json" \
    -d '{
            "name":"테스트_광고계정",
            "ownerCompanyId": 12,
            "advertiserCompanyId": 34
        }'

Response

{
    "id": 123,
    "name": "테스트_광고계정",
    "ownerCompany": {
        "businessRegistrationNumber": "123-12-12345",
        "name": "광고계정 소유 사업자"
    },
    "advertiser": {
        "businessRegistrationNumber": "678-67-67890",
        "name": "광고주 사업자"
    },
    "type": "BUSINESS",
    "config": "ON",
    "isAdminStop": false,
    "isOutOfBalance": true,
    "statusDescription": "잔액부족"
}

광고계정 상태 변경하기

기본 정보

PUT /openapi/v4/adAccounts/onOff HTTP/1.1
Host: apis.moment.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}

광고계정 상태를 ON 또는 OFF로 변경합니다. 광고계정 상태가 ON 또는 OFF일 경우에만 변경 가능합니다. 광고계정이 삭제 진행 중인 경우 변경할 수 없습니다.

광고계정을 OFF로 변경할 때 하위 다이렉트 메시지 광고 소재의 메시지 발송 상태가 발송 준비인 경우 발송 종료로 변경, 발송 중인 경우 발송 중지로 변경됩니다.

액세스 토큰(Access token)과 광고계정 ID(adAccountId)를 헤더에 담아 PUT으로 요청합니다. 성공 시 HTTP 상태 코드 200에 응답 바디는 없으며, 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.

이 API는 사용자 계정마다 1초에 한 번씩 요청 가능하도록 제한되어 있습니다.

Request

Header

Name	Type	Description	Required
Authorization	`String`	액세스 토큰 Bearer ${ACCESS_TOKEN} 형식으로 전달	O
adAccountId	`Long`	광고계정 ID	O

Parameter

Name	Type	Description	Required
config	`String`	ON, OFF 중 하나	O

Sample

Request

curl -X PUT "https://apis.moment.kakao.com/openapi/v4/adAccounts/onOff" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -H "AdAccountId: ${adAccountId}" \
    -H "Content-Type: application/json" \
    -d '{
            "config":"ON"
        }'

Response: 성공

HTTP/1.1 200 OK
Content-Length: 0
Content-type: application/json;charset=UTF-8

Response: 실패

{
    "code": -813,
    "msg": "KakaoMomentException",
    "extras": {
        "detailCode": 21400,
        "detailMsg": "광고계정이 삭제처리중입니다."
    }
}

menu

시작하기

로그인

커뮤니케이션

지도/로컬

내비게이션

검색

인공지능

광고

결제

다운로드

참고정보

카카오모먼트

광고 만들기: 광고계정

광고계정 목록 보기

기본 정보

Request

Header

Parameter

Response

AdAccount

Sample

Request

Response

광고계정 보기

기본 정보

Request

Header

Response

Sample

Request

Response: 성공

Response: 실패

실시간 잔액 보기

기본 정보

Request

Header

Parameter

Response

Sample

Request

Response: 성공

Response: 실패

영업권 보기

기본 정보

Request

Header

Parameter

Response

Sample

Request

Response: 성공

Response: 실패

카카오톡 채널 프로필 목록 보기

기본 정보

Request

Header

Parameter

Response

ChannelProfile

Sample

Request

Response

픽셀 & SDK 목록 보기

기본 정보

Request

Header

Parameter

Response

PixelAndSdkInfo

Sample

Request

Response

광고계정 생성하기

기본 정보

Request

Header

Parameter

Response

Sample