Hey! These docs are for version 1-search-api, which is no longer officially supported. Click here for the latest version, 2-Main-Docs!

A busca é utilizada para encontrar produtos através de uma consulta por termo ou id de produto. A busca personalizada utiliza diversas informações de sua loja, como dados de navegação e consumo para encontrar os produtos mais adequados à consulta de cada usuário. Esta request realiza uma consulta por um termo, id de produto ou conjunto de ids de produtos, retornando os produtos e features complementares resultantes.

Como fazer a consulta?

Para realizar uma consulta, você pode passar um termo para a consulta
https://api.linximpulse.com/engage/search/v3/search?apiKey=<loja>&secretKey=<secretKey>&terms=celular+samsung

Você também pode passar um ou vários ID de produto para a consulta

https://api.linximpulse.com/engage/search/v3/search?apiKey=<loja>&secretKey=<secretKey>&pids=P123458&pids=P987753

Para filtrar as consultas, realizar ações de paginação ou outras interações com a API, fornecemos links prontos, basta utilizá-los, incluindo sua secretKey.

Como é a resposta?

Os produtos retornados estarão no campo **products**. O formato/conteúdo de cada produto no **products **está listado acima na seção **Parameters** na explicação do campo **productFormat**. É importante notar que alguns valores retornados no **products** são opcionais, ou seja, nem sempre serão retornados, por exemplo o campo **customBusiness**.

Existem outros campos que são retornados conforme a resposta para aquela consulta. Os principais campos estão descritos abaixo.

