> ## 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 patrocinados de um conjunto de produtos

> Como executar um leilão para um conjunto de produtos

Neste exemplo, usaremos a API para executar um [leilão](/en/ad-server/auctions/auctions-api) para um conjunto de [produtos](/en/ad-server/catalog/).

Apenas os lances direcionados aos produtos neste conjunto terão a oportunidade de ganhar este leilão. Lances direcionados a outros produtos não participarão.

**Isso permite que você tenha controle total sobre quais produtos são exibidos e onde**, enquanto ainda permite que seus vendedores promovam produtos.

## Casos de uso

Não prescrevemos como criar seu conjunto de produtos, você pode usar qualquer algoritmo que desejar. Tudo o que precisamos é de uma lista de IDs de produtos.

Por exemplo, use seu próprio algoritmo para gerar:

* Vendas cruzadas.
* Produtos relacionados.
* Vendas adicionais no checkout.

Colete os IDs resultantes e passe-os para um leilão.

Seus vendedores poderão então fazer lances por oportunidades de aparecer em posições valiosas no marketplace.

## Exemplo de chamada API

### Solicitação

Suponha que usamos algum tipo de algoritmo para criar um conjunto de IDs de produtos. Então podemos passá-los para uma solicitação de leilão:

```json theme={null}
{
  "auctions": [
    {
      "type": "listings",
      "slots": 2,
      "products": {
        "ids": ["p_PJbnN", "p_ojng4", "p_8VKDt", "p_Mfk15"]
      }
    }
  ]
}
```

A solicitação acima criará um único leilão de listings:

* Terá no máximo dois vencedores devido ao campo `slots`.
* O `products.ids` é o conjunto de produtos. Estes devem existir em [seu catálogo](/en/ad-server/catalog/).

Como mencionado anteriormente, apenas os lances direcionados a esses produtos participarão do leilão.

O endpoint de leilões suporta até 10000 IDs de produtos por leilão, mas recomendamos enviar não mais que os 500 mais relevantes.

### Adicionar quality scores personalizados

Às vezes, você pode querer incorporar quality scores personalizados para cada produto. O quality
score é um número entre 0 e 1 que codifica a relevância dos produtos participantes. O uso de quality
scores ajuda a mitigar riscos e perdas devido a produtos não relevantes vencerem leilões.

Para incluir quality scores personalizados na solicitação, modifique o campo `products` conforme mostrado abaixo:

```json theme={null}
{
  "auctions": [
    {
      "type": "listings",
      "slots": 2,
      "products": {
        "ids": ["p_PJbnN", "p_ojng4", "p_8VKDt", "p_Mfk15"],
        "qualityScores": [0.5, 0.4, 0.7, 0.6]
      }
    }
  ]
}
```

Neste exemplo:

* O produto `p_PJbnN` tem um quality score de `0.5`.
* O produto `p_ojng4` tem um quality score de `0.4`.
* O produto `p_8VKDt` tem um quality score de `0.7`.
* O produto `p_Mfk15` tem um quality score de `0.6`.

**Importante**: O número de quality scores deve corresponder ao número de IDs de produtos. Se não corresponderem, a solicitação falhará.

**Aviso**: Você não pode incluir quality scores e uma consulta de pesquisa. Embora seja permitido executar um leilão com uma consulta de pesquisa e um
conjunto de produtos, a solicitação não pode incluir quality scores personalizados.

### Resposta

<Warning>
  **Não armazene em cache esta resposta** nem seus resultados. Os leilões devem ser únicos por visualização de página, isso é o que faz o sistema funcionar.

  Se os resultados do leilão forem armazenados em cache, os mesmos resultados podem ser exibidos para múltiplos usuários ou para o mesmo usuário várias vezes.
</Warning>

Se existirem lances direcionados aos produtos, eles podem ganhar este leilão. A resposta resultante seria algo assim:

```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
    }
  ]
}
```

Notável aqui:

* O tipo dos vencedores é `product`, porque estamos executando um leilão de listings.
* Ambos os `id` vencedores correspondem a um ID de produto na solicitação.
* Há dois vencedores, o máximo permitido pelo campo `slots` na solicitação.

## Próximos passos

Os vencedores precisarão ser combinados com dados de produtos para criar um resultado que possa ser exibido ao usuário final.

Consulte [esta página](/en/api-reference/examples/sponsored-listings/combining-results) para ver um exemplo.