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

# Introdução

Esta referência é gerada a partir da [especificação openapi](#especificação-openapi) da Topsort e inclui bastantes operações.

No entanto, apenas duas são necessárias para uma integração típica.

## Uma integração típica

<Steps>
  <Step>
    Forneça seu catálogo através de um feed de produtos.
  </Step>

  <Step>
    (Faça com que os vendedores criem campanhas).
  </Step>

  <Step>
    Execute leilões [através da API](/en/api-reference/auctions/create-auctions) ou usando nossos clientes.

    Os detalhes dependerão do seu marketplace e necessidades. Uma seleção de exemplos está disponível [aqui](/en/api-reference/examples/auctions).
  </Step>

  <Step>
    Use uma das bibliotecas de analytics para reportar eventos.
  </Step>
</Steps>

## APIs Disponíveis

As integrações típicas usarão estas APIs:

* **Auctions:** Executa leilões no seu marketplace.
* **Events:** Coleta dados sobre os resultados dos leilões.

Para integrações avançadas, você pode querer consultar:

* **Audiences:** Gerencie audiências.
* **Campaigns:** Gerencie campanhas.
* **Catalog:** Gerencie produtos, categorias e vendedores.
* **Billing:** Gerencie os saldos dos vendedores.
* **Reporting:** Leia relatórios sobre o desempenho do marketplace, campanhas ou produtos.
* **Invitations:** Convide vendedores para o seu marketplace.

## URLs e redirecionamentos

Para minimizar o impacto dos leilões no desempenho da sua aplicação, não há redirecionamento de URLs com barra final (`/`). Isso é para evitar uma viagem de ida e volta adicional antes que os vencedores do leilão sejam retornados.

Por exemplo, quando você quiser executar um leilão, use `/v2/auctions`, não `/v2/auctions/`.

Usar uma URL com barra final resultará em um erro `404 Not Found`.

## Status da API

Você pode monitorar e verificar o status da API [aqui](https://topsort.statuspage.io/).

## Limites de Taxa

A Topsort aplica limites de taxa em alguns dos endpoints para garantir que a qualidade do serviço seja mantida para todos os usuários.
Os limites de taxa são diferentes para os ambientes de produção e sandbox e são os seguintes:

| Ambiente   | Endpoint              | Limite de Taxa                    |
| ---------- | --------------------- | --------------------------------- |
| Sandbox    | Catalog API           | 4 rps                             |
| Sandbox    | Outras APIs Avançadas | 5 solicitações a cada 2 segundos  |
| Sandbox    | Auctions e Events     | 10.000 rps (padrão)               |
| Production | Catalog API           | 10 rps                            |
| Production | Outras APIs Avançadas | 45 solicitações a cada 2 segundos |
| Production | Auctions e Events     | 10.000 rps (padrão)               |

<Note>
  O limite de taxa padrão para os endpoints de Auctions e Events é de 10.000
  solicitações por segundo. Este limite pode ser aumentado com base nos seus
  requisitos de tráfego específicos. Entre em contato com seu representante da
  Topsort para discutir limites mais altos para sua integração.
</Note>

### Cabeçalhos de limite de taxa

Use estes cabeçalhos para navegar pelos limites de taxa e saber quando você pode fazer outra solicitação:

* `X-RateLimit-Limit` - número total de solicitações permitidas para o período de tempo
* `X-RateLimit-Remaining` - número restante de solicitações para o período de tempo
* `X-RateLimit-Reset` - quando você pode fazer outra solicitação

### Como lidar com os limites de taxa

Quando você exceder o limite de taxa, receberá uma resposta `429 Too Many Requests`. Para lidar com isso, você pode implementar um mecanismo de retry com uma estratégia de backoff exponencial. Isso ajudará você a evitar atingir o limite de taxa novamente.

Aqui está um exemplo de como você pode implementar isso em 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()}`
    );
  }
}
```

## Especificação OpenAPI

A especificação OpenAPI está disponível como um arquivo JSON [aqui](/openapi.json).