注文管理

注文管理ガイド

概要

注文管理（Order Management）APIは、セラー（売り手）が注文管理プロセスのさまざまな側面を処理するための機能を提供します。これらのAPIには、注文詳細の取得、注文ステータスの更新、配送および追跡情報の管理、さらには商品未着（Item Not Received: INR）の問い合わせ、注文のキャンセル、商品の返品処理を行うためのメソッドが含まれています。

APIのユースケース

  • 注文の取得とフルフィルメント（履行）
  • 注文キャンセルの管理
  • 商品未着（INR）問い合わせの管理
  • 返品の管理
  • 支払い紛争（Payment Dispute）の管理

注文の取得とフルフィルメント

バイヤー（買い手）がeBayでのチェックアウトプロセスを完了して商品を購入すると、「注文」が作成されます。注文は複数のラインアイテム（注文明細）で構成される場合があり、セラーは注文内のラインアイテムを1つ以上のパッケージにまとめ、出荷処理（フルフィルメント）を行う必要があります。

注文および配送フルフィルメントを管理する複数のアプローチについて、以下で説明します。

Fulfillment APIを使用した注文の取得とフルフィルメント

Fulfillment APIを使用すると、セラーは注文のフルフィルメントプロセスを効率的に管理できます。これには、注文の取得、配送パッケージへのラインアイテムの割り当て、配送追跡情報の提供などの機能が含まれます。

セラーは getOrder を使用して特定の注文を取得するか、getOrders を使用して注文ID、日付範囲、またはフルフィルメントステータスに基づいて複数の注文を取得できます。以下は、両方のメソッドのレスポンスで返される主要なフィールドの一部です。

  • ラインアイテムの数量 (lineItems.quantity)
  • 配送先住所 (shippingStep.shipTo)
  • バイヤーが選択した配送サービス (shippingCarrierCode および shippingServiceCode)
  • 選択された配送サービスとハンドリングタイム（出荷までの所要日数）に基づく配送予定日枠 (maxEstimatedDeliveryDate および minEstimatedDeliveryDate)
  • 発送期限 (lineItemFulfillmentInstructions.shipByDate)
  • 注文のコストおよび税金情報
    • 注文合計額 (pricingSummary.total)
    • 配送料 (pricingSummary.deliveryCost)
    • 税額 (pricingSummary.tax)

注文を「フルフィルメント完了（fulfilled）」とするには、発送済みとしてマークする必要があります（getOrder(s) メソッドの orderFulfillmentStatus レスポンスフィールドを参照）。セラーがその注文に対してeBay配送ラベルを購入した場合、eBayは自動的に注文を「フルフィルメント完了」としてマークし、追跡情報を提供します。セラーがeBay配送ラベルを使用しない場合は、createShippingFulfillment メソッドを使用して注文を発送済みとしてマークし、配送追跡情報を提供できます。

createShippingFulfillment メソッドを使用して、注文内の1つ以上のラインアイテムを単一のパッケージに割り当てることができます。そのパッケージには配送追跡情報を提供する必要があります。この呼び出しは、注文内のパッケージごとに繰り返す必要があります。

getShippingFulfillment を使用して特定の配送パッケージまたは注文の詳細を取得するか、getShippingFulfillments を使用して注文に関連するすべての配送パッケージの詳細を取得します。

Trading APIを使用した注文の取得とフルフィルメント

Trading API の注文管理コールを使用すると、セラーは注文のフルフィルメントプロセスを管理できます。これには、すべてのアクティブな注文の取得、バイヤーへの請求書の送付、未払いの複数注文ラインアイテムの結合、およびさまざまな販売後のタスクを実行する機能が含まれます。

注文管理に使用されるTrading APIコールについて、以下で説明します。

  • GetOrders を使用して、セラーに関連付けられた注文に関する情報を取得します。各注文について以下のデータが取得されます。
    • ラインアイテムの数量 (QuantityPurchased)
    • 配送先住所 (ShippingAddress)
    • バイヤーが選択した配送サービス (ShippingService)
    • 注文のコストおよび税金情報
      注文合計額 (Order.Total)、配送料 (ShippingServiceCost)、税額 (Taxes)

