Trading APIについて

eBay Trading APIは、ユーザ関連データへの認証仕組みを持つ安全なアクセスを提供します。 Trading APIを使えば、出品・受注・発送など販売業務を管理する機能が実装できます。ここでは、代表的な機能をピックアップして紹介します。詳細なドキュメントは、英語サイトを参照ください。

APIコール方式

Trading API利用するには、APIコールリクエストを送信し、レスポンスを取得する必要があります。ここでは、APIコールを呼び出す方法と条件を説明します。

文字コード

文字コードは、UTF-8のみです。アプリケーションの場合、ユーザから提供される入力（商品説明、タイトル、住所など）がUTF-8エンコードされたものかどうか確認し、必要に応じて文字コード変換を行う必要があります。

リクエスト方式

Trading APIコールは、全てHTTP POSTリクエストを受け付けます。 POSTするデータには、XMLとSOAPの2方式があります。

XML

XML形式でリクエストデータを送り、XML形式でレスポンスを受け取ることができます。

<GetItemRequest xmlns="urn:ebay:apis:eBLBaseComponents">
  <ItemID>110043671232</ItemID>
</GetItemRequest>

SOAP

SOAP 1.1、1.2バージョンがサポートされています。

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns="urn:ebay:apis:eBLBaseComponents">
   <soap:Header/>
   <soap:Body>
      <GetItemRequest>
         <ItemID>110043671232</ItemID>
      </GetItemRequest>
   </soap:Body>
</soap:Envelope>

SOAPリクエストに対するレスポンスは、SOAP形式のみで受け取れます。

サービスURI

Trading APIリクエストは、サンドボックスまたはプロダクション環境のURIに送信します。SOAP APIの場合は、正しくルーティングされるようにクエリストリングを付け加える必要があります。

環境/形式	XML	SOAP
Sandbox	https://api.sandbox.ebay.com/ws/api.dll	https://api.sandbox.ebay.com/wsapi
Production	https://api.ebay.com/ws/api.dll	https://api.ebay.com/wsapi

APIコールは、HTTPS/SSLを利用する必要があります。

APIコールパラメータ

HTTPヘッダー(XML形式のみ)

XML APIでは、以下のHTTPヘッダーを挿入する必要があります。

パラメータ名	必須有無	説明
X-EBAY-API-COMPATIBILITY-LEVEL	必須	eBayリリースバージョンを指定。バージョンのルールなど詳細は、こちらを参照。
X-EBAY-API-CALL-NAME	必須	利用するコール名。(例：AddItem) この値はXMLリクエスト名と合っている必要があります。例えば、AddItemRequestを送信している場合、この値にAddItemをセットします
X-EBAY-API-SITEID	必須	eBayサイトID。利用可能なサイトとその値（数値）は、SiteCodeTypeを参照。
X-EBAY-API-DEV-NAME	条件による	eBay developer programに登録したデベロッパーID（DevID）。このヘッダーは、ユーザトークンの取得、更新のAPIコール(GetSessionID, FetchToken, GetTokenStatus, RevokeToken)にのみセットします（必須）。その他のAPIコールでは無視されます。この値が手元にない場合、My Account > View Keysから確認できます。
X-EBAY-API-APP-NAME	条件による	eBay developer programに登録したアプリケーションID(AppID)。このヘッダーは、ユーザトークの取得、更新のAPIコール(FetchTokenなど)にのみセットします（必須）。その他のAPIコールでは無視されます。AddItemやその他商品リストを返すAPIコールの場合は、このヘッダーを、指定しないで下さい。アプリケーションIDは、開発者が作成したアプリケーション単位で一意な値になります。アプリケーションID証明書IDは対になっており、一人の開発者が複数の対を作成することが可能です。
X-EBAY-API-CERT-NAME	条件による	eBay developer programに登録した証明書ID(CertID)。このヘッダーは、ユーザトークの取得、更新のAPIコール(FetchTokenなど)にのみセットします（必須）。その他のAPIコールでは無視されます。AddItemやその他商品リストを返すAPIコールの場合は、このヘッダーを、指定しないで下さい。証明書IDは、開発者が作成したアプリケーション単位で一意な値になります。
Content-Type	推奨	“text/xml”をセットします。他の値をセットした場合、正常なレスポンスが得られない可能性があります。ContentTypeヘッダーを自動的に指定するライブラリーなどを使っている場合、”text/xml”がセットされていることを確認して下さい。
Content-Length	推奨	送信しているXMLリクエストのサイズ。送信されたデータサイズを特定するために利用される。

SOAP URLパラメータ(SOAP APIのみ)

SOAP APIでは、以下のクエリパラメータをセットする必要があります。