CampoDescrição
suggestionsAlgumas consultas podem possuir sugestões de consultas relacionadas.
filtersLista de filtros retornados pela consulta. Cada filtro pode ser de um tipo, identificaod no campo type. Os valores possíveis são:

  • discrete: Não há a noção de ordem entre os valores. Ex.: marca, cor.

  • continuous: Os valores podem ser agrupados de maneira ordenada. Ex.: preço, peso.

  • range: Os valores podem ser agrupados de maneira ordenada mas cada produto atende a uma faixa de valores. Ex.: suporte de tv (tamanhos 32" a 50").

    quickFiltersPermite que algumas consultas exibam de maneira destacada um conjunto pré-determinado de filtros para que o usuário possa direcionar o seu foco. Recomenda-se o uso em consultas muito genéricas. Por exemplo, a consulta "samsung" pode ser feita por um usuário buscando tvs, notebooks ou celulares. Neste caso, a utilização de um quickFilter ajudaria o usuário a direcionar o seu interesse. O retorno é uma lista de opções que o usuário pode selecionar para filtrar os produtos retornados pela consulta.
    bannersBanner a ser exibido na página de resultados. Algumas consultas podem ter banners associados a ela, neste caso eles serão retornados neste campo.

    Alguns campos existentes na resposta possuem valores padrões. Abaixo descrevemos alguns desses campos.

    O campo queries traz informações referentes à consulta realizada, como por exemplo a consulta original e normalizada. Um dos campos retornados é o queryType, onde você pode identificar qual o tipo de consulta foi realizada. Os possíveis valores retornados estão descritos abaixo. Observe, também, o código de resposta da pode variar conforme este tipo.

    ValorCodeDescrição
    found200Houve ao menos um produto com os termos pesquisados.
    corrected200Foi identificado um erro de digitação na consulta enviada e ela foi corrigida (ex.: "notebok" pode ser corrigido para "notebook").
    aproximated200Nenhum produto possui todos os termos da consulta, busca-se então por produtos com parte dos termos consultados. (ex.: "notebook sony vaio" pode ser corrigido para "notebook sony").
    notfound404Não houve nenhum produto com os termos pesquisados.
    redirect302Redirecionamento. A consulta está cadastrada como redirect e deve enviar o usuário a outra página, nesse caso são retornados apenas os campos "queries.queryType" e "queries.original".

    O campo pagination traz informações referentes à paginação. Em casos onde o resultado possui muitos produtos, estes são segmentados por páginas. Este campo é um objeto que pode possuir os campos abaixo:

    CampoDescrição
    first Url da primeira página de resultados. Por padrão seu número é 1.
    lastUrl da última página de resultados.
    nextUrl da próxima página de resultados. Por padrão seu valor é a página atual+1.
    previousUrl da página anterior de resultados. Por padrão seu valor é a página atual-1

    Tracking de eventos

    Eventos de click

    Cada produto do resultado da busca contém um campo chamado clickUrl.

    Este campo fornece uma URL da API de Busca, na rota /clicks que deverá ser usada para registrar todos os eventos de click dos usuários da aplicação com os produtos do resultado da busca. É por meio destes registros que geramos métricas de performance da busca, além de melhorar as estratégias para acertar em cheio cada resultado..

    {
        id: "10005354",
      	name: "oculos",
      	price: 249.98,
      	oldPrice: 249.98,
      	url: "...",
      	images: {
            template-418481: "...",
          	1000x1000: "..."
      	},
      	installment: {
            count: 6,
          	price: 41.66
      	},
      	status: "AVAILABLE",
      	clickUrl: "/search/v3/clicks?apikey=loja&trackingId=eyJzZWFyY2hJZCI6IjQ1NTE5MDkwLTQxMDktNGM1MC1hNGZmLTYwMGM0YTZhOWVkZiIsIm9yaWdpbiI6InNlYXJjaCIsInByb2R1Y3QiOnsicmFua2luZyI6MSwicGlkIjoiMTAwMDUzNTciLCJza3VzIjpbXX19",
      	categories: [
          {
            id: "ÓCULOS DE SOL",
            name: "ÓCULOS DE SOL",
            parents: [ ],
            used: true
          }
    	  ],
        tags: [
          {
            id: "oculos_de_sol",
            name: "ÓCULOS DE SOL",
            parents: [ ]
          }
        ],
        specs: { },
        created: "2018-08-02 11:52:51",
        brand: null,
        collectInfo: {
          skuList: [ ],
          productId: "10005354"
        },
        cId: "84",
        iId: 10641,
        skus: [
    				{
    						sku: "2067712",
                specs: { },
                properties: {
                    stock: 1,
                    name: "oculos",
                    oldPrice: 249.98,
                    url: "...",
                    price: 249.98,
                    eanCode: "7909140245889",
                    status: "available",
                    details: {
                        referenceId: "7909140245889",
                        measurement: {
                            unit: "un",
                            multiplier: 1
                        }
                    },
                    installment: {
                        price: 41.66,
                        count: 6
                    },
                    images: {
                        template-418481: "...",
                        1000x1000: "..."          
                    }
                }
        		}
        ],
        details: {
            productReference: [
            		"..."
            ],
            clusterHighlights: [
                {
                    178: "Mais Vistos",
                    192: "Todos produtos",
                    246: "lightbox-oculos",
                    247: "modal-oculos"
                }
    				],
    				brand: [
              "..."
            ],
            referenceId: [
              "7909140245889"
            ],
            measurement: [
            		{
                    unit: "un",
                    multiplier: 1
    						}
            ],
            categoryName: [
            		"ÓCULOS DE SOL"
            ]
        },
        description: "..."
    }
    

    Ao clickUrl deverá ser adicionada a URL base da API no início e ao final os parâmetros exigidos pela rota de click. Detalhes dos parâmetros da rota de click podem ser encontados na documentação /clicks

    Por exemplo:

    https://api.linximpulse.com/engage/search/v3/clicks?apikey=loja&trackingId=eyJzZWFyY2hJZCI6IjQ1NTE5MDkwLTQxMDktNGM1MC1hNGZmLTYwMGM0YTZhOWVkZiIsIm9yaWdpbiI6InNlYXJjaCIsInByb2R1Y3QiOnsicmFua2luZyI6MSwicGlkIjoiMTAwMDUzNTciLCJza3VzIjpbXX19&deviceid=teste&source=desktop
    

    É recomendado que este evento seja disparado somente depois que o usuário acessar a página do produto, evitando assim que o browser cancele a requisição caso a página de produto seja carregada antes que o disparo tenha sido concluído.

    A Coleta de Dados é parte essencial da implementação, pois sem ela não haverá aumento de performance nos resultados de busca e nem métricas disponíveis para você acompanhar o desempenho em produção.

    Language
    Click Try It! to start a request and see the response here!