channel3-api

Channel3 API 統合ガイド

Channel3 は汎用の商品カタログ API です。開発者の入力に合ったエンドポイントを選択してください。

開発者が持っているもの…	使用するもの
フリーテキストのクエリ、画像 URL、またはその両方	POST /v1/search
自然言語で詳しく記述された依頼（エンドユーザーのメッセージ、エージェントのコンテキスト）	config.mode: "agentic" を指定した POST /v1/search — 検索モードの選択を参照
構築する React ストアフロント UI（グリッド、フィルター、PDP、バリエーション）	Channel3 UI shadcn レジストリ — 型付きコンポーネントを使用し、独自実装は避けてください
Channel3 の product_id があり、類似商品を探したい	POST /v1/similar
Channel3 の product_id があり、詳細情報をすべて取得したい	GET /v1/products/{id}
product_id とバリエーションの選択肢（色／サイズなど）があり、一致するオファーを取得したい	selected_options（SDK）／option_<name>=<label> クエリパラメーター（HTTP）を指定した GET /v1/products/{id}
マーチャントの URL があり、正規の商品を取得したい	POST /v1/lookup
クエリはなく、フィルターだけを指定したい（ブランド／カテゴリ／ウェブサイトの商品をすべて取得）	POST /v1/browse
ショッピング用チャットインターフェース（ストリーミングエージェント）	POST /v1/conversations — references/conversations.mdを参照
クリック／トランザクションのアトリビューションデータ	GET /v1/reporting/clicks／GET /v1/reporting/transactions
product_id があり、価格／在庫状況／オファー変更のアラートを受け取りたい	POST /v1/product-subscriptions（ウェブフック）— 商品サブスクリプションを参照
product_id があり、価格履歴を取得したい	GET /v0/price-tracking/history/{id}
フリーテキストの語句があり、一致するカテゴリスラッグを取得したい	GET /v1/categories/search
色の条件（blue、navy、red など）	POST /v1/search または POST /v1/similar の filters.colors — 色名を sRGB の 16 進数に変換してください。filters.attributes.color は絶対に使用しないでください
色以外の構造化属性（素材、フレームの色など）	POST /v1/search または POST /v1/similar の filters.attributes — Category.attributes からハンドル／値を確認してください（color ハンドルは除外）

ベース URL： https://api.trychannel3.com
認証： x-api-key ヘッダー（サーバー側）。ブラウザクライアントでは有効期間の短いクライアントトークンを使用します。詳しくは references/conversations.mdを参照してください。
完全版ドキュメント： docs.trychannel3.com（SDK のセットアップ、エンドポイントごとのリファレンス、エラー処理、リトライ、非同期の使用方法）
オフライン用クイックリファレンス： references/api-reference.md · SDK 3.x からのアップグレード： references/sdk-4-upgrade.md

アンチパターン（先にお読みください）

• フリーテキストのクエリや画像に /v1/similar を使用しないでください。 Similar が受け取るのは Channel3 の product_id であり、クエリではありません。ユーザーが商品を説明している場合や画像を持っている場合は、/v1/search（query および／または image_url）を使用してください。
• タイトルによる /v1/search で済む場合は、/v1/similar の対象を指定するために /v1/lookup を使用しないでください。 Lookup は数秒かかり、カタログ未登録の URL では失敗することがあります。想定されている流れは search → product.id を取得 → similar です。必要に応じて lookup の後に similar を使うこともできますが、多くの場合、最適な流れではありません。
• ロケール（country／currency）によって返されるマーチャントのオファーが制限されます。 複数の地域を対象とするストアフロントでは、country を省略して currency: "EUR" のみを設定できます。デフォルトは en／US／USD です。
• フィルターはクエリへの条件の詰め込みより優先されますが、条件を省略するよりはクエリへの詰め込みが適切です。 価格、ブランド、カテゴリ、色、性別、状態、在庫状況、セール、寸法にはすべて構造化フィルターがあり、デフォルト／キーワードモードで結果を正確にする最適な方法です。フィルターで表現できない条件は、完全に省略するのではなく query に含めてください。列挙できない条件（美的な特徴の説明、モデル名、用途）に限って、query のみで指定してください。エージェント型モードでは逆に、コンテキスト全体を query に含めます。

クイックスタート

