AdCP — sync_catalogs

セラーアカウント上のカタログフィードを管理します。商品フィード、在庫データ、店舗所在地、オファリング、および業界垂直カタログ（ホテル、フライト、求人、車両、不動産、教育、目的地）を同期します。URL ベースのフィードのスケジュール再取得、インラインアイテムデータ、既存カタログのディスカバリーをサポートします。 用語について。 sync_catalogs は、セラーが広告のレンダリングやターゲティングに使う、バイヤー提供のデータフィードを管理します。これは、get_products buying_mode: "wholesale" が公開するセラー側のホールセール商品フィードや、get_signals discovery_mode: "wholesale" が公開するホールセールシグナルフィードとは別物です。Webhook はそれらセラー側フィードの変更をプッシュするレイヤーです。 レスポンス時間: 即時〜数日（小規模カタログは completed、プラットフォームレビューが必要な大規模フィードは submitted を返す） リクエストスキーマ: /schemas/v3/media-buy/sync-catalogs-request.json レスポンススキーマ: /schemas/v3/media-buy/sync-catalogs-response.json

呼び出し関係

バイヤーがセラーアカウントにカタログフィードをプッシュするために、セラーに対して sync_catalogs を呼び出す。セラーはアイテムを検証し、コンテンツポリシーチェックを実行し、アイテムごとの承認ステータスを返します。このタスクはアカウント状態セットアップシーケンスにおいて、フォーマットディスカバリーとクリエイティブ提出の間に位置します：

list_creative_formats — 各フォーマットの assets 配列にある catalog アセットタイプを確認し、同期すべきフィードを把握します
sync_catalogs — 必要なフィードをアカウントにプッシュします
sync_creatives — catalog_id で同期済みカタログを参照するクリエイティブを提出します
create_media_buy — キャンペーンを開始します

クイックスタート

商品フィードを同期します：

{
  "account": { "account_id": "acct_acmecorp" },
  "catalogs": [
    {
      "catalog_id": "product-feed",
      "name": "Acme Product Catalog",
      "type": "product",
      "url": "https://feeds.acmecorp.com/products.xml",
      "feed_format": "google_merchant_center",
      "update_frequency": "daily"
    }
  ]
}

リクエストパラメータ

パラメータ	型	必須	説明
`account`	account-ref	条件付き	アカウント参照。`{ "account_id": "..." }` または、セラーが暗黙的な解決をサポートしている場合は `{ "brand": {...}, "operator": "..." }` を渡します。エージェントが複数のアカウントを持つ場合は必須。
`catalogs`	Catalog[]	No	同期するカタログフィード（最大 50 件）。ディスカバリーモードでは省略します。
`catalog_ids`	string[]	No	同期スコープを特定のカタログ ID に限定します。アカウント上の他のカタログは影響を受けない。
`delete_missing`	boolean	No	true の場合、この同期に含まれないバイヤー管理カタログを削除します。セラー管理カタログには影響しません。`catalogs` の存在が必要。デフォルト: false。
`dry_run`	boolean	No	変更を適用せずにプレビューします。デフォルト: false。
`validation_mode`	string	No	`"strict"`（デフォルト）はエラーが発生した場合に同期全体を失敗させる。`"lenient"` は有効なカタログを処理してエラーを報告します。
`push_notification_config`	object	No	非同期完了通知のための Webhook 設定。

Catalog オブジェクト

catalogs 配列内の各カタログは Catalog オブジェクトです。主要フィールド：

フィールド	型	必須	説明
`catalog_id`	string	Yes	バイヤーの識別子。アップサートのために既存カタログとの照合に使用します。
`type`	CatalogType	Yes	カタログタイプ: `product`, `offering`, `inventory`, `store`, `promotion`, `hotel`, `flight`, `job`, `vehicle`, `real_estate`, `education`, `destination`
`url`	uri	No	外部フィード URL。`items` と相互排他的。
`feed_format`	string	No	フィードフォーマット: `google_merchant_center`, `facebook_catalog`, `shopify`, `linkedin_jobs`, `custom`
`update_frequency`	string	No	再取得スケジュール: `realtime`, `hourly`, `daily`, `weekly`
`items`	object[]	No	インラインカタログデータ。`url` と相互排他的。
`conversion_events`	EventType[]	No	このカタログ内のアイテムのコンバージョンを表すイベントタイプ

レスポンス

成功レスポンス — カタログごとの結果：

