> ## 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 em páginas de categoria

Os exemplos nesta página mostram como executar [leilões](/en/ad-server/auctions/auctions-api) para produtos que pertencem a [categorias](/en/ad-server/catalog/product-feed) específicas.

Apenas os lances direcionados a produtos que pertencem às categorias fornecidas terão a oportunidade de ganhar esses leilões. Lances direcionados a produtos que pertencem a outras categorias não participarão.

## Casos de uso

Executar este tipo de leilão em páginas de pesquisa permitirá que seus vendedores promovam produtos em páginas de categoria.

<Note>
  **Categorias não tradicionais:**

  Nosso sistema de catálogo não faz nenhuma suposição sobre o que **é** uma categoria.

  Se o seu marketplace trata de casas de férias, por exemplo, as categorias podem ser localizações geográficas em vez de grupos de produtos.
</Note>

## Especificar categorias

O endpoint `/auctions` suporta várias formas de especificar categorias.

Ao criar um leilão, você deve escolher **um** dos seguintes métodos:

| Método              | Campo relevante         | Descrição                                                                                                                                                          |
| :------------------ | :---------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Categoria única     | `category.id`           | Os alvos de lance devem pertencer à categoria. O `id` da categoria é o mesmo valor usado ao fazer [upsert product](/en/api-reference/catalog-api/upsert-products). |
| Todas as categorias | `category.ids`          | Os alvos de lance devem pertencer a **todas** as categorias.                                                                                                       |
| Disjunções          | `category.disjunctions` | Os alvos de lance devem pertencer a pelo menos **uma das** categorias da disjunção.                                                                                |

Vejamos alguns exemplos.

## Exemplos de chamadas API

### Solicitação: Categoria única

```json theme={null}
{
  "auctions": [
    {
      "type": "listings",
      "slots": 2,
      "category": {
        "id": "laptop_bags"
      }
    }
  ]
}
```

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

* Tem no máximo dois vencedores devido ao campo `slots`.
* Permite apenas lances direcionados a produtos em uma única categoria. O ID da categoria é especificado no campo `category.id`.

Neste caso, apenas os lances direcionados a produtos na categoria `laptop_bags` podem participar do leilão.

### Solicitação: Todas as categorias

```json theme={null}
{
  "auctions": [
    {
      "type": "listings",
      "slots": 2,
      "category": {
        "ids": ["summer_hats", "sale"]
      }
    }
  ]
}
```

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

* Tem no máximo dois vencedores devido ao campo `slots`.
* Permite apenas lances direcionados a produtos que pertençam a **todas as categorias**. Os IDs de categoria são especificados no campo `category.ids`.

<Note>Este campo é plural. É chamado `ids`, não `id`.</Note>

Apenas os lances direcionados a produtos que pertençam tanto às categorias `summer_hats` quanto `sale` podem participar deste leilão.

### Solicitação: Disjunções ("pelo menos uma categoria")

```json theme={null}
{
  "auctions": [
    {
      "type": "listings",
      "slots": 2,
      "category": {
        "disjunctions": [["large", "medium"]]
      }
    }
  ]
}
```

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

* Tem no máximo dois vencedores devido ao campo `slots`.
* Permite apenas lances direcionados a produtos que pertençam a **uma das categorias para a disjunção**. As disjunções são especificadas como arrays de strings no campo `category.disjunctions`.

Apenas os lances direcionados a produtos que estejam nas categorias `large` ou `medium` podem participar deste leilão.

### 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 a produtos nas categorias apropriadas, uma resposta a qualquer uma das solicitações acima pode se parecer com 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.
* 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.