npm install @channel3/sdk           # TypeScript
pip install channel3-sdk            # Python

Go SDK も利用できます。docs.trychannel3.com/sdkをご覧ください。

環境変数にCHANNEL3_API_KEYを設定します（無料のキーはtrychannel3.comで取得できます）。その後、最小限のエンドツーエンド呼び出しを実行します。

import { Channel3 } from '@channel3/sdk';

const client = new Channel3({ apiKey: process.env.CHANNEL3_API_KEY });
const page = await client.products.search({ query: 'running shoes', limit: 5 });
const products = page.data;  // Product[]

from channel3_sdk import Channel3

client = Channel3(api_key="YOUR_API_KEY")
page = client.products.search(query="running shoes", limit=5)
products = page.items  # list[Product]

SDK 4.0 に関する注意事項：TypeScript では名前付きインポート（import { Channel3 }）、オブジェクト形式のリクエスト（client.products.retrieve({ product_id })）、およびワイヤ形式に合わせたスネークケースのリクエストフィールドを使用します。ページネーション対応の呼び出しはPageを返します。TS では.data、Python では.itemsを使用し、どちらも非同期イテレーターとして扱えます。SDK 3.x のコードを使用していますか？references/sdk-4-upgrade.mdをご覧ください。

ロケールのデフォルト値は、コンストラクター（new Channel3({ country: 'GB', currency: 'GBP' })）またはCHANNEL3_LANGUAGE／CHANNEL3_COUNTRY／CHANNEL3_CURRENCY環境変数でクライアント全体に設定できます。呼び出しごとのconfig.country／config.currency／config.languageが常に優先されます。非同期クライアント、エラークラス、リトライ、タイムアウト、ロギングについては、docs.trychannel3.com/sdkをご覧ください。

CLI（ターミナルとテスト）

ターミナルから一時的に API を確認する場合、たとえばフィルターの形式を検証したり、統合テストで使うproduct_idを取得したり、プロジェクトを介さずに単発の呼び出しを行ったりするには、Channel3 CLIを使用してください。API 仕様は自動的に追跡されます。

npm install -g @channel3/cli
export CHANNEL3_API_KEY="..."

channel3 products search --query-param "running shoes" --limit 5 \
  --filters '{"price":{"max_price":100},"gender":"male"}' \
  --format jsonl \
  --query 'products[].{id: id, title: title, offers: offers[].{domain: domain, price: price.price, url: url}}'

--query-paramは検索語です。--queryはレスポンスに対するJMESPathの 射影です。CLI のバージョン0.4.1以前では、検索語に --queryを使用していました。古いコマンドは更新が必要です。

本番コードでは SDK を使用してください。CLI はターミナルでの作業に使用します。

UI コンポーネント（React）

Channel3 UIは、shadcn registryとして配布されるオープンソース（MIT）の React コンポーネントライブラリです。@channel3/sdkに直接型付けされているため、検索や商品の取得で得たProductをそのまま渡せます。

npx shadcn@latest add https://ui.trychannel3.com/r/all.json

• ブロック — product-search（検索バー＋ファセットフィルター＋無限スクロールグリッド）とproduct-details（完全な PDP：ギャラリー、バリアント選択、オファー比較、価格履歴、おすすめ商品）。
• 個別利用 — コンポーネント（product-card、variant-selector、offers-list、image-gallery、…）とフック（useProductSearch、useVariantSelection、useProductRecommendations、…）。
• プレゼンテーションに特化した設計 — コンポーネントは Channel3 のデータをプロパティとして受け取り、コールバックを通じて操作要求を返します。API を呼び出したり、API キーにアクセスしたりすることはありません。データはサーバー（CHANNEL3_API_KEYが置かれる場所）で取得・整形し、その結果を渡してください。
• SDK のメジャーアップグレード時 — コンポーネントの型を手作業で修正するのではなく、レジストリから再インストール（add --overwrite）してください。references/sdk-4-upgrade.mdをご覧ください。
• 省略していない SDK のレスポンスオブジェクトを渡してください — たとえば、PriceHistoryResponseにはcanonical_product_idが必要です。JSON の境界を越えると、Dateフィールドは ISO 文字列として渡されます。境界で変換してください（z.coerce.date()）。

エンドポイント