フィールド	型	説明
`catalogs`	object[]	処理された各カタログの結果
`catalogs[].catalog_id`	string	リクエストのカタログ ID
`catalogs[].action`	string	`created`, `updated`, `unchanged`, `failed`, `deleted`
`catalogs[].platform_id`	string	プラットフォームが割り当てた ID
`catalogs[].item_count`	integer	同期後の総アイテム数
`catalogs[].items_approved`	integer	プラットフォームが承認したアイテム数
`catalogs[].items_pending`	integer	レビュー待ちのアイテム数
`catalogs[].items_rejected`	integer	却下されたアイテム数
`catalogs[].item_issues`	object[]	アイテムごとの却下理由
`catalogs[].next_fetch_at`	datetime	次回スケジュールされたフィード取得日時（URL ベースのカタログ）

エラーレスポンス — 操作が完全に失敗した場合：

フィールド	型	説明
`errors`	Error[]	操作レベルのエラー（認証失敗、サービス利用不可）

レスポンスは判別ユニオンを使用する — catalogs または errors のいずれかが返され、両方が同時に返されることはない。

アイテムレベルレビューのレスポンス例

{
  "catalogs": [
    {
      "catalog_id": "product-feed",
      "action": "created",
      "platform_id": "plat_cat_001",
      "item_count": 1250,
      "items_approved": 1180,
      "items_pending": 45,
      "items_rejected": 25,
      "item_issues": [
        {
          "item_id": "SKU-789",
          "status": "rejected",
          "reasons": ["Missing required field: image_url"]
        }
      ],
      "next_fetch_at": "2025-03-01T06:00:00Z"
    }
  ]
}

アイテムレビューのライフサイクル

カタログアイテムはシンプルなレビューサイクルをたどります: アイテムは同期時に pending に入り、プラットフォームが非同期にレビューします。アイテムは approved、（理由付きの）rejected、または warning 付きの approved（配信されるが修正可能な問題あり）のいずれかになります。却下は最終的なものではありません——ソースカタログで問題を修正して再同期します。アイテムを再同期すると、再レビューのために pending にリセットされます。レスポンスの item_issues 配列がアイテムごとの却下理由を示します。

ディスカバリーモード

catalogs を省略することで、アカウント上のすべてのカタログを変更なしで一覧表示できます：

{
  "account": { "account_id": "acct_acmecorp" }
}

セラーが他のソースからブランドデータをすでに持っている場合があるため、これは重要である — 小売業者はコマースプラットフォームからブランドの商品カタログをすでに持っているかもしれない。ディスカバリーにより、バイヤーはすべてを再アップロードするのではなく、既存の状態を活用できます。

非同期承認ワークフロー

大規模なフィードやコンテンツポリシーレビューが必要なフィードは、task_id とともに status: "submitted" を返します。セラーは非同期でアイテムをレビューし、完了したら Webhook でバイヤーに通知します。非同期レスポンスの状態：

working — プラットフォームがフィードを処理中（URL の取得、アイテムの検証）
input-required — プラットフォームがバイヤーのアクションを必要としている（バリデーションエラーの修正、不足フィールドの提供）
submitted — レビュー完了、最終的なカタログごとの結果が利用可能

状態遷移の Webhook 通知を受け取るには、リクエストに push_notification_config を設定します。

一般的なシナリオ

リテールメディア（product + inventory + store）

{
  "account": { "account_id": "acct_acmecorp" },
  "catalogs": [
    {
      "catalog_id": "product-feed",
      "type": "product",
      "url": "https://feeds.acmecorp.com/products.xml",
      "feed_format": "google_merchant_center",
      "update_frequency": "daily"
    },
    {
      "catalog_id": "inventory-feed",
      "type": "inventory",
      "url": "https://feeds.acmecorp.com/inventory.json",
      "feed_format": "custom",
      "update_frequency": "hourly"
    },
    {
      "catalog_id": "store-locations",
      "type": "store",
      "url": "https://feeds.acmecorp.com/stores.json",
      "feed_format": "custom",
      "update_frequency": "weekly"
    }
  ]
}

採用（インライン求人オファリング）

{
  "account": { "account_id": "acct_restaurants" },
  "catalogs": [
    {
      "catalog_id": "chef-vacancies",
      "type": "offering",
      "items": [
        {
          "offering_id": "chef-amsterdam-42",
          "name": "Head Chef - Amsterdam",
          "landing_url": "https://jobs.acme-restaurants.com/chef-amsterdam-42",
          "geo_targets": {
            "countries": ["NL"],
            "regions": ["NL-NH"]
          }
        }
      ]
    }
  ]
}

