페이지 이동경로
  • 문서>
  • 카카오모먼트>
  • 광고 만들기: 광고계정

카카오모먼트

광고 만들기: 광고계정

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

광고계정 목록 보기

기본 정보
메서드 URL 인증 방식
GET https://apis.moment.kakao.com/openapi/v4/adAccounts/pages 비즈니스 토큰
권한 사전 설정 비즈니스 인증 비즈니스 동의항목
필요: 사용 권한 신청 비즈 앱 전환
비즈니스 Redirect URI 등록
비즈니스 동의항목
필요 필요

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

비즈니스 토큰을 헤더에 담아 GET으로 요청하고, 성공 시 응답은 광고계정 목록을 페이지 형식으로 포함합니다. 광고계정 목록의 다음 페이지를 조회하려면 page 값을 1씩 증가시켜 요청합니다. 실패 시 에러 코드상세 에러 코드로 사유를 확인합니다.

요청

헤더
이름 설명 필수
Authorization Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}
인증 방식, 비즈니스 토큰으로 인증 요청
O
쿼리 파라미터
이름 타입 설명 필수
config Array 광고계정 상태
ON, OFF, DEL 중 하나 이상의 값을 쉼표로 구분된 문자열에 담아 전달
(기본값 : ON, OFF)
X
page Integer 조회할 페이지 번호(기본값: 0) 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} 비즈니스 토큰
권한 사전 설정 비즈니스 인증 비즈니스 동의항목
필요: 사용 권한 신청 비즈 앱 전환
비즈니스 Redirect URI 등록
비즈니스 동의항목
필요 필요

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

광고계정 광고계정 소유 사업자 정보 광고계정 사업자 정보
사업자 광고계정
(광고주 생성)
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 - -

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

이 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 광고계정명
ownerCompany Company 광고계정 소유 사업자 정보
advertiser Company 광고주 사업자 정보
type String 광고계정 유형
BUSINESS(사업자 광고계정), INDIVIDUAL(개인 광고계정) 중 하나
config String 광고계정 상태
ON, OFF, DEL(삭제) 중 하나
isAdminStop Boolean 관리자 정지 여부
isOutOfBalance Boolean 잔액부족 여부
statusDescription String 광고계정의 게재와 관련된 현재 상태

예제

요청
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": "카카오모먼트_광고계정",
  "ownerCompany": {
    "businessRegistrationNumber": "120-81-47521",
    "name": "주식회사 카카오"
  },
  "advertiser": {
    "businessRegistrationNumber": "120-81-47521",
    "name": "주식회사 카카오"
  },
  "type": "BUSINESS",
  "config":"ON",
  "isAdminStop": false,
  "isOutOfBalance": false,
  "statusDescription": "운영중"
}
응답: 실패
{
    "code": -813,
    "msg": "KakaoMomentException",
    "extras": {
        "detailCode": 21006,
        "detailMsg": "존재하지 않는 광고계정입니다."
    }
}

실시간 잔액 보기

기본 정보
메서드 URL 인증 방식
GET https://apis.moment.kakao.com/openapi/v4/adAccounts/balance 비즈니스 토큰
권한 사전 설정 비즈니스 인증 비즈니스 동의항목
필요: 사용 권한 신청 비즈 앱 전환
비즈니스 Redirect URI 등록
비즈니스 동의항목
필요 필요

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

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

요청

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

응답

본문
이름 타입 설명
id Long 광고계정 번호
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,
  "cash": 5000000,
  "freeCash": 100000
}
응답: 실패
{
    "code": -813,
    "msg": "KakaoMomentException",
    "extras": {
        "detailCode": 21006,
        "detailMsg": "존재하지 않는 광고계정입니다."
    }
}

영업권 보기

기본 정보
메서드 URL 인증 방식
GET https://apis.moment.kakao.com/openapi/v4/adAccounts/bizRight 비즈니스 토큰
권한 사전 설정 비즈니스 인증 비즈니스 동의항목
필요: 사용 권한 신청 비즈 앱 전환
비즈니스 Redirect URI 등록
비즈니스 동의항목
필요 필요

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

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

요청

헤더
이름 설명 필수
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 인증 방식
GET https://apis.moment.kakao.com/openapi/v4/adAccounts/channel/profiles 비즈니스 토큰
권한 사전 설정 비즈니스 인증 비즈니스 동의항목
필요: 사용 권한 신청 비즈 앱 전환
비즈니스 Redirect URI 등록
비즈니스 동의항목
필요 필요

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

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

요청

헤더
이름 설명 필수
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 비즈니스 토큰
권한 사전 설정 비즈니스 인증 비즈니스 동의항목
필요: 사용 권한 신청 비즈 앱 전환
비즈니스 Redirect URI 등록
비즈니스 동의항목
필요 필요

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

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

픽셀 & 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 비즈니스 토큰
권한 사전 설정 비즈니스 인증 비즈니스 동의항목
필요: 사용 권한 신청 비즈 앱 전환
비즈니스 Redirect URI 등록
비즈니스 동의항목
필요 필요

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

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

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

요청

헤더
이름 설명 필수
Authorization Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}
인증 방식, 비즈니스 토큰으로 인증 요청
O
본문
이름 타입 설명 필수
name String 생성할 광고계정 이름 O
ownerCompanyId Long 광고계정 소유 사업자 번호
사업자 정보 보기를 통해 조회한 ID 값
대행사 사용자는 대행사 사업자 번호
O
advertiserCompanyId Long 광고주 사업자 번호
사업자 정보 보기를 통해 조회한 ID 값
O*

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

응답

본문
이름 타입 설명
id Long 광고계정 번호
name String 광고계정명
ownerCompany Company 광고계정 소유 사업자 정보
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":"테스트_광고계정",
            "ownerCompanyId": 12,
            "advertiserCompanyId": 34
        }'
응답
{
    "id": 123,
    "name": "테스트_광고계정",
    "ownerCompany": {
        "businessRegistrationNumber": "123-12-12345",
        "name": "광고계정 소유 사업자"
    },
    "advertiser": {
        "businessRegistrationNumber": "678-67-67890",
        "name": "광고주 사업자"
    },
    "type": "BUSINESS",
    "config": "ON",
    "isAdminStop": false,
    "isOutOfBalance": true,
    "statusDescription": "잔액부족"
}

광고계정 상태 변경하기

기본 정보
메서드 URL 인증 방식
PUT https://apis.moment.kakao.com/openapi/v4/adAccounts/onOff 비즈니스 토큰
권한 사전 설정 비즈니스 인증 비즈니스 동의항목
필요: 사용 권한 신청 비즈 앱 전환
비즈니스 Redirect URI 등록
비즈니스 동의항목
필요 필요

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

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

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

이 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": "광고계정이 삭제처리중입니다."
    }
}

더 보기