Saltar para o conteúdo principal
Esta referência é gerada a partir da 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

1
Forneça seu catálogo através de um feed de produtos.
2
(Faça com que os vendedores criem campanhas).
3
Execute leilões através da API ou usando nossos clientes.Os detalhes dependerão do seu marketplace e necessidades. Uma seleção de exemplos está disponível aqui.
4
Use uma das bibliotecas de analytics para reportar eventos.

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

​
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:
AmbienteEndpointLimite de Taxa
SandboxCatalog API4 rps
SandboxOutras APIs Avançadas5 solicitações a cada 2 segundos
SandboxAuctions e Events10.000 rps (padrão)
ProductionCatalog API10 rps
ProductionOutras APIs Avançadas45 solicitações a cada 2 segundos
ProductionAuctions e Events10.000 rps (padrão)
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.

​
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: 
/**
 * 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.