Listings patrocinados em páginas de categoria

Os exemplos nesta página mostram como executar leilões para produtos que pertencem a categorias específicas.

Apenas os lances direcionados a produtos que pertencem às categorias fornecidas terão a oportunidade de ganhar esses leilões. Lances direcionados a produtos que pertencem a outras categorias não participarão.

​

Casos de uso

Executar este tipo de leilão em páginas de pesquisa permitirá que seus vendedores promovam produtos em páginas de categoria.

Categorias não tradicionais:

Nosso sistema de catálogo não faz nenhuma suposição sobre o que é uma categoria.

Se o seu marketplace trata de casas de férias, por exemplo, as categorias podem ser localizações geográficas em vez de grupos de produtos.

​

Especificar categorias

O endpoint /auctions suporta várias formas de especificar categorias.

Ao criar um leilão, você deve escolher um dos seguintes métodos:

Método	Campo relevante	Descrição
Categoria única	category.id	Os alvos de lance devem pertencer à categoria. O id da categoria é o mesmo valor usado ao fazer upsert product.
Todas as categorias	category.ids	Os alvos de lance devem pertencer a todas as categorias.
Disjunções	category.disjunctions	Os alvos de lance devem pertencer a pelo menos uma das categorias da disjunção.

Vejamos alguns exemplos.

​

Exemplos de chamadas API

​

Solicitação: Categoria única

{
  "auctions": [
    {
      "type": "listings",
      "slots": 2,
      "category": {
        "id": "laptop_bags"
      }
    }
  ]
}

A solicitação acima criará um único leilão de listings que:

• Tem no máximo dois vencedores devido ao campo slots.
• Permite apenas lances direcionados a produtos em uma única categoria. O ID da categoria é especificado no campo category.id.

Neste caso, apenas os lances direcionados a produtos na categoria laptop_bags podem participar do leilão.

​

Solicitação: Todas as categorias

{
  "auctions": [
    {
      "type": "listings",
      "slots": 2,
      "category": {
        "ids": ["summer_hats", "sale"]
      }
    }
  ]
}

A solicitação acima criará um único leilão de listings que:

• Tem no máximo dois vencedores devido ao campo slots.
• Permite apenas lances direcionados a produtos que pertençam a todas as categorias. Os IDs de categoria são especificados no campo category.ids.

Este campo é plural. É chamado ids, não id.

Apenas os lances direcionados a produtos que pertençam tanto às categorias summer_hats quanto sale podem participar deste leilão.

​

Solicitação: Disjunções (“pelo menos uma categoria”)

{
  "auctions": [
    {
      "type": "listings",
      "slots": 2,
      "category": {
        "disjunctions": [["large", "medium"]]
      }
    }
  ]
}

A solicitação acima criará um único leilão de listings que:

• Tem no máximo dois vencedores devido ao campo slots.
• Permite apenas lances direcionados a produtos que pertençam a uma das categorias para a disjunção. As disjunções são especificadas como arrays de strings no campo category.disjunctions.

Apenas os lances direcionados a produtos que estejam nas categorias large ou medium podem participar deste leilão.

​

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 a produtos nas categorias apropriadas, uma resposta a qualquer uma das solicitações acima pode se parecer com 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.
• 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.