Passer au contenu principal

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.

L’API d’enchères vous permet de créer une grande variété d’enchères. 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 pour vous authentifier.
  2. Créer plusieurs campagnes, 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. 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. 
{
  "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 ou l’exemple de bannières sponsorisées pour plus d’informations.

​
Réponse

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.
S’il n’y a pas d’erreurs de requête, 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 : 
{
  "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 : 
{
  "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.