본문 바로가기메인 메뉴 바로가기사이드 메뉴 바로가기

kakao developers

관련사이트
  • 문서
  • 카카오모먼트
  • 광고 생성: 소재 공통

사이드 메뉴

카카오맵

검색

카카오모먼트

광고 생성: 소재 공통

이 문서는 소재 공통 API 사용 방법을 안내합니다.

소재 목록 조회

기본 정보
메서드URL인증 방식
GEThttps://apis.moment.kakao.com/openapi/v4/creatives비즈니스 토큰

소재 목록을 조회합니다.

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

요청

헤더
이름설명필수
AuthorizationAuthorization: Bearer ${BUSINESS_ACCESS_TOKEN}
인증 방식, 비즈니스 토큰으로 인증 요청
O
adAccountIdadAccountId: ${AD_ACCOUNT_ID}
광고계정 ID
O
쿼리 파라미터
이름타입설명필수
adGroupIdLong광고그룹 번호O
configArray소재 상태, 복수선택 (default : [ON, OFF])
enum {ON, OFF, DEL}
X

응답

본문
이름타입설명
contentCreative[]소재 정보 목록
Creative
이름타입설명
idLong원본 소재 번호
실제 집행 시 활용되는 소재 식별 값
nameString소재명
configString소재 상태, 아래 중 하나
  • ON: 운영중
  • OFF: 운영중지
  • DEL: 삭제
systemConfigString소재 시스템 상태
ON, ADMIN_STOP 중 하나

예제

요청
curl -X GET "https://apis.moment.kakao.com/openapi/v4/creatives?adGroupId=1234&config=ON" \
-H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
-H "adAccountId: ${AD_ACCOUNT_ID}"
응답
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"content": [
{
"id": 1111,
"name": "소재 1",
"config": "ON"
},
{
"id": 1112,
"name": "소재 2",
"config": "OFF"
}
]
}

소재 조회

기본 정보
메서드URL인증 방식
GEThttps://apis.moment.kakao.com/openapi/v4/creatives/${ID}비즈니스 토큰

각 소재의 상세 정보를 조회합니다.

비즈니스 토큰과 광고계정 ID(adAccountId)를 헤더에 담아 GET으로 요청합니다.

요청 성공 시 응답 본문에 JSON 객체로 종류별 광고 소재 상세 정보를 받습니다. 의견 및 증빙 파일의 경우 심사 처리 연동으로 인해 응답 값을 조회하는 데에 시간이 소요될 수 있으며, 연동이 완료되지 않은 경우 null 값으로 조회됩니다. 익스팬더블 요소 상세 정보는 지원하지 않습니다. 사용하지 않는 값도 응답에 null 값으로 노출될 수 있습니다.

실패 시 에러 코드에서 원인을 확인합니다.

요청

헤더
이름설명필수
AuthorizationAuthorization: Bearer ${BUSINESS_ACCESS_TOKEN}
인증 방식, 비즈니스 토큰으로 인증 요청
O
adAccountIdadAccountId: ${AD_ACCOUNT_ID}
광고계정 ID
O
경로 변수
이름타입설명필수
IDLong원본 소재 번호
실제 집행 시 활용되는 소재 식별 값
O

응답

본문: 디스플레이 소재
타입설명
idLong원본 소재 번호
실제 집행 시 활용되는 소재 식별 값
creativeIdLong소재 번호
  • 최초로 소재가 생성된 경우: 심사 상태와 무관하게 원본 소재 번호와 동일함
  • 최초 소재 생성 > 심사 승인 > 심사 과정이 필요한 소재를 수정한 경우: 신규 소재번호가 생성되어, 원본 소재 번호와 다른 값 가짐
  • 최초 소재 생성 > 심사 승인 > 심사 과정이 필요 없는 소재를 수정한 경우: 신규 소재번호가 생성되지 않으며, 원본 소재 번호와 동일함
nameString소재명
formatString소재 유형, 아래 중 하나
  • IMAGE_BANNER: 이미지 배너
  • IMAGE_NATIVE: 이미지 네이티브
  • CATALOG_MANUAL: 이미지 카탈로그
  • VIDEO_NATIVE: 비디오 네이티브