検索 — POST /v1/search

テキスト、画像、またはテキストと画像による検索です。Productのページネーション対応Pageを返します。

const page = await client.products.search({
  query: 'running shoes under $100',
  filters: { price: { max_price: 100 }, gender: 'male' },
  limit: 10,
});
const products = page.data;

page = client.products.search(
    query="running shoes under $100",
    filters={"price": {"max_price": 100}, "gender": "male"},
    limit=10,
)
products = page.items

呼び出しごとのロケール上書き：config: { country: 'GB', currency: 'GBP' }。フィルターの完全な形式はreferences/api-reference.md、エンドポイントごとの完全なスキーマはdocs.trychannel3.com/api-referenceをご覧ください。

検索モードの選択

config.mode で設定します。

• default（字句＋セマンティック）— ほとんどすべての呼び出しに適しています。
• agentic — 自分で作成したものではない、情報量の多い自然言語の依頼に適しています。エンドユーザーのメッセージや、エージェントが蓄積したコンテキストを引き継ぐ場合などです。コンテキスト全体を query に入れ、フィルターを手動で組み立てる代わりに、LLM プランナーに構造化された複数の検索へ分解させます。数秒余分にかかります。このモードは Channel3 の MCP サーバーを支えているため、自分のエージェントループで MCP 相当の動作を実現できます。
• keyword — 字句検索のみで、レイテンシが最も低くなります。画像入力とは併用できません。限定的な用途（広告ターゲティング、リアルタイム検索など）向けで、通常の検索には適していません。

構造化属性フィルターとカラー フィルター

カラーの制約には filters.attributes ではなく、filters.colors を使用します。 カラー名（navy、blue、red、...）を sRGB の 16 進数に変換してください。filters.attributes はカラー以外のハンドル（material、frame-color、...）専用です。

const page = await client.products.search({
  query: 'leather sofa',
  filters: {
    category_ids: ['sofas'],
    attributes: { material: ['Leather'] },
    colors: {
      palette: [
        { hex: '#001f3f' }, // navy — use colors for any color intent
        { hex: '#ffffff', percentage: 0.3 },
      ],
    },
  },
  limit: 10,
});

• colors.palette — 商品がリストされたすべての色を含む必要があります（AND）。hex は sRGB（#rrggbb）です。percentage（0～1）は任意で、その色が商品画像に占める割合の最小値を指定します。
• attributes — Record<string, string[]> です。キーはカラー以外の属性ハンドル（例：material、frame-color）です。値は同じキー内では OR、キー間では AND で適用されます。カテゴリで有効なハンドルと値を確認するには、client.categories.retrieve({ slug }) → Category.attributes を使用します。ここに color ハンドルを渡してはいけません。代わりに filters.colors を使用してください。カテゴリフィルターも指定する場合、各属性キーはそのカテゴリの少なくとも 1 つで有効である必要があります。

属性ハンドルや値を推測しないでください。カラー以外の属性については、categories.retrieve が信頼できる情報源です。返される商品には、表示用に structured_attributes（例：{ color: ["Navy"], material: ["Leather"] }）が含まれます。カラーをフィルターするには filters.colors を使用し、structured_attributes.color を filters.attributes にコピーしてはいけません。

生の HTTP または SDK 以外の呼び出し元の場合：

curl -X POST https://api.trychannel3.com/v1/search \
  -H "x-api-key: $CHANNEL3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"running shoes","filters":{"price":{"max_price":100}},"limit":10}'

類似商品 — POST /v1/similar

すでに持っている Channel3 の product_id を使って「これに似た商品」を取得します。 ほとんどの場合、前回の /v1/search のレスポンスを起点にします。ページネーションの形式は同じで、元の商品は除外されます。

const search = await client.products.search({ query: 'red leather jacket', limit: 5 });
const seedId = search.data[0].id;

const similar = await client.products.findSimilar({
  product_id: seedId,
  filters: { gender: 'female', price: { max_price: 200 } },
  limit: 10,
});

search = client.products.search(query="red leather jacket", limit=5)
seed_id = search.items[0].id

similar = client.products.find_similar(
    product_id=seed_id,
    filters={"gender": "female", "price": {"max_price": 200}},
    limit=10,
)

