> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adrop.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 광고 상품 API

> API 키로 서버에서 광고 상품을 만들고 조회·수정·삭제하는 방법을 안내합니다.

광고 상품 API를 사용하면 서버에서 광고 상품을 만들고 관리할 수 있습니다. 콘솔에서 하던 상품 만들기를 자동화하거나, 사내 시스템의 판매 상품 정보를 Adrop 광고 상품과 맞춰 둘 때 사용합니다.

API는 콘솔의 광고 상품과 같은 데이터를 다룹니다. API로 만든 상품은 콘솔 상품 목록에 바로 표시되고 콘솔에서 만든 상품과 같은 기준으로 판매됩니다. 콘솔에서 만든 상품도 API로 조회하고 수정할 수 있습니다.

***

## 사전 준비

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

> [!WARNING]
>
> API는 서버에서만 호출하세요. 앱이나 웹 페이지에 API 키를 넣지 마세요.

***

## 기본 정보

| 항목 | 값 |
| - | - |
| Base URL | `https://lake.adrop.io` |
| 인증 | `x-api-key` 헤더에 API 키를 넣습니다. 키가 속한 프로젝트의 상품만 다룰 수 있으며, 다른 프로젝트의 상품 ID는 `404`를 반환합니다. |
| Content-Type | 생성·수정 요청 본문은 JSON(`application/json`)만 받습니다. 다른 형식은 `415`를 반환합니다. |
| 요청 본문 최대 크기 | 8 MB. 이보다 크면 `413`을 반환합니다. 조회(`GET`) 요청에 본문을 넣으면 크기와 관계없이 `413`을 반환합니다. |
| ID 형식 | 영문자, 숫자, `_`, `-`로 된 64자 이하 문자열입니다. 새로 만든 상품의 ID는 26자 ULID입니다. |
| 시각 | `createdAt`, `updatedAt`, `deleteAt`은 epoch 밀리초입니다. |
| 동시 요청 | 프로젝트당 4건까지 동시에 처리합니다. 같은 프로젝트의 키를 여러 개 써도 합쳐서 셉니다. 넘으면 `429`를 반환합니다. |

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

***

## 엔드포인트

경로는 Base URL 기준입니다.

