> ## Documentation Index
> Fetch the complete documentation index at: https://docs.topsort.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Listings sponsorisés à partir d'un ensemble de produits

> Comment organiser une enchère pour un ensemble de produits

Dans cet exemple, nous utiliserons l'API pour organiser une [enchère](/en/ad-server/auctions/auctions-api) pour un ensemble de [produits](/en/ad-server/catalog/).

Seules les enchères qui ciblent les produits de cet ensemble auront une chance de gagner cette enchère. Les enchères qui ciblent d'autres produits ne participeront pas.

**Cela vous permet un contrôle total sur les produits affichés et où**, tout en permettant à vos vendeurs de promouvoir des produits.

## Cas d'utilisation

Nous ne prescrivons pas comment vous créez votre ensemble de produits, vous pouvez utiliser n'importe quel algorithme que vous souhaitez. Tout ce dont nous avons besoin est une liste d'ID de produits.

Par exemple, utilisez votre propre algorithme pour générer :

* Des ventes croisées.
* Des produits connexes.
* Des ventes incitatives à la caisse.

Collectez les ID résultants et transmettez-les à une enchère.

Vos vendeurs pourront alors enchérir pour des opportunités d'apparaître dans des positions précieuses sur la marketplace.

## Exemple d'appel API

### Requête

Supposons que nous utilisons une sorte d'algorithme pour créer un ensemble d'ID de produits. Nous pouvons ensuite les transmettre à une requête d'enchère :

```json theme={null}
{
  "auctions": [
    {
      "type": "listings",
      "slots": 2,
      "products": {
        "ids": ["p_PJbnN", "p_ojng4", "p_8VKDt", "p_Mfk15"]
      }
    }
  ]
}
```

La requête ci-dessus créera une seule enchère de listings :

* Elle aura un maximum de deux gagnants en raison du champ `slots`.
* Le `products.ids` est l'ensemble de produits. Ceux-ci doivent exister dans [votre catalogue](/en/ad-server/catalog/).

Comme dit précédemment, seules les enchères qui ciblent ces produits participeront à l'enchère.

Le point de terminaison d'enchères prend en charge jusqu'à 10 000 ID de produits par enchère, mais nous recommandons de n'envoyer pas plus de 500 des plus pertinents.

### Ajout de scores de qualité personnalisés

Vous pouvez parfois vouloir incorporer des scores de qualité personnalisés pour chaque produit. Le score de qualité
est un nombre entre 0 et 1 qui encode la pertinence des produits participants. L'utilisation de scores de qualité
aide à atténuer les risques et les pertes dus à des produits non pertinents gagnant des enchères.

Pour inclure des scores de qualité personnalisés dans la requête, modifiez le champ `products` comme indiqué ci-dessous :

```json theme={null}
{
  "auctions": [
    {
      "type": "listings",
      "slots": 2,
      "products": {
        "ids": ["p_PJbnN", "p_ojng4", "p_8VKDt", "p_Mfk15"],
        "qualityScores": [0.5, 0.4, 0.7, 0.6]
      }
    }
  ]
}
```

Dans cet exemple :

* Le produit `p_PJbnN` a un score de qualité de `0.5`.
* Le produit `p_ojng4` a un score de qualité de `0.4`.
* Le produit `p_8VKDt` a un score de qualité de `0.7`.
* Le produit `p_Mfk15` a un score de qualité de `0.6`.

**Important** : le nombre de scores de qualité doit correspondre au nombre d'ID de produits. S'ils ne correspondent pas, la requête échouera.

**Avertissement** : vous ne pouvez pas inclure de scores de qualité et une requête de recherche. Bien que l'organisation d'une enchère avec une requête de recherche et un
ensemble de produits soit autorisée, la requête ne peut pas inclure de scores de qualité personnalisés.

### Réponse

<Warning>
  **Ne mettez pas en cache cette réponse** ni ses résultats. Les enchères doivent être uniques par vue de page, c'est ce qui fait fonctionner le système.

  Si les résultats de l'enchère sont mis en cache, les mêmes résultats pourraient être affichés à plusieurs utilisateurs ou au même utilisateur plusieurs fois.
</Warning>

Si des enchères ciblant les produits existent, elles pourraient gagner cette enchère. La réponse résultante ressemblerait à quelque chose comme ceci :

```json theme={null}
{
  "results": [
    {
      "winners": [
        {
          "rank": 1,
          "type": "product",
          "id": "p_Mfk15",
          "resolvedBidId": "WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0="
        },
        {
          "rank": 2,
          "type": "product",
          "id": "p_PJbnN",
          "resolvedBidId": "WyJlX1BKYm5OIiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0="
        }
      ],
      "error": false
    }
  ]
}
```

À noter ici :

* Le type des gagnants est `product`, car nous organisons une enchère de listings.
* Les deux `id` gagnants correspondent à un ID de produit dans la requête.
* Il y a deux gagnants, le maximum autorisé par le champ `slots` dans la requête.

## Étapes suivantes

Les gagnants devront être combinés avec les données de produit pour créer un résultat qui peut être affiché à l'utilisateur final.

Consultez [cette page](/en/api-reference/examples/sponsored-listings/combining-results) pour un exemple.