注文を「フルフィルメント完了」とするには、発送済みとしてマークする必要があります（GetOrder(s) メソッドの OrderStatus レスポンスフィールドを参照）。セラーがその注文に対してeBay配送ラベルを購入した場合、eBayは自動的に注文を「フルフィルメント完了」としてマークし、追跡情報を提供します。セラーがeBay配送ラベルを使用しない場合は、CompleteSale メソッドを使用して注文を発送済みとしてマークし、配送追跡情報を提供できます。

CompleteSale は、注文を支払い済みとしてマークする（Paid ブール値を参照）や、バイヤーにフィードバックを残す（FeedbackInfo コンテナを参照）など、さまざまな販売後のタスクにも使用できます。

以下は、Trading APIで利用可能なその他の注文関連のコールです。

  • GetSellerTransactions を使用して1つ以上の注文のラインアイテム情報を取得するか、GetItemTransactions を使用して特定の固定価格出品のラインアイテム情報を取得します。
  • バイヤーがまだ注文の代金を支払っていない場合、SendInvoice を使用してバイヤーに請求書のリマインダーメールを送信します。
  • AddOrder を使用して、同じバイヤーからの2つ以上の未払い注文ラインアイテムを1つの同梱請求書（Combined Invoice）注文にまとめます。

Logistics APIを使用したUSPS配送ラベルのダウンロード

Logistics API を使用すると、発送元、発送先、およびパッケージの重量/寸法に基づいて利用可能なUSPS配送ラベルのコストを取得し、適切な配送オプションを選択して、USPS配送ラベルをダウンロードできます。

注意: Logistics APIは制限されており、承認されたeBayパートナーのみがアクセスできます。このAPIは米国内の配送にのみ使用でき、USPSの配送料金とラベルのみをサポートし、注文レベルのフルフィルメントのみに対応しています。

以下は、配送見積もりの表示、希望する見積もりの選択、および配送ラベルのダウンロードに使用される基本的なフローです。

  1. createShippingQuote を使用して利用可能なUSPS配送オプションのコストと詳細を取得し、以下の必須フィールドを設定します。
    ShipFrom, ShipTo, PackageSpecification
  2. createShippingQuote のレスポンスで返された shippingQuoteId と rateId の値を使用して、createFromShippingQuote を実行し、選択した配送サービス用のUSPS配送ラベルを生成およびカスタマイズします。選択した配送サービスは、バイヤーがチェックアウト時に選択した配送サービスと一致している必要があることに注意してください。
  3. createFromShippingQuote で返された shipmentId の値を使用して、downloadLabelFile を実行し、USPS配送ラベルのPDFファイルをダウンロードします。

以下は、Logistics APIで利用可能なその他のメソッドです。

  • getShipment を使用して、特定のシップメント（発送）の配送詳細を取得します。
  • getShippingQuote を使用して、特定の配送見積もりの詳細を取得します。
  • cancelShipment を使用して、シップメントをキャンセルし、関連する配送ラベルを削除します。

注文キャンセルの管理

Post-Order API を使用すると、セラーはチェックアウト後最大30日まで注文をキャンセルできます。セラーは、バイヤーがキャンセルをリクエストした場合や、購入された商品の在庫がない場合など、いくつかの理由で注文をキャンセルできます。セラーが Create Cancellation Request コールを行うと注文は自動的にキャンセルされ、注文が既に支払い済みの場合、eBayによってバイヤーに返金されます。

注文キャンセルを管理するために使用されるPost-Order APIメソッドについて、以下で説明します。

  1. Search Cancellations を使用して、セラーにキャンセルリクエストがあるかどうかを確認します。このメソッドには、日付範囲や item_id など、多数のフィルタが利用可能です。cancelReason フィールドを参照してバイヤーがキャンセルリクエストを開始した理由を確認し、cancelState および cancelStatus フィールドを参照して今後のキャンセルイベントと実行すべきアクションを決定してください。
  2. バイヤーが注文のキャンセルをリクエストした場合、セラーは Approve Cancellation または Reject Cancellation を使用して、キャンセルを承認または拒否できます。
    • セラーがキャンセルを 承認 した場合、バイヤーにはeBayによって全額返金されます。
    • 注文が既に発送されている場合など、セラーがキャンセルを 拒否 する場合は、それぞれ shipmentDate および trackingNumber フィールドを通じて発送日と追跡番号を提供する必要があります。
  3. 承認された場合、商品が既に支払い済みであれば、eBayは自動的にバイヤーに全額返金を発行します。