ドライランバリデーション

{
  "account": { "account_id": "acct_acmecorp" },
  "dry_run": true,
  "catalogs": [
    {
      "catalog_id": "product-feed",
      "type": "product",
      "url": "https://feeds.acmecorp.com/products.xml",
      "feed_format": "google_merchant_center"
    }
  ]
}

エラーハンドリング

エラー	説明	解決策
`REFERENCE_NOT_FOUND`	参照された `catalog_id` が存在しないかアクセスできない（`catalog_ids` フィルター使用時。`error.field` = `catalog_ids`）	以前の同期またはディスカバリー呼び出しからカタログ ID を確認する
`FEED_FETCH_FAILED`	プラットフォームがフィード URL を取得できなかった	URL のアクセス可能性、認証、フィードフォーマットを確認する
`INVALID_FEED_FORMAT`	フィードが宣言された `feed_format` と一致しない	フィードの内容がフォーマットと一致しているか確認する（google_merchant_center の場合は XML など）
`ITEM_VALIDATION_FAILED`	アイテムがスキーマバリデーションに失敗した	アイテムごとの却下理由を `item_issues` で確認する
`CATALOG_LIMIT_EXCEEDED`	アカウントが最大カタログ数に達した	未使用のカタログを削除するか、セラーに連絡する

ベストプラクティス

フォーマット要件を最初に確認する — 同期前に list_creative_formats を呼び出し、各フォーマットの assets 配列にある catalog アセットタイプを確認します。これにより、同期すべきカタログタイプと各アイテムに必要なフィールドがわかる。
ディスカバリーモードを使用する — 同期前に catalogs なしで呼び出し、セラーがすでに持っているものを確認します。セラーが他のソースからブランドデータを持っている可能性があります。
update_frequency を設定する — URL ベースのフィードでは、プラットフォームが再取得頻度を把握できるよう、常に update_frequency を設定します。フィードが古くなると、在庫切れ商品の広告が表示されることになります。
conversion_events を宣言する — どのイベントタイプがカタログアイテムのコンバージョンを表すかを宣言して、カタログをコンバージョントラッキングシステムに接続します。
大規模フィードには dry_run を使用する — 特に数千のアイテムを含む初回同期では、コミット前にバリデーションを行います。
アイテムレベルの失敗を処理する — lenient モードでは、一部のアイテムが失敗しても有効なアイテムは処理されます。却下されたアイテムを修正するには、レスポンスの item_issues を確認します。

次のステップ

Catalogs — カタログタイプ、ソーシング、フォーマット要件に関する完全なドキュメント
アカウント状態 — アカウントセットアップシーケンスにおけるカタログの位置づけ
sync_creatives — 同期済みカタログを参照するクリエイティブの提出
list_creative_formats — フォーマットのカタログ要件のディスカバリー

はじめに

AdCP で構築する

プロトコル

FAQ

トラストとセキュリティ

リファレンス

AAO

認定

sync_catalogs

呼び出し関係

クイックスタート

リクエストパラメータ

Catalog オブジェクト

レスポンス

アイテムレベルレビューのレスポンス例

アイテムレビューのライフサイクル

ディスカバリーモード

非同期承認ワークフロー

一般的なシナリオ

リテールメディア（product + inventory + store）

採用（インライン求人オファリング）

ドライランバリデーション

エラーハンドリング

ベストプラクティス

次のステップ

​呼び出し関係

​クイックスタート

​リクエストパラメータ

​Catalog オブジェクト

​レスポンス

​アイテムレベルレビューのレスポンス例

​アイテムレビューのライフサイクル

​ディスカバリーモード

​非同期承認ワークフロー

​一般的なシナリオ

​リテールメディア（product + inventory + store）

​採用（インライン求人オファリング）

​ドライランバリデーション

​エラーハンドリング

​ベストプラクティス

​次のステップ

呼び出し関係

クイックスタート

リクエストパラメータ

Catalog オブジェクト

レスポンス

アイテムレベルレビューのレスポンス例

アイテムレビューのライフサイクル

ディスカバリーモード

非同期承認ワークフロー

一般的なシナリオ

リテールメディア（product + inventory + store）

採用（インライン求人オファリング）

ドライランバリデーション

エラーハンドリング

ベストプラクティス

次のステップ