ディール API（Deal API）
Deal API を使用すると、サードパーティの開発者は eBay の取引やイベント、およびそれらに関連付けられたアイテムに関する詳細を検索して取得できます。
注: これは限定リリース API であり、ビジネスユニットによって承認された特定の開発者のみが利用できます。
バージョン: v1.3.0
ベースURL: https://api.ebay.com/buy/deal/v1
認証（OAuth スコープ）
この API は クライアント資格情報（Client Credentials） フローを使用します。
| スコープ | 説明 |
|---|
https://api.ebay.com/oauth/api_scope/buy.deal | eBay セールイベントとディールの表示 |
リソース一覧
Deal API は以下の 3 リソース、合計 4 エンドポイント（すべて GET）で構成されています。
deal_item — 取引アイテム（1 エンドポイント）
GET /deal_item
getDealItems — ページ分けされた取引アイテムのセットを取得します。最大 10,000 個のアイテムを返すことが可能です。
eBay パートナーネットワーク: コミッションを受け取るには itemAffiliateWebUrl の URL を使用してください。
| パラメータ | 場所 | 必須 | 説明 |
|---|
X-EBAY-C-MARKETPLACE-ID | ヘッダー | 必須 | eBay マーケットプレイス ID。 |
X-EBAY-C-ENDUSERCTX | ヘッダー | 任意 | eBay パートナーネットワークの収益分配と配送見積りのため。 |
category_ids | クエリ | 任意 | eBay カテゴリ ID。 |
commissionable | クエリ | 任意 | コミッション対象でフィルター（true/false）。米国マーケットプレイスのみ。 |
delivery_country | クエリ | 任意 | 配送先国（2 桁 ISO コード）。 |
limit | クエリ | 任意 | ページあたりの最大件数。 |
offset | クエリ | 任意 | スキップ数。デフォルト: 0 |
レスポンス: 200 / 400 / 403 / 500
event — イベント（2 エンドポイント）
GET /event
getEvents — 指定マーケットプレイスのすべての eBay イベントを含むページ分けされた結果を返します。最大 10,000 アイテム。
| パラメータ | 場所 | 必須 | 説明 |
|---|
X-EBAY-C-MARKETPLACE-ID | ヘッダー | 必須 | eBay マーケットプレイス ID。 |
X-EBAY-C-ENDUSERCTX | ヘッダー | 任意 | パートナーネットワーク用。 |
limit | クエリ | 任意 | デフォルト: 20、最大: 100 |
offset | クエリ | 任意 | デフォルト: 0 |
レスポンス: 200 / 400 / 403 / 500
GET /event/{event_id}
getEvent — 特定の eBay イベントの詳細（クーポン、開始/終了日、イベント条件）を取得します。
| パラメータ | 場所 | 必須 | 説明 |
|---|
event_id | パス | 必須 | eBay イベントの一意の識別子。 |
X-EBAY-C-MARKETPLACE-ID | ヘッダー | 必須 | eBay マーケットプレイス ID。 |
X-EBAY-C-ENDUSERCTX | ヘッダー | 任意 | パートナーネットワーク用。 |
レスポンス: 200 / 400 / 403 / 404 / 500
event_item — イベントアイテム（1 エンドポイント）
GET /event_item
getEventItems — 指定イベントに関連するページ分けされたアイテムのセットを返します。最大 10,000 アイテム。
| パラメータ | 場所 | 必須 | 説明 |
|---|
X-EBAY-C-MARKETPLACE-ID | ヘッダー | 必須 | eBay マーケットプレイス ID。 |
X-EBAY-C-ENDUSERCTX | ヘッダー | 任意 | パートナーネットワーク用。 |
event_ids | クエリ | 必須 | イベント ID。最大: 1 |
category_ids | クエリ | 任意 | カテゴリ ID。最大: 1 |
delivery_country | クエリ | 任意 | 配送先国（2 桁 ISO コード）。 |
limit | クエリ | 任意 | デフォルト: 20 |
offset | クエリ | 任意 | デフォルト: 0 |
レスポンス: 200 / 400 / 403 / 500
スキーマ定義（全 14 スキーマ）
DealItem
| フィールド | 型 | 説明 |
|---|
dealAffiliateWebUrl | string | アフィリエイト URL |
dealEndDate | string | 取引終了日 |
dealStartDate | string | 取引開始日 |
dealWebUrl | string | 取引の Web URL |
image | Image | アイテム画像 |
itemAffiliateWebUrl | string | アイテムのアフィリエイト URL |
itemGroupId | string | アイテムグループ ID |
itemGroupType | string | アイテムグループタイプ |
itemId | string | アイテム ID |
itemWebUrl | string | アイテムの Web URL |
legacyItemId | string | レガシーアイテム ID |
marketingPrice | MarketingPrice | マーケティング価格 |
price | Amount | 価格 |
qualifiedPrograms | array[string] | 対象プログラム |
shippingOptions | array[ShippingOption] | 配送オプション |
title | string | タイトル |
unitPrice | Amount | 単価 |
unitPricingMeasure | string | 単価の測定単位 |
commissionable | boolean | コミッション対象 |
DealItemSearchResponse
| フィールド | 型 | 説明 |
|---|
dealItems | array[DealItem] | 取引アイテムの配列 |
href | string | 現在ページの URI |
next | string | 次ページの URI |
prev | string | 前ページの URI |
limit | integer | 最大件数 |
offset | integer | オフセット |
total | integer | 総数 |
Event
| フィールド | 型 | 説明 |
|---|
applicableCoupons | array[Coupon] | 適用可能なクーポン |
description | string | イベントの説明 |
endDate | string | 終了日 |
eventAffiliateWebUrl | string | アフィリエイト URL |
eventId | string | イベント ID |
eventWebUrl | string | Web URL |
images | array[Image] | イベント画像 |
startDate | string | 開始日 |
terms | Terms | 利用条件 |
title | string | タイトル |
EventSearchResponse
| フィールド | 型 | 説明 |
|---|
events | array[Event] | イベントの配列 |
href | string | 現在ページの URI |
next | string | 次ページの URI |
prev | string | 前ページの URI |
limit | integer | 最大件数 |
offset | integer | オフセット |
total | integer | 総数 |
共通型
Amount
| フィールド | 型 | 説明 |
|---|
currency | string | 通貨コード |
value | string | 金額 |
Coupon
| フィールド | 型 | 説明 |
|---|
redemptionCode | string | 引き換えコード |
terms | Terms | 利用条件 |
Image
| フィールド | 型 | 説明 |
|---|
height | string | 高さ |
imageUrl | string | 画像 URL |
text | string | 代替テキスト |
width | string | 幅 |
MarketingPrice
| フィールド | 型 | 説明 |
|---|
discountAmount | Amount | 割引額 |
discountPercentage | string | 割引率 |
originalPrice | Amount | 元の価格 |
priceTreatment | string | 価格表示タイプ |
ShippingOption
| フィールド | 型 | 説明 |
|---|
shippingCost | Amount | 配送コスト |
shippingCostType | string | 配送コストタイプ |
Terms
| フィールド | 型 | 説明 |
|---|
fullText | string | 完全なテキスト |
summary | string | 要約 |
Error / ErrorParameter
標準エラースキーマ（他の API と同一構造）。
エンドポイント一覧（全 4 エンドポイント）
| メソッド | エンドポイント | operationId | 説明 |
|---|
| GET | /deal_item | getDealItems | 取引アイテムを検索 |
| GET | /event | getEvents | イベント一覧を取得 |
| GET | /event/{event_id} | getEvent | イベント詳細を取得 |
| GET | /event_item | getEventItems | イベントアイテムを取得 |