キー	値
appid	eBay developer programに登録したアプリケーションID(AppID)。このヘッダーは、ユーザトークの取得、更新のAPIコール(FetchTokenなど)にのみセットします（必須）。その他のAPIコールでは無視されます。AddItemやその他商品リストを返すAPIコールの場合は、このヘッダーを、指定しないで下さい。ユーザトークンを取得する場合は、このappidをSOAPエンベロープにも指定する必要があります。（DevId, CertIdと一緒に)
version	仕様するペイロードスキーマのバージョン。このバージョンは、メッセージ本体のバージョンと合っている必要があります。詳細はRelease Versionsを参照。
callname	利用するコール名。(例：AddItem) コール名はメッセージ本体にも指定しますが、どのコールを呼び出しかを先に識別する必要があるため、クエリパラメータにも設定する必要があります。
siteid	対象とするサイトの。利用可能なサイトとその値（数値）は、SiteCodeTypeを参照。
Routing	単一ネームスペースサーバにつなぐには、Routing=newを指定。

以下に、SOAP APIリクエストURLのサンプルを示します。この例は、Java言語であり、URLの構成を示すためパラメータ値がハードコーディングした形になっています。

// Define the endpoint (e.g., the Sandbox Gateway URI) String endpoint = "https://api.sandbox.ebay.com/wsapi"; // Define the query string parameters. String queryString = "?callname=AddItem" + "&siteid=0" + "&appid=myappid" + "&version=349"; + "&Routing=new"; String requestURL = endpoint + queryString; EBayAPIInterfaceServiceLocator sl = new EBayAPIInterfaceServiceLocator(); EBayAPIInterface privBinding = sl.geteBayAPI(new URL(requestURL));
((EBayAPISoapBindingStub)privBinding).setTimeout(60000);

セキュアなAPIリクエストについて

出品や入札などのAPIアクセスをする際は、APIコールの前にユーザー認証した状態(eBayにログインした状態）でAPIリクエストをする必要があります。詳細についてはこちらのドキュメントをご覧ください。

アクセス制限

Trading APIは、一日に5000リクエストまでの上限があります。互換アプリケーションチェックを行うことでこの上限を増やすことができます。 (各APIのリクエスト上限はこちら)

実際の使用例

Trading APIでは、eBayに対するセラーのアクションを十分にカバーできるよう、数多くのAPIコールが用意されています。ここでは、その中から代表的なものとして幾つか紹介します。全APIコールについては、Call Indexを参照下さい。

セラー向けツール提供（ユーザトークンを使用）

出品など販売支援アプリケーションを提供する場合は、そのアプリケーションからセラーに代わってデータにアクセスする権限が必要になります。その権限移譲を安全に行うために、ユーザトークンを使った仕組みが用意されています。アプリケーション側から、利用するセラーの同意の上、ユーザトークンを取得することで、セラーに代わってeBayに対する必要な操作をアプリケーションから行うことが可能になります。ここでは、以下のような前提条件で利用方法を説明します。ユーザトークンの取得方法については、ユーザトークンの取得を参照ください。英語サイトでは、詳細な処理フローを説明したチュートリアルもあります。

APIコール

以下の前提条件でユーザトークンを取得し、実際にAPIコールするための条件を説明します。

mydev というデベロッパーアカウントで、myappというアプリを作成
userA というユーザが myappアプリを使ってeBayに出品

この場合、認証関連キーはそれぞれ以下のように設定する必要があります。

DevID : mydevアカウントを識別するキー
AppID ： myapp アプリを識別するキー
CertID : API Callするときにアプリケーションを認証するもの（ユーザトークンとは関連がない）
eBayAuthToken ： userAの認証トークン（ユーザトークン）

出品

AddItem APIコールで出品できます。リクエストが正常処理され出品されると、出品した商品にeBayで一意なキー、アイテムID(Item ID)が振られます。レスポンスには、このアイテムIDと一緒に出品料を含め、出品された状態に関する情報が含まれます。ここからサンプルXMLを参考にすることができます。 1回のAPIコールで複数の商品を出品した場合は、AddItemsを利用可能です。もし、バリエーション(色、サイズなど)を持つ固定価格の商品を出品したい場合は、AddFixedPriceItemをご利用下さい。 AddItemで出品しようとしているデータが正しいかどうかをチェックできる、VerifyAddItemが用意されています。 eBayでは出品料が発生するため、テストとして出品する際、AddItem自体を利用しないことをお勧めします。テスト環境として、サンドボックスが用意されているので、テスト関連のAPIコールはサンドボックスをご利用下さい。

商品情報を取得

出品した商品など、特定の商品を取得する場合、GetItemを使います。前述したアイテムIDなどのキーを指定し、商品情報を取得します。レスポンスに含まれる内容を、DetailLevelニュー力フィールドで制御します。全ての情報をレスポンスに含めたい場合は、DetailLevelにReturnAllを指定します。同じセラーの複数の商品を取得したい場合は、GetItemを複数回呼び出す代わりに、GetSellerListを利用できます。 APIコールのサンプルは、GetItem Samplesを参照下さい。

出品中の商品リストを取得

セラー自身の商品リストを取得する場合、GetMyeBaySellingを利用します。 GetMyeBaySellingでは、レスポンスに含める商品を状態（現在出品中（Active)、入札された、販売済み、販売されなかった）に応じて指定可能です。例えば、現在出品中の商品を含める場合、

  <ActiveList>
    <Include>true</Include>
  </ActiveList>

