사이드 메뉴
시작하기
로그인
커뮤니케이션
광고
광고 생성: 소재 공통
이 문서는 소재 공통 API 사용 방법을 안내합니다.
| 메서드 | URL | 인증 방식 |
|---|---|---|
GET | https://apis.moment.kakao.com/openapi/v4/creatives | 비즈니스 토큰 |
소재 목록을 조회합니다.
비즈니스 토큰과 광고계정 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 | 소재 상태, 아래 중 하나
|
| 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 OKContent-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} | 비즈니스 토큰 |
각 소재의 상세 정보를 조회합니다.
비즈니스 토큰과 광고계정 ID(adAccountId)를 헤더에 담아 GET으로 요청합니다.
요청 성공 시 응답 본문에 JSON 객체로 종류별 광고 소재 상세 정보를 받습니다. 의견 및 증빙 파일의 경우 심사 처리 연동으로 인해 응답 값을 조회하는 데에 시간이 소요될 수 있으며, 연동이 완료되지 않은 경우 null 값으로 조회됩니다. 익스팬더블 요소 상세 정보는 지원하지 않습니다. 사용하지 않는 값도 응답에 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 | 소재 유형, 아래 중 하나
|
| 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 | 소재의 운영 상태, 아래 중 하나
|
| 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 | 소재 유형, 아래 중 하나
|
| config | String | 소재 상태, 아래 중 하나
|
| systemConfig | String | 소재 시스템 상태, 아래 중 하나
|
| statusDescription | String | 카카오톡채널 X 도달 하위 광고그룹의 현재 상태, 아래 중 하나
|
| creativeStatus | String | 소재의 운영 상태, 아래 중 하나
|
| createdDate | String | 소재 생성일시 |
| lastModifiedDate | String | 소재 마지막 수정일시 |
| messageElement | MessageElement | 메시지 상세 설명 |
| ageVerification | Boolean | 연령인증 메시지 여부 true: 연령인증 메시지 false: 일반 메시지 |
| 이름 | 타입 | 설명 |
|---|---|---|
| id | Long | 원본 소재 번호 실제 집행 시 활용되는 소재 식별 값 |
| creativeId | Long | 소재 번호
|
| format | String | 소재 유형 VIDEO_NATIVE |
| name | String | 소재 이름 |
| adGroupId | Long | 광고그룹 번호 |
| pcLandingUrl | String | 랜딩 URL (PC용 URL) |
| mobileLandingUrl | String | 랜딩 URL (모바일용 URL) |
| rspvLandingUrl | String | 랜딩 URL (반응형 URL) |
| frequencyCap | String | 게재빈도 상세 설정 값 |
| frequencyCapType | String | 게재빈도 상태, 아래 중 하나
|
| config | String | 소재 상태, 아래 중 하나
|
| systemConfig | String | 소재 시스템 상태 ON, ADMIN_STOP 중 하나 |
| reviewStatus | String | 심사 상태, 아래 중 하나
|
| createdDate | String | 소재 생성일시 |
| creativeStatus | String | 소재의 운영 상태, 아래 중 하나
|
| image | Image | 업로드 된 홍보 이미지 |
| title | String | 타이틀 |
| description | String | 홍보문구 |
| actionButton | String | 행동유도버튼 |
| profileName | String | 프로필 이름 |
| profileImage | Image | 업로드 된 프로필 이미지 |
| video | Video | 업로드 된 홍보 비디오 |
| statusDescription | String | 소재의 게재와 관련된 현재 상태 |
| rejectedReason | Array | 소재 심사 목적 (비어있는 배열) |
| createdDate | String | 소재 생성일시 |
| lastModifiedDate | String | 소재 마지막 수정일시 |
| opinionProof | OpinionFile[] | 심사 처리를 위한 의견, 증빙자료 파일 목록 |
| thumbnailImage | Image | 업로드 된 맞춤 썸네일 |
요청
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 OKContent-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 | 인증 방식 |
|---|---|---|
PUT | https://apis.moment.kakao.com/openapi/v4/creatives/onOff | 비즈니스 토큰 |
소재 상태를 변경합니다.
디스플레이 광고 소재인 경우에만 변경 가능합니다. 카카오톡 채널 유형의 캠페인 하위 소재는 상태 변경이 불가능합니다.
비즈니스 토큰과 광고계정 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 OKContent-Length: 0Content-Type: application/json;charset=UTF-8
응답: 실패
HTTP/1.1 200 OKContent-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} | 비즈니스 토큰 |
소재를 삭제합니다.
비즈니스 토큰과 광고계정 ID(adAccountId)를 헤더에 담아 DELETE로 요청하고, 성공 시 HTTP 상태 코드 200에 응답 본문은 없습니다. 실패 시 에러 코드에서 원인을 확인합니다.
소재 삭제는 데이터 삭제를 의미하는 것이 아닌, 소재에 대한 운영을 포기한다는 의미입니다.
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}인증 방식, 비즈니스 토큰으로 인증 요청 | O |
| adAccountId | adAccountId: ${AD_ACCOUNT_ID}광고계정 ID | O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| ID | Long | 원본 소재 번호 실제 집행 시 활용되는 소재 식별 값 | 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 OKContent-Length: 0Content-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 | 비즈니스 토큰 |
지정한 한 소재의 시스템 정지 사유를 조회합니다.
시스템 정지 사유가 여러건 있는 경우 가장 최근의 관리자 정지 사유를 조회합니다. 소재의 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 | 시스템 정지 상태
|
| 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 | 비즈니스 토큰 |
지정한 한 소재의 최근 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 | 시스템 정지 상태
|
| 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": "소재가 존재하지 않습니다."}}