9.【ハンズオンプロジェクト②】Trading APIで商品を新規登録・更新・削除する (CUD)

前回の記事はこちら

前回のハンズオンプロジェクト第一弾では、GetItemコールを使って商品の情報を「読み取る(Read)」スキルをマスターしました。APIから返ってきたXMLのレスポンスを読み解く、という重要な一歩を踏み出しましたね。

今回は、プロジェクトの第二弾です。商品管理の残りの部分、「C (Create) - 作成」「U (Update) - 更新」「D (Delete) - 削除」を一気に体験します。この三つの操作をマスターすれば、あなたはAPIを通じた商品管理の基本を完全に習得したことになります。

さあ、Postmanを開いて、一緒にプロジェクトを完成させましょう！

1. C (Create) - AddItemで商品を新規登録する

まずは、API経由でサンドボックスに新しい商品をゼロから出品してみましょう。

ステップ1：Postmanの準備

Postmanで新しいリクエストを作成し、「AddItem Project」と名付けます。メソッドは POST、URLは https://api.sandbox.ebay.com/ws/api.dll です。

ヘッダータブには、これまでのプロジェクトと同様に認証情報などを設定しますが、一番重要な X-EBAY-API-CALL-NAME には AddItem と指定してください。

ステップ2：リクエストボディの作成

AddItemは、出品する商品の詳細な情報をすべて含める必要があるため、リクエストボディが少し長くなります。Bodyタブに、以下のXMLを貼り付けてください。これは、出品に必要な最小限の項目を含んだサンプルです。

<?xml version="1.0" encoding="utf-8"?>
<AddItemRequest xmlns="urn:ebay:apis:eBLBaseComponents">
  <ErrorLanguage>en_US</ErrorLanguage>
  <WarningLevel>High</WarningLevel>
  <Item>
    <Title>【API出品】日本の素敵なテスト商品</Title>
    <Description>これはPostmanとTrading APIを使って出品されたテスト商品です。</Description>
    <PrimaryCategory>
      <CategoryID>29223</CategoryID>
    </PrimaryCategory>
    <StartPrice>1.0</StartPrice>
    <CategoryMappingAllowed>true</CategoryMappingAllowed>
    <Country>US</Country>
    <Currency>USD</Currency>
    <DispatchTimeMax>3</DispatchTimeMax>
    <ListingDuration>Days_7</ListingDuration>
    <ListingType>Chinese</ListingType>
    <PictureDetails>
      <PictureURL>https://mysamplepicture.com/14.jpg</PictureURL>
    </PictureDetails>
    <PostalCode>95125</PostalCode>
    <Quantity>1</Quantity>
    <ItemSpecifics>
      <NameValueList>
        <Name>Title</Name>
        <Value>Harry Potter and the Philosophers Stone</Value>
      </NameValueList>
      <NameValueList>
        <Name>Publisher</Name>
        <Value>Smashwords</Value>
      </NameValueList>
      <NameValueList>
        <Name>Author</Name>
        <Value>JK Rowling</Value>
      </NameValueList>
      <NameValueList>
        <Name>Language</Name>
        <Value>English</Value>
      </NameValueList>
    </ItemSpecifics>
    <ReturnPolicy>
      <ReturnsAcceptedOption>ReturnsAccepted</ReturnsAcceptedOption>
      <RefundOption>MoneyBack</RefundOption>
      <ReturnsWithinOption>Days_30</ReturnsWithinOption>
      <ShippingCostPaidByOption>Buyer</ShippingCostPaidByOption>
    </ReturnPolicy>
    <ShippingDetails>
      <ShippingType>Flat</ShippingType>
      <ShippingServiceOptions>
        <ShippingServicePriority>1</ShippingServicePriority>
        <ShippingService>USPSMedia</ShippingService>
        <ShippingServiceCost>2.50</ShippingServiceCost>
      </ShippingServiceOptions>
    </ShippingDetails>
    <Site>US</Site>
  </Item>
</AddItemRequest>

