> ## 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 sur les pages de catégories

Les exemples de cette page montrent comment organiser des [enchères](/en/ad-server/auctions/auctions-api) pour des produits appartenant à des [catégories](/en/ad-server/catalog/product-feed) spécifiques.

Seules les enchères qui ciblent des produits appartenant aux catégories données auront une chance de gagner ces enchères. Les enchères ciblant des produits appartenant à d'autres catégories ne participeront pas.

## Cas d'utilisation

L'organisation de ce type d'enchères sur les pages de recherche permettra à vos vendeurs de promouvoir des produits sur les pages de catégories.

<Note>
  **Catégories non traditionnelles :**

  Notre système de catalogue ne fait aucune hypothèse sur ce qu'est une catégorie.

  Si votre marketplace traite de maisons de vacances par exemple, les catégories pourraient être des emplacements géographiques au lieu de groupes de produits.
</Note>

## Spécification des catégories

Le point de terminaison `/auctions` prend en charge plusieurs façons de spécifier les catégories.

Lorsque vous créez une enchère, vous devez choisir **une** des méthodes suivantes :

| Méthode               | Champ pertinent         | Description                                                                                                                                                                               |
| :-------------------- | :---------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Catégorie unique      | `category.id`           | Les cibles d'enchères doivent appartenir à la catégorie. L'`id` de la catégorie est la même valeur utilisée lors de [l'upsert de produit](/en/api-reference/catalog-api/upsert-products). |
| Toutes les catégories | `category.ids`          | Les cibles d'enchères doivent appartenir à **toutes** les catégories.                                                                                                                     |
| Disjonctions          | `category.disjunctions` | Les cibles d'enchères doivent appartenir à au moins **une** des catégories de la disjonction.                                                                                             |

Examinons quelques exemples.

## Exemples d'appels API

### Requête : catégorie unique

```json theme={null}
{
  "auctions": [
    {
      "type": "listings",
      "slots": 2,
      "category": {
        "id": "laptop_bags"
      }
    }
  ]
}
```

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

* A un maximum de deux gagnants en raison du champ `slots`.
* N'autorise que les enchères qui ciblent des produits dans une seule catégorie. L'ID de catégorie est spécifié dans le champ `category.id`.

Dans ce cas, seules les enchères qui ciblent des produits dans la catégorie `laptop_bags` peuvent participer à l'enchère.

### Requête : toutes les catégories

```json theme={null}
{
  "auctions": [
    {
      "type": "listings",
      "slots": 2,
      "category": {
        "ids": ["summer_hats", "sale"]
      }
    }
  ]
}
```

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

* A un maximum de deux gagnants en raison du champ `slots`.
* N'autorise que les enchères qui ciblent des produits appartenant à **toutes les catégories**. Les ID de catégorie sont spécifiés dans le champ `category.ids`.

<Note>Ce champ est au pluriel. Il s'appelle `ids`, pas `id`.</Note>

Seules les enchères qui ciblent des produits appartenant à la fois aux catégories `summer_hats` et `sale` peuvent participer à cette enchère.

### Requête : disjonctions ("au moins une catégorie")

```json theme={null}
{
  "auctions": [
    {
      "type": "listings",
      "slots": 2,
      "category": {
        "disjunctions": [["large", "medium"]]
      }
    }
  ]
}
```

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

* A un maximum de deux gagnants en raison du champ `slots`.
* N'autorise que les enchères qui ciblent des produits appartenant à **l'une des catégories de la disjonction**. Les disjonctions sont spécifiées sous forme de tableaux de chaînes dans le champ `category.disjunctions`.

Seules les enchères qui ciblent des produits dans les catégories `large` ou `medium` peuvent participer à cette enchère.

### 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 les enchères ciblant des produits dans les catégories appropriées existent, une réponse à l'une des requêtes ci-dessus pourrait ressembler à 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.
* 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.