Saltar para o conteúdo principal

​
Visão Geral

A partir de 20 de fevereiro de 2026, os leilões do Topsort podem incorporar demanda de terceiros, permitindo que varejistas passem lances de terceiros para o leilão do Topsort, onde eles competem diretamente contra a demanda do Topsort. O lance mais alto vence, independentemente da fonte.

​
O que é Demand Mediation?

Anteriormente, os leilões do Topsort recebiam demanda apenas de fontes do Topsort (seja de fornecedores dentro de um marketplace ou via Toppie). Com a demand mediation, o Topsort agora pode buscar demanda de fontes de terceiros.
A primeira fonte de demanda de terceiros integrada é o Criteo, uma plataforma de mídia de varejo líder com orçamentos de grandes marcas ao redor do mundo. Para cada posicionamento de listagem patrocinada, um varejista busca lances do Criteo e os passa para o Topsort. O Topsort compara os lances do Criteo com os seus próprios lances e seleciona os lances vencedores entre eles.
O Topsort pode facilmente acomodar outras fontes de demanda além do Criteo, desde que seus lances possam ser enviados via o parâmetro demandSources do endpoint de leilão.

​
Como Funciona a Cobrança

Com a demand mediation usando Criteo:
  • O varejista é o proprietário da conta/instância do Criteo, não o Topsort
  • Os anunciantes pagam diretamente ao Criteo
  • O Criteo cobra os anunciantes, retém sua taxa de plataforma e paga ao varejista sua parcela de receita
  • O Topsort cobra o varejista separadamente (estrutura de cobrança a definir)

​
Benefícios para Marketplaces

Os varejistas podem gerar receita adicional de anúncios por meio da demand mediation:
  • Preencher lacunas: Quando não há demanda do Topsort para solicitações de anúncios, a demanda do Criteo pode estar disponível
  • Aumentar a competição: Quando há demanda do Topsort, a demanda do Criteo pode dar lances maiores, aumentando a receita geral

​
Quais Clientes Devem Usar Isso?

Embora qualquer cliente possa adicionar demanda do Criteo, essa integração é mais relevante para clientes com maior probabilidade de atrair gastos significativos de anúncios do Criteo:
  • Grandes marketplaces nos EUA: Muitas grandes marcas americanas dão lances em anúncios de mídia de varejo por meio de ferramentas como Pacvue e Skai, que por sua vez dão lances no inventário do Criteo. Essa configuração permite que grandes marcas evitem integração direta com cada varejista em que desejam anunciar.
  • Grandes marketplaces na LATAM: O Criteo tem presença significativa na América Latina, tornando essa integração valiosa para grandes marketplaces da LATAM também.

​
Processo de Onboarding

Para integrar um marketplace com demand mediation:
1

Configurar posicionamentos no Criteo

O marketplace deve configurar, na sua conta do Criteo, todos os posicionamentos para os quais deseja trazer demanda do Criteo.
2

Atualizar o código do frontend

No carregamento da página, o marketplace precisa:
  1. Buscar lances do Criteo para o posicionamento
  2. Enviar esses lances ao Topsort como um parâmetro extra na requisição de leilão
3

Tratar a resposta do leilão

O Topsort retorna os lances vencedores, que podem incluir vencedores tanto do Topsort quanto do Criteo.
4

Reportar eventos

Se houver vencedores do Criteo, o marketplace deve reportar eventos tanto para o Topsort quanto para o Criteo.

​
Implementação da API

O endpoint de leilões foi estendido para suportar fontes de demanda externas. Adicionar demanda externa requer um novo campo de entrada e dois novos campos de resposta para os vencedores do leilão.
O número de lances externos é limitado a 100 por requisição de leilão.

​
Alterações na Requisição

Um novo campo demandSources foi adicionado ao objeto de leilões:
  • demandSources: Array de objetos demandSource
    • source: Enum que identifica a fonte de demanda externa (ex.: "criteo")
    • bids: Array de objetos Bid, um para cada lance externo
Cada objeto Bid contém:
  • chargeType: Enum (apenas "CPC" é suportado na primeira versão)
  • entity: Objeto com os campos type e id que identificam o produto patrocinado
  • bidAmount: Valor do lance na moeda do marketplace
  • metadata: Campo livre para qualquer metadado necessário na resposta do vencedor (ex.: URLs de beacon de lance)

​
Alterações na Resposta

O objeto Winner foi atualizado com:
  • demandSource: String que identifica a fonte do lance vencedor (ex.: "topsort" ou "criteo"). Aparece apenas quando lances externos são incluídos na requisição.
  • metadata: Para vencedores de lances externos, repassa os metadados de entrada do lance externo. Omitido para lances internos/Topsort.
Para lances externos, o campo campaignId será omitido do objeto vencedor.

​
Casos de Erro

Novos casos de erro específicos da demand mediation:
  • Demanda externa não está autorizada para o marketplace
  • Lances externos inválidos (entidades que não são produtos, tipo de cobrança incorreto ou valor de lance negativo)
  • Lances externos em excesso (mais de 100)
  • Demanda externa com tipo de anúncio diferente de listagens
  • Fonte de demanda externa inválida (apenas Criteo é suportado atualmente)

​
Exemplo de Requisição

{
  "auctions": [
    {
      "type": "listings",
      "slots": 2,
      "category": {
        "id": "paper"
      },
      "opaqueUserId": "user123",
      "demandSources": [
        {
          "source": "criteo",
          "bids": [
            {
              "chargeType": "CPC",
              "entity": {
                "type": "product",
                "id": "product123"
              },
              "bidAmount": 0.75,
              "metadata": {
                "beaconUrls": ["https://example.com/beacon"],
                "clickUrls": ["https://example.com/click"]
              }
            }
          ]
        }
      ]
    }
  ]
}

​
Exemplo de Resposta

{
  "results": [
    {
      "resultType": "listings",
      "winners": [
        {
          "demandSource": "criteo",
          "type": "product",
          "id": "product123",
          "resolvedBidId": "UkoVYQoQBpaVc2jmdMO0BA4QS9VdHRIQAZgtj1MxeFGT5HL2fhBhKRoQBlhiMAUTfKyPJHhKpsqrQCIKCgZzdWJ3YXkQATCmFUDTBEgBUMXa8pu8Mw",
          "rank": 1,
          "metadata": {
            "beaconUrls": ["https://example.com/beacon"],
            "clickUrls": ["https://example.com/click"]
          }
        },
        {
          "demandSource": "topsort",
          "campaignId": "01982d6e-8655-70e2-94e3-3e5e764b4753",
          "type": "product",
          "id": "product456",
          "resolvedBidId": "zOzJwgoQBpaVfNrgdmeSBLgWZwYYmhIQAZgtboZVcOKU4z5edktHUxoQBlhiMAUTfKyPJHhKpsqrQCIQCgxwYW5lcmEtYnJlYWQQATCmFUDTBEgBUKH3-5u8Mw",
          "rank": 2
        }
      ],
      "error": false
    }
  ]
}
Para mais informações sobre a API de leilões, consulte aReferência da API de Criação de Leilões.
Última atualização: