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 EventsSem limite de taxa
ProductionCatalog API10 rps
ProductionOutras APIs Avançadas45 solicitações a cada 2 segundos
ProductionAuctions e EventsSem limite de taxa

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