Skip to main content

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つのエンティティを区別する:
エンティティ問い識別方法
ブランド誰のプロダクトが広告されるか?ブランド参照: domain + オプションの brand_id（brand.json）
アカウント誰が請求されるか? どのレートが適用されるか?アカウント参照
オペレーター誰がブランドのために操作するか?ドメイン（例: pinnacle-media.com）
エージェントどのソフトウェアが購入を配置するか?認証済みセッション
ブランド — プロダクトまたはサービスが宣伝される広告主。brand 参照（domain + オプションの brand_id）で識別され、/.well-known/brand.json を通じて解決されます。シングルブランドの企業はドメインのみを使用する（brand_id なし）。 アカウント — バイヤーとセラーの間の請求関係。レートカード、支払条件、信用限度、請求書を受け取る人を決定します。すべての請求可能な操作にはアカウント参照が必要だ — セラーが割り当てた account_id（明示的アカウント）または自然キー（brand、operator）（暗黙的アカウント）。サンドボックスアカウントは同じモデルに従う — 明示的サンドボックスは account_id を使用し、暗黙的サンドボックスは sandbox: true を含む自然キーを使用します。 オペレーター — 購入を主導するエンティティ — エージェンシートレーディングデスク、ブランドの内部チーム、または広告主の代わりに行動する別のエンティティ。ドメインで識別され、brand.json の認可オペレーターを通じて検証可能です。 エージェント — 購入を配置してキャンペーンを管理するソフトウェア。セラーで認証し、複数のオペレーターとブランドのために操作することがあります。 完全な商業モデルについてはアカウントプロトコルの概要を、タスクリファレンスについてはsync_accountsを参照。

​
セラーが宣言するもの

セラーは get_adcp_capabilities の account セクションを設定します: 1. どの請求モデルをサポートするか?（supported_billing） バイヤーはすべての sync_accounts エントリで billing としてこれらの値の1つを渡す必要があります。セラーは受け入れるか拒否するかを決める。
請求請求される対象ユースケース
operatorオペレーター（エージェンシーまたはブランドが直接購入）オペレーターが自分の条件で購入
agentエージェントエージェントがブランド間で請求を統合
2. オペレーターレベルの認証を必要とするか?（require_operator_auth） この単一フィールドが認証モデルとアカウント参照方法の両方を決定する: false（デフォルト）の場合 — 暗黙的アカウント: セラーはエージェントを信頼します。エージェントは一度認証して sync_accounts を通じてアカウントを宣言します。後続のリクエストでは、バイヤーは自然キー（brand + operator）を渡し、セラーが内部で解決します。 true の場合 — 明示的アカウント: 各オペレーターはセラーと直接認証する必要があります。エージェントはオペレーターごとにクレデンシャルを取得する — セラーの authorization_endpoint を使った OAuth、またはアウトオブバンドの API キーで。バイヤーは list_accounts を通じてアカウントを発見し、セラーが割り当てた account_id を渡します。 サンドボックスの場合、パスはアカウントモデルに従う: 明示的アカウント（require_operator_auth: true）は list_accounts を通じて既存のテストアカウントを発見し、暗黙的アカウントは sandbox: true を含む sync_accounts を通じてサンドボックスを宣言して自然キーで参照します。 セラーは account_financials: true を宣言して get_account_financials を通じてアカウントレベルの財務データ（支出、信用、請求書）を公開することもできます。これはオペレーター請求アカウントにのみ適用されます。 ケイパビリティの例: 
{
  "account": {
    "require_operator_auth": false,
    "supported_billing": ["operator", "agent"]
  }
}
これら2つのフィールドは3つの一般的なパターンに組み合わさる。

​
セラーパターン

どのようなプラットフォームから購入するか? それがアカウントセットアップパターンを決定します。
プラットフォームタイプrequire_operator_authsupported_billing
ソーシャル / ウォールドガーデンtrue["operator"]
ダイレクトパブリッシャーfalse["operator"] または ["operator", "agent"]
DSP / プログラマティックfalse["agent"]

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

