パートナーAPI
ガイド

オプション1 : API を使用してカタログを更新する

APIを使用して商品の詳細をカタログに追加します。

APIを使用して、商品コード、価格、在庫の詳細、画像のURLなど、商品の詳細を更新できます。さらに、位置情報や高脂肪、高糖質、高塩分（HFSS）情報も更新できます。

前提条件

カタログの作成をリクエストする前に、APIキーとベースURLが必要です。

  1. 有効なAPIキーが必要になります。APIキーを取得するには、次の手順を実行します。

    1. EpsilonのRetail Mediaチームアカウントにログインします。

    2. ページの右上に移動し、ドロップダウンメニューをクリックします。

    3. ドロップダウンメニューから[統合設定]を選択します。

    4. APIキータブをクリックします。シークレットAPIキーは最初は非表示になっています。表示するには、[表示]ボタンをクリックします。表示されたら、シークレットAPIキーをコピーします。このキーをAPI呼び出しを行うために使用します。

  2. APIエンドポイントのベースURLが必要になります。例：https://staging-test.citrusad.com/v1/ads/generate HTTP/1.1. ベースURLについては、テクニカルアカウントマネージャーに確認してください。

商品を追加するための標準コンテキスト

カタログを作成したら、APIを使って商品をカタログに同期させることができます。次の例は、商品を追加する標準的なコンテキストを示しています。

リクエスト指標

クエリと本文のパラメータは次のとおりです。

クエリパラメータ

対象type説明
teamId文字列、任意チームのID。もし teamId が指定されていない場合は、認証で指定された teamId がデフォルトになります。

本文パラメータ

対象type説明
catalogId文字列、必須商品が属するカタログの識別子。
gtin文字列、必須商品のGTIN（Global Trade Item Number）。
inventory数字、任意商品の在庫数。
price数字、任意商品の価格。
categoryHierarchy文字列の配列、任意商品が属するカテゴリーの階層。
tags文字列の配列、任意製品に関連付けられたタグ。
filters文字列の配列、任意商品に適用されたフィルター。

リクエスト例

POST $BASE_URL/v1/catalog-products?teamId=<YOUR_TEAM_ID> HTTP/1.1 
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
    "catalogProducts": [
        {
            "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
            "gtin": "23556578965543",
            "inventory": 50,
            "price": "19.99",
            "tags": [
                 "imageurl:https://your.image.host.com/image.jpg","name:Covergirl Clean 120 Creamy Natural Liquid Foundation30mL"
            ],
            "filters": [
                 "category:Health&Beauty","category:Grocery","Brand:Covergirl","Special_Flag:0"
            ]
        }
    ]
}

リクエストレスポンス

{
    "catalogProducts": [
        {
            "teamId": "e8158f9b-bbb9-49fb-93fe-3ad481ca8450",
            "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
            "gtin": "23556578965543",
            "inventory": 50,
            "price": 19.99,
            "tags": [
                 "imageurl:https://your.image.host.com/image.jpg",
                 "name:Covergirl Clean 120 Creamy Natural Liquid Foundation30mL"
            ],
            "filters": [
                 "category:Health&Beauty",
              	 "category:Grocery",
              	 "Brand:Covergirl",
              	 "Special_Flag:0"
            ],
            "groups": [],
            "profit": null
        }
    ]
}

位置情報を更新する

また、商品が販売されているさまざまな店舗のフィルターを更新することもできます。この機能は、店舗やロケーションレベルで商品情報を最適化するのに便利です。

リクエスト例

POST $BASE_URL/v1/catalog-products?teamId=<YOUR_TEAM_ID> HTTP/1.1 
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
    "catalogProducts": [
        {
            "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
            "gtin": "23556578965543",
            "inventory": 50,
            "price": "19.99",
            "tags": [
                 "imageurl:https://your.image.host.com/image.jpg","name:Covergirl Clean 120 Creamy Natural Liquid Foundation30mL"
            ],
            "filters": [
                 "category:Health&Beauty","category:Grocery","Brand:Covergirl","Special_Flag:0","location:123","location:ABC"
            ]
        }
    ]
}

レスポンス例

{
    "catalogProducts": [
        {
            "teamId": "e8158f9b-bbb9-49fb-93fe-3ad481ca8450",
            "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
            "gtin": "23556578965543",
            "inventory": 50,
            "price": 19.99,
            "tags": [
                 "imageurl:https://your.image.host.com/image.jpg",
                 "name:Covergirl Clean 120 Creamy Natural Liquid Foundation30mL"
            ],
            "filters": [
                 "category:Health&Beauty",
              	 "category:Grocery",
              	 "Brand:Covergirl",
              	 "Special_Flag:0",
              	 "location:123",
              	 "location:ABC"
            ],
            "groups": [],
            "profit": null
        }
    ]
}

HFSS情報を更新する

商品の更新にHFSS（高脂肪、高糖質、高塩分）情報を含めるには、次の値を持つフィルターを送信する必要があります。 hfss:true や hfss:falseこれにより、Epsilon Retail MediaはHFSS基準に基づいてインターフェースを適切にフィルタリングできるようになります。

リクエスト例

POST $BASE_URL/v1/catalog-products?teamId=<YOUR_TEAM_ID> HTTP/1.1 
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
    "catalogProducts": [
        {
            "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
            "gtin": "23556578965543",
            "inventory": 50,
            "price": "19.99",
            "tags": [
                 "imageurl:https://your.image.host.com/image.jpg","name:Covergirl Clean 120 Creamy Natural Liquid Foundation30mL"
            ],
            "filters": [
                 "hfss:true","category:Health&Beauty","category:Grocery","Brand:Covergirl","Special_Flag:0","location:123","location:ABC"
            ]
        }
    ]
}

