Vous pouvez utiliser les API pour mettre à jour les informations du produit telles que le code produit, le prix, les informations sur le stock, l’URL de l’image, etc. Vous pouvez également mettre à jour les informations relatives à l’emplacement et aux produits riches en matières grasses, en sucre et en sel (HFSS).

Conditions préalables

Vous devez disposer des clés API et de l’URL de base avant de demander la création de catalogues.

Vous devez disposer d’une clé API valide. Procédez comme suit :
1. Connectez-vous au compte de votre équipe Retail Media d’Epsilon.
2. Allez en haut à droite de la page et cliquez sur le menu déroulant.
3. Sélectionnez Paramètres d’intégration dans le menu déroulant.
4. Cliquez sur l’onglet Clé API. Votre clé API secrète est initialement masquée. Pour l’afficher, cliquez sur le bouton Afficher. Une fois visible, copiez-la. Utilisez-la pour effectuer des appels API.
Vous devez avoir l’URL de base pour le point de terminaison d’API. Par exemple, https://staging-test.citrusad.com/v1/ads/generate HTTP/1.1. Vérifiez-la auprès de votre responsable de compte technique.

Contexte standard pour ajouter des produits

Une fois votre catalogue créé, vous pouvez y synchroniser des produits à l’aide de l’API. L’exemple ci-dessous présente un contexte standard d’ajout de produits.

Paramètres de la requête

Voici les paramètres de requête et de corps :

Paramètre de requête

objet	type	Description
ID de l'équipe	chaîne, facultatif	ID de votre équipe. Si aucun identifiant `teamId` n’est fourni, l’identifiant par défaut sera le `teamId` indiqué dans l’authentification.

Paramètre du corps

objet	type	Description
ID du catalogue	chaîne, obligatoire	Identifiant du catalogue auquel le produit appartient.
gtin	chaîne, obligatoire	Code article international (GTIN) du produit.
inventaire	numéro, facultatif	Stock du produit.
prix	numéro, facultatif	Prix du produit.
categoryHierarchy	tableau de chaînes, facultatif	Hiérarchie des catégories auxquelles le produit appartient.
Balises	tableau de chaînes, facultatif	Balises associées au Produit.
filtres	tableau de chaînes, facultatif	Filtres appliqués au produit.

Exemple de requête

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"
            ]
        }
    ]
}

Réponse à la requête

{
    "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
        }
    ]
}

Mettre à jour les informations relatives à l’emplacement

Vous pouvez également mettre à jour les filtres pour les différents emplacements de la boutique où vos produits sont disponibles. Cette fonctionnalité est utile pour optimiser les informations sur les produits au niveau de la boutique ou de l’emplacement.

Exemple de requête

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"
            ]
        }
    ]
}

Exemple de réponse

{
    "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
        }
    ]
}

Mettre à jour les informations HFSS

Pour inclure les informations HFSS (riches en matières grasses, en sucre et en sel) dans la mise à jour de votre produit, vous devez envoyer un filtre avec la valeur hfss:true ou hfss:false. Cela permet à Epsilon Retail Media de filtrer l’interface de manière appropriée sur la base des critères HFSS.

Exemple de requête

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"
            ]
        }
    ]
}

Ajouter plusieurs produits

Lorsque vous mettez à jour plusieurs produits, vous pouvez en traiter jusqu’à 100 par requête. L’exemple ci-dessous illustre le contexte de mise à jour de deux produits.

Exemple de requête

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"
        }
    ]
}

Réponse à la requête

{
    "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"
            ]
        }
    ]
}

Ajouter des filtres de produits

Lorsque vous générez des annonces via l’API CitrusAd, vous souhaitez peut-être appliquer des filtres de produits pour affiner vos résultats. Pour ce faire, vous pouvez inclure un productFilters champ dans votre requête POST. Le productFilters champ est un tableau qui contient un ou plusieurs sous-tableaux, qui représentent chacun un filtre différent.

Exemple de requête

Voici un exemple de requête POST vers le /v1/ads/generate point de terminaison, qui inclut 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
}

Dans cet exemple,

deux filtres de produits sont inclus category:Cupboard et dietary:Gluten-free. L’option filterMode est définie sur AndOr, ce qui signifie que l’API renverra des annonces pour des produits qui correspondent à ces deux filtres.
Les annonces renvoyées ne présenteront que des produits appartenant à la catégorie « Placard » et qui sont également « Sans gluten ». Le nombre d’annonces renvoyées ne dépassera pas la valeur indiquée maxNumberOfAds, qui est définie sur 3 dans cet exemple.

En utilisant correctement productFilters, vous pouvez personnaliser efficacement les résultats des annonces afin de mieux répondre aux besoins de votre campagne.

Inclure des images et des noms de produits essentiels

Pour optimiser la recherche au cours du processus de création de la campagne dans le portail CitrusAd, fournissez des images et des noms de produits. Attribuez les valeurs des images et des noms dans les balises respectives. Ces valeurs sont envoyées à CitrusAd.

Exemple de requête

Voici un exemple de requête POST vers le /v1/catalog-products point de terminaison, qui inclut les images et les noms des produits :

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"
            ]
        }
    ]
}

Dans l’exemple ci-dessus, le champ « balises » contient deux informations essentielles : l’URL de l’image et le nom du produit. imageurl et name sont les clés, et elles sont chacune suivies de leurs valeurs respectives.

imageurl:https://your.image.host.com/image.jpg fournit l’URL où l’image du produit est hébergée.
name:Covergirl Clean 120 Creamy Natural Liquid Foundation 30mL fournit le nom du produit.