| 메서드 | 경로 | 권한 | 설명 |
| - | - | - | - |
| `POST` | `/ad-products` | `ad-product:write` | [상품 만들기](#상품-만들기) |
| `GET` | `/ad-products` | `ad-product:read` | [상품 목록 조회](#상품-목록-조회) |
| `GET` | `/ad-products/{productId}` | `ad-product:read` | [상품 조회](#상품-조회)(타겟팅 정책 포함) |
| `PATCH` | `/ad-products/{productId}` | `ad-product:write` | [상품 수정](#상품-수정) |
| `DELETE` | `/ad-products/{productId}` | `ad-product:write` | [상품 삭제](#상품-삭제)(삭제 예약) |
| `POST` | `/ad-products/{productId}/restore` | `ad-product:write` | [삭제 취소](#삭제-취소) |

***

## 상품 만들기

새 광고 상품을 만듭니다.

### 요청

```http theme={null}
POST /ad-products
```

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

### 필수 필드

| 필드 | 필요한 경우 | 설명 |
| - | - | - |
| `title` | 항상 | 광고 상품명. 빈 문자열은 받지 않습니다. |
| `pricing.pricingType` | 항상 | 과금 유형. `CPM`, `CPC`, `CPP`, `INHOUSE`(인하우스) 중 하나 |
| `unitGroups` | 항상 | 소재 세트. 광고 유닛이 1개 이상 든 소재 세트가 있어야 합니다. [소재 세트](#소재-세트)를 참고하세요. |
| `pricing.price` | 인하우스가 아닐 때 | 0보다 큰 단가 |
| `metric.eImpressions` | 인하우스가 아닐 때 | 0보다 큰 일 노출수 |
| `metric.eCTR` | 인하우스가 아닐 때 | 예상 클릭률. 모든 유닛이 스플래시 유닛이면 생략할 수 있습니다. |
| `options.cppSlots`, `options.cppMinDays` | CPP일 때 | 구좌 수(정수 1~~50)와 최소 집행 기간(정수 1~~150일) |
| `locale.currency` | 인하우스가 아니고 프로젝트에 통화가 없을 때 | `KRW`, `USD`, `JPY`, `INR` 중 하나. 프로젝트에 통화가 있으면 생략할 때 그 통화를 씁니다. |

생략한 필드는 다음 기본값으로 만들어집니다.

| 필드 | 기본값 |
| - | - |
| `private` | `false` |
| `frequency` | `50` |
| `minBudget` | `0` |
| `discountRate` | `0` |
| `locale` | 프로젝트의 국가, 통화, 시간대, 언어 |

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

### 요청 예시

```bash theme={null}
curl -X POST https://lake.adrop.io/ad-products \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Home Banner CPM",
    "pricing": { "pricingType": "CPM", "price": 3000 },
    "metric": { "eImpressions": 100000, "eCTR": 1.5 },
    "unitGroups": [
      { "name": "Home Banner", "units": ["01JAZ3KA1B2C3D4E5F6G7H8J9K"] }
    ],
    "targetings": [
      {
        "targeting": "01JAZ3K9Q8W5T2M4N6P7R8S9TV",
        "surchargeRate": 15,
        "policies": {
          "01JAZ3KC3D4E5F6G7H8J9K0M1N": { "policy": "included" },
          "01JAZ3KD4E5F6G7H8J9K0M1N2P": { "policy": "any" }
        }
      }
    ]
  }'
```

### 응답 예시

`201` 응답으로 만든 상품을 [상품 객체](#상품-객체)로 반환합니다.

```json theme={null}
{
  "_id": "01JAZ3KB2C3D4E5F6G7H8J9K0M",
  "title": "Home Banner CPM",
  "private": false,
  "pricing": { "pricingType": "CPM", "price": 3000 },
  "discountRate": 0,
  "minBudget": 0,
  "frequency": 50,
  "metric": { "eImpressions": 100000, "eCTR": 1.5 },
  "options": {},
  "locale": { "country": "KR", "currency": "KRW", "timezone": "Asia/Seoul", "language": "ko" },
  "unitGroups": [
    { "name": "Home Banner", "units": ["01JAZ3KA1B2C3D4E5F6G7H8J9K"], "fixRequired": [] }
  ],
  "targetings": [
    {
      "targeting": "01JAZ3K9Q8W5T2M4N6P7R8S9TV",
      "kind": "audience",
      "surchargeRate": 15,
      "policies": {
        "01JAZ3KC3D4E5F6G7H8J9K0M1N": { "policy": "included" },
        "01JAZ3KD4E5F6G7H8J9K0M1N2P": { "policy": "any" }
      }
    }
  ],
  "createdAt": 1790820300000,
  "updatedAt": 1790820300000
}
```

> [!NOTE]
>
> 생성 요청은 멱등(idempotent)하지 않습니다. 응답을 받지 못해 같은 요청을 다시 보내면 상품이 중복으로 만들어질 수 있으니, 다시 보내기 전에 [상품 목록](#상품-목록-조회)에서 상품이 만들어졌는지 확인하세요.

### 오류

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

***

## 상품 객체

조회, 생성, 수정, 삭제 취소 엔드포인트는 다음 형식으로 상품을 반환합니다. [상품 목록 조회](#상품-목록-조회)는 이 중 일부만 반환합니다.

| 필드 | 타입 | 설명 |
| - | - | - |
| `_id` | string | 상품 ID |
| `title` | string \| null | 광고 상품명. 오래된 상품은 값이 없거나 `null`일 수 있습니다. |
| `guide` | string \| null | 소재 제작 가이드 링크(`http` 또는 `https` URL). 값이 없으면 생략되거나 `null`입니다. |
| `private` | boolean | 비공개 상품인지 여부 |
| `pricing.pricingType` | string | 과금 유형: `CPM`, `CPC`, `CPP`, `INHOUSE`(인하우스). 지금은 쓰지 않는 과금 유형의 상품에는 이 필드가 없습니다. |
| `pricing.price` | number | 단가(`locale.currency` 통화). CPM은 1,000회 노출당, CPC는 클릭당, CPP는 하루당 단가입니다. 인하우스는 0입니다. |
| `discountRate` | number | 상품 할인율(%, `10`이면 10%). 값이 저장된 상품에만 있습니다. |
| `minBudget` | number | 최소 집행 금액(`locale.currency` 통화). 값이 저장된 상품에만 있습니다. |
| `frequency` | number | 노출 빈도 제한. 한 사용자에게 캠페인 하나가 하루에 노출될 수 있는 최대 횟수입니다. 콘솔에서 **제한 없음**으로 설정한 상품은 `0`입니다. 값이 저장된 상품에만 있습니다. |
| `metric.eImpressions` | number | 일 노출수 |
| `metric.eCTR` | number | 예상 클릭률(%, `1.5`면 1.5%) |
| `options.cppSlots` | number | 구좌 수. CPP 상품에 있습니다. |
| `options.cppMinDays` | number | 최소 집행 기간(일). CPP 상품에 있습니다. |
| `locale` | object | 상품의 `country`(국가), `currency`(통화), `timezone`(시간대), `language`(언어) |
| `unitGroups` | object\[] | 소재 세트 목록. 각 항목은 `name`(소재 세트 이름), `units`(유닛 ID 전체), `fixRequired`(그중 수정 필요 상태인 유닛 ID)입니다. [소재 세트](#소재-세트)를 참고하세요. |
| `targetings` | object\[] | 상품에 노출할 타겟팅 목록. 각 항목은 `targeting`(타겟팅 ID), `kind`(`audience` 오디언스, `context` 문맥), `surchargeRate`(할증률, %), `policies`(옵션별 정책)입니다. [타겟팅 정책](#타겟팅-정책)을 참고하세요. |
| `deleteAt` | number | 삭제 예정 시각. 삭제 예약 상품에만 있습니다. [상품 삭제](#상품-삭제)를 참고하세요. |
| `createdAt` | number | 상품을 만든 시각 |
| `updatedAt` | number | 상품을 마지막으로 수정한 시각 |

* `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`를 반환합니다.

| 필드 | 타입 | 설명 |
| - | - | - |
| `title` | string | 광고 상품명(200자 이하) |
| `guide` | string \| null | 소재 제작 가이드 링크(2,048자 이하). `null`을 보내면 지웁니다. `null`을 받는 필드는 `guide`뿐입니다. |
| `private` | boolean | 비공개 상품인지 여부 |
| `pricing` | object | `pricingType`(`CPM`, `CPC`, `CPP`, `INHOUSE`. 대소문자를 구분합니다)과 `price` |
| `discountRate` | number | 상품 할인율(%) |
| `minBudget` | number | 최소 집행 금액 |
| `frequency` | number | 노출 빈도 제한(정수 0\~999). `0`은 제한 없음입니다. |
| `metric` | object | `eImpressions`(일 노출수)와 `eCTR`(예상 클릭률, %) |
| `options` | object | `cppSlots`(구좌 수)와 `cppMinDays`(최소 집행 기간). CPP 상품에서만 쓰입니다. |
| `locale` | object | `currency`(통화)만 보낼 수 있습니다. 국가, 시간대, 언어는 바꿀 수 없습니다. |
| `unitGroups` | object\[] | 소재 세트 목록. 각 항목은 `name`과 `units`입니다. |
| `targetings` | object\[] | 타겟팅 목록. 각 항목은 `targeting`, `surchargeRate`, `policies`입니다. |

### 상품 규칙

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

| 대상 | 규칙 |
| - | - |
| 과금 유형 | `CPM`, `CPC`, `CPP`, `INHOUSE` 중 하나. 스플래시 유닛만 있는 상품은 CPC로 만들 수 없습니다. |
| 단가 | 인하우스가 아니면 0보다 커야 합니다. KRW와 JPY는 정수, USD와 INR은 소수점 둘째 자리까지 받습니다. 할인과 할증을 적용한 단가도 0보다 커야 합니다. |
| 상품 할인율 | 0 이상 100 미만 |
| 할증률 | 타겟팅마다 0 이상(상한 없음). CPP와 인하우스 상품은 0 |
| 최소 집행 금액 | 0이거나 단가 이상. CPP와 인하우스 상품은 0 |
| 일 노출수 | 0보다 커야 합니다. |
| 예상 클릭률 | 0\~100. CPC 상품은 0보다 커야 합니다. |
| 구좌 수, 최소 집행 기간 | CPP 상품은 필수. 정수 1~~50, 정수 1~~150 |
| 노출 빈도 제한 | 정수 0\~999. `0`은 제한 없음입니다. |
| 소재 제작 가이드 링크 | `http` 또는 `https` URL |
| 광고 상품명 | 비워 둘 수 없습니다. |
| 인하우스 | 자동으로 정해지는 값과 다른 값을 보내면 `400`을 반환합니다. |

### 소재 세트

`unitGroups`의 항목 하나가 콘솔의 소재 세트 하나입니다. `name`은 광고주에게 표시되는 소재 세트 이름이고, `units`는 그 세트에 넣을 광고 유닛 ID 목록입니다.

* 한 소재 세트의 유닛은 형식, 사이즈, 옵션(템플릿, 워터마크 등)이 같아야 합니다. 새로 넣은 유닛이 세트 기준과 다르면 `400 AD_UNIT_FIX_REQUIRED`를 반환합니다. 기준은 [소재 세트 구성](https://docs.adrop.io/ko/ad-product/create.md#2단계-소재-세트-구성)을 참고하세요.
* 같은 유닛 ID는 모든 소재 세트를 통틀어 한 번만 넣을 수 있습니다.
* 형식, 사이즈, 옵션이 같은 소재 세트끼리는 이름이 같을 수 없습니다.
* 새로 만드는 소재 세트에는 유닛이 1개 이상 있어야 합니다.
* 상품에는 세트 기준에 맞는 유닛이 1개 이상 남아 있어야 합니다. 수정 필요 상태인 유닛은 세지 않습니다.

`fixRequired`는 상품에 넣은 뒤 유닛의 형식, 사이즈, 옵션이 바뀌어 소재 세트 기준과 맞지 않게 된 유닛입니다. 콘솔의 **수정 필요** 상태와 같습니다. 수정 필요 유닛이 있는 상품으로는 새 캠페인을 예약할 수 없으니(기존 캠페인은 그대로 운영됩니다), 유닛 설정을 되돌리거나 소재 세트에서 빼세요.

[광고 유닛 API](https://docs.adrop.io/ko/integrations/ad-units.md#광고-상품에-미치는-영향)로 상품에 들어 있는 유닛의 설정을 바꾸거나 유닛을 삭제하면 상품의 소재 세트도 영향을 받습니다.

### 타겟팅 정책

`targetings`의 항목 하나가 상품에 노출할 타겟팅 하나입니다. 콘솔과 같이 한 상품에는 오디언스 타겟팅이나 문맥 타겟팅 중 한 종류만 넣으세요.

| 필드 | 설명 |
| - | - |
| `targeting` | 프로젝트의 오디언스 또는 문맥 타겟팅 ID |
| `surchargeRate` | 이 타겟팅을 쓸 때 적용할 할증률(%, 0 이상, 상한 없음). 할증률의 적용 방식은 [할증률 설정](https://docs.adrop.io/ko/targeting/overview.md#할증률-설정)을 참고하세요. |
| `policies` | 타겟팅 옵션 ID를 키로, `{ "policy": "..." }`를 값으로 넣은 객체. 상품에 노출할 옵션만 넣습니다. |

`policy`에는 콘솔의 적용 방식과 같은 값을 넣습니다.

| `policy` | 콘솔 | 설명 |
| - | - | - |
| `any` | 선택 | 광고주가 캠페인을 예약할 때 이 옵션을 선택할 수 있습니다. |
| `included` | 포함 | 모든 캠페인에 이 옵션이 필수로 포함됩니다. |
| `excluded` | 제외 | 모든 캠페인에서 이 옵션이 필수로 제외됩니다. |

* `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`과 함께 포함됩니다.

### 요청

```http theme={null}
GET /ad-products
```

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

### 쿼리 파라미터

| 파라미터 | 타입 | 필수 | 기본값 | 설명 |
| - | - | :-: | - | - |
| `limit` | number | - | `20` | 한 번에 받을 상품 수(1\~120) |
| `next` | string | - | - | 다음 페이지 커서. 앞 응답의 `next`를 그대로 넣습니다. 첫 페이지는 생략합니다. |

### 요청 예시

```bash theme={null}
curl "https://lake.adrop.io/ad-products?limit=20" \
  -H "x-api-key: YOUR_API_KEY"
```

### 응답 예시

`200` 응답으로 `items`(상품 목록)와 `next`(다음 페이지 커서)를 반환합니다. `next`가 없으면 마지막 페이지입니다.

```json theme={null}
{
  "items": [
    {
      "_id": "01JAZ3KB2C3D4E5F6G7H8J9K0M",
      "title": "Home Banner CPM",
      "private": false,
      "pricing": { "pricingType": "CPM", "price": 3000 },
      "discountRate": 0,
      "minBudget": 0,
      "frequency": 50,
      "metric": { "eImpressions": 100000, "eCTR": 1.5 },
      "options": {},
      "locale": { "country": "KR", "currency": "KRW", "timezone": "Asia/Seoul", "language": "ko" },
      "unitGroups": [{ "name": "Home Banner", "unitCount": 1, "fixRequiredCount": 0 }],
      "targetings": [{ "targeting": "01JAZ3K9Q8W5T2M4N6P7R8S9TV", "kind": "audience", "surchargeRate": 15 }],
      "createdAt": 1790820300000,
      "updatedAt": 1790820300000
    }
  ],
  "next": "01JAZ3KB2C3D4E5F6G7H8J9K0M"
}
```

목록 항목은 [상품 객체](#상품-객체)와 두 가지가 다릅니다.

* `targetings`에 `policies`가 없습니다. 정책이 필요하면 [상품 조회](#상품-조회)로 상품마다 읽으세요.
* `unitGroups`에 유닛 ID 대신 `unitCount`(유닛 수)와 `fixRequiredCount`(수정 필요 유닛 수)가 들어 있습니다.

정렬 순서는 대체로 만든 순서의 역순이지만, 오래된 상품은 순서가 다를 수 있습니다. 순서에 기대지 말고 `next`로 이어서 읽으세요.

***

## 상품 조회

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

### 요청

```http theme={null}
GET /ad-products/{productId}
```

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

### 요청 예시

```bash theme={null}
curl "https://lake.adrop.io/ad-products/01JAZ3KB2C3D4E5F6G7H8J9K0M" \
  -H "x-api-key: YOUR_API_KEY"
```

### 응답

`200` 응답으로 [상품 객체](#상품-객체)를 반환합니다.

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

### 오류

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

***

## 상품 수정

보낸 필드만 바꿉니다.

### 요청

```http theme={null}
PATCH /ad-products/{productId}
```

`ad-product:write` 권한이 필요합니다. 요청 본문은 [요청 본문](#요청-본문)과 같습니다.

### 쿼리 파라미터

| 파라미터 | 타입 | 필수 | 설명 |
| - | - | :-: | - |
| `ifUpdatedAt` | number | - | 마지막으로 조회한 상품의 `updatedAt`. 그 뒤에 상품이 바뀌었으면 `409 AD_PRODUCT_CONFLICT`를 반환하고 아무것도 바꾸지 않습니다. |

### 바뀌는 방식

* 보내지 않은 필드는 그대로입니다. 빈 본문 `{}`을 보내면 아무것도 바뀌지 않습니다.
* `unitGroups`와 `targetings`는 배열 전체가 보낸 내용으로 바뀝니다. 보내지 않은 소재 세트와 타겟팅은 상품에서 빠집니다.
* `pricing`, `metric`, `options`, `locale` 객체는 보낸 키만 바뀝니다.
* `targetings` 항목에서 `policies`를 생략하면 그 타겟팅의 정책은 그대로입니다. `policies`를 보내면 보낸 목록으로 바뀌고, 목록에 없는 최상위 옵션의 정책은 지워집니다.
* 소재 세트는 이름이 같은 기존 소재 세트와 대응되며, 새로 넣은 유닛만 검사합니다. 이미 들어 있던 수정 필요 유닛은 그대로 보내도 됩니다.
* 과금 유형을 `INHOUSE`로 바꾸면 인하우스에서 정해지는 값으로 함께 바뀝니다.
* 광고 상품명을 비우거나 상품의 유닛을 모두 뺄 수 없습니다.

콘솔에서 같은 상품을 수정하면 마지막으로 저장한 내용이 남습니다. `unitGroups`나 `targetings`처럼 배열 전체를 바꾸는 수정은 그 사이 콘솔에서 바꾼 내용을 덮어쓸 수 있으니 `ifUpdatedAt`을 함께 보내세요.

> [!TIP]
>
> 상품을 조회한 응답에서 응답에만 있는 필드(`_id`, `createdAt`, `updatedAt`, `deleteAt`, `unitGroups[].fixRequired`, `targetings[].kind`, `locale`의 `currency` 외 필드)를 빼고 그대로 보내면 아무것도 바뀌지 않습니다. 조회한 응답에서 바꿀 값만 고쳐 보내는 방식으로 안전하게 수정할 수 있습니다.

### 요청 예시

```bash theme={null}
curl -X PATCH "https://lake.adrop.io/ad-products/01JAZ3KB2C3D4E5F6G7H8J9K0M?ifUpdatedAt=1790820300000" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "frequency": 80,
    "pricing": { "price": 3500 }
  }'
```

### 응답

`200` 응답으로 수정된 [상품 객체](#상품-객체)를 반환합니다.

### 오류

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

***

## 상품 삭제

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

### 요청

```http theme={null}
DELETE /ad-products/{productId}
```

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

### 요청 예시

```bash theme={null}
curl -X DELETE "https://lake.adrop.io/ad-products/01JAZ3KB2C3D4E5F6G7H8J9K0M" \
  -H "x-api-key: YOUR_API_KEY"
```

### 응답 예시

`200` 응답으로 상품 ID와 삭제 예정 시각을 반환합니다.

```json theme={null}
{ "_id": "01JAZ3KB2C3D4E5F6G7H8J9K0M", "deleteAt": 1791079500000 }
```

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

### 오류

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

***

## 삭제 취소

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

### 요청

```http theme={null}
POST /ad-products/{productId}/restore
```

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

### 요청 예시

```bash theme={null}
curl -X POST "https://lake.adrop.io/ad-products/01JAZ3KB2C3D4E5F6G7H8J9K0M/restore" \
  -H "x-api-key: YOUR_API_KEY"
```

### 응답

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

### 오류

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

***

## 오류 처리

### 오류 응답

오류 응답에는 `statusCode`가 들어 있고, 아래 표에서 `errorCode` 칸이 `-`가 아닌 오류에는 `errorCode`도 들어 있습니다. 요청의 어느 부분이 잘못됐는지 알려 주는 오류는 `detail`도 함께 반환합니다. 처리 방식은 `errorCode`로 나누고, `errorCode`가 없으면 `statusCode`로 나누세요.

```json theme={null}
{
  "statusCode": 400,
  "errorCode": "AD_PRODUCT_VALIDATION_FAILED",
  "timestamp": "2026-11-05T19:58:22+09:00",
  "detail": {
    "errors": [
      {
        "path": "pricing.price",
        "constraint": "isPositive",
        "message": "pricing.price must be greater than 0",
        "value": 0
      }
    ]
  }
}
```

`detail.errors[]`의 `path`는 잘못된 필드의 위치(`pricing.price`, `unitGroups[0].name`, `targetings[0].policies.<옵션 ID>` 등)이고, `value`는 보낸 값입니다. `detail.errors`는 최대 100건까지 들어 있으니, 모두 고친 뒤 다시 보내면 남은 오류가 나옵니다. 요청 형식 오류(`VALIDATION_FAILED`)에는 `message`와 `error` 필드도 함께 들어 있습니다.

### 오류 코드

| 상태 | `errorCode` | 원인 |
| - | - | - |
| `400` | `VALIDATION_FAILED` | 요청 형식이 잘못됐습니다. 모르는 필드나 응답에만 있는 필드를 보냈거나, 값의 타입·형식·범위가 맞지 않거나, JSON 문법이 잘못됐습니다. |
| `400` | `AD_PRODUCT_VALIDATION_FAILED` | [상품 규칙](#상품-규칙)을 어겼습니다. `detail.errors`에 어긴 곳이 들어 있습니다. |
| `400` | `AD_UNIT_FIX_REQUIRED` | 새로 넣은 유닛이 소재 세트 기준과 다릅니다. `detail.mismatches[]`에 `path`(요청 위치), `unit`(유닛 ID), `differences`(다른 항목)가 들어 있습니다. |
| `400` | `AD_PRODUCT_TARGETING_INVALID` | 이 프로젝트의 타겟팅이 아니거나, 정책 키가 그 타겟팅의 최상위 옵션이 아닙니다. |
| `400` | `TARGETING_CONTEXT_EXCLUSIVE` | 포함·제외 정책이 있는 문맥 타겟팅과 정책이 있는 다른 문맥 타겟팅을 함께 넣었습니다. |
| `400` | `TARGETING_DUPLICATED_IN_REQUEST` | 같은 타겟팅을 두 번 넣었습니다. `detail.targetings`에 중복된 ID가 들어 있습니다. |
| `400` | `AD_PRODUCT_TARGETING_POLICY_LIMIT_EXCEEDED` | 포함·제외 정책이 상품당 500개를 넘습니다. |
| `401` | - | API 키가 없거나 잘못됐거나 폐기됐습니다. |
| `403` | - | 필요한 권한(`ad-product:read` 또는 `ad-product:write`)이 없습니다. |
| `404` | `AD_PRODUCT_NOT_FOUND` | 상품이 없거나 다른 프로젝트의 상품입니다. |
| `408` | `REQUEST_BODY_TIMEOUT` | 요청 본문을 30초 안에 다 보내지 못했거나 초당 16 KB보다 느리게 보냈습니다. |
| `409` | `AD_PRODUCT_CONFLICT` | `ifUpdatedAt`이 상품의 `updatedAt`과 다릅니다. |
| `409` | `AD_PRODUCT_LIMIT_EXCEEDED` | 프로젝트의 상품(삭제 예약 상품 포함)이 이미 1,000개입니다. |
| `409` | `AD_PRODUCT_MUTATION_NOT_ACCEPTABLE` | 삭제 예약 상품을 수정하려고 했습니다. |
| `413` | - | 요청 본문이 8 MB를 넘거나, 조회 요청에 본문을 넣었습니다. |
| `415` | `UNSUPPORTED_MEDIA_TYPE` | 요청 본문이 JSON이 아니거나 지원하지 않는 문자 인코딩입니다. UTF-8을 쓰세요. |
| `429` | `TOO_MANY_CONCURRENT_REQUESTS` | 동시 요청 한도를 넘었습니다. `Retry-After` 헤더의 시간(초)만큼 기다린 뒤 다시 보내세요. |
| `502` | - | 서버 내부 통신에 문제가 있습니다. |

### 다시 보내기

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

***

## 한도

| 항목 | 한도 |
| - | - |
| 프로젝트당 상품 | 1,000개(삭제 예약 상품 포함). 넘으면 `409 AD_PRODUCT_LIMIT_EXCEEDED` |
| 상품당 유닛 | 1,000개(모든 소재 세트의 유닛 ID를 중복 없이 센 수) |
| 소재 세트 | 상품당 100개 |
| 소재 세트당 유닛 | 300개 |
| 타겟팅 | 상품당 200개 |
| 포함·제외 정책 | 상품당 500개 |
| 정책 키 | 요청 하나의 모든 타겟팅을 합쳐 100,000개 |
| 광고 상품명 | 200자 |
| 소재 세트 이름 | 100자 |
| 소재 제작 가이드 링크 | 2,048자 |
| 요청 본문 | 8 MB |
| 동시 요청 | 프로젝트당 4건. 본문이 100 KB를 넘는 요청은 프로젝트당 2건 |
| 요청 본문 전송 | 30초 안에, 초당 16 KB 이상 |
| 응답 수신 | 30초 안에 응답을 다 받지 못하면 서버가 연결을 끊습니다. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.