複数の商品を追加する

複数の商品を更新する場合、1回のリクエストで最大100件のアイテムを処理できます。次の例は、2つの商品を更新する場合のコンテキストを示しています。

リクエスト例

POST $BASE_URL/v1/catalog-products?teamId=<YOUR_TEAM_ID> HTTP/1.1 
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
    "catalogProducts": [
        {
            "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
            "gtin": "23556578965543",
            "inventory": 50,
            "price": "19.99",
            "tags": [
                 "imageurl:https://your.image.host.com/image.jpg",
                 "name:Covergirl Clean 120 Creamy Natural Liquid Foundation30mL"
            ],
            "filters": [
                 "category:Health&Beauty",
              	 "category:Grocery",
              	 "Brand:Covergirl",
              	 "Special_Flag:0"
            ],
            "profit": "1.50"
        },
        {
            "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
            "gtin": "23556578965738",
            "inventory": 26,
            "price": "8.50",
            "tags": [
                "imageurl:https://your.image.host.com/image.jpg",
                "name:Kelloggs Froot Loops Breakfast Cereal 500g"
            ],
            "filters": [
                "Brand:Kelloggs",
                "category:Pantry",
                "category:BreakfastFoods",
                "category:Cereals",
                "Special_Flag:0"
            ],
            "profit": "0.50"
        }
    ]
}

リクエストレスポンス

{
    "catalogProducts": [
        {
            "gtin": "23556578965543",
            "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
            "price": 19.99,
            "teamId": "e8158f9b-bbb9-49fb-93fe-3ad481ca8450",
            "groups": [],
            "tags": [
                 "imageurl:https://your.image.host.com/image.jpg",
                 "name:Covergirl Clean 120 Creamy Natural Liquid Foundation30mL"
            ],
            "filters": [
                 "category:Health&Beauty",
              	 "category:Grocery",
              	 "Brand:Covergirl",
              	 "Special_Flag:0"
            ],
            "inventory": 50,
            "profit": 1.50,
            "tags": [
                "Natural",
                "Lasting",
                "Dry Skin",
                "Beige"
            ]
        },
        {
            "gtin": "23556578965736688",
            "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
            "price": 8.50,
            "teamId": "e8158f9b-bbb9-49fb-93fe-3ad481ca8450",
            "groups": [],
            "tags": [
                "imageurl:https://your.image.host.com/image.jpg",
                "name:Kelloggs Froot Loops Breakfast Cereal 500g"
            ],
            "filters": [
                "Brand:Kelloggs",
                "category:Pantry",
                "category:BreakfastFoods",
                "category:Cereals",
                "Special_Flag:0"
            ],
            "inventory": 26,
            "profit": 0.50,
            "tags": [
                "Pantry",
                "BreakfastFoods",
                "Cereals",
                "Kelloggs"
            ]
        }
    ]
}

商品フィルターを追加する

CitrusAd APIを通じて広告を生成する過程で、商品フィルターを適用して結果を絞り込むことができます。これには、 productFilters フィールドをPOSTリクエストに含めることで対応できます。 productFilters フィールドは、それぞれが異なるフィルターを表す1つ以上のサブ配列を含む配列です。

リクエスト例

以下はPOSTリクエストの例で、宛先は /v1/ads/generate エンドポイントです。このエンドポイントには次が含まれます。 productFilters:

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
    "customerId": "wertg5432a",
    "sessionId": "ec9-4e07-881d-3e9", 
    "placement": "search",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "searchTerm": "chocolate",
    "productFilters": [
         ["category:Cupboard"],["dietary:Gluten-free"]
    ],
    "options": {
                             "filterMode": "AndOr"
                             },
    "maxNumberOfAds": 3
}

この例では、

  • 次の2つの商品フィルターが含まれています。 category:Cupboard と dietary:Gluten-freefilterModeオプションが AndOrに設定されているため、API はこれら両方のフィルターに一致する商品の広告を返します。
  • 返される広告には、「Cupboard（食器棚）」カテゴリーに該当し、「Gluten-free（グルテンフリー）」でもある商品のみが表示されます。返される広告の数は、指定された maxNumberOfAds（この例では3に設定）を超えません。

正しく productFiltersを使用することで、キャンペーンのニーズに合わせて広告結果を効果的にカスタマイズできます。

重要な商品画像と名前を含める

CitrusAdポータルでのキャンペーン作成プロセス中の検索性を向上させるため、商品の画像と名前を提供します。それぞれのタグ内の画像と名前の値を割り当てます。これらの値はCitrusAdに送信されます。

リクエスト例

以下はPOSTリクエストの例で、宛先は /v1/catalog-products エンドポイントへのPOSTリクエストの例です。

POST $BASE_URL/v1/catalog-products?teamId=<YOUR_TEAM_ID> HTTP/1.1 
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
    "catalogProducts": [
        {
            "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
            "gtin": "23556578965543",
            "inventory": 50,
            "price": "19.99",
            "tags": [
                 ""imageurl:https://your.image.host.com/image.jpg","name:Covergirl Clean 120 Creamy Natural Liquid Foundation30mL"
            ],
            "filters": [
                 "category:Health&Beauty","category:Grocery","Brand:Covergirl","Special_Flag:0"
            ]
        }
    ]
}

上記のリクエストの例では、タグフィールドに画像のURLと商品名という2つの重要な情報が含まれています。 imageurl と name はキーであり、それぞれのキーの後にそれぞれの値が続きます。

  • imageurl:https://your.image.host.com/image.jpgは、商品画像がホストされているURLを提供します。
  • name: Covergirl Clean 120 Creamy Natural Liquid Foundation 30mLが商品名となります。

更新： 4か月前