オペレーターはすでにプラットフォーム上にアカウントを持っている — 広告アカウント、ビジネスマネージャー、セルフサービスダッシュボード。エージェントはオペレーターのクレデンシャルを取得（OAuth または API キーで）して、オペレーターごとのセッションを開く。プラットフォームはオペレーターに直接請求します。 ケイパビリティ: 
{
  "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. sync_accounts を呼び出してこのオペレーターの各ブランドをセットアップ
  3. アカウントステータスが active になるのを待つ（pending_approval の場合は list_accounts をポーリング）
  4. オペレーターのセッションと account 参照を使って get_products / create_media_buy を呼び出す
sync_accounts リクエスト: 
{
  "accounts": [{
    "brand": { "domain": "nova-brands.com", "brand_id": "spark" },
    "operator": "pinnacle-media.com",
    "billing": "operator"
  }]
}
セラーは nova-brands.com/.well-known/brand.json を確認し、authorized_operators に Pinnacle Media を見つけてプロビジョニングを迅速化する: 
{
  "accounts": [{
    "brand": { "domain": "nova-brands.com", "brand_id": "spark" },
    "operator": "pinnacle-media.com",
    "action": "created",
    "status": "active",
    "billing": "operator",
    "account_scope": "operator_brand"
  }]
}
重要ポイント: エージェントのクレデンシャルではなく、オペレーターのクレデンシャルがそのセッションのすべての呼び出しを認可します。brand.json の検証はクレデンシャルに対して二次的です。

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

パブリッシャーはエージェントを信頼するが、オペレーターに直接請求します。エージェントは sync_accounts を通じてアカウントをセットアップする — オペレーターごとのログインは不要。アカウントはアクティブになる前に人間の承認（信用調査、法的合意）が必要なことがあります。 多くのパブリッシャーはエージェント請求も受け入れる（supported_billing: ["operator", "agent"]）。バイヤーはアカウントごとに選択する — ダイレクト関係のあるオペレーターは billing: "operator" を使用し、それ以外は billing: "agent" を使用します。セラーが特定のアカウントに対して要求された請求をサポートしない場合、リクエストを拒否し、エージェントは別のモデルで再送信します。 ケイパビリティ: 
{
  "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 リクエスト — ブランドが直接購入: 
{
  "accounts": [{
    "brand": { "domain": "acme-corp.com" },
    "operator": "acme-corp.com",
    "billing": "operator"
  }]
}
セラーはリクエストを認め、プロビジョニング前にセットアップが必要: 
{
  "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 は通常のパスです。すべてのバイヤーはセラーとダイレクト関係が必要です。 請求拒否 — オペレーター請求が利用不可: セラーは一般的にオペレーター請求をサポートするが、すべてのオペレーターに対してサポートしない場合があります。ここで、エージェントはダイレクト関係のないオペレーターに対してオペレーター請求をリクエストする: 
{
  "accounts": [{
    "brand": { "domain": "acme-corp.com" },
    "operator": "acme-corp.com",
    "billing": "operator"
  }]
}
セラーはこのオペレーターにダイレクト請求関係がないためリクエストを拒否: 
{
  "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 / プログラマティック

すべての請求はエージェントを通じて流れる。エージェントはプラットフォームとの継続的な関係を持ち、すべてのブランドとオペレーターにわたって請求を統合します。アカウントは即座に作成される — 人間の承認は不要です。 ケイパビリティ: 
{
  "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 リクエスト: 
{
  "accounts": [{
    "brand": { "domain": "nova-brands.com", "brand_id": "spark" },
    "operator": "pinnacle-media.com",
    "billing": "agent"
  }]
}
アカウントは即座にアクティブ: 
{
  "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 を処理する際にこれに対してオペレーターを検証すべきです。 
{
  "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 はブランドとその代わりに操作する人との間のインターフェースをモデル化します。内部のエージェンシー階層はモデル化しません。

​
アカウント参照

すべてのアカウントスコープの操作は、フラットな account_id 文字列の代わりに account オブジェクトを受け入れる。セラーの require_operator_auth ケイパビリティが適用されるモデルを決定し、そのモデルがバイヤーの統合パス全体を決定します。

​
明示的アカウント（require_operator_auth: true）

アカウントは AdCP の外部で管理されます。広告主はセラーのプラットフォーム上でアカウントを作成し、オペレーターにそれを管理する権限を付与し、エージェントは list_accounts を通じてアカウントを発見します。エージェントは認証や請求には関与しない — それらは広告主とセラーの間で直接処理されます。 典型的なセラー: ソーシャルプラットフォーム、セルフサービス広告プラットフォーム — 広告主がすでにアカウントを持っているどこでも。 ワークフロー:
  1. 広告主がセラーのプラットフォームにアカウントを作成（アウトオブバンド）
  2. 広告主がオペレーターにアカウントを管理する権限を付与（アウトオブバンド）
  3. エージェントが list_accounts を呼び出して利用可能なアカウントを発見
  4. 人間がリストから正しいアカウントを選択
  5. エージェントがすべてのリクエスト（get_products、create_media_buy など）で { "account_id": "acc_acme_001" } を渡します
エージェントはアカウントをセットアップしたり、請求を交渉したり、セラーとの認証を管理したりしません。既存のものを発見して人間が選択できるようにするだけです。

​
暗黙的アカウント（require_operator_auth: false）

エージェントが購入関係を管理します。sync_accounts を呼び出して誰が広告するか、誰がブランドの代わりに操作するか、誰が支払うかをセラーに伝える。セラーはアカウントをプロビジョニングしてステータスで応答する — アカウント ID は宣言の副産物であり、バイヤーが事前に知る必要があるものではありません。 典型的なセラー: 従来のパブリッシャー、リテールメディアネットワーク、DSP — 購入関係がプログラム的に確立されるどこでも。 sync_accounts は宣言ツールです。各エントリはセラーにバイヤーが必要とするものを伝えるフラグのセットだ:
フラグセラーに伝えること
brand（domain + オプションの brand_id）どのブランドが広告するか
operator誰がブランドの代わりに操作するか（エージェンシー、トレーディングデスク、またはブランド自身）
billing誰が請求書を受け取るか — operator または agent
payment_termsこのアカウントの支払条件（net_15、net_30、net_45、net_60、net_90、prepay）。セラーはこれらの条件を受け入れるかアカウントを拒否しなければなりません — 条件はサイレントに再マッピングされることはない。
sandboxこれがサンドボックス（テスト）アカウントかどうか — 実際の支出なし。暗黙的アカウントのみで使用。明示的なサンドボックスアカウントは既存のものを使います。
セラーに異なることをさせる可能性があるフラグのすべての組み合わせ — 異なるエンティティへの請求、異なるレートカードのセットアップ、サンドボックスの作成 — は別々の宣言です。 ワークフロー:
  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" } を渡します
    • 明示的アカウント（require_operator_auth: true）: { "account_id": "acc_acme_001" } を渡す（list_accounts を通じて発見）
    • サンドボックス（暗黙的）: sandbox: true を含む自然キーを渡す（sync_accounts を通じて宣言）
    • サンドボックス（明示的）: { "account_id": "test_acc_001" } を渡す（既存のテストアカウント、list_accounts を通じて発見）
  4. 何かが変わった場合（請求モデル、新しいブランド、新しいオペレーター）、再度 sync_accounts を呼び出す
エージェントは請求に関与することがある（billing が "agent" または "operator" の場合）。セラーはアカウントをアクティブにする前に人間の承認を必要とすることがあります。

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

タプル (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 タスクリファレンスを参照。

​
アカウントステータス

ステータス意味次のステップ
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 がその理由を説明します。 sync_accounts は account_id を返さない — セラーがアカウント識別子を内部で管理します。明示的アカウント（require_operator_auth: true）では、サンドボックスのテストアカウントを含め、list_accounts を通じてアカウント ID を発見します。暗黙的アカウント（require_operator_auth: false）では、後続リクエストで自然キー（brand + operator）を使用する — サンドボックスアカウントには sandbox: true を追加します。

​
エラーコード

コード返されるタイミング解決策
ACCOUNT_REQUIRED複数のアカウント; セラーがどれか判断できないアカウント参照に account_id を渡す
ACCOUNT_NOT_FOUNDaccount_id が存在しないかエージェントがアクセス権を持たないアカウント参照を確認し、sync_accounts を再実行
ACCOUNT_SETUP_REQUIRED自然キーが解決されたがアカウントのセットアップが必要URL/メッセージの details.setup を確認
ACCOUNT_AMBIGUOUS自然キーが複数のアカウントに解決するaccount_id またはより具体的な自然キーを渡す
PAYMENT_REQUIRED信用限度に達したか資金が枯渇した資金を追加するか別のアカウントにルーティング
ACCOUNT_SUSPENDEDアカウントが正常な状態でないセラーに連絡
BRAND_REQUIREDブランド参照なしの請求可能な操作リクエストに brand を含める
セラーが ACCOUNT_REQUIRED を返す場合、利用可能なアカウントを含める: 
{
  "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 フィールドにより、ハウスドメインがホストされた場所にリダイレクトできる: 
{
  "house": {
    "domain": "local-bakery.com"
  },
  "authoritative_location": "https://registry.agenticadvertising.org/brands/local-bakery.com"
}