카카오모먼트

광고 생성: 광고계정

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

광고계정 목록 조회

기본 정보

메서드	URL	인증 방식
`GET`	`https://apis.moment.kakao.com/openapi/v4/adAccounts/pages`	비즈니스 토큰

요구 사항		참고
사용 권한 보유 비즈 앱 전환	비즈니스 리다이렉트 URI 등록 비즈니스 동의항목 설정	에러 코드 용어집

광고계정 목록을 반환합니다.

요청

헤더

이름	설명	필수
Authorization	`Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}` 인증 방식, 비즈니스 토큰으로 인증 요청	O

쿼리 파라미터

이름	타입	설명	필수
config	`Array`	광고계정 상태 `ON`, `OFF`, `DEL` 중 하나 이상의 값을 쉼표로 구분된 문자열에 담아 전달 (기본값: `ON, OFF`)	X
page	`Integer`	조회할 페이지 번호(기본값: 0) 다음 페이지 조회 시 값을 1씩 증가시켜 요청 필요	X
size	`Integer`	페이지당 광고계정 개수(기본값: 10)	X

응답

본문

이름	타입	설명
content	`AdAccount[]`	광고계정 정보 목록
number	`Integer`	페이지 번호, `page` 응답과 동일
size	`Integer`	페이지당 광고계정 개수
totalElements	`Integer`	전체 개수
totalPages	`Integer`	전체 페이지 개수
page	`Integer`	페이지 번호

AdAccount

이름	타입	설명
id	`Long`	광고계정 번호
name	`String`	광고계정명
memberType	`MemberType`	멤버 타입, 아래 중 하나 `MASTER`: 마스터 권한 `MEMBER`: 멤버 권한
config	`Config`	광고계정 상태

예제

요청

curl -v -G GET "https://apis.moment.kakao.com/openapi/v4/adAccounts/pages" \
    -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
    -d "config=ON,OFF" \
    -d "page=0" \
    -d "size=2"

응답

{
  "content": [
    {
      "id": 111,
      "name": "테스트계정1",
      "memberType": "MASTER",
      "config": "ON"
    },
    {
      "id": 222,
      "name": "테스트계정2",
      "memberType": "MASTER",
      "config": "ON"
    }
  ],
  "number": 0,
  "size": 2,
  "totalElements": 92,
  "totalPages": 46,
  "page": 0
}

광고계정 조회

기본 정보

메서드	URL	인증 방식
`GET`	`https://apis.moment.kakao.com/openapi/v4/adAccounts/${AD_ACCOUNT_ID}`	비즈니스 토큰

요구 사항		참고
사용 권한 보유 비즈 앱 전환	비즈니스 리다이렉트 URI 등록 비즈니스 동의항목 설정	에러 코드 용어집

특정 광고계정의 상세 정보를 반환합니다.

광고계정 유형

광고계정은 사업자 광고계정, 개인 광고계정 두 가지 종류가 있습니다.

광고계정	사업자 정보
사업자 광고계정	O
개인 광고계정	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	-	-

요청 수 제한

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

요청

헤더

이름	설명	필수
Authorization	`Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}` 인증 방식, 비즈니스 토큰으로 인증 요청	O
adAccountId	`adAccountId: ${AD_ACCOUNT_ID}` 광고계정 ID	O

경로 변수

이름	타입	설명	필수
AD_ACCOUNT_ID	`Long`	광고계정 ID	O

응답

본문

이름	타입	설명
id	`Long`	광고계정 번호
name	`String`	광고계정명
advertiser	`Company`	광고주 사업자 정보
type	`String`	광고계정 유형, 아래 중 하나 `BUSINESS`: 사업자 광고계정 `INDIVIDUAL`: 개인 광고계정
config	`String`	광고계정 상태, 아래 중 하나 `ON`, `OFF`, `DEL`
isAdminStop	`Boolean`	관리자 정지 여부
isOutOfBalance	`Boolean`	잔액부족 여부
statusDescription	`String`	광고계정의 게재와 관련된 현재 상태
bizWalletId	`Long`	광고계정에 연결된 비즈월렛 ID

예제

요청

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

응답: 성공

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

응답: 실패

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

실시간 잔액 조회

기본 정보

메서드	URL	인증 방식
`GET`	`https://apis.moment.kakao.com/openapi/v4/adAccounts/balance`	비즈니스 토큰

