Message API ドキュメント
メッセージ API（Commerce Message API）
この API により、eBay セラーはメッセージの送信、取得、管理が可能になります。バイヤーとセラー間（M2M）、または eBay からの通知メッセージを会話として管理できます。
バージョン: 1.0.0
ベースURL: https://api.ebay.com/commerce/message/v1
認証（OAuth スコープ）
| スコープ | 説明 |
|---|---|
https://api.ebay.com/oauth/api_scope/commerce.message | メッセージの送信・取得・管理 |
リソース一覧
Commerce Message API は 1 リソース（conversation）、合計 5 エンドポイント（2 GET + 3 POST）で構成されています。
| リソース | 説明 | 数 |
|---|---|---|
| conversation | 会話の取得・送信・更新・一括更新 | 5 |
conversation — 会話管理（5 エンドポイント）
GET /conversation
getConversations — ユーザーに関連付けられた会話一覧を取得します。会話ステータス、リファレンス、ユーザー名、時間範囲でフィルタリング可能。
| パラメータ | 場所 | 必須 | 説明 |
|---|---|---|---|
conversation_type | クエリ | 必須 | 会話タイプ: FROM_EBAY / FROM_MEMBERS |
conversation_status | クエリ | 任意 | ステータス: ACTIVE / ARCHIVE / DELETE / READ / UNREAD |
start_time | クエリ | 任意 | 開始時間（ISO 8601）。FROM_MEMBERS のみ。 |
end_time | クエリ | 任意 | 終了時間（ISO 8601）。FROM_MEMBERS のみ。 |
other_party_username | クエリ | 任意 | 相手の eBay ユーザー名。 |
reference_id | クエリ | 任意 | リファレンス ID。reference_type と併用必須。 |
reference_type | クエリ | 任意 | リファレンスタイプ。現在 LISTING のみ。 |
limit | クエリ | 任意 | 最大件数。デフォルト: 25、最大: 50 |
offset | クエリ | 任意 | スキップ件数。デフォルト: 0 |
レスポンス: 200 / 400 / 401 / 403 / 404 / 500
GET /conversation/{conversation_id}
getConversation — 特定の会話内のメッセージを取得します。
| パラメータ | 場所 | 必須 | 説明 |
|---|---|---|---|
conversation_id | パス | 必須 | 会話の一意の識別子。 |
conversation_type | クエリ | 必須 | 会話タイプ: FROM_EBAY / FROM_MEMBERS |
limit | クエリ | 任意 | 最大件数。デフォルト: 25、最大: 50 |
offset | クエリ | 任意 | スキップ件数。デフォルト: 0 |
レスポンス: 200 / 400 / 401 / 403 / 404 / 500
POST /send_message
sendMessage — 新しい会話を開始するか、既存の会話でメッセージを送信します。
既存の会話: conversationId 必須。新規会話: otherPartyUsername 必須。メディア（画像/ドキュメント）を最大 5 件添付可能。
| パラメータ | 場所 | 必須 | 説明 |
|---|---|---|---|
Content-Type | ヘッダー | 必須 | application/json |
リクエストボディ（SendMessageRequest）:
| フィールド | 型 | 説明 |
|---|---|---|
conversationId | string | 既存の会話 ID（既存会話時は必須） |
otherPartyUsername | string | 相手の eBay ユーザー名（新規会話時は必須） |
messageText | string | メッセージ本文。最大: 2000 文字 |
messageMedia | array[MessageMedia] | 添付メディア。最大 5 件。タイプ: IMAGE / PDF / DOC / TXT |
emailCopyToSender | boolean | 送信者にメールコピーを送るか |
reference | Reference | リスティングへの関連付け |
レスポンス: 201 / 400 / 401 / 403 / 500
POST /update_conversation
updateConversation — 会話の conversationStatus または read ステータスを更新します。一度に更新できるのは一方のみ。両方含まれる場合は read のみ更新されます。
| パラメータ | 場所 | 必須 | 説明 |
|---|---|---|---|
Content-Type | ヘッダー | 必須 | application/json |
リクエストボディ（UpdateConversationRequest）:
| フィールド | 型 | 説明 |
|---|---|---|
conversationId | string | 更新対象の会話 ID（必須） |
conversationType | string | 既存の会話タイプ（必須、更新不可）: FROM_MEMBERS / FROM_EBAY |
conversationStatus | string | 更新後のステータス: ACTIVE / ARCHIVE / DELETE |
read | boolean | 既読ステータス。true = 既読、false = 未読 |
レスポンス: 204 / 400 / 401 / 403 / 500
POST /bulk_update_conversation
bulkUpdateConversation — 最大 10 件の会話の conversationStatus を一括更新します。
| パラメータ | 場所 | 必須 | 説明 |
|---|---|---|---|
Content-Type | ヘッダー | 必須 | application/json |
レスポンス: 200 / 400 / 401 / 403 / 500
主要スキーマ定義（全 15 スキーマ）
ConversationDetail
| フィールド | 型 | 説明 |
|---|---|---|
conversationId | string | 会話の一意の識別子 |
conversationStatus | string | 会話の現在のステータス |
conversationTitle | string | 会話のタイトル |
conversationType | string | 会話タイプ: FROM_EBAY / FROM_MEMBERS |
createdDate | string | 会話作成日（ISO 8601） |
latestMessage | MessageDetail | 最新メッセージの詳細 |
referenceId | string | リファレンス ID（リスト ID 等） |
referenceType | string | リファレンスタイプ |
unreadCount | integer | 未読メッセージ数 |
MessageDetail
| フィールド | 型 | 説明 |
|---|---|---|
messageId | string | メッセージの一意の識別子 |
messageBody | string | メッセージ本文 |
subject | string | 件名 |
senderUsername | string | 送信者のユーザー名 |
recipientUsername | string | 受信者のユーザー名 |
readStatus | boolean | 既読かどうか |
createdDate | string | メッセージ作成日 |
messageMedia | array[MessageMedia] | 添付メディア |
MessageMedia
| フィールド | 型 | 説明 |
|---|---|---|
mediaName | string | メディア名 |
mediaType | string | メディアタイプ: IMAGE / PDF / DOC / TXT |
mediaUrl | string | メディア URL（HTTPS 必須） |
その他のスキーマ: BulkConversation, BulkUpdateConversationsRequest, BulkUpdateConversationsResponse, ConversationsMetadata, ConversationsResponse, GetAllMyConversationsResponse, GetMessagesByConversationIdResponse, Reference, SendMessageRequest, SendMessageResponse, UpdateConversationRequest, Error, ErrorParameter
エンドポイント一覧（全 5 エンドポイント）
| メソッド | エンドポイント | operationId | 説明 |
|---|---|---|---|
| GET | /conversation | getConversations | 会話一覧取得 |
| GET | /conversation/{conversation_id} | getConversation | 特定会話のメッセージ取得 |
| POST | /send_message | sendMessage | メッセージ送信 |
| POST | /update_conversation | updateConversation | 会話ステータス更新 |
| POST | /bulk_update_conversation | bulkUpdateConversation | 会話一括ステータス更新 |