> ## Documentation Index
> Fetch the complete documentation index at: https://adcp-docs-ja.pier1.co.jp/llms.txt
> Use this file to discover all available pages before exploring further.

# サンドボックスモード

> AdCP サンドボックスモード — シミュレートされたデータで商品発見、キャンペーン作成、クリエイティブ、配信をテストします。実際の支出やプロダクションへの副作用なし。

## 概要

サンドボックスモードを使用すると、バイヤーは実際のプラットフォームコールや実際の費用なしに、メディア購入のライフサイクル全体 — 発見、キャンペーン作成、クリエイティブ、配信 — をテストできます。レスポンスにはシミュレートされたが現実的なデータが含まれます。

サンドボックスはリクエストごとではなく**アカウントレベル**で機能します。リクエストがサンドボックスアカウントを参照すると、リクエスト全体がサンドボックスとして扱われる。これにより、マルチステップフローで実際のトラフィックとテストトラフィックを誤って混在させるリスクを排除します。

## ケイパビリティの発見

セラーは `get_adcp_capabilities` でサンドボックスサポートを宣言する:

```json theme={null}
{
  "account": {
    "sandbox": true
  }
}
```

サンドボックスモードを使用する前にこれを確認します。`account.sandbox` が宣言されていないか `false` の場合、セラーはサンドボックスをサポートしていません。

## サンドボックスへの2つの経路

サンドボックスモードへの入り方は、セラーのアカウントモデル（`require_operator_auth`）によって異なります。2つの経路はまったく異なる — 正しい方に従うようにすること。

### バイヤー宣言アカウント（`require_operator_auth: false`）

セラーはエージェントを信頼し、オペレーターごとの認証を必要としません。サンドボックスは**ナチュラルキー**の一部だ — 同じブランド/オペレーターのペアがプロダクションとサンドボックスの両方のアカウントを持つことができ、`sandbox: true` で区別されます。

**セットアップ:** アカウントエントリに `sandbox: true` を付けて `sync_accounts` でサンドボックスアカウントを宣言する:

```json theme={null}
// sync_accounts — サンドボックスアカウントを宣言する
{
  "accounts": [{
    "brand": { "domain": "acme-corp.com" },
    "operator": "acme-corp.com",
    "billing": "operator",
    "sandbox": true
  }]
}
```

**使用方法:** すべてのリクエストで `sandbox: true` を付けたナチュラルキーでサンドボックスアカウントを参照する:

```json theme={null}
// get_products — バイヤー宣言サンドボックス
{
  "account": {
    "brand": { "domain": "acme-corp.com" },
    "operator": "acme-corp.com",
    "sandbox": true
  },
  "brief": "Premium CTV inventory for Q2 campaign"
}
```

### アカウント ID 名前空間（`require_operator_auth: true`）

セラーは各オペレーターが直接認証することを要求します。サンドボックスアカウントは**セラーのプラットフォーム上の既存のテストアカウント**だ — Stripe のテストモード、Google Ads サンドボックスアカウント、Snap のテスト広告主アカウントのようなもの。作成するのではなく、発見します。

**セットアップ:** `sandbox: true` フィルターを使って `list_accounts` でサンドボックスアカウントを発見する:

```json theme={null}
// list_accounts — サンドボックスアカウントを探す
{
  "sandbox": true
}
```

セラーは既存のテストアカウントを返します:

```json theme={null}
{
  "accounts": [{
    "account_id": "acct_sandbox_acme_001",
    "name": "Acme Test Account",
    "status": "active",
    "sandbox": true
  }]
}
```

**使用方法:** すべてのリクエストで `account_id` でサンドボックスアカウントを参照する:

```json theme={null}
// get_products — アカウント ID 名前空間サンドボックス
{
  "account": { "account_id": "acct_sandbox_acme_001" },
  "brief": "Premium CTV inventory for Q2 campaign"
}
```

### クイックリファレンス

|                  | バイヤー宣言（`require_operator_auth: false`） | アカウント ID 名前空間（`require_operator_auth: true`） |
| ---------------- | -------------------------------------- | -------------------------------------------- |
| **サンドボックスアカウント** | バイヤーが `sync_accounts` で宣言              | セラーのプラットフォームに既存                              |
| **発見方法**         | N/A — バイヤーが作成                          | `sandbox: true` で `list_accounts`            |
| **アカウント参照**      | `sandbox: true` を持つナチュラルキー             | `account_id`                                 |
| **実世界の類似**       | セルフサービステストモード                          | Stripe テストモード、Google Ads サンドボックス             |

## レスポンスの確認

成功レスポンスには `sandbox: true` が含まれ、リクエストがサンドボックスモードで処理されたことを確認します:

```json theme={null}
{
  "products": [...],
  "sandbox": true
}
```

## 完全なライフサイクルの例（バイヤー宣言アカウント）

この例はバイヤー宣言アカウントのパスを示します。アカウント ID 名前空間の場合、サンドボックスアカウントを `list_accounts`（またはセラー定義 ID のためのアウトオブバンドのオンボーディング）を通じて解決してから、各ステップのナチュラルキーアカウント参照を `{ "account_id": "acct_sandbox_acme_001" }` に置き換える。

### 1. 商品の発見

```json theme={null}
// get_products
{
  "account": {
    "brand": { "domain": "acme-corp.com" },
    "operator": "acme-corp.com",
    "sandbox": true
  },
  "brief": "CTV inventory for brand awareness"
}
```

### 2. メディアバイの作成