ステップ3：送信とItemIDの記録

「Send」ボタンを押してリクエストを送信します。成功すると、レスポンスに <Ack>Success</Ack> と表示されるはずです。

そして、レスポンスの中にある <ItemID> というタグを探してください。これが、新しく出品されたあなたの商品固有のIDです。

2. U (Update) - ReviseItemで商品情報を更新する

次に、先ほど出品した商品の価格を更新してみましょう。

ステップ1：Postmanの準備

新しいリクエスト「ReviseItem Project」を作成します。ヘッダーの X-EBAY-API-CALL-NAME には ReviseItem と指定します。

ステップ2：リクエストボディの作成

ReviseItemのボディは非常にシンプルです。どの商品を（ItemID）、どの項目を（例：StartPrice）、どう変更したいか、だけを記述します。

<?xml version="1.0" encoding="utf-8"?>
<ReviseItemRequest xmlns="urn:ebay:apis:eBLBaseComponents">
  <Item>
   <ItemID>ここに先ほど記録したItemIDを入力</ItemID>
   <Description>APIでReviseされました</Description>
   <StartPrice>199</StartPrice>
  </Item>
</ReviseItemRequest>

ステップ3：送信と更新内容の確認

リクエストを送信し、成功を確認します。では、本当に価格が変更されたか、どうやって確かめれば良いでしょうか？

ここで、前回のプロジェクトでマスターした GetItem の出番です。先ほど作ったGetItemリクエストのタブに戻り、同じItemIDで再度リクエストを送信してみてください。レスポンスの中の <StartPrice> が「1」から「199」に変わっていれば、更新成功です！

3. D (Delete) - EndItemで出品を終了する

最後に、この商品の出品を取り下げて、プロジェクトを締めくくりましょう。

ステップ1：Postmanの準備

新しいリクエスト「EndItem Project」を作成し、ヘッダーの X-EBAY-API-CALL-NAME には EndItem と指定します。

ステップ2：リクエストボディの作成

EndItemに必要なのは、どの商品を（ItemID）、どういう理由で（EndingReason）終了させるか、です。EndingReasonは必須項目です。

<?xml version="1.0" encoding="utf-8"?>
<EndItemRequest xmlns="urn:ebay:apis:eBLBaseComponents">
   <ItemID>ここに先ほど記録したItemIDを入力</ItemID>
   <EndingReason>NotAvailable</EndingReason>
</EndItemRequest>

ステップ3：送信と最終確認

リクエストを送信し、成功を確認します。

そして、最後の最後に、もう一度だけGetItemでこのItemIDを問い合わせてみてください。

今度は <Ack>Success</Ack> というレスポンスが返ってくるはずですが、<ListingStatus> では Ended が見つけられます。ここに注意すべきなのは、厳密に言えばEndItemは出品のデータを削除することではなく、出品を終了（無効）にするAPI呼び出しです。実際の商品のデータの削除は、eBayのシステムが自動的に実行（数ヶ月後）します。

サイトでの効果は、下の画像のように見えます。

まとめと次回予告

素晴らしい！これで、あなたの商品はAPIによって生まれ（Create）、変更され（Update）、そしてその役目を終えました（Delete）。このCUDサイクルを自らの手で完遂したことで、あなたはAPIによる商品管理の、最も重要で基本的なスキルを完全に手にしたことになります。

さて、私たちのAPI入門講座も、いよいよ次が最終回です。

最終回では、これまでの学びを振り返り、エラーへの対処法やAPIの利用上限といった、より実践的な知識をご紹介します。 さらに、Trading API以外の便利なAPIの世界も覗いてみましょう。この旅の締めくくりと、次なるステップへの展望をお届けします。

APIは難しくない！あなたのビジネスを加速させる魔法の杖です。

リファレンス１：AddItem主要必須フィールドと設定例

リファレンス２：ReviseItem更新可能フィールドと注意点

リファレンス３：EndItem主なEndingReasonとその意味

次の記事はこちら