pcLandingUrlString랜딩 URL (PC용 랜딩 URL)
mobileLandingUrlString랜딩 URL (모바일용 랜딩 URL)
rspvLandingUrlString랜딩 URL (반응형 랜딩 URL)
frequencyCapInteger게재빈도
configString소재 상태
ON, OFF, DEL(삭제) 중 하나
systemConfigString소재 시스템 상태
ON, ADMIN_STOP 중 하나
reviewStatusString심사 상태
APPROVED(승인), WAITING(심사중), REJECTED(심사보류), MODIFICATION_WAITING(수정사항심사중), MODIFICATION_REJECTED(수정사항심사보류) 중 하나
creativeStatusString소재의 운영 상태, 아래 중 하나
  • OPERATING: 운영가능
  • UNAPPROVED: 심사미승인
  • INVALID_DATE: 기간오류
  • MONITORING_REJECTED: 모니터링 보류
  • OFF: 사용자OFF
  • DELETED: 삭제
  • ADGROUP_UNAVAILABLE: 광고그룹 운영불가
  • SYSTEM_CONFIG_ADMIN_STOP: 관리자 정지
statusDescriptionString소재의 게재와 관련된 현재 상태
imageImageIMAGE_BANNER, IMAGE_NATIVE, VIDEO_NATIVE 소재의 메인 이미지
landingInfoLandingInfo랜딩 정보
altTextStringIMAGE_BANNER 소재의 이미지 대체 설명문구
titleStringIMAGE_NATIVE, VIDEO_NATIVE 소재의 타이틀
descriptionStringIMAGE_NATIVE, VIDEO_NATIVE 소재의 홍보문구
actionButtonStringIMAGE_NATIVE, VIDEO_NATIVE 소재의 행동유도버튼
profileNameStringIMAGE_NATIVE, VIDEO_NATIVE 소재의 프로필 이름
profileImageImage업로드 된 프로필 이미지
videoVideoVIDEO_NATIVE 소재의 비디오
videoSkippableTypeStringVIDEO_INSTREAM 소재의 비디오 노출 유형
SECONDS_5(최대 5초까지 노출),
SECONDS_15(최대 15초까지 노출)
rejectedReasonRejectedReason[]소재 보류 사유
assetGroupsAssetGroup[]CATALOG_MANUAL(이미지 카탈로그) 소재의 슬라이드 아이템
hasExpandableBoolean익스팬더블 요소 포함 여부
opinionString심사 처리를 위한 참조 의견
opinionProofOpinionFile[]심사 처리를 위한 의견, 증빙자료 파일 목록
createdDateString소재 생성일시
lastModifiedDateString소재 마지막 수정일시
ageVerificationBoolean연령인증 메시지 여부
true: 연령인증 메시지
false: 일반 메시지
본문: 메시지 소재
이름타입설명
idLong원본 소재 번호
실제 집행 시 활용되는 소재 식별 값
creativeIdLong소재 번호
메시지 소재는 심사 상태가 존재하지 않으며, 항상 원본 소재 번호와 동일함
nameString소재명
adGroupIdLong광고그룹 번호
formatString소재 유형, 아래 중 하나
  • BASIC_TEXT_MESSAGE: 기본텍스트
  • WIDE_MESSAGE: 와이드이미지
  • WIDE_LIST_MESSAGE: 와이드리스트
  • CAROUSEL_COMMERCE_MESSAGE: 캐러셀커머스
  • CAROUSEL_FEED_MESSAGE: 캐러셀피드
  • PREMIUM_VIDEO_MESSAGE: 프리미엄동영상
configString소재 상태, 아래 중 하나
  • ON: 운영중
  • OFF: 운영중지
  • DEL: 삭제
systemConfigString소재 시스템 상태, 아래 중 하나
  • ON: 운영중
  • ADMIN_STOP: 운영중지
statusDescriptionString카카오톡채널 X 도달 하위 광고그룹의 현재 상태, 아래 중 하나
  • 발송 대기
  • 발송중
  • 발송중지
  • 발송종료
