이 문서는 소재 공통 API 사용 방법을 안내합니다.
메서드 | URL | 인증 방식 |
---|---|---|
GET |
https://apis.moment.kakao.com/openapi/v4/creatives |
비즈니스 토큰 |
권한 | 사전 설정 | 비즈니스 인증 | 비즈니스 동의항목 |
---|---|---|---|
필요: 사용 권한 신청 | 비즈 앱 전환 비즈니스 Redirect URI 등록 비즈니스 동의항목 |
필요 | 필요 |
소재 목록을 조회합니다.
비즈니스 토큰과 광고계정 ID(adAccountId
)를 헤더에 담아 GET
으로 요청하며, 성공 시 응답 본문에 JSON
객체로 소재 상세 정보 목록을 받습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: Bearer ${BUSINESS_ACCESS_TOKEN} 인증 방식, 비즈니스 토큰으로 인증 요청 |
O |
adAccountId | adAccountId: ${AD_ACCOUNT_ID} 광고계정 ID |
O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
adGroupId | Long |
광고그룹 번호 | O |
config | Array |
소재 상태, 복수선택 (default : [ON, OFF]) enum{ON, OFF, DEL} |
X |
이름 | 타입 | 설명 |
---|---|---|
content | Creative[] |
소재 정보 목록 |
이름 | 타입 | 설명 |
---|---|---|
id | Long |
원본 소재 번호 실제 집행 시 활용되는 소재 식별 값 |
name | String |
소재명 |
config | String |
소재 상태 ON , OFF , DEL (삭제) 중 하나 |
systemConfig | String |
소재 시스템 상태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 | 인증 방식 |
---|---|---|
GET |
https://apis.moment.kakao.com/openapi/v4/creatives/${ID} |
비즈니스 토큰 |
권한 | 사전 설정 | 비즈니스 인증 | 비즈니스 동의항목 |
---|---|---|---|
필요: 사용 권한 신청 | 비즈 앱 전환 비즈니스 Redirect URI 등록 비즈니스 동의항목 |
필요 | 필요 |
각 소재의 상세 정보를 조회합니다.
비즈니스 토큰과 광고계정 ID(adAccountId
)를 헤더에 담아 GET
으로 요청합니다.
요청 성공 시 응답 본문에 JSON
객체로 종류별 광고 소재 상세 정보를 받습니다. 의견 및 증빙 파일의 경우 심사 처리 연동으로 인해 응답 값을 조회하는 데에 시간이 소요될 수 있으며, 연동이 완료되지 않은 경우 null
값으로 조회됩니다. 익스팬더블 요소 상세 정보는 지원하지 않습니다.
실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: Bearer ${BUSINESS_ACCESS_TOKEN} 인증 방식, 비즈니스 토큰으로 인증 요청 |
O |
adAccountId | adAccountId: ${AD_ACCOUNT_ID} 광고계정 ID |
O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
ID | Long |
원본 소재 번호 실제 집행 시 활용되는 소재 식별 값 |
O |
키 | 타입 | 설명 |
---|---|---|
id | Long |
원본 소재 번호 실제 집행 시 활용되는 소재 식별 값 |
creativeId | Long |
소재 번호 소재 수정사항 심사 중, 수정사항 심사 보류 상태일 경우 임시로 발급된 신규 소재 번호 그 외 심사 상태에서는 원본 소재 번호와 동일함 |
name | String |
소재명 |
format | String |
소재 유형 IMAGE_BANNER(이미지 배너), IMAGE_NATIVE(이미지 네이티브), CATALOG_MANUAL(이미지 카탈로그), VIDEO_NATIVE(비디오 네이티브) 중 하나 |
pcLandingUrl | String |
랜딩 URL (PC용 랜딩 URL) |
mobileLandingUrl | String |
랜딩 URL (모바일용 랜딩 URL) |
rspvLandingUrl | String |
랜딩 URL (반응형 랜딩 URL) |
frequencyCap | Integer |
게재빈도 |
config | String |
소재 상태 ON, OFF, DEL(삭제) 중 하나 |
systemConfig | String |
소재 시스템 상태 ON, ADMIN_STOP 중 하나 |
reviewStatus | String |
심사 상태 APPROVED(승인), WAITING(심사중), REJECTED(심사보류), MODIFICATION_WAITING(수정사항심사중), MODIFICATION_REJECTED(수정사항심사보류) 중 하나 |
creativeStatus | String |
소재의 운영 상태OPERATING (운영가능), UNAPPROVED (심사미승인), INVALID_DATE (기간오류), MONITORING_REJECTED (모니터링 보류), OFF (사용자OFF), DELETED (삭제), ADGROUP_UNAVAILABLE (광고그룹 운영불가), SYSTEM_CONFIG_ADMIN_STOP (관리자 정지) 중 하나 |
statusDescription | String |
소재의 게재와 관련된 현재 상태 |
image | Image |
IMAGE_BANNER, IMAGE_NATIVE, VIDEO_NATIVE 소재의 메인 이미지 |
landingInfo | LandingInfo |
랜딩 정보 |
altText | String |
IMAGE_BANNER 소재의 이미지 대체 설명문구 |
title | String |
IMAGE_NATIVE, VIDEO_NATIVE 소재의 타이틀 |
description | String |
IMAGE_NATIVE, VIDEO_NATIVE 소재의 홍보문구 |
actionButton | String |
IMAGE_NATIVE, VIDEO_NATIVE 소재의 행동유도버튼 |
profileName | String |
IMAGE_NATIVE, VIDEO_NATIVE 소재의 프로필 이름 |
profileImage | Image |
업로드 된 프로필 이미지 |
video | Video |
VIDEO_NATIVE 소재의 비디오 |
videoSkippableType | String |
VIDEO_INSTREAM 소재의 비디오 노출 유형 SECONDS_5(최대 5초까지 노출), SECONDS_15(최대 15초까지 노출) |
rejectedReason | RejectedReason[] |
소재 보류 사유 |
assetGroups | AssetGroup[] |
CATALOG_MANUAL(이미지 카탈로그) 소재의 슬라이드 아이템 |
hasExpandable | Boolean |
익스팬더블 요소 포함 여부 |
opinion | String |
심사 처리를 위한 참조 의견 |
opinionProof | OpinionFile[] |
심사 처리를 위한 의견, 증빙자료 파일 목록 |
createdDate | String |
소재 생성일시 |
lastModifiedDate | String |
소재 마지막 수정일시 |
ageVerification | Boolean |
연령인증 메시지 여부 true: 연령인증 메시지 false: 일반 메시지 |
이름 | 타입 | 설명 |
---|---|---|
id | Long |
원본 소재 번호 실제 집행 시 활용되는 소재 식별 값 |
creativeId | Long |
소재 번호 소재 수정사항 심사 중, 수정사항 심사 보류 상태일 경우 임시로 발급된 신규 소재 번호 그 외 심사 상태에서는 원본 소재 번호와 동일함 메시지 소재는 심사 상태가 존재하지 않으므로 항상 원본 소재 번호와 동일함 |
name | String |
소재명 |
adGroupId | Long |
광고그룹 번호 |
format | String |
소재 유형 BASIC_TEXT_MESSAGE (기본텍스트), WIDE_MESSAGE (와이드이미지), WIDE_LIST_MESSAGE (와이드리스트), CAROUSEL_COMMERCE_MESSAGE (캐러셀커머스), CAROUSEL_FEED_MESSAGE (캐러셀피드), PREMIUM_VIDEO_MESSAGE (프리미엄동영상) |
config | String |
소재 상태 ON, OFF, DEL(삭제) 중 하나 |
systemConfig | String |
소재 시스템 상태 ON, ADMIN_STOP 중 하나 |
statusDescription | String |
카카오톡채널 X 도달 하위 광고그룹의 현재 상태 발송 대기, 발송중, 발송중지, 발송종료 중 하나 |
creativeStatus | String |
소재의 운영 상태 OPERATING(운영가능), UNAPPROVED(심사미승인), INVALID_DATE(기간오류), MONITORING_REJECTED(관리자정지), OFF(사용자OFF), DELETED(삭제), ADGROUP_UNAVAILABLE(광고그룹 운영불가) 중 하나 |
createdDate | String |
소재 생성일시 |
lastModifiedDate | String |
소재 마지막 수정일시 |
messageElement | MessageElement |
메시지 상세 설명 |
ageVerification | Boolean |
연령인증 메시지 여부 true: 연령인증 메시지 false: 일반 메시지 |
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
}
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"id": 12345,
"creativeId": 12345,
"name": "카카오톡 채널_도달_20210623",
"adGroupId": 39656,
"format": "WIDE_LIST_MESSAGE",
"config": "ON",
"statusDescription": "발송 종료",
"creativeStatus": "OPERATING",
"createdDate": "2021-06-23T13:26:53",
"lastModifiedDate": "2021-06-23T13:26:54",
"messageElement": {
"id": 12345,
"adAccountId": 123,
"profileId": "_xbHxd",
"name": "카카오톡 채널_도달_20210623",
"creativeFormat": "WIDE_LIST_MESSAGE",
"title": "와이드리스트홍보문구",
"shareFlag": true,
"adFlag": true,
"buttonAssetGroups": [
{
"ordering": 0,
"title": "버튼1",
"pcLandingUrl": "http://www.daum.net",
"mobileLandingUrl": "https://www.kakaocorp.com",
"landingType": "LANDING_URL"
}
],
"itemAssetGroups": [
{
"ordering": 0,
"image": {
"fileSize": 168816,
"url": "//beta.daumcdn.net/b2/creative/759/dca51ee4c3fc2248999e7a770563b98d.jpg",
"imageWidth": 1280,
"imageHeight": 720,
"mimeType": "image/jpeg",
"imageHash": "35156f0c1393434ced4be21423d08a6a"
},
"title": "타이틀1",
"mobileLandingUrl": "https://www.kakaocorp.com",
"landingType": "LANDING_URL"
},
{
"ordering": 1,
"image": {
"fileSize": 168816,
"url": "//beta.daumcdn.net/b2/creative/759/03b324a5e0a5fc29a8df001af6737279.jpg",
"imageWidth": 1280,
"imageHeight": 720,
"mimeType": "image/jpeg",
"imageHash": "35156f0c1393434ced4be21423d08a6a"
},
"title": "타이틀2",
"mobileLandingUrl": "https://www.kakaocorp.com",
"landingType": "LANDING_URL"
},
{
"ordering": 2,
"image": {
"fileSize": 168816,
"url": "//beta.daumcdn.net/b2/creative/759/9248be0ea852f655b03294ea7435d09d.jpg",
"imageWidth": 1280,
"imageHeight": 720,
"mimeType": "image/jpeg",
"imageHash": "35156f0c1393434ced4be21423d08a6a"
},
"title": "타이틀3",
"mobileLandingUrl": "https://www.kakaocorp.com",
"landingType": "LANDING_URL"
}
],
"thumbnailUrl": "//beta.daumcdn.net/b2/creative/759/dca51ee4c3fc2248999e7a770563b98d.jpg",
"messageThumbnail": {
"fileSize": 168816,
"url": "//beta.daumcdn.net/b2/creative/759/dca51ee4c3fc2248999e7a770563b98d.jpg",
"imageWidth": 1280,
"imageHeight": 720,
"mimeType": "image/jpeg",
"imageHash": "35156f0c1393434ced4be21423d08a6a"
},
"createdDate": "2021-06-23T13:26:53",
"lastModifiedDate": "2021-06-23T13:26:54"
}
}
{
"code": -813,
"msg": "KakaoMomentException",
"extras": {
"detailCode": 33003,
"detailMsg": "소재가 존재하지 않습니다."
}
}
메서드 | URL | 인증 방식 |
---|---|---|
PUT |
https://apis.moment.kakao.com/openapi/v4/creatives/onOff |
비즈니스 토큰 |
권한 | 사전 설정 | 비즈니스 인증 | 비즈니스 동의항목 |
---|---|---|---|
필요: 사용 권한 신청 | 비즈 앱 전환 비즈니스 Redirect URI 등록 비즈니스 동의항목 |
필요 | 필요 |
소재 상태를 변경합니다. 디스플레이 광고 소재인 경우에만 변경 가능합니다. 카카오톡 채널 유형의 캠페인 하위 소재는 상태 변경이 불가능합니다.
비즈니스 토큰과 광고계정 ID(adAccountId
)를 헤더에 담아 PUT
으로 요청하고, 성공 시 HTTP 상태 코드 200에 응답 본문은 없습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.
이 API는 사용자 계정, 광고계정마다 1초에 한 번씩 요청 가능하도록 제한되어 있습니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: Bearer ${BUSINESS_ACCESS_TOKEN} 인증 방식, 비즈니스 토큰으로 인증 요청 |
O |
adAccountId | adAccountId: ${AD_ACCOUNT_ID} 광고계정 ID |
O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
id | Long |
원본 소재 번호 실제 집행 시 활용되는 소재 식별 값 |
O |
config | String |
ON, 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 | 인증 방식 |
---|---|---|
DELETE |
https://apis.moment.kakao.com/openapi/v4/creatives/${ID} |
비즈니스 토큰 |
권한 | 사전 설정 | 비즈니스 인증 | 비즈니스 동의항목 |
---|---|---|---|
필요: 사용 권한 신청 | 비즈 앱 전환 비즈니스 Redirect URI 등록 비즈니스 동의항목 |
필요 | 필요 |
소재를 삭제합니다.
비즈니스 토큰과 광고계정 ID(adAccountId
)를 헤더에 담아 DELETE
로 요청하고, 성공 시 HTTP 상태 코드 200에 응답 본문은 없습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.
소재 삭제는 데이터 삭제를 의미하는 것이 아닌, 소재에 대한 운영을 포기한다는 의미입니다. 카카오 비즈보드 X 도달, 다음쇼핑, 동영상 유형 캠페인 하위 광고 소재는 삭제가 불가능합니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: Bearer ${BUSINESS_ACCESS_TOKEN} 인증 방식, 비즈니스 토큰으로 인증 요청 |
O |
adAccountId | adAccountId: ${AD_ACCOUNT_ID} 광고계정 ID |
O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
ID | Long |
원본 소재 번호 실제 집행 시 활용되는 소재 식별 값 |
O |
curl -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 | 인증 방식 |
---|---|---|
GET |
https://apis.moment.kakao.com/openapi/v4/creatives/${ID}/systemConfigHistory |
비즈니스 토큰 |
권한 | 사전 설정 | 비즈니스 인증 | 비즈니스 동의항목 |
---|---|---|---|
필요: 사용 권한 신청 | 비즈 앱 전환 비즈니스 Redirect URI 등록 비즈니스 동의항목 |
필요 | 필요 |
지정한 한 소재의 시스템 정지 사유를 조회합니다. 시스템 정지 사유가 여러건 있는 경우 가장 최근의 관리자 정지 사유를 조회합니다. 소재의 systemConfig
가 ADMIN_STOP
일 경우에만 응답이 있습니다.
비즈니스 토큰과 광고계정 ID(adAccountId)를 헤더에 담아 GET
으로 요청합니다. 성공 시 응답 본문에 JSON
객체로 시스템 정지 사유 상세정보를 받습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: Bearer ${BUSINESS_ACCESS_TOKEN} 인증 방식, 비즈니스 토큰으로 인증 요청 |
O |
adAccountId | adAccountId: ${AD_ACCOUNT_ID} 광고계정 ID |
O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
ID | Long |
원본 소재 번호 실제 집행 시 활용되는 소재 식별 값 |
O |
이름 | 타입 | 설명 |
---|---|---|
id | Long |
시스템 정지 번호 |
systemConfig | String |
시스템 정지 상태ON : 정상ADMIN_STOP : 관리자정지 |
reason | String |
시스템 정지 사유 |
createdDate | String |
시스템 정지 사유 생성일시 ( yyyy-MM-dd'T'HH:mm:ss 형식) |
lastModifiedDate | String |
시스템 정지 사유 마지막 수정일시 ( 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 | 인증 방식 |
---|---|---|
GET |
https://apis.moment.kakao.com/openapi/v4/creatives/${ID}/systemConfigHistories |
비즈니스 토큰 |
권한 | 사전 설정 | 비즈니스 인증 | 비즈니스 동의항목 |
---|---|---|---|
필요: 사용 권한 신청 | 비즈 앱 전환 비즈니스 Redirect URI 등록 비즈니스 동의항목 |
필요 | 필요 |
지정한 한 소재의 최근 2년 동안의 시스템 정지 사유를 조회합니다. 소재의 systemConfig
가 ADMIN_STOP
일 경우에만 응답이 있습니다.
비즈니스 토큰과 광고계정 ID(adAccountId)를 헤더에 담아 GET
으로 요청합니다. 성공 시 응답 본문에 JSON
객체로 시스템 정지 사유 상세정보 리스트를 받습니다. 실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: Bearer ${BUSINESS_ACCESS_TOKEN} 인증 방식, 비즈니스 토큰으로 인증 요청 |
O |
adAccountId | adAccountId: ${AD_ACCOUNT_ID} 광고계정 ID |
O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
ID | Long |
원본 소재 번호 실제 집행 시 활용되는 소재 식별 값 |
O |
이름 | 타입 | 설명 |
---|---|---|
- | SystemStopReason[] |
소재 정보 목록 |
이름 | 타입 | 설명 |
---|---|---|
id | Long |
시스템 정지 번호 |
systemConfig | String |
시스템 정지 상태ON : 정상ADMIN_STOP : 관리자정지 |
reason | String |
시스템 정지 사유 |
createdDate | String |
시스템 정지 사유 생성일시 ( yyyy-MM-dd'T'HH:mm:ss 형식) |
lastModifiedDate | String |
시스템 정지 사유 마지막 수정일시 ( 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": "소재가 존재하지 않습니다."
}
}