Saltar para o conteúdo principal

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.

Neste exemplo, usaremos a API para executar um leilão para um conjunto de produtos. Apenas os lances direcionados aos produtos neste conjunto terão a oportunidade de ganhar este leilão. Lances direcionados a outros produtos não participarão. Isso permite que você tenha controle total sobre quais produtos são exibidos e onde, enquanto ainda permite que seus vendedores promovam produtos.

​
Casos de uso

Não prescrevemos como criar seu conjunto de produtos, você pode usar qualquer algoritmo que desejar. Tudo o que precisamos é de uma lista de IDs de produtos. Por exemplo, use seu próprio algoritmo para gerar:
  • Vendas cruzadas.
  • Produtos relacionados.
  • Vendas adicionais no checkout.
Colete os IDs resultantes e passe-os para um leilão. Seus vendedores poderão então fazer lances por oportunidades de aparecer em posições valiosas no marketplace.

​
Exemplo de chamada API

​
Solicitação

Suponha que usamos algum tipo de algoritmo para criar um conjunto de IDs de produtos. Então podemos passá-los para uma solicitação de leilão: 
{
  "auctions": [
    {
      "type": "listings",
      "slots": 2,
      "products": {
        "ids": ["p_PJbnN", "p_ojng4", "p_8VKDt", "p_Mfk15"]
      }
    }
  ]
}
A solicitação acima criará um único leilão de listings:
  • Terá no máximo dois vencedores devido ao campo slots.
  • O products.ids é o conjunto de produtos. Estes devem existir em seu catálogo.
Como mencionado anteriormente, apenas os lances direcionados a esses produtos participarão do leilão. O endpoint de leilões suporta até 10000 IDs de produtos por leilão, mas recomendamos enviar não mais que os 500 mais relevantes.

​
Adicionar quality scores personalizados

Às vezes, você pode querer incorporar quality scores personalizados para cada produto. O quality score é um número entre 0 e 1 que codifica a relevância dos produtos participantes. O uso de quality scores ajuda a mitigar riscos e perdas devido a produtos não relevantes vencerem leilões. Para incluir quality scores personalizados na solicitação, modifique o campo products conforme mostrado abaixo: 
{
  "auctions": [
    {
      "type": "listings",
      "slots": 2,
      "products": {
        "ids": ["p_PJbnN", "p_ojng4", "p_8VKDt", "p_Mfk15"],
        "qualityScores": [0.5, 0.4, 0.7, 0.6]
      }
    }
  ]
}
Neste exemplo:
  • O produto p_PJbnN tem um quality score de 0.5.
  • O produto p_ojng4 tem um quality score de 0.4.
  • O produto p_8VKDt tem um quality score de 0.7.
  • O produto p_Mfk15 tem um quality score de 0.6.
Importante: O número de quality scores deve corresponder ao número de IDs de produtos. Se não corresponderem, a solicitação falhará. Aviso: Você não pode incluir quality scores e uma consulta de pesquisa. Embora seja permitido executar um leilão com uma consulta de pesquisa e um conjunto de produtos, a solicitação não pode incluir quality scores personalizados.

​
Resposta

Não armazene em cache esta resposta nem seus resultados. Os leilões devem ser únicos por visualização de página, isso é o que faz o sistema funcionar.Se os resultados do leilão forem armazenados em cache, os mesmos resultados podem ser exibidos para múltiplos usuários ou para o mesmo usuário várias vezes.
Se existirem lances direcionados aos produtos, eles podem ganhar este leilão. A resposta resultante seria algo assim: 
{
  "results": [
    {
      "winners": [
        {
          "rank": 1,
          "type": "product",
          "id": "p_Mfk15",
          "resolvedBidId": "WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0="
        },
        {
          "rank": 2,
          "type": "product",
          "id": "p_PJbnN",
          "resolvedBidId": "WyJlX1BKYm5OIiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0="
        }
      ],
      "error": false
    }
  ]
}
Notável aqui:
  • O tipo dos vencedores é product, porque estamos executando um leilão de listings.
  • Ambos os id vencedores correspondem a um ID de produto na solicitação.
  • Há dois vencedores, o máximo permitido pelo campo slots na solicitação.

​
Próximos passos

Os vencedores precisarão ser combinados com dados de produtos para criar um resultado que possa ser exibido ao usuário final. Consulte esta página para ver um exemplo.