Skip to main content
광고 상품 API를 사용하면 서버에서 광고 상품을 만들고 관리할 수 있습니다. 콘솔에서 하던 상품 만들기를 자동화하거나, 사내 시스템의 판매 상품 정보를 Adrop 광고 상품과 맞춰 둘 때 사용합니다. API는 콘솔의 광고 상품과 같은 데이터를 다룹니다. API로 만든 상품은 콘솔 상품 목록에 바로 표시되고 콘솔에서 만든 상품과 같은 기준으로 판매됩니다. 콘솔에서 만든 상품도 API로 조회하고 수정할 수 있습니다.

사전 준비

  • ad-product:read와 ad-product:write 권한(scope)이 있는 API 키가 필요합니다. 이 두 권한은 콘솔 [관리] > [연동] 메뉴에서 선택할 수 없습니다. 에이드랍에 요청하면 두 권한을 넣은 키를 발급해 드리며, 앱 API, 광고 유닛 API, 오디언스 타겟팅 API 권한도 같은 키에 함께 받을 수 있습니다.
  • 두 권한은 따로 확인합니다. ad-product:write만 있는 키는 조회(GET) 요청에서 403을 받습니다. 만들기·수정·삭제 취소 응답에는 상품 전체가 담기지만, 상품을 따로 조회하려면 ad-product:read도 필요합니다.
  • 상품에 넣을 광고 유닛 ID는 광고 유닛 API로 조회하거나 콘솔 광고 유닛 메뉴에서 확인합니다. 타겟팅 ID와 타겟팅 옵션 ID는 오디언스 타겟팅 API와 문맥 타겟팅 API로 조회합니다.
API는 서버에서만 호출하세요. 앱이나 웹 페이지에 API 키를 넣지 마세요.

기본 정보

429를 받으면 Retry-After 헤더에 적힌 시간(초)만큼 기다린 뒤 다시 보내세요. 서버가 바쁠 때는 요청을 하나씩 보내도 429를 받을 수 있습니다. 요청 한도 전체는 한도를 참고하세요.

엔드포인트

경로는 Base URL 기준입니다.

상품 만들기

새 광고 상품을 만듭니다.

요청

ad-product:write 권한이 필요합니다. 요청 본문에 넣을 수 있는 필드는 요청 본문을 참고하세요.

필수 필드

생략한 필드는 다음 기본값으로 만들어집니다. 인하우스 상품은 title, pricing.pricingType: "INHOUSE", unitGroups만 보내면 됩니다. 비공개(private: true), 단가·상품 할인율·최소 집행 금액 0 같은 나머지 값은 자동으로 정해집니다. 이 필드를 함께 보낼 때는 정해지는 값과 같은 값만 보낼 수 있으며, 다르면 400을 반환합니다.

요청 예시

응답 예시

201 응답으로 만든 상품을 상품 객체로 반환합니다.
생성 요청은 멱등(idempotent)하지 않습니다. 응답을 받지 못해 같은 요청을 다시 보내면 상품이 중복으로 만들어질 수 있으니, 다시 보내기 전에 상품 목록에서 상품이 만들어졌는지 확인하세요.

오류

  • 400: 요청 본문이 상품 규칙에 맞지 않습니다. 오류 처리를 참고하세요.
  • 409 AD_PRODUCT_LIMIT_EXCEEDED: 프로젝트의 상품이 이미 1,000개입니다. 삭제 예약 상품도 개수에 포함됩니다.

상품 객체

조회, 생성, 수정, 삭제 취소 엔드포인트는 다음 형식으로 상품을 반환합니다. 상품 목록 조회는 이 중 일부만 반환합니다.
  • discountRate, minBudget, frequency는 값이 없을 때 0으로 채워 반환하지 않습니다. 값이 없으면 수정할 때도 보내지 마세요. frequency에 0을 보내면 제한 없음으로 바뀝니다.
  • 콘솔에서만 설정하는 상품 옵션은 응답에 포함되지 않습니다. API로 상품을 수정해도 이 옵션은 그대로 유지됩니다.
  • 인하우스 상품은 private이 true, price·discountRate·minBudget·metric.eCTR이 0, metric.eImpressions가 9007199254740991로 고정됩니다.

