Feedback API ドキュメント
フィードバック API（Commerce Feedback API）
フィードバック API には、フィードバック待ちアイテムの取得、フィードバックエントリの取得と送信、フィードバック評価サマリーの提供、フィードバックへの返信のためのリソースが含まれます。これらのメソッドにより、ユーザーは購入と販売のアクティビティ全体でフィードバックを管理できます。
注: フィードバックは注文全体ではなく、注文内の明細項目レベルで追跡されます。各明細項目は独自のフィードバックレコードを持つことができます。
バージョン: v1.0.0
ベースURL: https://api.ebay.com/commerce/feedback/v1
認証（OAuth スコープ）
この API は OAuth 2.0 認証を使用します。エンドポイントによって必要なスコープが異なります。
| スコープ | 説明 | 使用先 |
|---|---|---|
https://api.ebay.com/oauth/api_scope/commerce.feedback | フィードバックの読み取りと書き込み | awaiting_feedback, feedback (POST), respond_to_feedback |
https://api.ebay.com/oauth/api_scope/commerce.feedback.readonly | フィードバックの読み取り専用 | feedback (GET), feedback_rating_summary |
リソース一覧
Commerce Feedback API は以下の 4 リソース、合計 5 エンドポイント（3 GET + 2 POST）で構成されています。
| リソース | 説明 | 数 |
|---|---|---|
| awaiting_feedback | フィードバック待ちアイテムの取得 | 1 |
| feedback | フィードバックの取得と送信 | 2 |
| feedback_rating_summary | フィードバック評価サマリーの取得 | 1 |
| respond_to_feedback | フィードバックへの返信 | 1 |
awaiting_feedback — フィードバック待ち（1 エンドポイント）
GET /awaiting_feedback
getItemsAwaitingFeedback — ユーザーの取引パートナーからのフィードバックを待っている明細項目を取得します。
セラーの場合はまだフィードバックを受け取っていない販売アイテム、バイヤーの場合はフィードバックが保留中の購入アイテムが含まれます。ユーザーがバイヤーとセラーの両方の場合、両方のロールのアイテムが返されます。
レスポンスには、バイヤーとセラーの両方のロールのフィードバック待ちカウントと、各明細項目の詳細（リスト ID、タイトル、価格、フィードバックテンプレート）が含まれます。
| パラメータ | 場所 | 必須 | 説明 |
|---|---|---|---|
filter | クエリ | 任意 | フィルター。サポート: listingId、receiverName、userRole（BUYER/SELLER）。形式: filter=listingId:123,receiverName:user,userRole:BUYER |
limit | クエリ | 任意 | ページあたりの最大項目数。デフォルト: 25、最小: 25、最大: 200 |
offset | クエリ | 任意 | スキップする項目数。デフォルト: 0 |
sort | クエリ | 任意 | ソート順。有効値: END_TIME_ASC、END_TIME_DESC（デフォルト） |
レスポンス: 200 / 400 / 401 / 500
feedback — フィードバック管理（2 エンドポイント）
GET /feedback
getFeedback — 指定されたユーザー ID とフィードバックタイプ（送信または受信）のフィードバックを取得します。
フィルターにより、コメントタイプ、画像の有無、AI ベースのトピック分析（shipping、service、packaging、description、quality、price 等 20 種類）、期間、ユーザーロール、自動フィードバックの包含/除外で絞り込めます。
プライバシー: ログイン状況やコンテキストに応じて表示される詳細が制限されます。自分のフィードバックではすべての名前が表示されますが、他のユーザーのフィードバックではマスキングされます。
| パラメータ | 場所 | 必須 | 説明 |
|---|---|---|---|
user_id | クエリ | 必須 | フィードバックを取得するユーザーの eBay ユーザー名。ユーザー名とパブリックユーザー ID の両方が受け入れられます。 |
feedback_type | クエリ | 必須 | フィードバックタイプ。有効値: FEEDBACK_RECEIVED（受信）、FEEDBACK_SENT（送信） |
feedback_id | クエリ | 任意 | 特定のフィードバック ID。指定時は他のフィルター無効。 |
filter | クエリ | 任意 | フィルター。commentType、filterImage、topics、period（7/30/90/180/365）、role、includeAutomatedFeedback |
limit | クエリ | 任意 | ページあたりの最大項目数。デフォルト: 25、最大: 200 |
listing_id | クエリ | 任意 | リスト ID でフィルタリング。 |
offset | クエリ | 任意 | スキップする項目数。デフォルト: 0 |
order_line_item_id | クエリ | 任意 | 注文明細項目 ID。最大 2 件返却。指定時は他のフィルター無効。 |
sort | クエリ | 任意 | ソート順。有効値: RELEVANCE（デフォルト）、TIME |
transaction_id | クエリ | 任意 | トランザクション ID でフィルタリング。 |
レスポンス: 200 / 400 / 401 / 500
POST /feedback
leaveFeedback — 注文内の明細項目に対して取引パートナーにフィードバックを作成・送信します。
フィードバック評価、コメント（最大 500 文字）、セラー評価を含む詳細情報を提供できます。画像も最大 5 枚添付可能。
注: セラーはバイヤーへのポジティブフィードバック（コメントのみ）を提供可能。バイヤーはコメントに加えてセラーの DSR（詳細セラー評価）も提供可能。フィードバックは送信後 1 回のみ修正可能。
| パラメータ | 場所 | 必須 | 説明 |
|---|---|---|---|
Content-Type | ヘッダー | 必須 | application/json に設定。 |
リクエストボディ（LeaveFeedbackRequest）:
| フィールド | 型 | 説明 |
|---|---|---|
commentText | string | フィードバックコメント。最大 500 文字。HTML や個人情報は不可。 |
commentType | string | 評価タイプ: POSITIVE、NEUTRAL、NEGATIVE |
listingId | string | リスト ID。 |
transactionId | string | トランザクション ID。 |
orderLineItemId | string | 注文明細項目 ID。形式: listing_id-transaction_id |
sellerRatings | array[SellerRating] | セラー評価。キー: ON_TIME_DELIVERY、ITEM_AS_DESCRIBED、COMMUNICATION、SHIPPING_CHARGES、SHIPPING_TIME |
images | array[Image] | 画像 URL の配列。最大 5 枚。 |
レスポンス: 200 / 400 / 401 / 409 / 500
feedback_rating_summary — 評価サマリー（1 エンドポイント）
GET /feedback_rating_summary
getFeedbackRatingSummary — ユーザーに関連するフィードバック評価の詳細な概要を提供します。評価タイプとユーザーロール別にカテゴリ化された集計フィードバックデータを取得します。
返されるデータには、評価タイプ別の集計メトリクス（平均値、カウント、一意のフィードバック提供者数、ポジティブ評価率）と、特定の評価値の分布が含まれます。
| パラメータ | 場所 | 必須 | 説明 |
|---|---|---|---|
user_id | クエリ | 必須 | フィードバックサマリーを取得するユーザーの eBay ユーザー名。 |
filter | クエリ | 必須 | フィルター。ratingType（必須）: OVERALL_EXPERIENCE、OVERALL_EXPERIENCE_COMMENT、ON_TIME_DELIVERY、DSR_ITEM_AS_DESCRIBED、DSR_COMMUNICATION、DSR_SHIPPING_CHARGES、DSR_SHIPPING_TIME、ITEM_RATING。excludeRepeatFeedback: true でリピート除外。lookbackPeriodInDays: 7/30/90/180/365 |
レスポンス: 200 / 400 / 401 / 404 / 500
respond_to_feedback — フィードバック返信（1 エンドポイント）
POST /respond_to_feedback
respondToFeedback — 取引パートナーが提供したフィードバックに返信します。追加のコンテキストを提供したり、フィードバックに対処したりできます。
フィードバックがまだ返信されていない場合のみ使用可能。返信してもフィードバックスコアには影響しません。
| パラメータ | 場所 | 必須 | 説明 |
|---|---|---|---|
Content-Type | ヘッダー | 必須 | application/json に設定。 |
リクエストボディ（RespondToFeedbackRequest）:
| フィールド | 型 | 説明 |
|---|---|---|
feedbackId | string | 返信するフィードバックの一意の識別子。 |
recipientUserId | string | 元のフィードバックを提供したユーザーの識別子。 |
responseText | string | 返信テキスト。最大 500 文字。HTML や個人情報は不可。 |
responseType | string | 返信タイプ: REPLY（セラー用）、FOLLOW_UP（バイヤー用） |
レスポンス: 200 / 400 / 401 / 403 / 409 / 500
主要スキーマ定義（全 27 スキーマ）
FeedbackDetail（フィードバック詳細）
| フィールド | 型 | 説明 |
|---|---|---|
feedbackId | string | フィードバックの一意の識別子 |
commentType | string | フィードバックタイプ: POSITIVE / NEUTRAL / NEGATIVE |
feedbackComment | Comment | フィードバックコメントの詳細 |
feedbackEnteredDate | string | フィードバック送信日時 |
feedbackRatings | array[FeedbackRating] | 評価の配列（バイヤーからセラーへの DSR のみ） |
feedbackScore | integer | フィードバック受信者のスコア |
feedbackState | string | フィードバックの状態（例: ENTERED） |
eligibleForRevision | boolean | 修正可能かどうか（30 日以内で未修正の場合 true） |
automatedFeedback | boolean | eBay 自動生成フィードバックかどうか |
hasImages | boolean | 画像が添付されているかどうか |
images | array[Image] | 添付画像の URL 配列 |
followupComment | Comment | フォローアップコメント（バイヤー用） |
replyComment | Comment | 返信コメント（セラー用） |
providerUserDetail | ProviderUserDetail | フィードバック提供者のユーザー詳細 |
orderLineItemSummary | OrderLineItemSummary | 関連する明細項目のサマリー |
topics | array[Topic] | AI 生成のトピックインサイト |
AwaitingFeedback（フィードバック待ち明細項目）
| フィールド | 型 | 説明 |
|---|---|---|
listingId | string | リストの一意の識別子 |
listingTitle | string | リストのタイトル |
listingPrice | ListingPrice | 販売価格 |
orderLineItemId | string | 注文明細項目 ID |
transactionId | string | トランザクション ID |
ratingTemplates | array[FeedbackRatingTemplateType] | 利用可能な評価テンプレート |
Topic（AI トピックインサイト）
| フィールド | 型 | 説明 |
|---|---|---|
coarseTopic | string | 検出されたメイントピック（例: shipping、quality） |
highlightedTexts | array[string] | トピックを裏付けるフィードバックからのテキスト抜粋 |
sentiment | string | センチメント分類: Positive / Negative / Neutral |
その他のスキーマ: Comment、CommentCommentPeriod、FeedbackEnteredPeriod、FeedbackMetrics、FeedbackRating、FeedbackRatingAcceptableValue、FeedbackRatingSummary、FeedbackRatingTemplateType、FeedbackRatingValueDistribution、GetFeedbackRatingSummaryResponse、GetFeedbackResponse、Image、ItemsAwaitingFeedbackCount、LeaveFeedbackRequest、LeaveFeedbackResponse、ListingPrice、OrderLineItemAttribute、OrderLineItemSummary、Pagination、Period、ProviderUserDetail、ProviderUserDetailUserAttributes、RatingSummaryByRatingType、RespondToFeedbackRequest、SellerRating、TransactionPeriod、Error、ErrorParameter（詳細は OpenAPI 仕様を参照）。
エンドポイント一覧（全 5 エンドポイント）
| メソッド | エンドポイント | operationId | 説明 |
|---|---|---|---|
| GET | /awaiting_feedback | getItemsAwaitingFeedback | フィードバック待ちアイテム取得 |
| GET | /feedback | getFeedback | フィードバック取得 |
| POST | /feedback | leaveFeedback | フィードバック送信 |
| GET | /feedback_rating_summary | getFeedbackRatingSummary | 評価サマリー取得 |
| POST | /respond_to_feedback | respondToFeedback | フィードバックへの返信 |