> ## 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 アカウントとエージェント: すべてのトランザクションにおける4つのエンティティ（ブランド、アカウント、オペレーター、エージェント）、アカウント ID 名前空間、バイヤー宣言アカウント、請求設定。

AdCP はすべての請求可能な操作において4つのエンティティを区別する:

| エンティティ     | 問い                      | 識別方法                                                                                |
| ---------- | ----------------------- | ----------------------------------------------------------------------------------- |
| **ブランド**   | 誰のプロダクトが広告されるか?         | ブランド参照: `domain` + オプションの `brand_id`（[brand.json](/docs/brand-protocol/brand-json)） |
| **アカウント**  | 誰が請求されるか? どのレートが適用されるか? | [アカウント参照](#account-references)                                                      |
| **オペレーター** | 誰がブランドのために操作するか?        | ドメイン（例: `pinnacle-media.com`）                                                       |
| **エージェント** | どのソフトウェアが購入を配置するか?      | 認証済みセッション                                                                           |

**ブランド** — プロダクトまたはサービスが宣伝される広告主。`brand` 参照（`domain` + オプションの `brand_id`）で識別され、`/.well-known/brand.json` を通じて解決されます。シングルブランドの企業はドメインのみを使用する（`brand_id` なし）。

**アカウント** — バイヤーとセラーの間の請求関係。レートカード、支払条件、信用限度、請求書を受け取る人を決定します。すべての請求可能な操作にはアカウント参照が必要だ — セラーまたは上流プラットフォームが正規のアカウント名前空間を所有する場合はセラーが割り当てた `account_id`、そのタプルがバイヤー宣言アカウントの耐久性のあるプロトコルキーである場合は自然キー（`brand`、`operator`）。サンドボックスアカウントは同じモデルに従う — アカウント ID 名前空間は `list_accounts` またはアウトオブバンドのセットアップからの既存のサンドボックス ID を使用し、バイヤー宣言サンドボックスは `sandbox: true` を含む自然キーを使用します。

**オペレーター** — 購入を主導するエンティティ — エージェンシートレーディングデスク、ブランドの内部チーム、または広告主の代わりに行動する別のエンティティ。ドメインで識別され、`brand.json` の[認可オペレーター](#authorized-operators)を通じて検証可能です。

**エージェント** — 購入を配置してキャンペーンを管理するソフトウェア。セラーで認証し、複数のオペレーターとブランドのために操作することがあります。

完全な商業モデルについては[アカウントプロトコルの概要](/docs/accounts/overview)を、タスクリファレンスについては[sync\_accounts](/docs/accounts/tasks/sync_accounts)を参照。

## セラーが宣言するもの

セラーは [`get_adcp_capabilities`](/docs/protocol/get_adcp_capabilities#account) の `account` セクションを設定します:

**1. どの請求モデルをサポートするか?**（`supported_billing`）

バイヤーはすべての `sync_accounts` エントリで `billing` としてこれらの値の1つを渡す必要があります。セラーは受け入れるか拒否するかを決める。

| 請求           | 請求される対象                     | ユースケース                                                    |
| ------------ | --------------------------- | --------------------------------------------------------- |
| `operator`   | オペレーター（エージェンシーまたはブランドが直接購入） | オペレーターが自分の条件で購入                                           |
| `agent`      | エージェント                      | エージェントがブランド間で請求を統合                                        |
| `advertiser` | 広告主が直接                      | オペレーターが発注するが広告主が支払う（ソーシャルプラットフォームや DACH の B2B ワークフローで一般的） |

**2. オペレーターレベルの認証を必要とするか?**（`require_operator_auth`）

このフィールドが認証モデルとアカウント参照の形状を決定する:

`false`（デフォルト）の場合 — **バイヤー宣言アカウント**: セラーはエージェントを信頼します。エージェントは一度認証して `sync_accounts` を通じてアカウントを宣言します。後続のリクエストでは、バイヤーは自然キー（`brand` + `operator`）を渡し、セラーが内部で解決します。

`true` の場合 — **アカウント ID 名前空間**: 各オペレーターはセラーと直接認証する必要があります。エージェントはオペレーターごとにクレデンシャルを取得する — セラーの `authorization_endpoint` を使った OAuth、またはアウトオブバンドの API キーで。後続のリクエストはセラーが割り当てた `account_id` を渡します。クレデンシャルが複数のアカウントにアクセスし得る場合、セラーは `list_accounts` を公開しなければならず（MUST）、バイヤーは最初のアカウントスコープリクエストの前に明示的なアカウントを解決しなければなりません（MUST）。クレデンシャルが正確に 1 つのアカウントに束縛される場合、セラーはそのシングルトンを返す `list_accounts` を公開すべきです（SHOULD）。セラーが `list_accounts` を省略してもよい（MAY）のは、別の宣言されたパスまたはアウトオブバンドのオンボーディングを通じて同じ明示的なアカウント ID を供給する場合のみです。

サンドボックスの場合、パスはアカウント名前空間に従う: アカウント ID 名前空間は `list_accounts` またはアウトオブバンドのセットアップからの既存のテストアカウントを使用し、バイヤー宣言アカウントは `sandbox: true` を含む `sync_accounts` を使用して自然キーで参照します。

セラーは `account_financials: true` を宣言して [`get_account_financials`](/docs/accounts/tasks/get_account_financials) を通じてアカウントレベルの財務データ（支出、信用、請求書）を公開することもできます。これはオペレーター請求アカウントにのみ適用されます。

**ケイパビリティの例:**

```json theme={null}
{
  "account": {
    "require_operator_auth": false,
    "supported_billing": ["operator", "agent"]
  }
}
```

`advertiser` 請求をサポートするセラーはそれを明示的に宣言します:

```json theme={null}
{
  "account": {
    "require_operator_auth": false,
    "supported_billing": ["operator", "agent", "advertiser"]
  }
}
```

これらのフィールドは一般的なパターンに組み合わさる。

## セラーパターン

どのようなプラットフォームから購入するか? それがアカウントセットアップパターンを決定します。

| プラットフォームタイプ                           | アカウントパターン          | `require_operator_auth` | `supported_billing`                        |
| ------------------------------------- | ------------------ | ----------------------- | ------------------------------------------ |
| [ソーシャル / ウォールドガーデン](#social-platform) | 上流管理のアカウント ID 名前空間 | `true`                  | `["operator"]`                             |
| [ダイレクトパブリッシャー](#direct-publisher)     | バイヤー宣言アカウント        | `false`                 | `["operator"]` または `["operator", "agent"]` |
| [DSP / プログラマティック](#dsp--programmatic) | バイヤー宣言アカウント        | `false`                 | `["agent"]`                                |

### ソーシャルプラットフォーム

オペレーターはすでにプラットフォーム上にアカウントを持っている — 広告アカウント、ビジネスマネージャー、セルフサービスダッシュボード。上流プラットフォームがそのクレデンシャルでアクセス可能な正規のアカウント名前空間を所有します。エージェントはオペレーターのクレデンシャルを取得（OAuth または API キーで）し、オペレーターごとのセッションを開き、`list_accounts` を通じて明示的なアカウントを解決し、返された `account_id` 値を使用します。プラットフォームはオペレーターに直接請求します。

**ケイパビリティ:**

```json theme={null}
{
  "account": {
    "require_operator_auth": true,
    "supported_billing": ["operator"],
    "authorization_endpoint": "https://seller.example.com/oauth/authorize"
  }
}
```

**バイヤーワークフロー:**

1. `get_adcp_capabilities` を呼び出す — `require_operator_auth: true` と `authorization_endpoint` を確認
2. 各オペレーターについて:
   a. オペレーターのクレデンシャルを取得（`authorization_endpoint` を使った OAuth、またはアウトオブバンドの API キー）
   b. オペレーターのクレデンシャルで新しいセッションを開く
   c. `list_accounts` を呼び出してそのクレデンシャルで見えるアカウントを発見する
3. 人間またはポリシーがリストから正しいアカウントを選択する
4. オペレーターのセッションと `{ "account_id": "..." }` を使って `get_products` / `create_media_buy` を呼び出す

**list\_accounts レスポンス:**

```json theme={null}
{
  "accounts": [{
    "account_id": "acc_spark_social_001",
    "name": "Spark paid social",
    "brand": { "domain": "nova-brands.com", "brand_id": "spark" },
    "operator": "pinnacle-media.com",
    "status": "active",
    "billing": "operator",
    "account_scope": "operator_brand"
  }]
}
```

後続の呼び出しは発見された ID を使用する:

```json theme={null}
{
  "account": { "account_id": "acc_spark_social_001" }
}
```

**重要ポイント:** エージェントのクレデンシャルではなく、オペレーターのクレデンシャルがそのセッションのすべての呼び出しを認可します。バイヤーは 3.0.x のアカウント ID モデルでは AdCP を通じてアカウントを宣言または作成しません。`list_accounts` は上流の名前空間をミラーします。セラーが `sync_accounts` を公開する場合、それは既存の `account_id` に対する設定更新のためだけであり、将来の明示的なケイパビリティがアカウント ID プロビジョニングを宣言しない限り、自然キーのプロビジョニングではありません。

### ダイレクトパブリッシャー

パブリッシャーはエージェントを信頼するが、オペレーターに直接請求します。エージェントは `sync_accounts` を通じてアカウントをセットアップする — オペレーターごとのログインは不要。アカウントはアクティブになる前に人間の承認（信用調査、法的合意）が必要なことがあります。

多くのパブリッシャーはエージェント請求も受け入れる（`supported_billing: ["operator", "agent"]`）。バイヤーはアカウントごとに選択する — ダイレクト関係のあるオペレーターは `billing: "operator"` を使用し、それ以外は `billing: "agent"` を使用します。セラーが特定のアカウントに対して要求された請求をサポートしない場合、リクエストを拒否し、エージェントは別のモデルで再送信します。

**ケイパビリティ:**

```json theme={null}
{
  "account": {
    "supported_billing": ["operator", "agent"]
  }
}
```

**バイヤーワークフロー:**

1. `get_adcp_capabilities` を呼び出す — `require_operator_auth` が欠如（デフォルトは `false`）を確認
2. 各ブランド/オペレーターペアに対して `sync_accounts` を呼び出す
3. アカウントステータスが `active` になるのを待つ — 人間が `setup.url` で信用/法的手続きを完了する必要がある場合があります
4. `account` 参照を使って `get_products` を呼び出す
5. `account` 参照を使って `create_media_buy` を呼び出す

**sync\_accounts リクエスト — ブランドが直接購入:**

```json theme={null}
{
  "accounts": [{
    "brand": { "domain": "acme-corp.com" },
    "operator": "acme-corp.com",
    "billing": "operator"
  }]
}
```

セラーはリクエストを認め、プロビジョニング前にセットアップが必要:

```json theme={null}
{
  "accounts": [{
    "brand": { "domain": "acme-corp.com" },
    "operator": "acme-corp.com",
    "action": "created",
    "status": "pending_approval",
    "billing": "operator",
    "account_scope": "brand",
    "setup": {
      "url": "https://seller.example.com/advertiser-onboard",
      "message": "Complete advertiser registration and credit application"
    }
  }]
}
```

セラーは関係 `(brand: "acme-corp.com", operator: "acme-corp.com", billing: "operator")` を認めたが、アカウントはアクティブになる前にレビューが保留中です。Acme Corp の担当者が URL でセットアップを完了します。進捗を確認するため、エージェントは次のいずれかを行う:

* 同じ自然キーで `sync_accounts` を再呼び出す — セラーが更新されたステータスを返す
* リクエストに `push_notification_config` が提供されていた場合はウェブフック通知を受け取ります

**重要ポイント:** `pending_approval` は通常のパスです。すべてのバイヤーはセラーとダイレクト関係が必要です。

**請求拒否 — オペレーター請求が利用不可:**

セラーは一般的にオペレーター請求をサポートするが、すべてのオペレーターに対してサポートしない場合があります。ここで、エージェントはダイレクト関係のないオペレーターに対してオペレーター請求をリクエストする:

```json theme={null}
{
  "accounts": [{
    "brand": { "domain": "acme-corp.com" },
    "operator": "acme-corp.com",
    "billing": "operator"
  }]
}
```

セラーはこのオペレーターにダイレクト請求関係がないためリクエストを拒否:

```json theme={null}
{
  "accounts": [{
    "brand": { "domain": "acme-corp.com" },
    "operator": "acme-corp.com",
    "action": "failed",
    "status": "rejected",
    "errors": [{
      "code": "BILLING_NOT_SUPPORTED",
      "message": "Operator billing is not available for this account. Re-submit with billing: \"agent\"."
    }]
  }]
}
```

エージェントは `billing: "agent"` で再送信するか、このセラーではオペレーター請求が利用できないことをバイヤーに伝える。請求はサイレントに再マッピングされることはない。

### DSP / プログラマティック

すべての請求はエージェントを通じて流れる。エージェントはプラットフォームとの継続的な関係を持ち、すべてのブランドとオペレーターにわたって請求を統合します。アカウントは即座に作成される — 人間の承認は不要です。

**ケイパビリティ:**

```json theme={null}
{
  "account": {
    "supported_billing": ["agent"]
  }
}
```

**バイヤーワークフロー:**

1. `get_adcp_capabilities` を呼び出す — `supported_billing: ["agent"]` を確認
2. `billing: "agent"` で各ブランド/オペレーターペアに `sync_accounts` を呼び出す
3. アカウントは即座にアクティブ — 人間の承認は不要
4. `account` 参照を使って `get_products` / `create_media_buy` を呼び出す

**sync\_accounts リクエスト:**

```json theme={null}
{
  "accounts": [{
    "brand": { "domain": "nova-brands.com", "brand_id": "spark" },
    "operator": "pinnacle-media.com",
    "billing": "agent"
  }]
}
```

アカウントは即座にアクティブ:

```json theme={null}
{
  "accounts": [{
    "brand": { "domain": "nova-brands.com", "brand_id": "spark" },
    "operator": "pinnacle-media.com",
    "action": "created",
    "status": "active",
    "billing": "agent",
    "account_scope": "operator_brand"
  }]
}
```

**重要ポイント:** エージェントは統合された単一の請求書を受け取ります。ブランドごとのアカウントはレポートの粒度を提供するが、請求は一元化されます。

## 認可オペレーター

ブランドは `/.well-known/brand.json` の `authorized_operators` フィールドを通じて誰が代表できるかを宣言します。セラーは `sync_accounts` を処理する際にこれに対してオペレーターを検証すべきです。

```json theme={null}
{
  "house": {
    "domain": "nova-brands.com",
    "name": "Nova Brands"
  },
  "brands": [
    { "id": "spark", "names": [{"en": "Spark"}] },
    { "id": "glow", "names": [{"en": "Glow"}] }
  ],
  "authorized_operators": [
    {
      "domain": "pinnacle-media.com",
      "brands": ["spark", "glow"],
      "countries": ["US", "GB", "DE"]
    },
    {
      "domain": "summit-agency.jp",
      "brands": ["spark"],
      "countries": ["JP"]
    },
    {
      "domain": "nova-brands.com",
      "brands": ["*"]
    }
  ]
}
```

| フィールド       | 必須  | 説明                                             |
| ----------- | --- | ---------------------------------------------- |
| `domain`    | はい  | オペレーターのドメイン                                    |
| `brands`    | はい  | このオペレーターが代表できるブランド ID。`["*"]` はすべてのブランドを意味します。 |
| `countries` | いいえ | ISO 3166-1 alpha-2 国コード。グローバル認可の場合は省略します。      |

### 検証フロー

1. `{brand.domain}/.well-known/brand.json` を解決します
2. `authorized_operators` でマッチする `domain` と `brands` 内のブランドを確認
3. 見つかった場合 → 進む（アカウントはまだ信用/法的承認が必要なことがあります）
4. 見つからない場合 → アカウントを拒否（`action: "failed"`）または手動レビュー用に `pending_approval` を返す

検証は信頼シグナルであり、ゲートではありません。セラーは `brand.json` でオペレーターを見つけることでプロビジョニングを迅速化できます。オペレーターがリストにない場合でも、セラーは独自のレビュープロセスを通じて承認できます。

**自己認可は暗黙的です。** `operator` ドメインがブランドのドメインと一致する場合、ブランドが直接操作している — `authorized_operators` へのリストは不要です。

`authorized_operators` はブランドとその代わりに操作する人との間のインターフェースをモデル化します。内部のエージェンシー階層はモデル化しません。

## バイヤーエージェントのアイデンティティ

`authorized_operators` は、オペレーターがブランドを代表することを許可されているかどうかをセラーに伝えます。しかし、呼び出しを行う*エージェント*が誰か、そのエージェントとどんな商業関係が記録されているかは伝えません。それらは別の問いであり、セラーはプロビジョニング前に両方を確認します。

すべての `sync_accounts` リクエストで 2 つのレイヤーが動作します:

| レイヤー               | 問い                                     | どこに存在するか                                                                                                                                                                                                             |
| ------------------ | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **エージェントアイデンティティ** | どのバイヤーエージェントがこのリクエストを発行したか？            | セラーのオンボーディングレコード。署名付きリクエストの `agent_url`（[リクエスト署名](/docs/building/by-layer/L1/security#signed-requests-transport-layer)使用時）またはエージェントが提示した bearer / API キー / OAuth クレデンシャルで照会される。署名またはクレデンシャルがアイデンティティを確立する。認可は別のチェック。 |
| **ブランド-オペレーター認可**  | リクエストで名指しされたオペレーターはブランドのために行動する認可を持つか？ | `brand.json` の `authorized_operators`（上記）。リクエストが署名されているかどうかに関わらず検証される。                                                                                                                                               |

両方のレイヤーが通過しなければなりません（MUST）。オンボード済みエージェントからの署名付きリクエストでも、認可されていないオペレーター向けならブランド-オペレーターチェックで拒否されます。認可されたオペレーター向けでも、認識されていないエージェントからのリクエストはアイデンティティチェックで拒否されます。`sync_accounts` で [`request_signing.required_for`](/docs/building/by-layer/L1/security#transport-scope) を宣伝するセラーは、アイデンティティレイヤーで未署名トラフィックを拒否します。それを宣伝しないセラーも、エージェント請求可能な値を受け入れる前に確立されたクレデンシャルマッピングを要求してもよい（MAY）。

ブランド-オペレーターチェックは、[オペレーターの取り消しとキャッシング](#オペレーターの取り消しとキャッシング)に従いセラーがキャッシュした `brand.json` に対して実行されます — 取り消しは最終的です。高価値または初回のブランドプロビジョニングを行うセラーは、TOCTOU ウィンドウを閉じるためキャッシュをバイパスすべきです（SHOULD）。

**ブランド-オペレーター認可 Protocol の SDK 命名。** ブランド-オペレーターチェック向けの型付き Protocol を（アダプターが独自のリゾルバーを差し込めるよう）公開する SDK は、参照するファイルにちなんで名前を付けるべきです（SHOULD）: `BrandAuthorizationResolver`（または各言語の慣用的なケーシングでの同等物）。ファイルは `brand.json/authorized_operators` — ブランドを代表してよい人のブランド側の宣言です。SDK はこの Protocol を `adagents.json` にちなんで命名すべきではありません（SHOULD NOT）。`adagents.json` はパブリッシャー側 / データプロバイダー側であり、別の関係（どの sales agent がそのパブリッシャーのインベントリを販売してよいか）をモデル化します。バイヤー側のリゾルバーを `AdagentsResolver` と命名すると 2 つの面が混同され、アダプターが誤ったメンタルモデルに固定されます。これはスペック側の推奨です。SDK の慣習は上流に追随します。

**エージェントの商業状態はオフラインです。** バイヤーエージェントが*パススルー専用*（支払い関係なし — オペレーターのみが請求され得る）か*エージェント請求可能*（エージェントが直接請求され得る）かは、オペレーターアカウント作成と同じように、セラーのオンボーディングシステムに記録されます。そのレコードのプロビジョニング — 契約、KYC、支払条件、請求エンティティのキャプチャ — は AdCP のスコープ外です。スコープ内なのはワイヤー上の 2 つの帰結です:

1. **ランタイム請求ゲート。** `billing: "agent"` または `billing: "advertiser"` を送信するパススルー専用エージェントは、`BILLING_NOT_PERMITTED_FOR_AGENT` と `operator` の `error.details.suggested_billing` で拒否されます。リカバリー契約は [Billing and Account Setup](/docs/building/by-layer/L3/error-handling#billing-and-account-setup) を参照してください。
2. **エージェントごとのデフォルト。** セラーは、そのエージェントの下で新しいアカウントをプロビジョニングする際、バイヤーエージェントのオンボーディングレコードから `payment_terms`、`billing_entity`、レートカードの紐付け、信用限度を事前入力してもよい（MAY）。`sync_accounts` リクエストのアカウントごとの値は常にエージェントごとのデフォルトより優先されます — バイヤーは行ごとにオーバーライドできます。エージェントごとのレイヤーは推奨される実装パターンです（SSP が OpenRTB DSP 向けに `buyer_id` / `seat_id` 行を維持する方法をミラーします）。小規模パブリッシャーは、エージェントごとの条件を区別する債権業務を持つまで、セラー全体のデフォルトに折りたたんでもよい（MAY）。

## アカウント参照

すべてのアカウントスコープの操作は、フラットな `account_id` 文字列の代わりに `account` オブジェクトを受け入れる。セラーの `require_operator_auth` ケイパビリティが認証モデルと参照の形状を決定します。ツールの公開が、上流管理の `account_id` 名前空間と、アウトオブバンドで供給されるセラー定義の ID を区別します。

<Note>
  呼び出し元スコープのイントロスペクションをサポートするセラーは、[`sync_accounts`](/docs/accounts/tasks/sync_accounts) と [`list_accounts`](/docs/accounts/tasks/list_accounts) のレスポンスの各アカウントエントリに、任意の `authorization` オブジェクトを付加します — この呼び出し元がそのアカウントで使用を許可されているタスクとリクエストフィールド、および標準的な名前付きスコープ（例: `attestation_verifier`）をリストします。完全な形状とセマンティクスは [Caller authorization](/docs/accounts/overview#caller-authorization) を参照してください。
</Note>

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

アカウントは AdCP の外部で管理されます。広告主はセラーのプラットフォーム上でアカウントを作成し、オペレーターにそれを管理する権限を付与し、バイヤーはセラーが割り当てた `account_id` を渡します。エージェントはアカウント作成や請求セットアップには関与しない — それらは広告主、オペレーター、セラーの間で直接処理されます。

**典型的なセラー:** ソーシャルプラットフォーム、セルフサービス広告プラットフォーム — 広告主がすでにアカウントを持っているどこでも。

**上流管理のワークフロー:**

1. 広告主がセラーのプラットフォームにアカウントを作成（アウトオブバンド）
2. 広告主がオペレーターにアカウントを管理する権限を付与（アウトオブバンド）
3. エージェントが `list_accounts` を呼び出して利用可能なアカウントを発見
4. 人間がリストから正しいアカウントを選択
5. エージェントがすべてのリクエスト（`get_products`、`create_media_buy` など）で `{ "account_id": "acc_acme_001" }` を渡します

`list_accounts` は、上流が名前空間を所有するため、認証済みクレデンシャルが複数のアカウントにアクセスし得る場合は必須です。クレデンシャルが正確に 1 つのアカウントに束縛される場合でも、SDK が自動選択して必須アカウント呼び出しで明示的な `{ "account_id": "..." }` を送れるよう、セラーはそのシングルトンを返す `list_accounts` を公開すべきです（SHOULD）。`sync_accounts` プロビジョニングは、将来の明示的なケイパビリティが宣言しない限り、3.0.x のアカウント ID 名前空間ではスコープ外です。今日 `sync_accounts` が公開されている場合、それは既存の `account_id` に対する設定更新モードです。

**セラー定義のワークフロー:**

一部のセラーは、アカウント発見面を公開せずに `account_id` を使用します。そのパターンでは、セラーはオンボーディングまたは設定時にバイヤーにアカウント ID を渡し、バイヤーはアカウントスコープ呼び出しでその ID を渡します。`list_accounts` の不在は、発見すべきプロトコル名前空間がないことを意味します。バイヤーが自然キーでプロビジョニングを試みるべきことを意味しません。

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

エージェントが購入関係を管理します。`sync_accounts` を呼び出して誰が広告するか、誰がブランドの代わりに操作するか、誰が支払うかをセラーに伝える。セラーはアカウントをプロビジョニングしてステータスで応答する — アカウント ID は宣言の副産物であり、バイヤーが事前に知る必要があるものではありません。

**典型的なセラー:** 従来のパブリッシャー、リテールメディアネットワーク、DSP — 購入関係がプログラム的に確立されるどこでも。

`sync_accounts` は宣言ツールです。各エントリはセラーにバイヤーが必要とするものを伝えるフラグのセットだ:

| フラグ                                   | セラーに伝えること                                                                                                                          |
| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `brand`（`domain` + オプションの `brand_id`） | どのブランドが広告するか                                                                                                                       |
| `operator`                            | 誰がブランドの代わりに操作するか（エージェンシー、トレーディングデスク、またはブランド自身）                                                                                     |
| `billing`                             | 誰が請求書を受け取るか — `operator`、`agent`、または `advertiser`                                                                                  |
| `billing_entity`                      | 支払責任を負う当事者の構造化されたビジネスエンティティ詳細 — 法人名、VAT ID、税務 ID、住所、連絡先、銀行詳細。正式な B2B インボイスに使用。銀行詳細は書き込み専用（レスポンスでエコーされない）。                          |
| `payment_terms`                       | このアカウントの支払条件（`net_15`、`net_30`、`net_45`、`net_60`、`net_90`、`prepay`）。セラーはこれらの条件を受け入れるかアカウントを拒否しなければなりません — 条件はサイレントに再マッピングされることはない。 |
| `sandbox`                             | これがサンドボックス（テスト）アカウントかどうか — 実際の支出なし。バイヤー宣言アカウントのみで使用。アカウント ID 名前空間のサンドボックスは既存のもので、`list_accounts` を通じて発見されるかアウトオブバンドで供給されます。        |

セラーに異なることをさせる可能性があるフラグのすべての組み合わせ — 異なるエンティティへの請求、異なるレートカードのセットアップ、サンドボックスの作成 — は別々の宣言です。

### 請求エンティティとインボイス受取人

構造化されたインボイスデータを必要とする市場（例: VAT ID を要求する EU B2B トランザクション）では、アカウントの `billing_entity` が、`billing` が指す相手のデフォルトのビジネスエンティティ詳細を提供します。これには法人名、税務識別子、郵送先住所、請求連絡先、銀行詳細が含まれます。

個々のメディアバイでは、`invoice_recipient` がアカウントのデフォルトをオーバーライドできます — 特定のキャンペーンを別の当事者に請求すべき場合に便利です。`invoice_recipient` がアカウントのデフォルトと異なり、かつアカウントに `governance_agents` がある場合、セラーはガバナンスエージェントが請求リダイレクトを承認または拒否できるよう、それを `check_governance` リクエストに含めなければなりません（MUST）。

**ワークフロー:**

1. エージェントが1つ以上の宣言で `sync_accounts` を呼び出す
2. セラーがそれぞれのアカウントをプロビジョニングまたはリンクし、ステータスで応答:
   * `active` — 使用準備完了
   * `pending_approval` — セラーがレビュー中（人間が `setup.url` を訪れる必要があるかもしれない）
   * `rejected` — セラーがリクエストを拒否
3. 後続リクエストでアカウント参照を渡す:
   * **バイヤー宣言アカウント**（`require_operator_auth: false`）: 自然キー `{ "brand": { "domain": "acme-corp.com" }, "operator": "pinnacle-media.com" }` を渡します
   * **アカウント ID 名前空間**（`require_operator_auth: true`）: `{ "account_id": "acc_acme_001" }` を渡す（上流管理の名前空間では `list_accounts` を通じて発見、セラー定義の名前空間ではアウトオブバンドで受領）
   * **サンドボックス（バイヤー宣言）**: `sandbox: true` を含む自然キーを渡す（`sync_accounts` を通じて宣言）
   * **サンドボックス（アカウント ID 名前空間）**: `{ "account_id": "test_acc_001" }` を渡す（既存のテストアカウント、`list_accounts` を通じて発見またはアウトオブバンドで供給）
4. 何かが変わった場合（請求モデル、新しいブランド、新しいオペレーター）、再度 `sync_accounts` を呼び出す

`billing` が `"agent"` の場合、エージェントは請求に直接責任を負うことがある。`billing` が `"operator"` または `"advertiser"` の場合、エージェントは仲介するが請求される当事者ではありません。セラーはアカウントをアクティブにする前に人間の承認を必要とすることがあります。

### 自然キーセマンティクス

タプル `(brand, operator, sandbox)` はアカウント関係を一意に識別します。`brand` は `domain` とオプションの `brand_id` を持つネストされたオブジェクトです。`operator` は常に必要 — ブランドが直接操作する場合は `operator` をブランドのドメインに設定します。`sandbox` は省略時のデフォルトは `false`。例えば、`{brand: {domain: "acme-corp.com"}, operator: "acme-corp.com"}`（ブランドが直接購入）は `{brand: {domain: "acme-corp.com"}, operator: "pinnacle-media.com"}`（エージェンシー経由のブランド）とは異なるアカウントです。`sandbox: true` を追加すると同じペアのサンドボックスアカウントを参照します。

完全なリクエスト/レスポンススキーマについては[sync\_accounts タスクリファレンス](/docs/accounts/tasks/sync_accounts)を参照。

### アカウントステータス

| ステータス              | 意味               | 次のステップ                                                        |
| ------------------ | ---------------- | ------------------------------------------------------------- |
| `active`           | 使用準備完了           | このアカウントで購入を配置                                                 |
| `pending_approval` | セラーがレビュー中        | 人間が `setup.url` を訪れる必要があるかもしれない。更新のため `list_accounts` をポーリング。 |
| `rejected`         | セラーがリクエストを拒否     | 拒否理由を確認し、調整して再同期するか、セラーに連絡                                    |
| `payment_required` | 信用限度に達した         | 資金を追加するか他のアカウントに支出をルーティング                                     |
| `suspended`        | アクティブだったが現在は一時停止 | セラーに連絡                                                        |
| `closed`           | アクティブだったが現在は終了   | —                                                             |

### アカウントスコープ

エージェントは自然キー — `(brand, operator)` でアカウントをリクエストします。セラーが割り当てる粒度を決定します。レスポンスの `account_scope` フィールドはセラーがリクエストをどのように解決したかをエージェントに伝える:

| スコープ             | 意味                                  | 例                                                                                            |
| ---------------- | ----------------------------------- | -------------------------------------------------------------------------------------------- |
| `operator`       | このオペレーター下のすべてのブランドに対して1つのアカウント      | エージェントが（Pinnacle Media, Acme）と（Pinnacle Media, Nova）を送信 — セラーは両方を Pinnacle Media アカウントにマッピング |
| `brand`          | オペレーターに関わらずこのブランドに対して1つのアカウント       | エージェントが（Acme, Pinnacle Media）と（Acme, Summit Agency）を送信 — セラーは両方を Acme アカウントにマッピング            |
| `operator_brand` | このオペレーター+ブランドペアに専用アカウント             | エージェントが（Pinnacle Media, Acme）を送信 — セラーが特定の Acme-via-Pinnacle アカウントを作成                        |
| `agent`          | ブランド別・オペレーター別の分割がないエージェントスコープのアカウント | エージェントがどんなブランドを送信しても — セラーがリクエストを継続的なエージェントスコープのアカウントにマップ                                    |

エージェントはスコープを選択しない — セラーが独自のアカウントポリシーに基づいて割り当てる。`(brand: {domain: "acme-corp.com"}, operator: "pinnacle-media.com")` をリクエストするエージェントは、セラーに応じてオペレータースコープ、ブランドスコープ、または専用の operator\_brand アカウントを受け取ることがあります。

複数の自然キーが同じスコープに解決する場合、`account_scope` がその理由を説明します。

バイヤー宣言アカウント（`require_operator_auth: false`）では、後続リクエストで自然キー（`brand` + `operator`）を使用する — サンドボックスアカウントには `sandbox: true` を追加します。セラーは内部ハンドルとして `sync_accounts` から `account_id` を返してもよいが、この方法でプロビジョニングされたすべてのアカウントについて自然キーの `AccountRef` を受け入れ続けなければなりません（MUST）。アカウント ID 名前空間（`require_operator_auth: true`）では、上流管理の名前空間では `list_accounts` を通じて、セラー定義の名前空間ではアウトオブバンドで、サンドボックスのテストアカウントを含めアカウント ID を取得します。

## エラーコード

| コード                      | 返されるタイミング                             | 解決策                              |
| ------------------------ | ------------------------------------- | -------------------------------- |
| `ACCOUNT_REQUIRED`       | 複数のアカウント; セラーがどれか判断できない               | アカウント参照に `account_id` を渡す        |
| `ACCOUNT_NOT_FOUND`      | `account_id` が存在しないかエージェントがアクセス権を持たない | アカウント参照を確認し、`sync_accounts` を再実行 |
| `ACCOUNT_SETUP_REQUIRED` | 自然キーが解決されたがアカウントのセットアップが必要            | URL/メッセージの `details.setup` を確認   |
| `ACCOUNT_AMBIGUOUS`      | 自然キーが複数のアカウントに解決する                    | `account_id` またはより具体的な自然キーを渡す    |
| `PAYMENT_REQUIRED`       | 信用限度に達したか資金が枯渇した                      | 資金を追加するか別のアカウントにルーティング           |
| `ACCOUNT_SUSPENDED`      | アカウントが正常な状態でない                        | セラーに連絡                           |
| `BRAND_REQUIRED`         | ブランド参照なしの請求可能な操作                      | リクエストに `brand` を含める              |

セラーが `ACCOUNT_REQUIRED` を返す場合、利用可能なアカウントを含める:

```json theme={null}
{
  "errors": [{
    "code": "ACCOUNT_REQUIRED",
    "message": "Multiple accounts available. Please specify account_id in the account reference.",
    "details": {
      "available_accounts": [
        { "account_id": "acc_acme_001", "name": "Acme Corp" },
        { "account_id": "acc_pinnacle", "name": "Pinnacle Media" }
      ]
    }
  }]
}
```

## 設計ノート

### sync\_accounts とセラーのレコードシステム

エージェントが `(brand: {domain: "acme-corp.com"}, operator: "pinnacle-media.com")` を宣言すると、セラーは独自のシステム — CRM、OMS、広告サーバー、または請求プラットフォーム — でレコードを検索または作成します。

`sync_accounts` はセラーのレコードシステムへのバイヤーサイドインターフェースです。セラーは:

* 自然キーを既存のアカウントにマッピングして `status: "active"` を返すことがあります
* 新しいレコードを作成して即座に返すことがある（`status: "active"`）
* 人間のレビューを保留するプレースホルダーを作成することがある（`status: "pending_approval"`）
* リクエストを完全に拒否することがある（`status: "rejected"`）

`list_accounts` はセラーがこのエージェントにマッピングしたすべてのレコードを返す — 保留中と拒否されたエントリを含みます。エージェントは `list_accounts` を使用して、アクティブなアカウントだけでなく、このセラーとのポートフォリオの完全な状態を確認します。

### アカウントとインサーションオーダー

アカウントは継続的な関係を表す — 誰が請求されるか、どのレートが適用されるか、どのくらいの信用が利用可能か。キャンペーンやインサーションオーダーではありません。

インサーションオーダーとキャンペーンフライトは `create_media_buy` を通じたメディアバイとしてモデル化されます。アカウントは*請求条件*を決定し、メディアバイは*何がいつ実行されるか*を決定します。単一のアカウントはそのライフタイムにわたって多くのメディアバイを持つことができます。

### オペレーターの取り消しとキャッシング

ブランドが `authorized_operators` からオペレーターを削除した場合、既存のアクティブなアカウントは自動的に非アクティブ化されない。取り消しは即時ではなく最終的なものだ — `ads.txt` の変更がサプライサイドで伝播する方法に似ています。

セラーは `brand.json` の標準 HTTP キャッシングヘッダーを尊重して定期的に再検証すべきです。合理的なキャッシュ TTL は 24 時間です。

### SMB のブランドアイデンティティ

`/.well-known/brand.json` を通じたドメインベースのアイデンティティはあらゆる規模の組織に機能する — どのウェブサーバーにでもホストできる静的な JSON ファイルです。

ドメインにファイルをホストできない組織の場合、`brand.json` の `authoritative_location` フィールドにより、ハウスドメインがホストされた場所にリダイレクトできる:

```json theme={null}
{
  "house": {
    "domain": "local-bakery.com"
  },
  "authoritative_location": "https://registry.agenticadvertising.org/brands/local-bakery.com"
}
```