性別、ブランド、カテゴリ、価格など、同じ範囲の商品に絞るため、フィルターの使用をおすすめします。「これに似た商品。ただしネイビーで」という場合は、filters.attributes.color ではなく filters.colors（例：{ hex: '#001f3f' }）を使用してください。カラー以外の属性には filters.attributes を使用します。商品がまだカタログにない場合は 404 が返されます。その場合は、タイトルで /v1/search を実行してください。

検索 — POST /v1/lookup

販売店の URL を正規の Channel3 Product に解決します。開発者が商品を特定する手段として URL しか持っていない場合（例：ユーザーが貼り付けたリンク）に限り使用してください。

const { product } = await client.products.lookup({
  url: 'https://merchant.com/products/red-jacket',
});

result = client.products.lookup(url="https://merchant.com/products/red-jacket")
product = result.product

レイテンシ：キャッシュされていない URL の場合は通常 2～10 秒（リアルタイム抽出）、キャッシュ済みの場合は 1 秒未満です。商品ページ以外（カテゴリ一覧、検索結果、ホームページ）の場合は 422、タイムアウト時は 504 が返されます。max_staleness_hours（デフォルトは 3）でキャッシュの鮮度を制限します。レスポンスには GET /v1/products/{id} と同じく、展開済みの variants と structured_attributes が含まれます。product.id を取得したら、client.products.retrieve() または client.products.findSimilar() で使用してください。

商品詳細 — GET /v1/products/{product_id}

既知の product_id に対応する完全な Product を取得します。レスポンスの形式は検索結果と同じですが、現在の選択内容に合わせて variants が完全に展開され、各オプション値の在庫状況とサムネイルも含まれます。この呼び出しは無料です。

const product = await client.products.retrieve({
  product_id: 'prod_abc123',
  country: 'GB',
  currency: 'GBP',
});

product = client.products.retrieve("prod_abc123", country="GB", currency="GBP")

ロケールは config（language、country、currency、length_unit、weight_unit）で指定します。販売店は filters.website_ids で絞り込めます（"nike.com" のようなドメインを指定できます）。指定したロケールで商品の販売店オファーがない場合は 404 が返されます。同じロケールで実行した /v1/search 呼び出しから product_id を取得するか、ロケールを省略してデフォルトにフォールバックしてください。

バリエーションと selected_options

バリエーションを持つ Product には、次の情報が含まれます。

• variants.options — 各属性（例：Color、Size）と、その values（label、exists、available、および色を別商品に切り替える設定で使用する任意の thumbnail_url と product_id）。
• variants.selected — このレスポンスで現在解決されている属性（[{ name: "Color", label: "Navy" }, ...]）。
• structured_attributes — 解決されたバリエーションから抽出された属性値（例：{ color: ["Navy"], material: ["Leather"] }）。

異なるバリエーション設定で商品を再取得するには、selected_options（SDK）または option_<DimensionName>=<Label> のクエリパラメーター（HTTP）を渡します。複数の属性を組み合わせられます。名前の大文字・小文字は維持され、商品ファミリーとの照合では大文字・小文字が区別されません。

const product = await client.products.retrieve({
  product_id: 'prod_abc123',
  selected_options: { Color: 'Blue', Size: 'XL' },
});

curl -X GET \
  "https://api.trychannel3.com/v1/products/prod_abc123?option_Color=Blue&option_Size=XL" \
  -H "x-api-key: $CHANNEL3_API_KEY"

サーバーは、解決された設定を反映するよう variants.selected を更新し、同じ Product 形式を返します。リクエストしたオプションと variants.selected の差分を確認して、サーバー側で条件が緩和されたかどうか（例：リクエストした色では、指定したサイズが利用できなかった場合）を検出してください。

バリエーションモデルの詳細（検索と詳細取得の違い、product_id による移動（色ごとに別商品）、および exists／available の UI 階層）については、references/variants.md を参照してください。React では、Channel3 UI の useVariantSelection フックが、この選択と再解決のループを実装します。

ブラウズ — POST /v1/browse

フィルターのみの商品一覧です。クエリや画像は不要です。ブランドページ、カテゴリーのページ、または小売店のコレクションの表示に使用します。brand_ids、category_ids、website_ids のうち、少なくとも 1 つが必須です（それ以外の場合は 422）。他のすべての SearchFilters フィールドも使用できます。検索と同じページネーション形式で返されます。

