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

# Ejecutar subastas

> Aprenda cómo usar la API de subastas para crear subastas de listings y banners.

La API de subastas le permite crear una amplia variedad de [subastas](/en/ad-server/auctions/auctions-api).

Ya sea que desee incluir listings patrocinados en los resultados de búsqueda o banners en su página de inicio, lo tenemos cubierto.

## Antes de comenzar

Antes de estar listo para usar la API de subastas, necesita:

1. [Obtener una API key](/en/api-reference/authentication#obtaining-an-api-key) para autenticarse.
2. [Crear varias campañas](/en/knowledge-base/ad-platform/campaign-creation/), para tener ofertas disponibles para las subastas.

## Solicitud

El endpoint `/auctions` le permite ejecutar hasta 5 subastas en una sola solicitud.

La especificación completa para este endpoint [se encuentra aquí](/en/api-reference/auctions/create-auctions).

Esto puede ser mucho para asimilar de una vez, así que mantengámonos en lo básico por ahora.

Cada cuerpo de solicitud debe proporcionarse como JSON y generalmente se estructura de la siguiente manera.

```json theme={null}
{
  "auctions": [
    {
      "type": "listings",
      "slots": 2
    },
    {
      "type": "banners",
      "slots": 1
    }
  ]
}
```

Hay varias cosas interesantes sobre este fragmento (incompleto):

* Las subastas se proporcionan como un array en el campo `auctions`. Puede proporcionar de 1 a 5 subastas en una sola solicitud.
* Cada subasta tiene un `type` que determinará si se están subastando listings o banners.
* Cada subasta tiene un campo `slots`, esto determina el número máximo de ganadores de la subasta.

Para completar el fragmento anterior, necesitará agregar más campos, consulte el [ejemplo de listings patrocinados](/en/api-reference/examples/sponsored-listings/set-of-products) o el [ejemplo de banners patrocinados](/en/api-reference/examples/sponsored-banners/banners) para más información.

## 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 no hay [errores de solicitud](https://topsort.mintlify.app/api-reference/errors), el endpoint de subastas devolverá los resultados para cada subasta.

Una respuesta exitosa no significa que cada subasta tuvo éxito o tiene ganadores. Deberá verificar los resultados para determinar esto.

### Respuesta con ganadores

Supongamos que ambas subastas en la solicitud anterior resultan en ganadores, la respuesta podría verse algo así:

```json theme={null}
{
  "results": [
    {
      "winners": [
        {
          "rank": "1",
          "resolvedBidId": "WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0="
        },
        {
          "rank": "2",
          "resolvedBidId": "WyJlX1hKYm5OIiwiMTNiNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0=="
        }
      ],
      "error": false
    },
    {
      "winners": [
        {
          "rank": "1",
          "resolvedBidId": "WyJzb21lLXNsb3QiLCIxM2I1NTgyOC04ZWFkLTQyOTktODMyNy1jZWJiMDAyYTBmYTgiLCJiYW5uZXJzIiwiZGVmYXVsdCIsIiJd=="
        }
      ],
      "error": false
    }
  ]
}
```

Cosas a tener en cuenta sobre esta respuesta:

* Los resultados de la subasta están bajo una propiedad de nivel superior `results`.
* El orden de los resultados corresponde al orden de las subastas.
* Cada resultado tiene un array de ganadores. Este array puede estar vacío y nunca será más que los `slots` de la subasta.
* Es posible que las subastas fallen/tengan éxito de forma independiente. La bandera `error` indica si una subasta tuvo éxito.

Los campos exactos en los ganadores dependen del tipo de subasta, pero siempre tendrán:

* `rank` un número basado en 1 que corresponde a su posición en `winners`.
* `resolvedBidId` identificando la oferta que hizo que este ganador ganara. Este ID se usa para relacionar la oferta con los eventos.

### Respuesta sin ganadores

No está garantizado que una subasta resulte en ganadores. Si no hay campañas activas que coincidan con sus criterios, no habrá ofertas para colocar.

Si nuestra solicitud de subasta anterior no tuvo ganadores para ninguna de las subastas, su respuesta se verá algo así:

```json theme={null}
{
  "results": [
    {
      "winners": [],
      "error": false
    },
    {
      "winners": [],
      "error": false
    }
  ]
}
```

Tenga en cuenta que esta respuesta aún contiene resultados para ambas subastas.

## Lectura adicional

Consulte las otras páginas de esta sección para ver ejemplos completos para diferentes casos de uso.