> ## 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.

# Exécution d'enchères

> Apprenez à utiliser l'API d'enchères pour créer des enchères pour les listings et les bannières.

L'API d'enchères vous permet de créer une grande variété d'[enchères](/fr/ad-server/auctions/auctions-api).

Que vous souhaitiez inclure des listings sponsorisés dans les résultats de recherche ou des bannières sur votre page d'accueil, nous avons ce qu'il vous faut.

## Avant de commencer

Avant d'être prêt à utiliser l'API d'enchères, vous devez :

1. [Obtenir une clé API](/fr/api-reference/authentication#obtaining-an-api-key) pour vous authentifier.
2. [Créer plusieurs campagnes](/fr/knowledge-base/ad-platform/campaign-creation/), pour avoir des enchères disponibles pour les enchères.

## Requête

L'endpoint `/auctions` vous permet d'exécuter jusqu'à 5 enchères en une seule requête.

La spécification complète pour cet endpoint [se trouve ici](/fr/api-reference/auctions/create-auctions).

Cela peut être beaucoup à assimiler d'un coup, alors restons-en aux bases pour l'instant.

Chaque corps de requête doit être fourni au format JSON et est généralement structuré comme suit.

```json theme={null}
{
  "auctions": [
    {
      "type": "listings",
      "slots": 2
    },
    {
      "type": "banners",
      "slots": 1
    }
  ]
}
```

Il y a plusieurs choses intéressantes à propos de cet extrait (incomplet) :

* Les enchères sont fournies sous forme de tableau dans le champ `auctions`. Vous pouvez fournir 1 à 5 enchères dans une seule requête.
* Chaque enchère a un `type` qui déterminera s'il s'agit d'une enchère de listings ou de bannières.
* Chaque enchère a un champ `slots`, cela détermine le nombre maximum de gagnants de l'enchère.

Pour compléter l'extrait ci-dessus, vous devrez ajouter plus de champs, consultez l'[exemple de listings sponsorisés](/fr/api-reference/examples/sponsored-listings/set-of-products) ou l'[exemple de bannières sponsorisées](/fr/api-reference/examples/sponsored-banners/banners) pour plus d'informations.

## Réponse

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

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

S'il n'y a pas d'[erreurs de requête](https://topsort.mintlify.app/api-reference/errors), l'endpoint d'enchères renverra les résultats pour chaque enchère.

Une réponse réussie ne signifie pas que chaque enchère a réussi ou a des gagnants. Vous devrez vérifier les résultats pour le déterminer.

### Réponse avec gagnants

Supposons que les deux enchères de la requête précédente aient des gagnants, la réponse pourrait ressembler à ceci :

```json theme={null}
{
  "results": [
    {
      "winners": [
        {
          "rank": "1",
          "resolvedBidId": "WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0="
        },
        {
          "rank": "2",
          "resolvedBidId": "WyJlX1hKYm5OIiwiMTNiNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0=="
        }
      ],
      "error": false
    },
    {
      "winners": [
        {
          "rank": "1",
          "resolvedBidId": "WyJzb21lLXNsb3QiLCIxM2I1NTgyOC04ZWFkLTQyOTktODMyNy1jZWJiMDAyYTBmYTgiLCJiYW5uZXJzIiwiZGVmYXVsdCIsIiJd=="
        }
      ],
      "error": false
    }
  ]
}
```

Remarques sur cette réponse :

* Les résultats de l'enchère se trouvent sous une propriété `results` de premier niveau.
* L'ordre des résultats correspond à l'ordre des enchères.
* Chaque résultat a un tableau de gagnants. Ce tableau peut être vide et ne sera jamais plus grand que les `slots` de l'enchère.
* Il est possible que les enchères échouent/réussissent indépendamment. Le drapeau `error` indique si une enchère a réussi.

Les champs exacts sur les gagnants dépendent du type d'enchère, mais ils auront toujours :

* `rank` un nombre basé sur 1 correspondant à sa position dans `winners`.
* `resolvedBidId` identifiant l'enchère qui a fait gagner ce gagnant. Cet ID est utilisé pour relier l'enchère aux événements.

### Réponse sans gagnants

Il n'est pas garanti qu'une enchère ait des gagnants. S'il n'y a pas de campagnes actives qui correspondent à ses critères, il n'y aura pas d'enchères à placer.

Si notre requête d'enchère précédente n'avait pas de gagnants pour l'une ou l'autre enchère, sa réponse ressemblera à ceci :

```json theme={null}
{
  "results": [
    {
      "winners": [],
      "error": false
    },
    {
      "winners": [],
      "error": false
    }
  ]
}
```

Notez que cette réponse contient toujours des résultats pour les deux enchères.

## Lectures complémentaires

Consultez les autres pages de cette section pour voir des exemples complets pour différents cas d'utilisation.