const page = await client.products.browse({
  filters: { brand_ids: ['MpZS'], sale: 'on_sale' },
  limit: 20,
});

page = client.products.browse(
    filters={"brand_ids": ["MpZS"], "sale": "on_sale"},
    limit=20,
)

会話 — POST /v1/conversations

ターン形式の会話型ショッピングです。開発者がユーザーメッセージを送信すると、Channel3 がエージェント（検索、比較、絞り込み）を実行し、返信をストリーミングで返します。ブラウザクライアントは、サーバーで発行する短期間有効な クライアントトークン で認証します。API キーがブラウザに送信されることはありません。

// Server: mint a token for the browser session
const { token, expires_at } = await client.conversations.clientTokens.create({
  ttl_seconds: 900,
});

// Browser: authenticate with the token via the `auth` option
const browserClient = new Channel3({
  auth: () => Promise.resolve({ headers: { Authorization: `Bearer ${token}` } }),
});
const stream = await browserClient.conversations.createTurnStream({
  message: { parts: [{ type: 'text', text: 'running shoes under $100' }] },
  conversation_id, // omit to start a new thread
});
for await (const event of stream) {
  if (event.type === 'part.delta') process.stdout.write(event.delta);
}

認証モデルの全体像、SSE イベントリファレンス、Python の例については、references/conversations.md を参照してください。

レポート — /v1/reporting/...

API キーのクリックと取引のアトリビューション情報です。リクエストに付与した user_id で絞り込めます（以下の ユーザーアトリビューション を参照）。

• GET /v1/reporting/clicks?start_date=&end_date= — オファーリンクのクリック
• GET /v1/reporting/transactions?start_date=&end_date= — アトリビューションされた売上

const clicks = await client.reporting.listClicks({
  start_date: new Date('2026-08-01T00:00:00Z'), // Date objects, not ISO strings
  end_date: new Date('2026-08-17T00:00:00Z'),
  user_id: 'user_123', // optional
});
clicks.data; // Click[]
clicks.response.summary; // aggregates, e.g. { total_clicks }

日付範囲は 1 回の呼び出しにつき最大 90 日です（デフォルト：直近 30 日）。レスポンスにはページネーションが適用されます（page／limit、最大 100）。フィールドのリファレンスについては、references/api-reference.md を参照してください。

商品サブスクリプション — /v1/product-subscriptions

商品のオファーに変更があったときに通知するWebhookです。価格、在庫状況、販売店でのオファーの追加や終了を通知します。ポーリングせずに、再入荷通知、セール検索、値下がり通知に利用できます。無料 — クレジットは消費されません。

現時点ではHTTPのみです — SDKとCLIは、まだ商品サブスクリプションに対応していません。

curl -X POST https://api.trychannel3.com/v1/product-subscriptions \
  -H "x-api-key: $CHANNEL3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "2yh8WH5",
    "events": ["offer.price.changed", "offer.availability.changed"],
    "domains": ["nike.com"]
  }'

• イベント（サブスクリプションごとに選択。最小1件）：offer.price.changed、offer.availability.changed、offer.created、offer.deleted。
• 対象範囲：domains（販売店のドメインを最大25件。省略するとすべてのオファーが対象）および／またはselection（1つのバリエーション設定を指定します。例：[{"name": "Size", "label": "L"}] — 商品のvariants.selectedと同じ形式です）。
• 冪等性のある作成 — 同一の有効なサブスクリプション（イベント、ドメイン、選択内容が同じ）がある場合、既存のサブスクリプションが返されます。/v1/lookupのproduct_idは自動的に正規化されます。lookupの処理中に作成を試みると409が返されるため、同じIDで再試行してください。
• 管理：GET /v1/product-subscriptions?status=&cursor=&limit= · GET /v1/product-subscriptions/{id} · DELETE /v1/product-subscriptions/{id}（削除が返された後、そのサブスクリプションのイベントは送信されません）。
• 配信：イベントは、アカウントのダッシュボードにあるWebhookポータル（Svix）で登録したWebhookエンドポイントにPOSTされます。エンドポイントはサブスクリプションごとではなく、アカウントごとに設定されます。一致するイベントタイプが有効になっているすべてのエンドポイントにイベントが届きます。svix-signatureヘッダー（HMAC-SHA256、Standard Webhooks形式、エンドポイントごとのwhsec_シークレット）を検証し、イベントのidで重複を排除してください。ペイロードのスキーマ、再試行、検証コードについては、docs.trychannel3.com/product-subscription-webhooksをご覧ください。
• 実行頻度：サブスクライブすると、商品の優先度の高い日次再スクレイピングがスケジュールされます。イベントは固定スケジュールではなく、更新によって変更が検出されたときに発生します。

