カタログ API（Catalog API）
Catalog API を使用すると、ユーザーは販売したい製品と直接一致する eBay カタログ製品を検索して見つけることができます。eBay カタログ製品に対して出品すると、すべての出品に完全で正確な情報が含まれるようになります。カタログ情報を使用することで、出品タイトル、説明、商品の詳細、ストック画像などが事前に入力され、出品プロセスが高速かつ簡単になります。
バージョン: v1_beta.5.2
ベースURL: https://api.ebay.com/commerce/catalog/v1_beta
認証（OAuth スコープ）
この API は 認可コード（Authorization Code） フローを使用します。ユーザーの認可が必要です。
| スコープ |
説明 |
https://api.ebay.com/oauth/api_scope/commerce.catalog.readonly |
サインインユーザーのカタログデータの読み取り |
https://api.ebay.com/oauth/api_scope/sell.inventory |
在庫とオファーの表示と管理 |
リソース一覧
Catalog API は以下の 2 リソース、合計 2 エンドポイント（すべて GET）で構成されています。
product — カタログ製品の取得（1 エンドポイント）
GET /product/{epid}
getProduct — リクエストで指定された eBay 製品 ID（ePID）で識別されるカタログ製品の詳細を取得します。これらの詳細には、製品のタイトルと説明、アスペクトとその値、関連する画像、該当するカテゴリ ID、および製品に適用される認識された ID（GTIN、MPN 等）が含まれます。
ヒント: 新しいリストの場合、まず search メソッドで候補製品を特定し、getProduct で完全な詳細を取得して最終選択を行います。
| パラメータ | 場所 | 必須 | 説明 |
|---|
epid | パス | 必須 | 要求される製品の eBay 製品 ID（ePID）。search メソッドの productSummaries.epid フィールドから取得可能。 |
X-EBAY-C-MARKETPLACE-ID | ヘッダー | 条件付 | 販売者の eBay マーケットプレイスを識別。デフォルトの EBAY_US を除くすべてのマーケットプレイスで必須。 |
レスポンス: 200 → Product / 400 / 403 / 404 / 500
product_summary — カタログ製品の検索（1 エンドポイント）
GET /product_summary/search
search — セラーが指定した検索条件に一致する eBay カタログ内の 1 つ以上の製品の概要を検索して取得します。セラーは概要を使用して、販売したい商品に対応する eBay カタログ内の製品を選択できます。
このメソッドは、製品の概要に加えて、絞り込み（Refinement）を識別するためにも使用できます。絞り込みは、探している製品をより正確に特定するのに役立つアスペクト値と、各値が以前の eBay リストで使用された回数で構成されます。
| パラメータ | 場所 | 必須 | 説明 |
|---|
X-EBAY-C-MARKETPLACE-ID | ヘッダー | 条件付 | 販売者の eBay マーケットプレイスを識別。EBAY_US を除くすべてのマーケットプレイスで必須。 |
q | クエリ | 条件付 | eBay カタログ内の製品を検索するキーワード。検索対象: title、description、brand、aspects.localizedName。ワイルドカード不可。
注: q、category_ids、gtin、mpn のいずれかが必須。gtin / mpn と同時使用不可。 |
category_ids | クエリ | 条件付 | 製品コレクションを絞り込むためのカンマ区切りのカテゴリ ID。現在は最初の ID のみ有効。最上位（L1）カテゴリは単独指定不可。
Taxonomy API の getCategorySuggestions で適切な ID を取得可能。 |
aspect_filter | クエリ | 任意 | カテゴリとアスペクト値による絞り込み。構文: aspect_filter=categoryId:{id},aspectName:{value1|value2}。gtin / mpn と同時使用不可。 |
fieldgroups | クエリ | 任意 | 応答で返される情報タイプ。値: ASPECT_REFINEMENTS（アスペクト絞り込み）、MATCHING_PRODUCTS（一致製品、デフォルト）、FULL（すべて）。 |
gtin | クエリ | 条件付 | カンマ区切りのグローバルトレードアイテム番号（EAN, ISBN, UPC）。q / aspect_filter と同時使用不可。 |
mpn | クエリ | 条件付 | カンマ区切りの製造元部品番号。q / aspect_filter と同時使用不可。 |
limit | クエリ | 任意 | 返される製品概要の最大数。最大: 200、デフォルト: 50。 |
offset | クエリ | 任意 | 内部または将来の使用のために予約。 |
レスポンス: 200 → ProductSearchResponse / 204 / 400 / 403 / 500
スキーマ定義（全 10 スキーマ）
製品
Product
| フィールド | 型 | 説明 |
|---|
epid | string | eBay 製品 ID |
title | string | 製品タイトル |
description | string | 製品説明 |
brand | string | ブランド名 |
aspects | array[Aspect] | 製品アスペクトの配列 |
image | Image | メイン画像 |
additionalImages | array[Image] | 追加画像の配列 |
primaryCategoryId | string | 主要カテゴリ ID |
otherApplicableCategoryIds | array[string] | その他の適用カテゴリ ID |
ean | array[string] | EAN コード |
isbn | array[string] | ISBN コード |
upc | array[string] | UPC コード |
gtin | array[string] | GTIN（EAN、ISBN、UPC を含む） |
mpn | array[string] | 製造元部品番号 |
productWebUrl | string | eBay 上の製品ページ URL |
version | string | 製品レコードのバージョン |
ProductSummary
| フィールド | 型 | 説明 |
|---|
epid | string | eBay 製品 ID |
title | string | 製品タイトル |
brand | string | ブランド名 |
aspects | array[Aspect] | 製品アスペクト |
image | Image | メイン画像 |
additionalImages | array[Image] | 追加画像 |
ean | array[string] | EAN コード |
isbn | array[string] | ISBN コード |
upc | array[string] | UPC コード |
gtin | array[string] | GTIN |
mpn | array[string] | 製造元部品番号 |
productHref | string | getProduct API の URI |
productWebUrl | string | eBay 上の製品ページ URL |
検索レスポンス
ProductSearchResponse
| フィールド | 型 | 説明 |
|---|
href | string | 現在の結果セットの URI |
limit | integer | 結果セット内の最大件数 |
next | string | 次ページの URI |
offset | integer | オフセット |
prev | string | 前ページの URI |
total | integer | 一致する製品の総数 |
productSummaries | array[ProductSummary] | 製品概要の配列 |
refinement | Refinement | 絞り込み情報 |
絞り込み
Refinement
| フィールド | 型 | 説明 |
|---|
aspectDistributions | array[AspectDistribution] | アスペクト分布の配列 |
dominantCategoryId | string | 最も支配的なカテゴリ ID |
AspectDistribution
| フィールド | 型 | 説明 |
|---|
localizedAspectName | string | ローカライズされたアスペクト名 |
aspectValueDistributions | array[AspectValueDistribution] | アスペクト値分布の配列 |
AspectValueDistribution
| フィールド | 型 | 説明 |
|---|
localizedAspectValue | string | ローカライズされたアスペクト値 |
matchCount | integer | この値を使用する製品の数 |
refinementHref | string | この値で絞り込む URI |
共通スキーマ
Aspect
| フィールド | 型 | 説明 |
|---|
localizedName | string | ローカライズされたアスペクト名 |
localizedValues | array[string] | ローカライズされたアスペクト値の配列 |
Image
| フィールド | 型 | 説明 |
|---|
imageUrl | string | 画像の URL |
height | integer | 画像の高さ（ピクセル） |
width | integer | 画像の幅（ピクセル） |
Error
| フィールド | 型 | 説明 |
|---|
category | string | エラーカテゴリ |
domain | string | エラードメイン |
errorId | integer | エラー ID |
message | string | 短いメッセージ |
longMessage | string | 詳細メッセージ |
inputRefIds | array[string] | 入力参照 ID |
outputRefIds | array[string] | 出力参照 ID |
parameters | array[ErrorParameter] | エラーパラメータ |
subdomain | string | エラーサブドメイン |
ErrorParameter
| フィールド | 型 | 説明 |
|---|
name | string | パラメータ名 |
value | string | パラメータ値 |
エンドポイント一覧（全 2 エンドポイント）
| メソッド |
エンドポイント |
operationId |
説明 |
| GET | /product/{epid} | getProduct | ePID でカタログ製品の詳細を取得 |
| GET | /product_summary/search | search | 検索条件に一致するカタログ製品の概要を取得 |
