광고 만들기: 소재 공통

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

소재 목록 보기

기본 정보

소재 목록을 조회합니다.

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

요청

헤더

쿼리 파라미터

응답

본문

Creative

예제

요청

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"
    }
  ]
}

소재 보기

기본 정보

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

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

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

실패 시 에러 코드 및 상세 에러 코드로 사유를 확인합니다.

요청

헤더

경로 변수

응답

본문: 디스플레이 소재

본문: 메시지 소재

예제

요청

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": "소재가 존재하지 않습니다."
    }
}

소재 상태 변경하기

기본 정보

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

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

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

요청

헤더

본문

예제

요청

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": "소재가 존재하지 않습니다."
    }
}

소재 삭제하기

기본 정보

소재를 삭제합니다.

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

요청

헤더

경로 변수

예제

요청

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"
    }
}

시스템 정지 사유 보기

기본 정보

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

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

요청

헤더

경로 변수

응답

본문

예제

요청

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": "소재가 존재하지 않습니다."
    }
}

시스템 정지 사유 목록 보기

기본 정보

지정한 한 소재의 최근 2년 동안의 시스템 정지 사유를 조회합니다. 소재의 systemConfig가 ADMIN_STOP일 경우에만 응답이 있습니다.

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

요청

헤더

경로 변수

응답

본문

SystemStopReason

예제

요청

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": "소재가 존재하지 않습니다."
    }
}

더 보기

카카오모먼트 API 레퍼런스