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

# Executar leilões

> Aprenda como usar a API de leilões para criar leilões de listings e banners.

A API de leilões permite que você crie uma ampla variedade de [leilões](/en/ad-server/auctions/auctions-api).

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](/en/api-reference/authentication#obtaining-an-api-key) para autenticação.
2. [Criar várias campanhas](/en/knowledge-base/ad-platform/campaign-creation/), 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](/en/api-reference/auctions/create-auctions).

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.

```json theme={null}
{
  "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](/en/api-reference/examples/sponsored-listings/set-of-products) ou o [exemplo de banners patrocinados](/en/api-reference/examples/sponsored-banners/banners) para mais informações.

## Resposta

<Warning>
  **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.
</Warning>

Se não houver [erros de solicitação](https://topsort.mintlify.app/api-reference/errors), 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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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.