요청 본문

생성과 수정 요청 본문에는 다음 필드를 넣을 수 있습니다. 여기에 없는 필드와 응답에만 있는 필드(_id, createdAt, updatedAt, deleteAt, unitGroups[].fixRequired, targetings[].kind)를 보내면 400 VALIDATION_FAILED를 반환합니다.

상품 규칙

요청 본문을 아래 상품 규칙으로 검사합니다. 규칙을 어기면 400 AD_PRODUCT_VALIDATION_FAILED를 반환하고, 어긴 곳을 detail.errors로 알려 줍니다. 단, 광고 상품명이 빈 문자열이거나 과금 유형이 목록에 없는 값이면 요청 형식 오류(400 VALIDATION_FAILED)를 반환합니다.

소재 세트

unitGroups의 항목 하나가 콘솔의 소재 세트 하나입니다. name은 광고주에게 표시되는 소재 세트 이름이고, units는 그 세트에 넣을 광고 유닛 ID 목록입니다.
  • 한 소재 세트의 유닛은 형식, 사이즈, 옵션(템플릿, 워터마크 등)이 같아야 합니다. 새로 넣은 유닛이 세트 기준과 다르면 400 AD_UNIT_FIX_REQUIRED를 반환합니다. 기준은 소재 세트 구성을 참고하세요.
  • 같은 유닛 ID는 모든 소재 세트를 통틀어 한 번만 넣을 수 있습니다.
  • 형식, 사이즈, 옵션이 같은 소재 세트끼리는 이름이 같을 수 없습니다.
  • 새로 만드는 소재 세트에는 유닛이 1개 이상 있어야 합니다.
  • 상품에는 세트 기준에 맞는 유닛이 1개 이상 남아 있어야 합니다. 수정 필요 상태인 유닛은 세지 않습니다.
fixRequired는 상품에 넣은 뒤 유닛의 형식, 사이즈, 옵션이 바뀌어 소재 세트 기준과 맞지 않게 된 유닛입니다. 콘솔의 수정 필요 상태와 같습니다. 수정 필요 유닛이 있는 상품으로는 새 캠페인을 예약할 수 없으니(기존 캠페인은 그대로 운영됩니다), 유닛 설정을 되돌리거나 소재 세트에서 빼세요. 광고 유닛 API로 상품에 들어 있는 유닛의 설정을 바꾸거나 유닛을 삭제하면 상품의 소재 세트도 영향을 받습니다.

타겟팅 정책

targetings의 항목 하나가 상품에 노출할 타겟팅 하나입니다. 콘솔과 같이 한 상품에는 오디언스 타겟팅이나 문맥 타겟팅 중 한 종류만 넣으세요. policy에는 콘솔의 적용 방식과 같은 값을 넣습니다.
  • policies의 키에는 그 타겟팅의 최상위 옵션 ID만 넣을 수 있습니다. 옵션 그룹은 그룹의 ID를 넣고, 하위 옵션의 ID는 넣지 않습니다. 다른 ID를 넣으면 400 AD_PRODUCT_TARGETING_INVALID를 반환합니다.
  • 포함(included)과 제외(excluded) 정책은 상품당 500개까지 넣을 수 있습니다. 선택(any)은 제한이 없습니다.
  • 포함이나 제외 정책이 있는 문맥 타겟팅이 있으면, 정책이 있는 다른 문맥 타겟팅을 같은 상품에 함께 넣을 수 없습니다(400 TARGETING_CONTEXT_EXCLUSIVE).
  • 같은 타겟팅을 두 번 넣으면 400 TARGETING_DUPLICATED_IN_REQUEST를 반환합니다.
  • 다른 프로젝트의 타겟팅 ID나 없는 타겟팅 ID는 400 AD_PRODUCT_TARGETING_INVALID를 반환합니다.

