Recomendações por Página

Retorna recomendações por página. Utilize nosso painel de controle para definir regras de negócio e configurar vitrines.

Aqui você configura suas vitrines por página através do nosso painel de controle, definindo regras de negócio e configurando elas como quiser. Inclusive, é possível definir tags e categorias para filtrar recomendações em páginas de categoria, subcategoria e produto, de acordo com o contexto de cada uma delas.

Utilizando em páginas de produto:

productId=P001

Em páginas de produto, é necessário especificar o campo productId. Caso contrário, vitrines que levem em consideração o produto referência ficarão vazias :(


Utilizando em páginas de carrinho:

productId=P001&productId=P002

Já na página de carrinho, o campo productId passa a ser usado para especificar o conjunto de produtos presentes no carrinho do clientes. Por exemplo, se tivermos os produtos P001 e P002 no carrinho.


Utilizando várias categorias aplicadas:

categoryId=L1299S&categoryId=I893L&categoryId=A307V

Neste caso, a categoria formada pela junção das categorias Livros > Infantil > Aventura, onde:
  • Aventura (A307V) é uma subcategoria de Infantil (I893L);
  • Infantil (I893L) é uma subcategoria de Livros (L1299S);
  • Livros (L1299S) é a categoria.
Assim, vitrines com filtro por categoria ativo, terão produtos recomendados que pertençam a categoria de ids L1299S > I893L > A307V. Ou seja, cada elemento da lista de categoryId será um componente da árvore da categoria, o valor de categoryId difere para cada cliente, podendo ser igual ao name, ou diferente.Exemplo do objeto categoria:
{
  "categories":
  [
      {
          "id":"A307V",
          "name":"Aventura",
          "parents":["I893L"]
      },
      {
          "id":"I893L",
          "name":"Infantil",
          "parents":["L1299S"]
      },
      {
          "id":"L1299S",
          "name":"Livros",
          "parents":[]
      },
  ]
}
Requests com filtro de categoria
Envie sempre o id da categoria para filtrar as recomendações da vitrine. Se enviar o name da categoria, o filtro não será aplicado corretamente.
Se desejar, você pode filtrar por uma categoria específica, como livros de aventura, enviando a categoria correspondente, conforme o exemplo a seguir.

categoryId=A307V


Utilizando várias tags aplicadas:

tagId=tolkien&tagId=fantasia

Aqui, vitrines com filtro por categoria/tags ativo terão produtos recomendados que contenham as tags tolkien e fantasia. Não existe relação de hierarquia. Caso as vitrines configuradas para a página tenham o filtro de produtos por categoria/tags ativo, as recomendações feitas terão todas as tags especificadas na requisição feita pela API.

O campo userId define qual usuário logado está navegando pelo site. Caso não seja especificado na consulta o campo userId, o campo deviceId é usado pelo sistema para recuperar o histórico de visitas do usuário a fim de preencher vitrines que utilizem históricos de produtos vistos e/ou produtos abandonados no carrinho.

Tipos de Página

TipoDescrição
homePágina inicial da aplicação
productProduto
categoryCategoria
subcategorySubcategoria
cartCarrinho de compras
transactionPágina de confirmação de compra
userprofilePágina do usuário
not_foundErro 404
searchBusca
landing_pageLanding page
otherOutras

Query Params

apiKey
stringrequired

Identificador único da loja. Não sabe qual a apiKey da sua loja? Solicite ao responsável técnico de integração enviando um email para atendimento@linximpulse.com.br

secretKey
stringrequired

Utilizado para validar autenticação, caso o modelo utilizado seja apiKey+secretKey. Neste caso, será um parâmetro obrigatório. Não sabe qual a secretKey da sua loja? Solicite ao responsável técnico de integração enviando um email para atendimento@linximpulse.com.br

name
stringrequired

Tipo da página (home, product, category, subcategory, cart, search, emptysearch, checkout, transaction, userprofile e not_found).

source
stringrequired

Origem do dispositivo utilizado. Os tipos suportados são:
  • desktop
  • mobile
  • app

deviceId
stringrequired

Identificador único do dispositivo. Todas as requisições feitas a partir do mesmo dispositivo devem possuir o mesmo deviceId.

url
string

URL da pagina.

categoryId
string[]

Ids de categoria da página.

tagId
string[]

Tags da página.

productId
string[]

Em uma página de produto, este campo define o produto da página. Na página de carrinho, este campo define a lista de produtos presentes no carrinho.

userId
string

Identificador do usuário. Deve ser o mesmo identificador utilizado no site ou um e-mail, caso userIdType esteja configurado como "email".

productFormat
string default: complete

Define o formato de resposta dos produtos.Valores permitidos:
  • onlyIds
  • complete
  • compact

salesChannel
string

Sales Channel do usuário. Para este campo funcionar corretamente, é necessário que a integração de catálogo de produtos tenha sido feita com suporte a Sales Channel ativo.

dummy
boolean default: false

Quando este campo está ativado, a API fornecerá recomendação para todas as vitrines configuradas no painel de controle. O conteúdo dessa recomendação é aleatório e serve apenas para facilitar a etapa de integração. Isso deve ser usado somente em etapas de validação, não devendo ficar ativo em um cenário de produção

homologation
boolean default: false

Quando este campo está ativo, a API irá retornar as vitrines que estão desligadas no painel de controle. Isso deve ser usado somente em etapas de validação, não devendo ficar ativo em um cenário de produção

showOnlyAvailable
boolean default: true

Define se as recomendações serão compostas apenas por produtos com status disponível.

userIdType
string default: userId

Tipo de identificador de usuário. Pode ser "userId" ou "email".

Headers

Accept-Encoding
string default: gzip,deflate

Permite que o servidor envie a resposta em formato comprimido. Melhorando o tempo de download e reduzindo o volume de dados trafegados.

Edit this page on GitHub

Requests

home
curl -v -G "https://recs.chaordicsystems.com/v0/pages/recommendations" \
  -d apiKey="<my-api-key>" \
  -d secretKey="<my-secret-key>" \
  -d source=desktop \
  -d name=home \
  -d deviceId="<device-id>" \
  -d userId="<user-id>"
category
curl -v -G "https://recs.chaordicsystems.com/v0/pages/recommendations" \
  -d apiKey="<my-api-key>" \
  -d secretKey="<my-secret-key>" \
  -d source=desktop \
  -d name=category \
  -d deviceId="<device-id>" \
  -d userId="<user-id>" \
  -d categoryId[]="Skate"
subcategory
curl -v -G "https://recs.chaordicsystems.com/v0/pages/recommendations" \
  -d apiKey="<my-api-key>" \
  -d secretKey="<my-secret-key>" \
  -d source=desktop \
  -d name=subcategory \
  -d deviceId="<device-id>" \
  -d userId="<user-id>" \
  -d categoryId[]="Skate" \
  -d categoryId[]="Tênis"
cart
curl -v -G "https://recs.chaordicsystems.com/v0/pages/recommendations" \
  -d apiKey="<my-api-key>" \
  -d secretKey="<my-secret-key>" \
  -d source=desktop \
  -d name=cart \
  -d deviceId="<device-id>" \
  -d userId="<user-id>" \
  -d productId[]="P001" \
  -d productId[]="P002"
landing_page
curl -v -G "https://recs.chaordicsystems.com/v0/pages/recommendations" \
  -d apiKey="<my-api-key>" \
  -d secretKey="<my-secret-key>" \
  -d source=desktop \
  -d name=landing_page \
  -d deviceId="<device-id>" \
  -d userId="<user-id>" \
  -d url="https://www.sample.com.br/feminino/home"
search
curl -v -G "https://recs.chaordicsystems.com/v0/pages/recommendations" \
  -d apiKey="<my-api-key>" \
  -d secretKey="<my-secret-key>" \
  -d source=desktop \
  -d name=search \
  -d deviceId="<device-id>" \
  -d userId="<user-id>"
  -d productId[]="P001" \
  -d productId[]="P002"
emptysearch
curl -v -G "https://recs.chaordicsystems.com/v0/pages/recommendations" \
-d apiKey="<my-api-key>" \
-d secretKey="<my-secret-key>" \
-d source=desktop \
-d name=emptysearch \
-d deviceId="<device-id>" \
-d userId="<user-id>"

Product Formats

compact
{
  "id": "12345",
  "status": "available",
  "name": "sample-product-A",
  "price": 99.9,
  "oldPrice": 109.9,
  "installment": {
    "count": 2,
    "price": 50.00
  },
  "trackingUrl": "https://recs.chaordicsystems.com/v0/click/?trackingId=<tracking-id>",
  "url": "sample.com.br/sample-product-a.html",
  "images": {
    "default": "sample.com.br/img/sample-product-a.img"
  }
}
complete
{
  "id": "12345",
  "status": "available",
  "name": "sample-product-A",
  "price": 99.9,
  "oldPrice": 109.9,
    "installment": {
        "count": 2,
        "price": 50.00
  },
  "description": "A description about sample-product-A.",
  "url": "sample.com.br/sample-product-a.html",
  "categories": [
      {
          "id": "sample_category_0003",
          "name": "sample_category_0003",
          "parents": [
              "sample_category_0002"
          ]
      },
      {
          "id": "sample_category_0002",
          "name": "sample_category_0002",
          "parents": [
              "sample_category_0001"
          ]
      },
      {
          "id": "sample_category_0001",
          "name": "sample_category_0001",
          "parents": null
      }
  ],
  "tags": [
      {
          "id": "sample_tag_0001",
          "name": "sample_tag_0001",
          "parents": null
      },
      {
          "id": "sample_tag_0002",
          "name": "sample_tag_0002",
          "parents": null
      },
      {
          "id": "sample_tag_0003",
          "name": "sample_tag_0003",
          "parents": null
      }
  ],
  "images": {
      "default": "sample.com.br/img/sample-product-a.img"
  },
  "details": {
      "altura": "95 cm",
      "largura": "221 cm",
      "profundidade": "101 cm",
      "peso": "55,000 kg"
  },
  "skus": [
      {
        "images": {
            "default": "sample.com.br/product-sku-image"
        },
        "price": 74,
        "oldPrice": 74,
        "installment": {
            "count": 3,
            "price": 24.66
        },
        "url": "sample.com.br/product-sku-link",
        "status": "unavailable",
        "sku": "0014542",
        "specs": {
            "color": "branco"
        }
    },
      {
        "images": {
            "default": "sample.com.br/product-sku-image"
        },
        "price": 74,
        "oldPrice": 74,
        "installment": {
            "count": 3,
            "price": 24.66
        },
        "url": "sample.com.br/product-sku-link",
        "status": "unavailable",
        "sku": "0014542",
        "specs": {
            "color": "preto"
        }
    }
  ],
    "trackingUrl": "https://recs.chaordicsystems.com/v0/click/?trackingId=<tracking-id>"
}
onlyIds
{
  "id": "12345",
  "trackingUrl": "https://recs.chaordicsystems.com/v0/click/?trackingId=<tracking-id>"
}

Responses

Visualizados
{
  "top": [
    {
      "id": "widget_id_001",
      "title": "Widget 001 Title",
      "name": "Visualizados",
      "feature": "ViewPersonalized",
      "impressionUrl": "https://recs.chaordicsystems.com/v0/impression/?trackingImpression=<impression-hash>",
      "displays": [
        {
          "references": [
            {
              "id": "product-A",
              "name": "sample-product-A",
              //...
            }
          ],
          "recommendations": [
            {
              "id": "product-B",
              "name": "sample-product-B",
              //...
            },
            {
              "id": "product-C",
              "name": "sample-product-C",
              //...
            },
            {
              "id": "product-D",
              "name": "sample-product-D",
              //...
            },
            //...
          ],
          "refreshReferenceUrl": "https://recs.chaordicsystems.com/v0/widgets/?data=<reference-data>"
        }
      ]
    },
    //...
  ],
  "middle": [
    //...
  ],
  "bottom": [
    //...
  ]
}
Comprados
{
  "top": [
    //...
  ],
  "middle": [
    {
      "id": "widget_id_003",
      "title": "Widget 003 Title",
      "name": "Comprados",
      "feature": "PurchasePersonalized",
      "impressionUrl": "https://recs.chaordicsystems.com/v0/impression/?trackingImpression=<impression-hash>",
      "displays": [
        {
          "references": [
            {
              "id": "product-A",
              "name": "sample-product-A",
              //...
            }
          ],
          "recommendations": [
            {
              "id": "product-B",
              "name": "sample-product-B",
              //...
            },
            {
              "id": "product-C",
              "name": "sample-product-C",
              //...
            },
            {
              "id": "product-D",
              "name": "sample-product-D",
              //...
            },
            //...
          ],
          "refreshReferenceUrl": "https://recs.chaordicsystems.com/v0/widgets/?data=<reference-data>"
        }
      ]
    }
  ],
  "bottom": [
    //...
  ]
}
Abandonados
{
  "top": [
    //...
  ],
  "middle": [
    //...
  ],
  "bottom": [
    {
      "id": "widget_id_004",
      "title": "Widget 004 Title",
      "name": "Abandonados",
      "feature": "cartpersonalized",
      "impressionUrl": "https://recs.chaordicsystems.com/v0/impression/?trackingImpression=<impression-hash>",
      "displays": [
        {
          "references": [
            {
              "id": "product-A",
              "name": "sample-product-A",
              //...
            }
          ],
          "recommendations": [
            {
              "id": "product-B",
              "name": "sample-product-B",
              //...
            },
            {
              "id": "product-C",
              "name": "sample-product-C",
              //...
            },
            {
              "id": "product-D",
              "name": "sample-product-D",
              //...
            },
            //...
          ],
          "refreshReferenceUrl": "https://recs.chaordicsystems.com/v0/widgets/?data=<reference-data>"
        }
      ]
    },
    //...
  ]
}
Histórico
{
  "top": [
    {
      "id": "widget_id_001",
      "title": "Últimos Vistos",
      "name": "Histórico",
      "feature": "HistoryPersonalized",
      "impressionUrl": "https://recs.chaordicsystems.com/v0/impression/?trackingImpression=<impression-hash>",
      "displays": [
        {
          "references": [
            {
                "id": "product-A",
                "name": "sample-product-A",
                "getRecommendationsUrl": "https://recs.chaordicsystems.com/v0/widgets/?data=<reference-data>"
                //...
            },
            {
                "id": "product-A",
                "name": "sample-product-A",
                "getRecommendationsUrl": "https://recs.chaordicsystems.com/v0/widgets/?data=<reference-data>"
                //...
            },
            {
                "id": "product-A",
                "name": "sample-product-A",
                "getRecommendationsUrl": "https://recs.chaordicsystems.com/v0/widgets/?data=<reference-data>"
                //...
            },
            {
                "id": "product-A",
                "name": "sample-product-A",
                "getRecommendationsUrl": "https://recs.chaordicsystems.com/v0/widgets/?data=<reference-data>"
                //...
            }
          ],
          "recommendations": [
            {
                "id": "product-B",
                "name": "sample-product-B",
                //...
            },
            {
                "id": "product-C",
                "name": "sample-product-C",
                //...
            },
            {
                "id": "product-D",
                "name": "sample-product-D",
                //...
            },
            //...
          ]
        }
      ]
    }
  ],
  "middle": [
    //...
  ],
  "bottom": [
    //...
  ]
}
Promovidos com Menu
{
  "top": [
    {
      "id": "widget_id_001",
      "title": "Widget 001 Title",
      "name": "Promovidos",
      "feature": "Push",
      "impressionUrl": "https://recs.chaordicsystems.com/v0/impression/?trackingImpression=<impression-hash>",
      "displays": [
        {
          "references": [
            //...
          ],
          "recommendations": [
            {
                "id": "product-B",
                "name": "sample-product-B",
                //...
            },
            {
                "id": "product-C",
                "name": "sample-product-C",
                //...
            },
            {
                "id": "product-D",
                "name": "sample-product-D",
                //...
            },
            //...
          ],
          "menu": [
            {
              "campaignId": "campaignId-00",
              "label": "label0",
              "index": 0,
              "selected": true,
              "url": "https://recs.chaordicsystems.com/v0/widgets/?data=<reference-data>"
            },
            {
              "campaignId": "campaignId-01",
              "label": "label1",
              "index": 1,
              "url": "https://recs.chaordicsystems.com/v0/widgets/?data=<reference-data>"
            },
            {
              "campaignId": "campaignId-02",
              "label": "label2",
              "index": 2,
              "url": "https://recs.chaordicsystems.com/v0/widgets/?data=<reference-data>"
            }
          ]
        }
      ]
    }
  ],
  "middle": [
    //...
  ],
  "bottom": [
    //...
  ]
}
Promovidos com CownDown
{
  "top": [
    {
      "id": "widget_id_001",
      "title": "Widget 001 Title",
      "name": "Promovidos",
      "feature": "Push",
      "impressionUrl": "https://recs.chaordicsystems.com/v0/impression/?trackingImpression=<impression-hash>",
      "displays": [
        {
          "references": [
            //...
          ],
          "recommendations": [
            {
              "id": "product-B",
              "name": "sample-product-B",
              //...
            },
            {
              "id": "product-C",
              "name": "sample-product-C",
              //...
            },
            {
              "id": "product-D",
              "name": "sample-product-D",
              //...
            },
            //...
          ],
          "deadline": "YYY-MM-DD"
        }
      ]
    }
  ],
  "middle": [
    //...
  ],
  "bottom": [
    //...
  ]
}
Coleções
{
  "top": [
    {
      "id": "widget_id_001",
      "title": "Widget 001 Title",
      "name": "Coleções",
      "feature": "collections",
      "impressionUrl": "https://recs.chaordicsystems.com/v1/impression/?trackingImpression=<impression-hash>",
      "references": [],
      "recommendations": [],
      "collections": [
        {
          "apiKey": "sample",
          "active": true,
          "updatedAt": "2020-04-14T15:21:32.530Z",
          "images": [
            "https://www.sualoja.com/images/collection_01.jpg"
          ],
          "id": "collection_id_001",
          "items": [
            {
              "id": "product-A",
              "name": "sample-product-A"
            },
            {
              "id": "product-B",
              "name": "sample-product-B"
            },
            {
              "id": "product-C",
              "name": "sample-product-C"
            }
          ],
          "name": "Coleção 01",
          "type": "url"
        },
        {
          "apiKey": "sample",
          "active": true,
          "updatedAt": "2020-04-14T15:25:31.794Z",
          "images": [
            "https://www.sualoja.com/images/collection_02.jpg"
          ],
          "id": "collection_id_002",
          "items": [
            {
              "id": "product-D",
              "name": "sample-product-D"
            },
            {
              "id": "product-E",
              "name": "sample-product-E"
            },
            {
              "id": "product-F",
              "name": "sample-product-F"
            }
          ],
          "name": "Coleção 02",
          "type": "url"
        }
      ]
    }
  ],
  "middle": [
    //...
  ],
  "bottom": [
    //...
  ]
}