> ## 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 en páginas de categoría

Los ejemplos en esta página muestran cómo ejecutar [subastas](/en/ad-server/auctions/auctions-api) para productos que pertenecen a [categorías](/en/ad-server/catalog/product-feed) específicas.

Solo las ofertas que se dirijan a productos que pertenezcan a las categorías dadas tendrán la oportunidad de ganar estas subastas. Las ofertas dirigidas a productos que pertenecen a otras categorías no participarán.

## Casos de uso

Ejecutar este tipo de subastas en páginas de búsqueda permitirá a sus vendedores promover productos en páginas de categoría.

<Note>
  **Categorías no tradicionales:**

  Nuestro sistema de catálogo no hace ninguna suposición sobre qué **es** una categoría.

  Si su marketplace se ocupa de casas de vacaciones, por ejemplo, las categorías podrían ser ubicaciones geográficas en lugar de grupos de productos.
</Note>

## Especificar categorías

El endpoint `/auctions` admite varias formas de especificar categorías.

Cuando cree una subasta, debe elegir **una** de los siguientes métodos:

| Método               | Campo relevante         | Descripción                                                                                                                                                                         |
| :------------------- | :---------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Categoría única      | `category.id`           | Los objetivos de oferta deben pertenecer a la categoría. El `id` de la categoría es el mismo valor usado cuando se [upsert product](/en/api-reference/catalog-api/upsert-products). |
| Todas las categorías | `category.ids`          | Los objetivos de oferta deben pertenecer a **todas** las categorías.                                                                                                                |
| Disyunciones         | `category.disjunctions` | Los objetivos de oferta deben pertenecer a al menos **una de** las categorías de la disyunción.                                                                                     |

Veamos algunos ejemplos.

## Ejemplos de llamadas API

### Solicitud: Categoría única

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

La solicitud anterior creará una sola subasta de listings que:

* Tiene un máximo de dos ganadores debido al campo `slots`.
* Solo permite ofertas que se dirijan a productos en una sola categoría. El ID de categoría se especifica en el campo `category.id`.

En este caso, solo las ofertas que se dirijan a productos en la categoría `laptop_bags` pueden participar en la subasta.

### Solicitud: Todas las categorías

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

La solicitud anterior creará una sola subasta de listings que:

* Tiene un máximo de dos ganadores debido al campo `slots`.
* Solo permite ofertas que se dirijan a productos que pertenezcan a **todas las categorías**. Los IDs de categoría se especifican en el campo `category.ids`.

<Note>Este campo es plural. Se llama `ids`, no `id`.</Note>

Solo las ofertas que se dirijan a productos que pertenezcan tanto a las categorías `summer_hats` como `sale` pueden participar en esta subasta.

### Solicitud: Disyunciones ("al menos una categoría")

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

La solicitud anterior creará una sola subasta de listings que:

* Tiene un máximo de dos ganadores debido al campo `slots`.
* Solo permite ofertas que se dirijan a productos que pertenezcan a **una de las categorías para la disyunción**. Las disyunciones se especifican como arrays de cadenas en el campo `category.disjunctions`.

Solo las ofertas que se dirijan a productos que estén en las categorías `large` o `medium` pueden participar en esta subasta.

### Respuesta

<Warning>
  **No almacene en caché esta respuesta** ni sus resultados. Las subastas deben ser únicas por vista de página, esto es lo que hace que el sistema funcione.

  Si los resultados de la subasta se almacenan en caché, los mismos resultados podrían mostrarse a múltiples usuarios o al mismo usuario varias veces.
</Warning>

Si existen ofertas dirigidas a productos en las categorías apropiadas, una respuesta a cualquiera de las solicitudes anteriores podría verse algo así:

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

Notable aquí:

* El tipo de los ganadores es `product`, porque estamos ejecutando una subasta de listings.
* Hay dos ganadores, el máximo permitido por el campo `slots` en la solicitud.

## Próximos pasos

Los ganadores deberán combinarse con datos de productos para crear un resultado que pueda mostrarse al usuario final.

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