페이지 이동경로
- 문서>
- 카카오모먼트>
- 광고 만들기: 광고계정
카카오모먼트
광고 만들기: 광고계정
이 문서는 광고 만들기: 광고계정 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": "광고계정이 삭제처리중입니다."
}
}