> ## 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`のスコープを持つAPIキーが必要です。この2つのスコープは、コンソールの **\[設定]** > **\[連携]** メニューでは選択できません。Adropにご依頼いただければ、2つのスコープを含むキーを発行します。[アプリAPI](https://docs.adrop.io/ja/integrations/apps.md)、[広告ユニットAPI](https://docs.adrop.io/ja/integrations/ad-units.md)、[オーディエンスターゲティングAPI](https://docs.adrop.io/ja/integrations/audience-targeting.md)のスコープも同じキーにまとめて付与できます。
* 2つのスコープは別々に確認されます。`ad-product:write`だけのキーは、取得（`GET`）リクエストで`403`を受け取ります。作成・更新・削除の取り消しのレスポンスには商品全体が含まれますが、商品を別途取得するには`ad-product:read`も必要です。
* 商品に入れる広告ユニットIDは、[広告ユニットAPI](https://docs.adrop.io/ja/integrations/ad-units.md)で取得するか、コンソールの **広告ユニット** メニューで確認します。ターゲティングIDとターゲティングオプションのIDは、[オーディエンスターゲティングAPI](https://docs.adrop.io/ja/integrations/audience-targeting.md)と[コンテキストターゲティングAPI](https://docs.adrop.io/ja/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`はエポックミリ秒です。 |
| 同時リクエスト | プロジェクトごとに4件まで同時に処理します。同じプロジェクトのキーを複数使っても合算します。超えると`429`を返します。 |

`429`を受け取ったら、`Retry-After`ヘッダーの秒数だけ待ってから再送信してください。サーバーが混雑しているときは、リクエストを1件ずつ送っても`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より大きい1日のインプレッション数 |
| `metric.eCTR` | インハウス以外 | 予想CTR。すべてのユニットがスプラッシュユニットの場合は省略できます。 |
| `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は1クリックあたり、CPPは1日あたりの単価です。インハウスは0です。 |
| `discountRate` | number | 商品割引率（%、`10`は10%）。値が保存されている商品にのみあります。 |
| `minBudget` | number | 最低予算（`locale.currency`の通貨）。値が保存されている商品にのみあります。 |
| `frequency` | number | フリークエンシーキャップ。1つのキャンペーンを1人のユーザーに1日に表示できる最大回数です。コンソールで **制限なし** に設定した商品は`0`です。値が保存されている商品にのみあります。 |
| `metric.eImpressions` | number | 1日のインプレッション数 |
| `metric.eCTR` | number | 予想CTR（%、`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`（1日のインプレッション数）と`eCTR`（予想CTR、%） |
| `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は小数点以下2桁まで受け付けます。割引とプレミアム料金を適用した単価も0より大きくする必要があります。 |
| 商品割引率 | 0以上100未満 |
| プレミアム料金の率 | ターゲティングごとに0以上（上限なし）。CPP商品とインハウス商品は0 |
| 最低予算 | 0または単価以上。CPP商品とインハウス商品は0 |
| 1日のインプレッション数 | 0より大きくする必要があります。 |
| 予想CTR | 0〜100。CPC商品は0より大きくする必要があります。 |
| スロット数、最低期間 | CPP商品では必須。整数1〜50、整数1〜150 |
| フリークエンシーキャップ | 整数0〜999。`0`は制限なしです。 |
| クリエイティブガイドリンク | `http`または`https`のURL |
| 広告商品名 | 空にできません。 |
| インハウス | 自動で設定される値と異なる値を送ると`400`を返します。 |

### クリエイティブセット

`unitGroups`の1項目が、コンソールのクリエイティブセット1つにあたります。`name`は広告主に表示されるクリエイティブセット名で、`units`はそのセットに入れる広告ユニットIDの一覧です。

* 1つのクリエイティブセットのユニットは、フォーマット、サイズ、オプション（テンプレート、透かしなど）が同じである必要があります。新しく入れたユニットがセットの基準と異なる場合は`400 AD_UNIT_FIX_REQUIRED`を返します。基準は[クリエイティブセットを設定する](https://docs.adrop.io/ja/ad-product/create.md#ステップ2-クリエイティブセットを設定する)を参照してください。
* 同じユニットIDは、すべてのクリエイティブセットを通して1回だけ入れられます。
* フォーマット、サイズ、オプションが同じクリエイティブセット同士は、同じ名前にできません。
* 新しく作るクリエイティブセットには、ユニットが1つ以上必要です。
* 商品には、セットの基準に合うユニットが1つ以上残っている必要があります。修正必要ステータスのユニットは数えません。

`fixRequired`は、商品に入れた後にユニットのフォーマット、サイズ、オプションが変わり、クリエイティブセットの基準に合わなくなったユニットです。コンソールの **修正必要** ステータスと同じです。これらのユニットがある商品では新しいキャンペーンを予約できない（既存のキャンペーンはそのまま運用されます）ため、ユニットの設定を元に戻すか、クリエイティブセットから外してください。

[広告ユニットAPI](https://docs.adrop.io/ja/integrations/ad-units.md#広告商品への影響)で商品に含まれるユニットの設定を変更したり、ユニットを削除したりすると、商品のクリエイティブセットにも影響します。

### ターゲティングポリシー

`targetings`の1項目が、商品に表示するターゲティング1つにあたります。コンソールと同じく、1つの商品にはオーディエンスターゲティングかコンテキストターゲティングのどちらか一方だけを入れてください。

| フィールド | 説明 |
| - | - |
| `targeting` | プロジェクトのオーディエンスまたはコンテキストターゲティングのID |
| `surchargeRate` | このターゲティングを使うときに適用するプレミアム料金の率（%、0以上、上限なし）。適用方法は[プレミアム料金の設定](https://docs.adrop.io/ja/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`）。
* 同じターゲティングを2回入れると`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回で受け取る商品の数（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"
}
```

一覧の項目は、[商品オブジェクト](#商品オブジェクト)と2点が異なります。

* `targetings`に`policies`がありません。ポリシーが必要な場合は、[商品の取得](#商品の取得)で商品ごとに読み込んでください。
* `unitGroups`には、ユニットIDの代わりに`unitCount`（ユニット数）と`fixRequiredCount`（修正必要のユニット数）が入っています。

並び順はおおむね作成の新しい順ですが、古い商品は順序が異なる場合があります。順序に頼らず、`next`で続きを読み込んでください。

***

## 商品の取得

1つの商品をターゲティングポリシーと一緒に返します。

### リクエスト

```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` | 同じターゲティングを2回入れました。`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件 |
| ポリシーのキー | 1つのリクエストのすべてのターゲティングを合わせて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.