광고 만들기: 소재 공통

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

소재 목록 보기

기본 정보

소재 목록을 조회합니다.

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

요청

헤더

쿼리 파라미터

응답

본문

Creative

예제

요청

curl -X GET "https://apis.moment.kakao.com/openapi/v4/creatives?adGroupId=1234&config=ON" \
    -H "Authorization: Bearer ${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"
    }
  ]
}

소재 보기

기본 정보

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

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

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

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

요청

헤더

경로 변수

응답

본문: 디스플레이 소재

본문: 메시지 소재

예제

요청

curl -X GET "https://apis.moment.kakao.com/openapi/v4/creatives/${ID}" \
    -H "Authorization: Bearer ${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": "소재가 존재하지 않습니다."
    }
}

소재 상태 변경하기

기본 정보

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

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

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

요청

헤더

본문

예제

요청

curl -X PUT "https://apis.moment.kakao.com/openapi/v4/creatives/onOff" \
    -H "Authorization: Bearer ${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": "소재가 존재하지 않습니다."
    }
}

소재 삭제하기

기본 정보

소재를 삭제합니다.

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

요청

헤더

경로 변수

예제

요청

curl -X DELETE "https://apis.moment.kakao.com/openapi/v4/creatives/${ID}" \
    -H "Authorization: Bearer ${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일 경우에만 응답이 있습니다.

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

요청

헤더

경로 변수

응답

본문

예제

요청

curl -X GET "https://apis.moment.kakao.com/openapi/v4/creatives/${ID}/systemConfigHistory" \
    -H "Authorization: Bearer ${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일 경우에만 응답이 있습니다.

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

요청

헤더

경로 변수

응답

본문

SystemStopReason

예제

요청

curl -X GET "https://apis.moment.kakao.com/openapi/v4/creatives/${ID}/systemConfigHistories" \
    -H "Authorization: Bearer ${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 레퍼런스