상품 목록 조회

프로젝트의 상품을 최신 순으로 페이지 단위로 반환합니다. 삭제 예약 상품도 deleteAt과 함께 포함됩니다.

요청

ad-product:read 권한이 필요합니다.

쿼리 파라미터

요청 예시

응답 예시

200 응답으로 items(상품 목록)와 next(다음 페이지 커서)를 반환합니다. next가 없으면 마지막 페이지입니다.
목록 항목은 상품 객체와 두 가지가 다릅니다.
  • targetings에 policies가 없습니다. 정책이 필요하면 상품 조회로 상품마다 읽으세요.
  • unitGroups에 유닛 ID 대신 unitCount(유닛 수)와 fixRequiredCount(수정 필요 유닛 수)가 들어 있습니다.
정렬 순서는 대체로 만든 순서의 역순이지만, 오래된 상품은 순서가 다를 수 있습니다. 순서에 기대지 말고 next로 이어서 읽으세요.

상품 조회

상품 하나를 타겟팅 정책과 함께 반환합니다.

요청

ad-product:read 권한이 필요합니다.

요청 예시

응답

200 응답으로 상품 객체를 반환합니다.
  • policies에는 지금 그 타겟팅의 최상위 옵션 정책만 들어 있습니다. 삭제됐거나 옵션 그룹 아래로 옮겨진 옵션의 정책은 응답에 없습니다.
  • 옵션이 많은 문맥 타겟팅을 쓰는 상품은 응답이 커질 수 있습니다. 필요한 상품만 조회하세요.

오류

  • 404 AD_PRODUCT_NOT_FOUND: 상품이 없거나 다른 프로젝트의 상품입니다.

상품 수정

보낸 필드만 바꿉니다.

요청

ad-product:write 권한이 필요합니다. 요청 본문은 요청 본문과 같습니다.

쿼리 파라미터

바뀌는 방식

  • 보내지 않은 필드는 그대로입니다. 빈 본문 {}을 보내면 아무것도 바뀌지 않습니다.
  • unitGroups와 targetings는 배열 전체가 보낸 내용으로 바뀝니다. 보내지 않은 소재 세트와 타겟팅은 상품에서 빠집니다.
  • pricing, metric, options, locale 객체는 보낸 키만 바뀝니다.
  • targetings 항목에서 policies를 생략하면 그 타겟팅의 정책은 그대로입니다. policies를 보내면 보낸 목록으로 바뀌고, 목록에 없는 최상위 옵션의 정책은 지워집니다.
  • 소재 세트는 이름이 같은 기존 소재 세트와 대응되며, 새로 넣은 유닛만 검사합니다. 이미 들어 있던 수정 필요 유닛은 그대로 보내도 됩니다.
  • 과금 유형을 INHOUSE로 바꾸면 인하우스에서 정해지는 값으로 함께 바뀝니다.
  • 광고 상품명을 비우거나 상품의 유닛을 모두 뺄 수 없습니다.
콘솔에서 같은 상품을 수정하면 마지막으로 저장한 내용이 남습니다. unitGroups나 targetings처럼 배열 전체를 바꾸는 수정은 그 사이 콘솔에서 바꾼 내용을 덮어쓸 수 있으니 ifUpdatedAt을 함께 보내세요.
상품을 조회한 응답에서 응답에만 있는 필드(_id, createdAt, updatedAt, deleteAt, unitGroups[].fixRequired, targetings[].kind, locale의 currency 외 필드)를 빼고 그대로 보내면 아무것도 바뀌지 않습니다. 조회한 응답에서 바꿀 값만 고쳐 보내는 방식으로 안전하게 수정할 수 있습니다.