요구 사항		참고
사용 권한 보유 비즈 앱 전환	비즈니스 리다이렉트 URI 등록 비즈니스 동의항목 설정	에러 코드 용어집

광고계정의 실시간 잔액을 반환합니다.

요청

헤더

이름	설명	필수
Authorization	`Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}` 인증 방식, 비즈니스 토큰으로 인증 요청	O
adAccountId	`adAccountId: ${AD_ACCOUNT_ID}` 광고계정 ID	O

응답

본문

이름	타입	설명
id	`Long`	광고계정 번호
bizWalletId	`Long`	광고계정에 연결된 비즈웰렛 ID
cash	`Long`	유상캐시
freeCash	`Long`	무상캐시

예제

요청

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

응답: 성공

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

응답: 실패

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

영업권 조회

기본 정보

메서드	URL	인증 방식
`GET`	`https://apis.moment.kakao.com/openapi/v4/adAccounts/bizRight`	비즈니스 토큰

요구 사항		참고
사용 권한 보유 비즈 앱 전환	비즈니스 리다이렉트 URI 등록 비즈니스 동의항목 설정	에러 코드 용어집

광고계정 영업권을 반환합니다.

요청

헤더

이름	설명	필수
Authorization	`Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}` 인증 방식, 비즈니스 토큰으로 인증 요청	O
adAccountId	`adAccountId: ${AD_ACCOUNT_ID}` 광고계정 ID	O

응답

본문

이름	타입	설명
id	`Long`	광고계정 번호
bizRightCompanyName	`String`	영업권을 가진 회사명

예제

요청

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

응답: 성공

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

응답: 실패

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

영업권 자동 승인

기본 정보

메서드	URL	인증 방식
`POST`	`https://apis.moment.kakao.com/openapi/v4/adAccounts/${AD_ACCOUNT_ID}/bizRight`	비즈니스 토큰

요구 사항		참고
사용 권한 보유 비즈 앱 전환	비즈니스 리다이렉트 URI 등록 비즈니스 동의항목 설정	에러 코드 용어집

광고계정 영업권을 승인합니다.

요청

헤더

이름	설명	필수
Authorization	`Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}` 인증 방식, 비즈니스 토큰으로 인증 요청	O
adAccountId	`adAccountId: ${AD_ACCOUNT_ID}` 광고계정 ID	O

경로 변수

이름	타입	설명	필수
AD_ACCOUNT_ID	`Long`	광고계정 ID	O

응답

본문

이름	타입	설명
id	`Long`	광고계정 번호
bizRightCompanyName	`String`	영업권을 가진 회사명

예제

요청

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

응답

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

카카오톡 채널 프로필 목록 조회

기본 정보

메서드	URL	인증 방식
`GET`	`https://apis.moment.kakao.com/openapi/v4/adAccounts/channel/profiles`	비즈니스 토큰

요구 사항		참고
사용 권한 보유 비즈 앱 전환	비즈니스 리다이렉트 URI 등록 비즈니스 동의항목 설정	에러 코드 용어집

사용자의 카카오톡 채널 프로필 목록을 반환합니다.

응답의 각 id 값을 캠페인 생성 API 시 이용할 수 있습니다.

요청

헤더

이름	설명	필수
Authorization	`Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}` 인증 방식, 비즈니스 토큰으로 인증 요청	O
adAccountId	`adAccountId: ${AD_ACCOUNT_ID}` 광고계정 ID	O

응답

본문

이름	타입	설명
-	`ChannelProfile[]`	카카오톡 채널 프로필 정보 목록

ChannelProfile

이름	타입	설명
id	`String`	카카오톡 채널 프로필 ID 참고: 카카오톡 채널 프로필 ID 확인 방법
name	`String`	카카오톡 채널 이름
searchId	`String`	검색용 ID(UUID)

예제

요청

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

응답

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

픽셀 & SDK 목록 조회

기본 정보

메서드	URL	인증 방식
`GET`	`https://apis.moment.kakao.com/openapi/v4/adAccounts/trackers`	비즈니스 토큰

요구 사항		참고
사용 권한 보유 비즈 앱 전환	비즈니스 리다이렉트 URI 등록 비즈니스 동의항목 설정	에러 코드 용어집

유형, 목표별 권한을 보유한 픽셀 & SDK 목록을 반환합니다.

응답의 각 id 값을 캠페인 생성 API 시 이용할 수 있습니다.

픽셀 & SDK란?

