페이지 이동경로
  • 문서>
  • 카카오모먼트>
  • 광고 만들기: 소재 공통

카카오모먼트

광고 만들기: 소재 공통

이 문서는 소재 공통 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[] 소재 정보 목록
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 등록
비즈니스 동의항목
필요 필요

지정한 한 소재의 시스템 정지 사유를 조회합니다. 시스템 정지 사유가 여러건 있는 경우 가장 최근의 관리자 정지 사유를 조회합니다. 소재의 systemConfigADMIN_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년 동안의 시스템 정지 사유를 조회합니다. 소재의 systemConfigADMIN_STOP일 경우에만 응답이 있습니다.

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

요청

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

응답

본문
이름 타입 설명
- SystemStopReason[] 소재 정보 목록
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": "소재가 존재하지 않습니다."
    }
}

더 보기