요청 예시

응답

200 응답으로 수정된 상품 객체를 반환합니다.

오류

  • 404 AD_PRODUCT_NOT_FOUND: 상품이 없거나 다른 프로젝트의 상품입니다.
  • 409 AD_PRODUCT_CONFLICT: ifUpdatedAt이 상품의 updatedAt과 다릅니다. 상품을 다시 조회한 뒤 수정하세요.
  • 409 AD_PRODUCT_MUTATION_NOT_ACCEPTABLE: 삭제 예약 상품입니다. 삭제 취소를 먼저 하세요.

상품 삭제

상품 삭제를 예약합니다. 예약한 상품은 삭제 예정 시각(deleteAt) 전까지 삭제 취소로 되돌릴 수 있습니다.

요청

ad-product:write 권한이 필요합니다.

요청 예시

응답 예시

200 응답으로 상품 ID와 삭제 예정 시각을 반환합니다.
  • 삭제 예정 시각은 이 상품의 캠페인 중 가장 늦게 끝나는 캠페인의 종료 시각이 지금보다 늦으면 그 3일 뒤, 그렇지 않으면 지금부터 3일 뒤입니다.
  • 삭제 예정 시각이 지나면 보통 1분 안에 상품이 삭제되고, 이후 조회하면 404를 반환합니다.
  • 삭제 예약 상품도 목록과 조회 응답에 deleteAt과 함께 나오며, 프로젝트의 상품 수에 포함됩니다. 다시 삭제하면 삭제 예정 시각을 새로 계산합니다.

오류

  • 404 AD_PRODUCT_NOT_FOUND: 상품이 없거나 다른 프로젝트의 상품입니다.

삭제 취소

삭제 예약을 취소하고 상품을 되돌립니다.

요청

ad-product:write 권한이 필요합니다. 요청 본문은 보내지 않습니다.

요청 예시

응답

200 응답으로 되돌린 상품 객체를 반환합니다. 삭제 예약이 아닌 상품에도 200을 반환하며, 이때는 아무것도 바뀌지 않습니다.

오류

  • 404 AD_PRODUCT_NOT_FOUND: 상품이 없거나, 다른 프로젝트의 상품이거나, 이미 삭제된 상품입니다.

오류 처리

오류 응답

오류 응답에는 statusCode가 들어 있고, 아래 표에서 errorCode 칸이 -가 아닌 오류에는 errorCode도 들어 있습니다. 요청의 어느 부분이 잘못됐는지 알려 주는 오류는 detail도 함께 반환합니다. 처리 방식은 errorCode로 나누고, errorCode가 없으면 statusCode로 나누세요.
detail.errors[]의 path는 잘못된 필드의 위치(pricing.price, unitGroups[0].name, targetings[0].policies.<옵션 ID> 등)이고, value는 보낸 값입니다. detail.errors는 최대 100건까지 들어 있으니, 모두 고친 뒤 다시 보내면 남은 오류가 나옵니다. 요청 형식 오류(VALIDATION_FAILED)에는 message와 error 필드도 함께 들어 있습니다.

오류 코드

다시 보내기

  • 429는 Retry-After 헤더의 시간만큼 기다린 뒤 다시 보내세요.
  • 쓰기 요청(POST, PATCH, DELETE, 삭제 취소)이 502를 받거나 응답 없이 끊겼다면 요청이 반영됐을 수 있습니다. 다시 보내기 전에 상품을 조회해 반영 여부를 확인하세요. 생성 요청은 멱등하지 않으므로 그대로 다시 보내면 상품이 중복으로 만들어질 수 있습니다.
  • ifUpdatedAt을 붙인 수정 요청을 다시 보낼 때는, 앞선 요청이 반영됐다면 409 AD_PRODUCT_CONFLICT를 받을 수 있습니다. 상품을 다시 조회해 확인하세요.

한도