価格トラッキング — /v0/price-tracking/...

価格トラッキングのサブスクリプションは、新規連携では非推奨です — 代わりに商品サブスクリプションを使用してください。移行するには、既存のトラッキングをキャンセルし（client.priceTracking.stop({ canonical_product_id })。現在のトラッキングはclient.priceTracking.listSubscriptions()で確認できます）、商品サブスクリプションを作成してください。

価格履歴は非推奨ではありません — 商品サブスクリプションに相当する機能はありません。

• client.priceTracking.retrieveHistory({ canonical_product_id, days }) — デフォルトは90日、最大90日です。current_price、min/max/mean/std_dev、current_status（low / typical / high）を返します。

const history = await client.priceTracking.retrieveHistory({
  canonical_product_id: 'prod_abc123',
  days: 90,
});
console.log(history.statistics?.current_price, history.statistics?.current_status);

ブランドとウェブサイト — /v1/brands*、/v1/websites*

検索フィルター用のIDを取得するために主に使用する検索ヘルパーです。

• client.brands.search({ query, limit? }) — ブランドを名前で検索します。関連度順に最大limit件を返します（デフォルト5件、最大20件）。
• client.brands.retrieve({ brand_id }) — IDで検索します。
• client.brands.list() — カーソルページネーションに対応したPageを返します。for awaitを使うと、awaitしたページを反復処理できます。最後まで反復すると、ブランドカタログ全体（数千のブランド、多数ページ分のAPI呼び出し）を処理します。必ず早めに中断するか、ブランドを1つだけ探す場合はclient.brands.searchを使用してください。
• client.websites.retrieve({ query: 'nike.com' }) — 販売店を名前またはドメインで検索します。
• client.websites.search({ query, category_ids? }) / client.websites.list({ category_ids? }) — 販売店を検索します。指定したカテゴリーの商品を販売する販売店だけに絞ることもできます（listは上位5,000件を処理するため、早めに中断してください）。

// Find a brand ID for filtering
const { brands } = await client.brands.search({ query: 'Nike', limit: 5 });
const brandId = brands[0]?.id;  // top match — inspect `brands` to disambiguate when multiple match

カテゴリ — /v1/categories*

SearchFilters.category_ids / exclude_category_ids に渡せるカテゴリのスラッグと、SearchFilters.attributes に渡せる属性のキー／値を確認できます。スラッグはURLに適した安定した識別子（例：shoes、sofas、handbags）で、内部IDよりも優先して使用してください。分類体系には、想定されるすべてのサブカテゴリに対応する末端カテゴリがあるわけではなく、未知のスラッグは通知なく除外されるため、推測せず、必ず client.categories.search で実際のスラッグを確認してください。

• client.categories.search({ query, limit? }) — フリーテキスト検索 → CategorySummary[]（limit は1～20、デフォルトは5）
• client.categories.list({ roots_only?, page?, page_size? }) — ページ分割で一覧表示。ルートカテゴリから表示します（page_size は1～100、デフォルトは20）
• client.categories.retrieve({ slug }) — 説明、属性、直接の子カテゴリ、ルートから自身までの path を含む完全な Category

const { categories } = await client.categories.search({ query: 'running shoes', limit: 5 });
const slug = categories[0].slug;

const page = await client.products.search({
  query: 'lightweight trainers',
  filters: { category_ids: [slug] },
});

result = client.categories.search(query="running shoes", limit=5)
slug = result.categories[0].slug

page = client.products.search(
    query="lightweight trainers",
    filters={"category_ids": [slug]},
)

exclude_category_ids は、指定したカテゴリとそのすべての子孫カテゴリを除外します。