creativeStatusString소재의 운영 상태, 아래 중 하나
  • OPERATING: 운영가능
  • UNAPPROVED: 심사미승인
  • INVALID_DATE: 기간오류
  • MONITORING_REJECTED: 관리자정지
  • OFF: 사용자OFF
  • DELETED: 삭제
  • ADGROUP_UNAVAILABLE: 광고그룹 운영불가
createdDateString소재 생성일시
lastModifiedDateString소재 마지막 수정일시
messageElementMessageElement메시지 상세 설명
ageVerificationBoolean연령인증 메시지 여부
true: 연령인증 메시지
false: 일반 메시지
본문: 동영상 소재
이름타입설명
idLong원본 소재 번호
실제 집행 시 활용되는 소재 식별 값
creativeIdLong소재 번호
  • 최초로 소재가 생성된 경우: 심사 상태와 무관하게 원본 소재 번호와 동일함
  • 최초 소재 생성 > 심사 승인 > 심사 과정이 필요한 소재를 수정한 경우: 신규 소재번호가 생성되어, 원본 소재 번호와 다른 값 가짐
  • 최초 소재 생성 > 심사 승인 > 심사 과정이 필요 없는 소재를 수정한 경우: 신규 소재번호가 생성되지 않으며, 원본 소재 번호와 동일함
formatString소재 유형
VIDEO_NATIVE
nameString소재 이름
adGroupIdLong광고그룹 번호
pcLandingUrlString랜딩 URL (PC용 URL)
mobileLandingUrlString랜딩 URL (모바일용 URL)
rspvLandingUrlString랜딩 URL (반응형 URL)
frequencyCapString게재빈도 상세 설정 값
frequencyCapTypeString게재빈도 상태, 아래 중 하나
  • DAY_IMP: 상세 설정
  • AUTO: 자동 설정
configString소재 상태, 아래 중 하나
  • ON: 운영중
  • OFF: 운영중지
  • DEL: 삭제
systemConfigString소재 시스템 상태
ON, ADMIN_STOP 중 하나
reviewStatusString심사 상태, 아래 중 하나
  • APPROVED: 승인
  • WAITING: 심사중
  • REJECTED: 심사보류
  • MONITORING_REJECTED: 관리자정지
createdDateString소재 생성일시
creativeStatusString소재의 운영 상태, 아래 중 하나
  • OPERATING: 운영가능
  • UNAPPROVED: 심사미승인
  • INVALID_DATE: 기간오류
  • MONITORING_REJECTED: 관리자정지
  • OFF: 사용자OFF
  • DELETED: 삭제
  • ADGROUP_UNAVAILABLE: 광고그룹 운영불가
imageImage업로드 된 홍보 이미지
titleString타이틀
descriptionString홍보문구
actionButtonString행동유도버튼
profileNameString프로필 이름
profileImageImage업로드 된 프로필 이미지
videoVideo업로드 된 홍보 비디오
statusDescriptionString소재의 게재와 관련된 현재 상태
rejectedReasonArray소재 심사 목적 (비어있는 배열)
createdDateString소재 생성일시
lastModifiedDateString소재 마지막 수정일시
opinionProofOpinionFile[]심사 처리를 위한 의견, 증빙자료 파일 목록
thumbnailImageImage업로드 된 맞춤 썸네일

예제

요청
curl -X GET "https://apis.moment.kakao.com/openapi/v4/creatives/${ID}" \
-H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
-H "adAccountId: ${AD_ACCOUNT_ID}"
응답
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"id": 1111,
"name": "디스플레이 광고 소재",
"landingInfo": {
"landingType": "AD_VIEW",
"communicatorAdViewId": 1
},
"format": "IMAGE_BANNER",
"landingUrl": "http://www.daum.net",
"frequencyCapType": "DAY_IMP",
"frequencyCap": 3,
"config": "ON",
"image": {
"url": "http://xxx.kakao.co.kr/sample.jpg",
"fileName": "sample.jpeg",
"width": 640,
"height": 100,
"size": 50000
},
"reviewStatus": "REJECTED",
"creativeStatus": "UNAPPROVED",
"statusDescription": "심사보류",
"rejectedReason": [
{
"rejectedTitle": "공통1>가격 불일치",
"rejectedContent": "등록하신 광고 소재 내 가격 정보가 랜딩페이지 내 실제 판매금액과 일치하지 않아 광고 등록이 보류되었습니다.\n* 광고 소재 내 가격 정보 : 39,800\n* 랜딩 페이지 내 가격 정보 : 49,800\n - 수정방법 : 모든 이용자가 구매 가능한 정확한 가격을 기재해 주시기 바랍니다."
}
],
"createdDate": "2020-01-01T00:00:00",
"lastModifiedDate": "2020-01-01T01:00:00",
"hasExpandable" : false
}
응답: 실패
{
"code": -813,
"msg": "KakaoMomentException",
"extras": {
"detailCode": 33003,
"detailMsg": "소재가 존재하지 않습니다."
}
}