광고주의 웹사이트 또는 앱에 설치하여, 광고 클릭 유입과 무관하게 이벤트별 로그를 수집해 아래와 같은 목적으로 사용할 수 있습니다.

광고 클릭 유입을 분리하여 보고서용으로 사용
이벤트별로 리타겟팅(Re-Targeting)에 사용
광고효율(예: ctr, cvr)등을 높이는 기반 자료로 사용

요청

헤더

이름	설명	필수
Authorization	`Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}` 인증 방식, 비즈니스 토큰으로 인증 요청	O
adAccountId	`adAccountId: ${AD_ACCOUNT_ID}` 광고계정 ID	O

쿼리 파라미터

이름	타입	설명	필수
campaignType	`String`	캠페인 유형 정보 `CampaignType` 중 하나	X
goal	`String`	목표 정보 `Goal` 중 하나	X

응답

본문

이름	타입	설명
-	`PixelAndSdkInfo[]`	픽셀 & SDK 정보 목록

PixelAndSdkInfo

이름	타입	설명
id	`String`	픽셀 & SDK 번호
name	`String`	픽셀 & SDK 이름

예제

요청

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

응답

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

광고계정 생성

기본 정보

메서드	URL	인증 방식
`POST`	`https://apis.moment.kakao.com/openapi/v4/adAccounts`	비즈니스 토큰

요구 사항		참고
사용 권한 보유 비즈 앱 전환	비즈니스 리다이렉트 URI 등록 비즈니스 동의항목 설정	에러 코드 용어집

새로운 광고계정을 생성합니다.

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

요청 수 제한

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

요청

헤더

이름	설명	필수
Authorization	`Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}` 인증 방식, 비즈니스 토큰으로 인증 요청	O

본문

이름	타입	설명	필수
name	`String`	생성할 광고계정 이름	O
advertiserCompanyId	`Long`	광고주 사업자 번호 사업자 정보 조회 API로 조회한 ID 값	O

응답

본문

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

예제

요청

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

응답: 성공

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

응답: 실패

{
  "code": -813,
  "msg": "KakaoMomentException",
  "extras": {
    "detailCode": 75105,
    "detailMsg": "ownerCompanyId 정보를 전달하지 않아야 합니다."
  }
}

광고계정 상태 변경

기본 정보

메서드	URL	인증 방식
`PUT`	`https://apis.moment.kakao.com/openapi/v4/adAccounts/onOff`	비즈니스 토큰

요구 사항		참고
사용 권한 보유 비즈 앱 전환	비즈니스 리다이렉트 URI 등록 비즈니스 동의항목 설정	에러 코드 용어집

광고계정 상태를 ON 또는 OFF로 변경합니다.

사용 조건

광고계정 상태가 ON 또는 OFF인 경우에만 변경 가능
광고계정을 삭제 중인 경우 변경 불가
광고계정을 OFF로 변경할 때 하위 다이렉트 메시지 광고 소재의 메시지 발송 상태가 발송 준비인 경우 발송 종료, 발송 중인 경우 발송 중지로 변경됨

요청 수 제한

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

요청

헤더

이름	설명	필수
Authorization	`Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}` 인증 방식, 비즈니스 토큰으로 인증 요청	O
adAccountId	`adAccountId: ${AD_ACCOUNT_ID}` 광고계정 ID	O

본문

이름	타입	설명	필수
config	`String`	ON, OFF 중 하나	O

예제

요청

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

응답: 성공

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

응답: 실패

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

사이드 메뉴

시작하기

카카오디벨로퍼스

로그인

커뮤니케이션

광고

지도

내비게이션

검색

더 보기

광고 생성: 광고계정

광고계정 목록 조회

기본 정보

요청

헤더

쿼리 파라미터

응답

본문

AdAccount

예제

요청

응답

광고계정 조회

기본 정보

광고계정 유형

광고계정 상태

요청 수 제한

요청

헤더

경로 변수

응답

본문

예제

요청

응답: 성공

응답: 실패

실시간 잔액 조회

기본 정보

요청

헤더

응답

본문

예제

요청

응답: 성공

응답: 실패

영업권 조회

기본 정보

요청

헤더

응답

본문

예제

요청

응답: 성공

응답: 실패

영업권 자동 승인

기본 정보

요청

헤더

경로 변수

응답

본문

예제

요청

응답

카카오톡 채널 프로필 목록 조회

기본 정보

요청

헤더

응답

본문

ChannelProfile

예제

요청

응답

픽셀 & SDK 목록 조회

기본 정보

요청

헤더