```json theme={null}
// create_media_buy
{
  "account": {
    "brand": { "domain": "acme-corp.com" },
    "operator": "acme-corp.com",
    "sandbox": true
  },
  "proposal_id": "prop_abc",
  "total_budget": { "amount": 50000, "currency": "USD" },
  "brand": { "domain": "acme-corp.com" },
  "start_time": { "start_type": "asap" },
  "end_time": "2026-04-01T00:00:00Z"
}
```

セラーはリアルな ID、パッケージ、クリエイティブ締め切りを持つシミュレートされたメディアバイを返す — 実際のプラットフォームには何も予約されない。

### 3. クリエイティブのアップロード

```json theme={null}
// sync_creatives
{
  "account": {
    "brand": { "domain": "acme-corp.com" },
    "operator": "acme-corp.com",
    "sandbox": true
  },
  "creatives": [{
    "creative_id": "hero_video_30s",
    "name": "Brand Hero Video 30s",
    "format_id": {
      "agent_url": "https://creative.adcontextprotocol.org",
      "id": "video_standard_30s"
    },
    "assets": {
      "video": {
        "url": "https://cdn.example.com/hero.mp4",
        "width": 1920,
        "height": 1080,
        "duration_ms": 30000
      }
    }
  }],
  "assignments": {
    "hero_video_30s": ["pkg_001"]
  }
}
```

### 4. 配信の確認

```json theme={null}
// get_media_buy_delivery
{
  "account": {
    "brand": { "domain": "acme-corp.com" },
    "operator": "acme-corp.com",
    "sandbox": true
  },
  "media_buy_ids": ["mb_sandbox_123"]
}
```

セラーはシミュレートされた配信メトリクス — インプレッション、スペンド、ペーシング — をキャンペーンが実行中であるかのように返します。

## サンドボックス vs ドライラン

一部の sync タスク（`sync_creatives`、`sync_catalogs`）は `dry_run` パラメータをサポートします。これらは異なる目的を持ちます:

|            | サンドボックスアカウント   | `dry_run`          |
| ---------- | -------------- | ------------------ |
| **意味**     | 何も実際ではない       | 変更を適用せずにプレビュー      |
| **スコープ**   | アカウント上のすべてのタスク | sync タスクのみ         |
| **副作用**    | なし（シミュレート）     | なし（プレビューのみ）        |
| **ユースケース** | 完全なライフサイクルのテスト | コミット前に同期が何を変えるかを確認 |

これらは組み合わせられます——サンドボックスアカウントでの `dry_run: true` は、サンドボックスの状態すら更新せずに同期をプレビューします。

<Warning>
  `X-Dry-Run`、`X-Test-Session-ID`、`X-Mock-Time` の HTTP ヘッダーは**非推奨**です。サンドボックスモードが、プロトコルレベルのパラメータとしてそれらを置き換えます。

  * **セラーはこれらのヘッダーに基づいて挙動を変えてはなりません（MUST NOT）**。サンドボックスモードはアカウント参照のみで決まります。セラーはヘッダーを完全に無視すべきであり（SHOULD）、バイヤーが古い統合を特定するのを助けるために非推奨の警告をログに記録してもかまいません（MAY）。
  * **バイヤーはプロダクションの副作用を防ぐためにこれらのヘッダーに頼ってはなりません（MUST NOT）**。アカウント参照の `sandbox: true` のみがサンドボックスセマンティクスを保証します。
</Warning>

## セラーの実装

リクエストがサンドボックスアカウントを参照する場合（ナチュラルキーの `sandbox: true` またはサンドボックスの `account_id` を通じて）、エージェントはプロダクションの状態を永続化したり実世界の副作用を引き起こしたりしてはなりません（MUST NOT）:

* 実際の広告プラットフォーム API コール（実際の注文、ラインアイテムなど）を**行ってはならない（MUST NOT）**
* 実際のお金を請求したり、実際の請求レコードを**作成してはならない（MUST NOT）**
* プロダクションと同じ方法で入力を**検証しなければならない（MUST）**（無効な予算、不正な日付などを拒否します）
* シミュレートされたデータを含むリアルなレスポンスシェイプを**返さなければならない（MUST）**
* 成功レスポンスに `sandbox: true` を含める**べきだ（SHOULD）**

サンドボックスのエラーは実際の検証エラーです。バイヤーがサンドボックスアカウントを使用して無効な予算を送信した場合、実際のエラーを返す — 偽のエラーをシミュレートしません。

**アカウント ID 名前空間のセラー**: プラットフォームに `list_accounts` が `sandbox: true` でフィルタリングした際に返すことができる既存のサンドボックス/テストアカウントがあることを確認するか、サンドボックス ID をアウトオブバンドで供給します。

**バイヤー宣言アカウントのセラー**: `sync_accounts` とアカウント参照でナチュラルキーの一部として `sandbox: true` を受け入れる。`(brand, operator, sandbox: true)` を `(brand, operator)` とは別のアカウントとして扱います。

## プロトコルコンプライアンス

ケイパビリティで `account.sandbox: true` を宣言するセラーは以下をしなければなりません (MUST):

* アカウントモデルに適したサンドボックスアカウントを受け入れる
* サンドボックスアカウントを参照するすべてのリクエストにサンドボックスセマンティクスを適用します
* サンドボックスリクエストを処理する際、プロダクションの状態を永続化したり実世界の副作用を引き起こしたりしない
* 通常の入力検証を適用する（サンドボックスは検証をバイパスしない）

セラーはサンドボックスアカウントリクエストを処理する際に成功レスポンスに `sandbox: true` を含めるべきだ (SHOULD)。