소재 상태 변경

기본 정보
메서드URL인증 방식
PUThttps://apis.moment.kakao.com/openapi/v4/creatives/onOff비즈니스 토큰

소재 상태를 변경합니다.

디스플레이 광고 소재인 경우에만 변경 가능합니다. 카카오톡 채널 유형의 캠페인 하위 소재는 상태 변경이 불가능합니다.

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

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

요청

헤더
이름설명필수
AuthorizationAuthorization: Bearer ${BUSINESS_ACCESS_TOKEN}
인증 방식, 비즈니스 토큰으로 인증 요청
O
adAccountIdadAccountId: ${AD_ACCOUNT_ID}
광고계정 ID
O
본문
이름타입설명필수
idLong원본 소재 번호
실제 집행 시 활용되는 소재 식별 값
O
configStringON, OFF 중 하나O

예제

요청
curl -X PUT "https://apis.moment.kakao.com/openapi/v4/creatives/onOff" \
-H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
-H "adAccountId: ${AD_ACCOUNT_ID}" \
-H "Content-Type: application/json" \
-d '{
"id": 1234,
"config": "ON"
}'
응답: 성공
HTTP/1.1 200 OK
Content-Length: 0
Content-Type: application/json;charset=UTF-8
응답: 실패
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"code": -813,
"msg": "KakaoMomentException",
"extras": {
"detailCode": 33003,
"detailMsg": "소재가 존재하지 않습니다."
}
}

소재 삭제

기본 정보
메서드URL인증 방식
DELETEhttps://apis.moment.kakao.com/openapi/v4/creatives/${ID}비즈니스 토큰

소재를 삭제합니다.

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

소재 삭제는 데이터 삭제를 의미하는 것이 아닌, 소재에 대한 운영을 포기한다는 의미입니다.

요청

헤더
이름설명필수
AuthorizationAuthorization: Bearer ${BUSINESS_ACCESS_TOKEN}
인증 방식, 비즈니스 토큰으로 인증 요청
O
adAccountIdadAccountId: ${AD_ACCOUNT_ID}
광고계정 ID
O
경로 변수
이름타입설명필수
IDLong원본 소재 번호
실제 집행 시 활용되는 소재 식별 값
O

예제

요청
curl -v -X DELETE "https://apis.moment.kakao.com/openapi/v4/creatives/${ID}" \
-H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
-H "adAccountId: ${AD_ACCOUNT_ID}" \
-H "Content-Type: application/json"
응답: 요청 성공
HTTP/1.1 200 OK
Content-Length: 0
Content-Type: application/json;charset=UTF-8
응답: 요청 실패
{
"code": -813,
"msg": "KakaoMomentException",
"extras": {
"detailCode": 75008,
"detailMsg": "카카오톡 채널_도달 소재는 삭제할 수 없습니다.",
"path": "/v2/moment/creatives",
"timestamp": "2020-04-01T10:16:14.294+0000"
}
}

시스템 정지 사유 조회

기본 정보
메서드URL인증 방식
GEThttps://apis.moment.kakao.com/openapi/v4/creatives/${ID}/systemConfigHistory비즈니스 토큰

지정한 한 소재의 시스템 정지 사유를 조회합니다.

시스템 정지 사유가 여러건 있는 경우 가장 최근의 관리자 정지 사유를 조회합니다. 소재의 systemConfigADMIN_STOP일 경우에만 응답이 있습니다.

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

