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

# Introducción

Esta referencia se genera a partir de la [especificación openapi](#especificación-openapi) de Topsort e incluye bastantes operaciones.

Sin embargo, solo dos son necesarias para una integración típica.

## Una integración típica

<Steps>
  <Step>
    Proporcione su catálogo a través de un feed de productos.
  </Step>

  <Step>
    (Haga que los vendedores creen campañas).
  </Step>

  <Step>
    Ejecute subastas [a través de la API](/en/api-reference/auctions/create-auctions) o usando nuestros clientes.

    Los detalles dependerán de su marketplace y necesidades. Una selección de ejemplos está disponible [aquí](/en/api-reference/examples/auctions).
  </Step>

  <Step>
    Use una de las bibliotecas de analíticas para reportar eventos.
  </Step>
</Steps>

## APIs Disponibles

Las integraciones típicas usarán estas APIs:

* **Auctions:** Ejecuta subastas en su marketplace.
* **Events:** Recopila datos sobre los resultados de las subastas.

Para integraciones avanzadas, es posible que desee consultar:

* **Audiences:** Gestione audiencias.
* **Campaigns:** Gestione campañas.
* **Catalog:** Gestione productos, categorías y vendedores.
* **Billing:** Gestione los saldos de los vendedores.
* **Reporting:** Lea informes sobre el rendimiento del marketplace, campañas o productos.
* **Invitations:** Invite vendedores a su marketplace.

## URLs y redirecciones

Para minimizar el impacto de las subastas en el rendimiento de su aplicación, no hay redirección desde URLs con una barra diagonal final (`/`). Esto es para evitar un viaje de ida y vuelta adicional antes de que se devuelvan los ganadores de la subasta.

Por ejemplo, cuando desee ejecutar una subasta, use `/v2/auctions`, no `/v2/auctions/`.

Usar una URL con una barra diagonal final resultará en un error `404 Not Found`.

## Estado de la API

Puede monitorear y verificar el estado de la API [aquí](https://topsort.statuspage.io/).

## Límites de Tasa

Topsort aplica límites de tasa en algunos de los endpoints para garantizar que se mantenga la calidad del servicio para todos los usuarios.
Los límites de tasa son diferentes para los entornos de producción y sandbox y son los siguientes:

| Entorno    | Endpoint             | Límite de Tasa                 |
| ---------- | -------------------- | ------------------------------ |
| Sandbox    | Catalog API          | 4 rps                          |
| Sandbox    | Otras APIs Avanzadas | 5 solicitudes cada 2 segundos  |
| Sandbox    | Auctions y Events    | 10,000 rps (por defecto)       |
| Production | Catalog API          | 10 rps                         |
| Production | Otras APIs Avanzadas | 45 solicitudes cada 2 segundos |
| Production | Auctions y Events    | 10,000 rps (por defecto)       |

<Note>
  El límite de tasa predeterminado para los endpoints de Auctions y Events es de
  10,000 solicitudes por segundo. Este límite puede aumentarse según sus
  requisitos de tráfico específicos. Contacte a su representante de Topsort para
  discutir límites más altos para su integración.
</Note>

### Encabezados de límite de tasa

Use estos encabezados para navegar los límites de tasa y saber cuándo puede hacer otra solicitud:

* `X-RateLimit-Limit` - número total de solicitudes permitidas para el período de tiempo
* `X-RateLimit-Remaining` - número restante de solicitudes para el período de tiempo
* `X-RateLimit-Reset` - cuándo puede hacer otra solicitud

### Cómo manejar los límites de tasa

Cuando exceda el límite de tasa, recibirá una respuesta `429 Too Many Requests`. Para manejar esto, puede implementar un mecanismo de reintento con una estrategia de retroceso exponencial. Esto le ayudará a evitar alcanzar el límite de tasa nuevamente.

Aquí hay un ejemplo de cómo puede implementar esto en Typescript:

```typescript theme={null}
/**
 * Wraps `fetch()` with a retry function that respects retry limits from the API
 *
 * @param {string|URL} url
 * @param {RequestInit} request
 * @param {number} retries = 1
 * @returns {Promise<Response>}
 */
async function fetchWithRetry(url, request, retries = 1) {
  const response = await fetch(url, request);
  if (!response.ok) {
    if (response.status === 429) {
      // Handle rate limit
      const ms = response.headers.get("X-RateLimit-Reset");
      await new Promise((resolve) => setTimeout(resolve, ms));
      return fetchWithRetry(url, request, retries + 1);
    }
    throw new Error(
      `Failed to upload: ${response.status} ${await response.text()}`
    );
  }
}
```

## Especificación OpenAPI

La especificación OpenAPI está disponible como un archivo JSON [aquí](/openapi.json).