以下は、Post-Order APIを使用した注文キャンセルの管理に適用できるその他のメソッドです。

  • セラーが注文キャンセルを開始するには、Create Cancellation Request を使用し、cancelReason フィールドで以下のいずれかの値を指定してキャンセルの理由を特定します。
    BUYER_ASKED_CANCEL（バイヤーからのリクエストによる注文キャンセル）。
    OUT_OF_STOCK_OR_CANNOT_FULFILL（セラーが商品の在庫切れであるか、その他の理由で注文を履行できない場合に使用）。
  • Get Cancellation を使用して、特定のキャンセルリクエストに関する詳細を取得します。

商品未着（INR）問い合わせの管理

商品未着（Item Not Received: INR）の問い合わせは、購入した商品の配送予定日枠を過ぎても商品が届かない場合に、バイヤーによって作成されます。バイヤーがINR問い合わせを作成する際、商品の全額返金をリクエストするか、商品をまだ希望していることをセラーに通知することができます。

INR問い合わせを管理するために使用されるPost-Order APIメソッドについて、以下で説明します。

INR問い合わせの管理

  1. Search Inquiries を使用して、セラーにINR問い合わせリクエストがあるかどうかを確認します。このメソッドには、日付範囲や item_id など、多数のフィルタが利用可能です。InquiryStatusEnum レスポンス列挙体を参照して、INR問い合わせの現在のステータスを確認してください。
  2. バイヤーがINR問い合わせを行った商品をまだ希望している場合、Provide Inquiry Shipment Info を使用して、ラインアイテムの配送に関する更新された配送追跡詳細を提供します。
  3. バイヤーがINR問い合わせを行った商品の返金を希望している場合、Issue Inquiry Refund を使用して、不足しているラインアイテムの返金を発行します。必要に応じて、セラーは Provide Inquiry Refund Info を使用して、返金に関する詳細情報をバイヤーに提供することもできます。

INRケースの管理

セラーがINR問い合わせにタイムリーに対応しない場合、バイヤーは問い合わせをINRケースにエスカレーションする可能性があります。以下は、Post-Order APIメソッドを使用する場合の一般的なフローです。

  1. Search Cases を使用して、最近のすべてのケースを取得します。このメソッドには、日付範囲フィルタやケースステータスなど、多数のフィルタが利用可能です。すべてのオープンなケースを取得するには、case_status_filter クエリパラメータを含め、その値を OPEN に設定することをお勧めします。
  2. Search Cases の後に Get Case を使用して、ケースを解決するために何ができるかを確認します。このコールにはパスパラメータとしてケースIDが必要です。このコールのレスポンスには、ケースにつながったINR問い合わせの履歴を含む完全な履歴詳細が含まれています。
  3. ケースの解決に役立ち、バイヤーまたはeBayによるケースの終了につながるメソッドとして、以下のいずれかを使用できます。
    • Issue Case Refund: このメソッドは、バイヤーが商品をもう希望しておらず、単に返金を求めている場合に使用する必要があります。
    • Provide Case Shipment Info: このメソッドは、バイヤーがまだ商品を希望しており、注文の配送状況を追跡できるようにしたい場合に使用する必要があります。

以下は、Post-Order APIを使用したINR問い合わせの管理に適用できるその他のメソッドです。

  • Send Inquiry Message を使用して、INR問い合わせに関するメッセージをバイヤーに送信します。
  • 必要に応じて、Escalate Inquiry を使用して、INR問い合わせをケースにエスカレーションします。これは、セラーが注文ラインアイテムをすでに発送済みであるにもかかわらず、バイヤーが問い合わせを閉じることを拒否している場合などに使用できます。
  • Get Inquiry を使用して、特定のINR問い合わせに関する詳細を取得します。

返品の管理

バイヤーが商品の返品をリクエストする状況が時折発生します。これには、衣類のサイズが合わなかった、配送中に商品が破損した、商品が出品説明と異なっていた、あるいはバイヤーが単に商品に対する考えを変えたなど、さまざまな理由があります。Post-Order APIには、セラーが現在の返品リクエストを表示し、返品プロセスを管理できるメソッドがあります。

返品リクエストを管理するために使用されるPost-Order APIメソッドについて、以下で説明します。