요청

헤더
이름설명필수
AuthorizationAuthorization: Bearer ${BUSINESS_ACCESS_TOKEN}
인증 방식, 비즈니스 토큰으로 인증 요청
O
adAccountIdadAccountId: ${AD_ACCOUNT_ID}
광고계정 ID
O
경로 변수
이름타입설명필수
IDLong원본 소재 번호
실제 집행 시 활용되는 소재 식별 값
O

응답

본문
이름타입설명
idLong시스템 정지 번호
systemConfigString시스템 정지 상태
  • ON: 정상
  • ADMIN_STOP: 관리자정지
reasonString시스템 정지 사유
createdDateString시스템 정지 사유 생성일시
(yyyy-MM-dd'T'HH:mm:ss 형식)
lastModifiedDateString시스템 정지 사유 마지막 수정일시
(yyyy-MM-dd'T'HH:mm:ss 형식)

예제

요청
curl -X GET "https://apis.moment.kakao.com/openapi/v4/creatives/${ID}/systemConfigHistory" \
-H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
-H "adAccountId: ${AD_ACCOUNT_ID}"
응답: 요청 성공
{
"id": 1234,
"systemConfig": "ADMIN_STOP",
"reason": "해당 소재 랜딩 지원 종료로 관리자 정지되었습니다.",
"createdDate": "2021-01-01T00:00:00",
"lastModifiedDate": "2021-01-01T00:00:00"
}
응답: 요청 실패
{
"code": -813,
"msg": "KakaoMomentException",
"extras": {
"detailCode": 33003,
"detailMsg": "소재가 존재하지 않습니다."
}
}

시스템 정지 사유 목록 조회

기본 정보
메서드URL인증 방식
GEThttps://apis.moment.kakao.com/openapi/v4/creatives/${ID}/systemConfigHistories비즈니스 토큰

지정한 한 소재의 최근 2년 동안의 시스템 정지 사유를 조회합니다.

소재의 systemConfigADMIN_STOP일 경우에만 응답이 있습니다.

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

요청

헤더
이름설명필수
AuthorizationAuthorization: Bearer ${BUSINESS_ACCESS_TOKEN}
인증 방식, 비즈니스 토큰으로 인증 요청
O
adAccountIdadAccountId: ${AD_ACCOUNT_ID}
광고계정 ID
O
경로 변수
이름타입설명필수
IDLong원본 소재 번호
실제 집행 시 활용되는 소재 식별 값
O

응답

본문
이름타입설명
-SystemStopReason[]소재 정보 목록
SystemStopReason
이름타입설명
idLong시스템 정지 번호
systemConfigString시스템 정지 상태
  • ON: 정상
  • ADMIN_STOP: 관리자정지
reasonString시스템 정지 사유
createdDateString시스템 정지 사유 생성일시
(yyyy-MM-dd'T'HH:mm:ss 형식)
lastModifiedDateString시스템 정지 사유 마지막 수정일시
(yyyy-MM-dd'T'HH:mm:ss 형식

예제

요청
curl -X GET "https://apis.moment.kakao.com/openapi/v4/creatives/${ID}/systemConfigHistories" \
-H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
-H "adAccountId: ${AD_ACCOUNT_ID}"
응답: 요청 성공
[
{
"id": 1235,
"systemConfig": "ADMIN_STOP",
"reason": "해당 소재 랜딩 지원 종료로 관리자 정지되었습니다.",
"createdDate": "2021-01-01T00:00:00",
"lastModifiedDate": "2021-01-01T00:00:00"
},
{
"id": 1234,
"systemConfig": "ADMIN_STOP",
"reason": "해당 소재 랜딩 지원 종료로 관리자 정지되었습니다.",
"createdDate": "2021-01-01T00:00:00",
"lastModifiedDate": "2021-01-01T00:00:00"
}
]
응답: 요청 실패
{
"code": -813,
"msg": "KakaoMomentException",
"extras": {
"detailCode": 33003,
"detailMsg": "소재가 존재하지 않습니다."
}
}

더 보기

도움이 되었나요?