Saltar para o conteúdo 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.

A API de leilões permite que você crie uma ampla variedade de leilões. Seja que você queira incluir listings patrocinados nos resultados de pesquisa ou banners na sua página inicial, nós temos você coberto.

​
Antes de começar

Antes de estar pronto para usar a API de leilões, você precisa:
  1. Obter uma API key para autenticação.
  2. Criar várias campanhas, para ter lances disponíveis para os leilões.

​
Solicitação

O endpoint /auctions permite executar até 5 leilões em uma única solicitação. A especificação completa para este endpoint está aqui. Isso pode ser muito para absorver de uma vez, então vamos manter o básico por enquanto. Cada corpo de solicitação deve ser fornecido como JSON e geralmente é estruturado da seguinte forma. 
{
  "auctions": [
    {
      "type": "listings",
      "slots": 2
    },
    {
      "type": "banners",
      "slots": 1
    }
  ]
}
Há várias coisas interessantes sobre este trecho (incompleto):
  • Os leilões são fornecidos como um array no campo auctions. Você pode fornecer de 1 a 5 leilões em uma única solicitação.
  • Cada leilão tem um type que determinará se listings ou banners estão sendo leiloados.
  • Cada leilão tem um campo slots, isso determina o número máximo de vencedores do leilão.
Para completar o trecho acima, você precisará adicionar mais campos, consulte o exemplo de listings patrocinados ou o exemplo de banners patrocinados para mais informações.

​
Resposta

Não armazene em cache esta resposta ou seus resultados. Os leilões devem ser únicos por visualização de página, é isso que faz o sistema funcionar.Se os resultados do leilão forem armazenados em cache, os mesmos resultados podem ser exibidos para vários usuários ou para o mesmo usuário várias vezes.
Se não houver erros de solicitação, o endpoint de leilões retornará os resultados para cada leilão. Uma resposta bem-sucedida não significa que cada leilão teve sucesso ou tem vencedores. Você precisará verificar os resultados para determinar isso.

​
Resposta com vencedores

Supondo que ambos os leilões na solicitação anterior resultaram em vencedores, a resposta poderia se parecer com algo assim: 
{
  "results": [
    {
      "winners": [
        {
          "rank": "1",
          "resolvedBidId": "WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0="
        },
        {
          "rank": "2",
          "resolvedBidId": "WyJlX1hKYm5OIiwiMTNiNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0=="
        }
      ],
      "error": false
    },
    {
      "winners": [
        {
          "rank": "1",
          "resolvedBidId": "WyJzb21lLXNsb3QiLCIxM2I1NTgyOC04ZWFkLTQyOTktODMyNy1jZWJiMDAyYTBmYTgiLCJiYW5uZXJzIiwiZGVmYXVsdCIsIiJd=="
        }
      ],
      "error": false
    }
  ]
}
Coisas a observar sobre esta resposta:
  • Os resultados do leilão estão sob uma propriedade de nível superior results.
  • A ordem dos resultados corresponde à ordem dos leilões.
  • Cada resultado tem um array de vencedores. Este array pode estar vazio e nunca será maior que os slots do leilão.
  • É possível que os leilões falhem/tenham sucesso independentemente. A flag error indica se um leilão teve sucesso.
Os campos exatos nos vencedores dependem do tipo de leilão, mas sempre terão:
  • rank um número baseado em 1 que corresponde à sua posição em winners.
  • resolvedBidId identificando o lance que fez este vencedor ganhar. Este ID é usado para relacionar o lance aos eventos.

​
Resposta sem vencedores

Não é garantido que um leilão resulte em vencedores. Se não houver campanhas ativas que correspondam aos seus critérios, não haverá lances para colocar. Se nossa solicitação de leilão anterior não teve vencedores para nenhum dos leilões, sua resposta se parecerá com algo assim: 
{
  "results": [
    {
      "winners": [],
      "error": false
    },
    {
      "winners": [],
      "error": false
    }
  ]
}
Observe que esta resposta ainda contém resultados para ambos os leilões.

​
Leitura adicional

Consulte as outras páginas desta seção para ver exemplos completos para diferentes casos de uso.