標準的な返品承認フロー

  1. Search Returns を使用して、セラーに返品リクエストがあるかどうかを確認します。ある場合は、creationInfo.reason フィールドを参照してバイヤーの返品理由を確認し、creationInfo.reasonType フィールドを確認して返品が SNAD（商品説明との著しい相違）または REMORSE（買い手都合）に分類されているかどうかを確認します。SNADによる返品の場合、返送料はセラーの負担となります。
  2. Process Return Request を使用して返品リクエストを承認します。
    • 承認され、バイヤーが返送料を負担する 場合、バイヤーはセラーによる返品リクエスト承認後に商品を返送できます。
    • 承認され、セラーが返送料を負担する 場合、Add Shipping Label Info を使用して配送ラベルを作成し、バイヤーに送信します。
  3. バイヤーから商品が返送されたら、Mark Return Received を使用して商品を受け取り済みとしてマークします。

SNAD返品ケースの管理

セラーがSNAD（商品説明との著しい相違）返品リクエストにタイムリーに対応しない場合、バイヤーは返品リクエストを返品ケースにエスカレーションする可能性があります。以下は、Post-Order APIメソッドを使用する場合の一般的なフローです。

  1. Search Cases を使用して、最近のすべてのケースを取得します。このメソッドには、日付範囲やケースステータスなど、多数のフィルタが利用可能です。すべてのオープンなケースを取得するには、case_status_filter クエリパラメータを含め、その値を OPEN に設定することをお勧めします。
  2. Get Case を使用して、ケースを解決するために何ができるかを確認します。このコールにはパスパラメータとしてケースIDが必要です。このコールのレスポンスには、ケースにつながった返品リクエストの履歴を含む完全な履歴詳細が含まれています。
  3. ケースの解決に役立ち、バイヤーまたはeBayによるケースの終了につながるメソッドとして、以下のいずれかを使用できます。
    • Issue Case Refund: このメソッドは、セラーがバイヤーに商品をそのまま保持させつつ、全額返金を発行する場合に使用できます。
    • Provides Return Address: このメソッドは、バイヤーに返送先住所とRMA番号（該当する場合）を提供するために使用できます。

以下は、Post-Order APIを使用した返品リクエストの管理に適用できるその他のメソッドです。

  • Issue Return Refund を使用して、返品された商品に対してバイヤーに全額または一部返金を発行します。このメソッドは、セラーがバイヤーに商品を保持するように伝えつつ全額返金する場合、またはバイヤーがSNADとして報告したがバイヤーとセラーが一部返金で合意した場合に使用されます。返金が送信されたら、Mark Return Refund Sent を使用して、商品に対して返金が発行されたことをバイヤーに通知します。
  • Get Return Files を使用して、返品リクエストに関連付けられたファイルを取得します。
  • Set Return Preferences を使用して、返品された商品に返品確認番号（RMA）が必要かどうかなどの返品設定を行います。
  • Get Return Preferences を使用して、RMAが必要かどうかや自動返品ルールがオンになっているかなど、セラーの返品設定を取得します。
  • Get Return Shipping Label を使用して、ラベルをダウンロードできるURLを含む返品配送ラベルのデータを取得します。
  • Get Shipment Tracking Info を使用して、特定の返品リクエストに関する配送追跡アクティビティを取得します。
  • Send Return Message を使用して、返品リクエストに関してバイヤーにメッセージを送信します。
  • Void Shipping Label を使用して、現在の返品配送ラベルを無効にします。
  • 必要に応じて、Escalate Return を使用して、返品リクエストをケースにエスカレーションします。これは、セラーがバイヤーから商品を返送されない場合や、返品された商品に問題がある場合などに使用できます。

支払い紛争の管理

eBayのバイヤーは、eBayプラットフォーム上で直接ではなく、決済プロバイダーを通じて支払い紛争（Payment Dispute）を開始する可能性があります。Fulfillment API の支払い紛争オペレーションにより、セラーはこれらのタイプの紛争を確認できます。このAPIには、作成された支払い紛争を取得するメソッドのほか、これらの支払い紛争を受け入れるか、または異議を申し立てる（contest）ためのオペレーション、およびセラーが紛争に異議を申し立てる場合にセラーの主張を裏付ける画像ファイルをアップロードするオペレーションが含まれています。