のように指定できます。また、レスポンスのリストのソート順、ページネーションも指定可能です。 APIコールのサンプルは、GetMyeBaySelling Samplesを参照下さい。 GetMyeBaySellingでは全て25,000件を超える件数を取得できない制約があります。その場合、GetSellerListを使うことで全ての商品情報が取得可能です。

通知を受け取る

eBayでは、出品の終了、落札、商品が販売されるなど、特定のイベントに対して通知を受け取るPlatform Notifications機能が用意されています。通知はSOAPメッセージとして、設定された通知先（アプリケーションのURL、メールアドレスなど）に送信されます。通知を受け取るには、APIコールで通知受け取り設定を行うことができます。通知はイベントが発生したタイミングで送信されますが、ネットワーク遅延など意図しない遅れが発生することがあります。そのような問題を防ぐため、定期的なAPIコールで確認することをお勧めします。例えば、商品が落札されたイベントの通知を受け取っている場合、GetOrders APIコールを定期的に呼び出すようにします。詳細なユーザガイドは、Platform Notifications Guideを参照下さい。 Platform Notification以外で、Client Alerts APIという仕組みがあります。 Client Alertsは、クライアント側からeBay側にアラートがあれば取得します。つまり、プル型(一方、Platform Notificationsはプッシュ型)方式です。

プラットフォーム通知受け取り設定

通知受け取りの設定を行うAPIコールは、SetNotificationPreferencesです。どのようなイベントに対して通知を受け取れるかは、NotificationEventTypeCodeTypeを参照下さい。現在設定されている設定については、GetNotificationPreferencesで確認できます。 GetNotificationsUsageで、通知の送信状況も確認可能です。通知受け取り先として、HTTP POST送信可能なURL、又はメールアドレスが指定可能です。いずれも送信データとしてSOAPメッセージが送信されます。メッセージ受け取り後は、XMLパースすることで内容を解釈します。通知受け取り設定を行うと、eBayではユーザトークンからアプリケーションIDを特定し、そのアプリケーションに設定を紐付けます。

プラットフォーム通知を受け取る

通知受け取り設定後、eBayからアプリケーションに通知を送信されるようになります。アプリケーションを介して通知設定されているイベントを発生させた場合（例えば、新規出品に通知設定をし、AddItemで出品した場合）、eBay側でユーザトークンからアプリケーションを特定し、そのアプリケーションの通知先に通知を送信します。通知先がURLの場合、通知を受け取ったらHTTPステータス「200 OK」レスポンスを返す必要があります。もしレスポンスがない場合は、eBayは失敗とみなし、再送信はしません。通知先URLのレスポンス失敗し続けると、eBay側でそのアプリケーションに対する通知を止める可能性があります。送信される通知の仕様については、Receiving Platform Notificationsを参照下さい。

受注データを取得

受注管理用にデータ取得する際は、GetOrdersがお勧めです。このAPIコールは、セラーが自身の受注データを取得することはもちろん、バイヤーが自身の購入データを取得する際も利用できます。取得する受注データを絞ったり、特定の受注データのみ取得する場合、以下の方法があります。

OrderIDArrayに一つまたは複数のOrderIDを指定することで、特定の受注データを取得できます。
CreateTimeFrom/CreateTimeToとModTimeFrom/ModTimeToを指定することで、ある期間内の受注データを取得できます。NumberOfDaysを指定して、本日より指定した日数だけさかのぼって受注データを取得することも可能です。
OrderRoleを指定して、バイヤーまたはセラーのデータに限定します。
OrderStatusにActive(完了待ち)、Completed(完了)、Shipped(発送済み)などを指定し、特定の状態の受注データに限定します。
Paginationを指定して、レスポンスに含まれる件数を決定します。1回のコールで最大100件まで含まれます。コールした結果、さらにデータがあるかどうかの判定は、HasMoreOrdersの値で判断します。

OrderIDが指定されている場合は、他の入力フィールドは全て無視されます。 APIコールのサンプルは、GetOrders Samplesを参照下さい。

追跡番号を登録する

eBayでは、商品発送時に発送状況が確認できるよう、追跡番号(Tracking Number)を登録することが求められます。追跡番号登録専用のAPIコールではありませんが、CompleteSaleを利用して追跡番号が登録できます。このAPIコールは、受注後の様々な処理を実施する際に利用するものです。

商品を発送したら、発送済みフラグをたてる
追跡番号を登録する
バイヤーにフィードバックを送る

追跡番号を登録するには、CompleteSaleでShipmentTrackingDetails内にShipmentTrackingNumberを設定します。実際のXML例は、Adding/Updating Shipment Tracking Detailsから確認できます。 CompleteSaleのサンプルは、CompleteSale Samplesを参照下さい。