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.

セラーアカウント上のカタログフィードを管理します。商品フィード、在庫データ、店舗所在地、オファリング、および業界垂直カタログ（ホテル、フライト、求人、車両、不動産、教育、目的地）を同期します。URL ベースのフィードのスケジュール再取得、インラインアイテムデータ、既存カタログのディスカバリーをサポートします。 レスポンス時間: 即時〜数日（小規模カタログは completed、プラットフォームレビューが必要な大規模フィードは submitted を返す） リクエストスキーマ: /schemas/latest/media-buy/sync-catalogs-request.json レスポンススキーマ: /schemas/latest/media-buy/sync-catalogs-response.json

​
呼び出し関係

バイヤーがセラーアカウントにカタログフィードをプッシュするために、セラーに対して sync_catalogs を呼び出す。セラーはアイテムを検証し、コンテンツポリシーチェックを実行し、アイテムごとの承認ステータスを返します。 このタスクはアカウント状態セットアップシーケンスにおいて、フォーマットディスカバリーとクリエイティブ提出の間に位置します：
  1. list_creative_formats — 各フォーマットの assets 配列にある catalog アセットタイプを確認し、同期すべきフィードを把握します
  2. sync_catalogs — 必要なフィードをアカウントにプッシュします
  3. sync_creatives — catalog_id で同期済みカタログを参照するクリエイティブを提出します
  4. 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"
    }
  ]
}

​
リクエストパラメータ

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

​
Catalog オブジェクト

catalogs 配列内の各カタログは Catalog オブジェクトです。主要フィールド：
フィールド型必須説明
catalog_idstringYesバイヤーの識別子。アップサートのために既存カタログとの照合に使用します。
typeCatalogTypeYesカタログタイプ: product, offering, inventory, store, promotion, hotel, flight, job, vehicle, real_estate, education, destination
urluriNo外部フィード URL。items と相互排他的。
feed_formatstringNoフィードフォーマット: google_merchant_center, facebook_catalog, shopify, linkedin_jobs, custom
update_frequencystringNo再取得スケジュール: realtime, hourly, daily, weekly
itemsobject[]Noインラインカタログデータ。url と相互排他的。
conversion_eventsEventType[]Noこのカタログ内のアイテムのコンバージョンを表すイベントタイプ

​
レスポンス

成功レスポンス — カタログごとの結果：
フィールド型説明
catalogsobject[]処理された各カタログの結果
catalogs[].catalog_idstringリクエストのカタログ ID
catalogs[].actionstringcreated, updated, unchanged, failed, deleted
catalogs[].platform_idstringプラットフォームが割り当てた ID
catalogs[].item_countinteger同期後の総アイテム数
catalogs[].items_approvedintegerプラットフォームが承認したアイテム数
catalogs[].items_pendingintegerレビュー待ちのアイテム数
catalogs[].items_rejectedinteger却下されたアイテム数
catalogs[].item_issuesobject[]アイテムごとの却下理由
catalogs[].next_fetch_atdatetime次回スケジュールされたフィード取得日時（URL ベースのカタログ）
エラーレスポンス — 操作が完全に失敗した場合：
フィールド型説明
errorsError[]操作レベルのエラー（認証失敗、サービス利用不可）
レスポンスは判別ユニオンを使用する — 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"
    }
  ]
}

​
ディスカバリーモード

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"
    }
  ]
}

​
エラーハンドリング

エラー説明解決策
CATALOG_NOT_FOUND参照された catalog_id が存在しない（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アカウントが最大カタログ数に達した未使用のカタログを削除するか、セラーに連絡する

​
ベストプラクティス

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

​
次のステップ

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