第三者の支払い紛争を管理するために使用されるFulfillment APIメソッドについて、以下で説明します。

  1. getPaymentDisputeSummaries を使用して、セラーに対して申し立てられた1つ以上の支払い紛争を取得します。注文ID、バイヤーのユーザーID、日付範囲、または紛争ステータスでフィルタリングできます。各支払い紛争について以下の情報が返されます。
    • paymentDisputeStatus: 支払い紛争のステータス。ステータスが ACTION_NEEDED の紛争は、支払い紛争がオープンであり、セラーがアクションを起こす必要があることを示します。
    • respondByDate: セラーが支払い紛争に応答しなければならない期日。
    • reason: バイヤーが支払い紛争を開始した理由。サポートされている理由のリストについては、DisputeReasonEnum を参照してください。
    • paymentDisputeId: 支払い紛争の一意の識別子。この値は将来の参照のために保存する必要があります。
  2. セラーが対処する必要があるオープンな紛争の詳細を取得するには、getPaymentDispute を使用します。
  3. acceptPaymentDispute を使用して紛争を受け入れるか、紛争に異議を申し立てます。支払い紛争が受け入れられた場合、バイヤーに返金され、紛争は終了します。セラーが支払い紛争に異議を申し立てることを選択した場合は、次の手順に進んでください。
  4. uploadEvidenceFile を使用して、紛争への異議申し立てに使用する各ファイルをアップロードします。
  5. 前の手順で返された fileId の値を参照し、addEvidence を使用して証拠セットを作成し、1つ以上のアップロードされたファイルを証拠セットに追加します。必要な証拠の種類は、バイヤーの紛争理由によって異なります。サポートされている種類の完全なリストについては、EvidenceTypeEnum を参照してください。
  6. 証拠セットが作成されたら、contestPaymentDispute を使用して正式に紛争に異議を申し立てます。アップロードした証拠はすでに紛争に関連付けられています。

以下は、Fulfillment APIを使用した支払い紛争の管理に適用できるその他のメソッドです。

  • getActivities を使用して、支払い紛争のアクティビティログを取得します。これには、作成から解決までの紛争の各アクションのタイムスタンプが含まれます。
  • updateEvidence を使用して、既存の証拠セットに1つ以上の証拠ファイルを追加します。
  • fetchEvidenceContent を使用して、支払い紛争の特定の証拠ファイルを取得します。

コードサンプル

支払い済み注文の取得 

curl -X GET "https://api.ebay.com/sell/fulfillment/v1/order"
-H "Authorization:Bearer OAUTH_token"

注文返品リクエストの検索 

curl -X GET "https://api.ebay.com/post-order/v2/return/search"
-H "Authorization:Bearer OAUTH_token"

エラーハンドリング

  • ファイル形式が無効であるために uploadEvidenceFile コールが失敗した場合は、ファイルが .JPEG、.JPG、または .PNG ファイルのいずれかであること、および画像のアップロードに使用されるキーの名前が 'file' であることを確認してください。
  • 紛争に異議を申し立てるための証拠が利用できないために contestPaymentDispute コールが失敗した場合は、支払い紛争に異議を申し立てる前にすべての証拠ファイルをアップロードしていることを確認してください。セラーが正式に紛争に異議を申し立てた後は、addEvidence および updateEvidence メソッドは使用できなくなります。
  • 無効な配送追跡番号のために createShippingFulfillment コールが失敗した場合は、リクエストに入力された追跡番号を確認してください。配送追跡番号では英数字のみがサポートされています。配送ラベル上の追跡番号にスペースが含まれていても、APIリクエストにはスペースを含めないでください。
  • 1つ以上のラインアイテムが同梱請求書の対象外であるために AddOrder コールが失敗した場合は、含まれているラインアイテムが同梱請求書注文の基本要件を満たしていることを確認してください。要件と対象外カテゴリのリストについては、Combined invoiceのドキュメントを参照してください。
  • Post-Order APIのさまざまなメソッド、および Fulfillment API の issueRefund メソッドは、EUまたは英国に拠点を置くセラーが使用する場合、デジタル署名が必要です。このデジタル署名がヘッダーに含まれていない場合、エラーが発生します。詳細および影響を受けるメソッドのリストについては、Digital Signatures for APIsのガイドを参照してください。

ベストプラクティス

  • Fulfillment APIを使用して配送フルフィルメントを作成する場合、Trading APIの GeteBayDetails コールを使用し、リクエストに DetailName フィールドを含めてその値を ShippingCarrierDetails に設定することで、最新の配送キャリア列挙値を取得できます。
トップに戻る