Category.attributes には、SearchFilters.attributes で使えるインデックス済みの属性ハンドルが一覧表示されます。色以外のスラッグ（例：material、frame-color）を使用してください。color は商品に関する参考情報です。色で絞り込む場合は attributes.color ではなく、filters.colors を使用してください。

const category = await client.categories.retrieve({ slug: 'sofas' });
const materialAttr = category.attributes.find(a => a.slug === 'material');
//   materialAttr?.values → ["Leather", "Velvet", "Linen", ...]

const page = await client.products.search({
  query: 'leather sectional',
  filters: {
    category_ids: ['sofas'],
    attributes: { material: ['Leather'] },
    colors: { palette: [{ hex: '#001f3f' }] }, // navy via colors filter
  },
});

ユーザーの帰属情報

レポートでエンドユーザーのクリック数や売上を集計するには、すべてのリクエストにエンドユーザーのIDを渡してください。生のHTTPリクエストでは x-user-id ヘッダーを使用します。Python SDKでは user_id キーワード引数を使用します（ヘッダーにマッピングされます）。TypeScriptではリクエストオプションでヘッダーを渡してください。Channel3はレスポンス内の購入URLにこのIDを追加します。最大128文字で、使用できるのは英字、数字、.、_、@、- のみです。

await client.products.search(
  { query: 'desk lamp' },
  { headers: { 'x-user-id': 'user_123' } },
);

client.products.search(query="desk lamp", user_id="user_123")

curl -X POST https://api.trychannel3.com/v1/search \
  -H "x-api-key: $CHANNEL3_API_KEY" -H "x-user-id: user_123" \
  -H "Content-Type: application/json" -d '{"query":"desk lamp"}'

アフィリエイトリンク

レスポンス内のすべての ProductOffer.url は、アフィリエイト計測対象のリンクです。あらゆるUIで購入ボタンとして表示してください。これらのURL経由で発生した売上には、追加設定なしでコミッションが発生します。小売業者の識別には offer.domain を、販売店ごとの収益性の比較には offer.max_commission_rate を使用してください。

キャッシュと鮮度

• データではなくIDをキャッシュしてください。 product.id とカテゴリのスラッグは安定しているため、自由にキャッシュできます。商品のその他すべての情報（価格、在庫状況、オファー、画像、説明、バリエーション）は不安定な情報として扱ってください。販売店がカタログを更新すると変わることがあります。
• 表示時に更新してください。 ユーザーに商品を表示する前に、GET /v1/products/{id}（client.products.retrieve）で再取得してください。この呼び出しは無料で、最新の価格、在庫、詳細なバリエーションの在庫状況、新しいオファーURLが返されます。
• オファーURLの有効期間は短いものです。 ProductOffer.url をキャッシュして後から表示しないでください。購入リンクを表示する前に、最新のURLを取得してください。
• 表示用のフィールド（タイトル、画像など）は短いTTL（数分から数時間）であれば問題ありません。価格や在庫状況を数時間から数日間キャッシュするのは避けてください。

ロケールコード

• 言語： en、de、fr、it、es、nl、sv、fi、pt、cs、el、ro
• 国： US、GB、EU、AU、CA、IE、DE、AT、FR、BE、IT、ES、NL、SE、FI、PT、CZ、GR、RO
• 通貨： USD、CAD、AUD、GBP、EUR、SEK、CZK、RON
• 長さの単位： mm、cm、m、in、ft · 重さの単位： mg、g、kg、oz、lb

country のみを設定すると、サーバーは currency（GB → GBP）と language（GB → en）を推測します。3つすべてを未設定にした場合のデフォルトは en / US / USD です。length_unit / weight_unit は寸法の表示単位のみを制御します。未設定の場合は、販売店が指定した単位が返されます。

MCPを使用する場合

ノーコードでエージェントを統合する場合、ホストがすでに対応しているなら、APIコードを記述する代わりに Channel3 MCP を使用してください。

行き詰まった場合

• SDK ガイド（インストール、非同期処理、エラー、再試行、ログ記録）：docs.trychannel3.com/sdk
• API リファレンス全文（試用例、スキーマ）：docs.trychannel3.com/api-reference
• オフライン用クイックカード：references/api-reference.md
• 既存のコードを SDK 4.0 に移行する方法：references/sdk-4-upgrade.md
• サポート：[email protected]