Manual de Integração – SmartHint

Manual de Integração – SmartHint

Última atualização – agosto de 2018

Introdução

A integração com a SmartHint é realizada em duas implementações a serem descritas nesse documento, sendo a primeira de API onde é obtido informações de produto, categoria e ordem/pedido de compra e a segunda implementação sobre a inserção de javascript na loja que será responsável por localização de onde as vitrines serão exibidas.

 

Endereço de web service

O endereço do webservice é constituído da URL descrita abaixo, ele deve ser enviada com o tipo de requisição `POST` com o tipo de conteúdo postado em Json.

Cada tipo de dado possui seu próprio endereço:

 

https://api.smarthint.co/api/Product/

https://api.smarthint.co/api/Order/

https://api.smarthint.co/api/Category/

 

Produto – As informações de produto devem ser enviadas para as ações de criação, alteração ou remoção (recomendamos adicionar um webhook nessas ações).

Ordem – Deve ser enviado após o cliente realizar uma compra.

Categoria – As informações de categoria devem ser enviadas para as ações de criação, alteração ou remoção.


Token – Ao criar uma conta na Smarthint, você deve receber um código de autorização concedido pela SmartHint, esse código representa sua loja e não pode ser compartilhado com ninguém. Você deve passar esse valor no cabeçalho `Authorization` da requisição. Para obter o Token acesse: https://admin.smarthint.co/Config/ApiConfig

SH-Code – Será inserido em todas as páginas via Javascript, ele identifica sua loja para obtenção e envio de dados.

 

Requisição modelo

var url = “https://api.smarthint.co/api/Product/”;
HttpWebRequest request = (HttpWebRequest)HttpWebRequest.Create(url);
request.Headers.Add(“Authorization”, CÓDIGO);
request.ContentType = “application/json”;
request.Method = “POST”;
HttpWebResponse response = (HttpWebResponse)request.GetResponse();Stream dataStream = response.GetResponseStream();

StreamReader reader = new StreamReader(dataStream);

String json = reader.ReadToEnd();
var OBJETO = JsonConvert.SerializeObject(json);
streamWriter.Write(jsonItem);
streamWriter.Flush();
streamWriter.Close();

 

Retorno da API

Basicamente a API retorna 4 códigos descrevendo o resultado da operação:

 

  • 200: A operação solicitada foi concluída com sucesso.
  • 401: O token Authorization inserido no header da requisição é inválido ou expirou.
  • 403: Houve um erro na operação. Normalmente este erro ocorre quando não se coloca a Key Authorization no header da requisição contendo o token.
  • 500: Ocorreu um erro interno do servidor.

 

Para todos os códigos de erro, junto ao cabeçalho de resposta é inserido duas chaves que descrevem o erro:

 

  • sh-error-message: Mensagem de erro geral. Nela acompanha uma breve descrição da SmartHint API sobre o erro.
  • sh-stack: Último dado na pilha de chamadas que ocasionou o erro.

 

Estrutura do Objeto

A estrutura de objetos de cada método varia de acordo com o tipo de dados enviado para a requisição, eles devem ser enviados no formato json, abaixo está a descrição dos campos junto de exemplo pra cada um dos tipos:
(Campos com asterisco são obrigatórios).

 

Produto

 

Produto
Tipo Campo Descrição do campo
string ProductId* Identificador do produto
string Mpn Código de referência do fabricante
string Sku Código de referência de estoque
string Link* URL do produto
string Title* Título / Nome
string Description Descrição
string ImageLink* Imagem principal
Lista<string> AdicionalImageLink Lista de imagens adicionais
string Brand Marca / Fabricante
string ProductType* Tipo do produto
Lista<string> Categories Lista de categorias do produto
decimal Price* Preço comum
decimal SalePrice Preço de desconto
decimal BankSlipPrice Preço quando pagamento via Boleto
string Condition* Estado de condição
string Availability* Disponibilidade
date CreatedDate* Data de criação
string ItemGroupId Identificador do produto (quando for uma variação)
Installments Installments.Months Quantidade máxima de parcelas
Installments Installments.Amount Valor de cada parcela

 

*O campo `ItemGroupId` não deve ser enviado quando for um produto e não uma variação. Quando receber uma variação de produto basta colocar o Id da variação em `ProductId` e o Id referência do produto em `ProductId`.

*Campo `Condition` possui os valores `new` para produtos novos e `old` para usados.

*Campo `Availability` possui os valores `in stock` para produtos publicados, com estoque e disponíveis para venda e `out of stock` para produtos que não devem ser vendidos e fora de estoque.

{
“ProductId”: “1234”,
“Mpn”: “9999ABC”,
“Sku”: “9999ABC”,
“Link”: “http://loja.com/produto”,
“Title”: “Produto exemplo”,
“Description”: “Descrição do produto”,
“ImageLink”: “http://loja.com/produto/foto-principal”,
“AdicionalImageLink”: [
“http://loja.com/produto/foto1”,
“http://loja.com/produto/foto2”
],
“Brand”: “Oakley”,
“ProductType”: “Óculos de sol”,
“Categories”: [
“Masculino,
Acessórios
],
Price“: 259.90,
SalePrice“: 229.90,
BankSlipPrice“: 219.90,
Condition“: “new“,
Availability“: “in stock“,
CreatedDate“: “2013-07-22 21:52:38“,
ItemGroupId“: “1230“,
Installments“: {
Months“: 5,
Amount“: 51.98  
}
}

 

Ordem ou pedido (pode ser feito via Script)

 

*Essa informação pode ser enviada via javascript após o cliente realizar a compra.

 

Ordem / Pedido
Tipo Campo Descrição do campo
string session Gravado no cookie SmartHint-Session
string anonymousConsumer Gravado no cookie SmartHint-AnonymousConsumer
string OrderId* Identificador da ordem
date Date* Data do pedido
decimal Freight Valor do frete
decimal Discount Valor de desconto
decimal Total* Total do pedido
string Billing.Mode* Modo de pagamento
string Billing.ModeId Identificador do modo de pagamento
int Billing.Installments Quantidade de parcelas
decimal Billing.InstallmentsValue Valor de cada parcela
Lista<string> Items* Itens/produtos do pedido
Items.Name* Nome do produto
Items.ProductId* Identificador do produto
Items.Quantity* Quantidade comprada
Items.UnitPrice* Preço unitário

 

{
“OrderId”: “1234”,
“Date”: “2018-06-06”,
“Discount”: 0.0,
“Freight”: 17.76,
“Total”: 195.6,“session”:[COOKIE : SmartHint-Session],
“anonymousConsumer”: [COOKIE : SmartHint-AnonymousConsumer],
“Billing”: {
“Mode”: “BOLETO”,
“ModeId”: “10”,
“Installments”: 1,
“InstallmentsValue”: 195.60
},
“Items”: [{
“Name”: “Pop Deadpool Two Swords”,
“ProductId”: “15”,
“Quantity”: 1,
“UnitPrice”: 98.1
}, {
“Name”: “Pop Homem de Ferro”,
“ProductId”: “20”,
“Quantity”: 1,
“UnitPrice”: 89.1
}]
}

Categoria

 

Categoria
Tipo Campo Descrição do campo
string CategoryId* Identificador da categoria
string CategoryParentId Identificador da categoria superior (mais abrangente)
string Name* Nome
string Url* Caminho para acesso
string FullPath Caminho completo da categoria
int Level* Level da categoria

 

*Campo `CategoryParentId` deve ser deixado vazio quando não possuir uma categoria pai.
*Campo `Level` deve indicar o nível da categoria sendo zero quando for a maior.

 

{
“CategoryId”: “10”,
“CategoryParentId”: “”,
“Name”: “Outlet”,
“Url”: “https://www.dominio.com.br/outlet/”,
“FullPath”: “Outlet”,
“Level”: 0
}

 

Inserção de Script da Loja

Após realizar a integração com a API da Smarthint é necessário configurar a loja para receber as vitrines.

Para isso será necessário realizar algumas etapas, sendo elas:

 

  • Inserção de script genérico;
  • Adicionar posições do layout nas lojas;
  • Identificar o tipo da página;
  • Obter dados de pedido/ordem (pode ser feito via API);
  • Identificar de busca produtos (não obrigatório);
  • Informações de carrinho (não obrigatório).

 

 

Script genérico

 

Para captar corretamente os dados, é necessário inserir um script  genérico. Basta copiar e colar no cabeçalho <header> de todas as páginas.

 

<script type=“text/javascript”>
   var smarthintkey = “{0}”;
   SmartHint = typeof SmartHint !=‘undefined’? SmartHint : {};
   SmartHint.Calls = SmartHint.Calls ? SmartHint.Calls : [];
   SmartHint.Call = function (action, args) {
       SmartHint.Calls.push({ action: action, args: args });
   };    (function () {
var script = document.createElement(‘script’);
script.type = ‘text/javascript’;
script.async = true;
script.src = ‘https://service.smarthint.co/Scripts/i/SmartHint.min.js’;
var s = document.getElementsByTagName(‘script’)[0];
s.parentNode.insertBefore(script, s);
})();
</script>

 

Posições do layout das páginas

 

Todas as páginas devem ser inseridas cinco posições, sendo que seu conteúdo pode ser configurado no portal da SmartHint. Para obter melhor taxa de vendas, recomendamos que essas posições fiquem bem espalhadas pela página (como no topo da página, outras entre o conteúdo, outra no final da página..).

 

As posições a ser inseridas são:

 

<div id=“smarthint-position-1”></div>
<div id=“smarthint-position-2”></div>
<div id=“smarthint-position-3”></div>
<div id=“smarthint-position-4”></div>
<div id=“smarthint-position-5”></div>

 

Identificação de páginas

 

Ao final de cada página, deve-se indicar se é uma página de categoria, produto, principal…

Para isso insira o código ao final da página:

 

SmartHint.Call(‘setPage’,{type:’PÁGINA’, data: {} })

 

As páginas podem ser (inseridos em minúsculo):

 

  • category;
  • search;
  • home;
  • cart;
  • checkout;
  • notfound;
  • product.

 

 

Além disso, no campo `data` deve ser enviado `content` para Search e Category.

 

Search – >

SmartHint.Call(‘setPage’,{type:’search’, data: { content: “BUSCA” } })

 

Category – >

SmartHint.Call(‘setPage’,{type:’category’, data: { content: “CATEG” } })

 

Obter dados de ordem/pedido

 

Ao finalizar uma compra, é necessário realizar a chamada das funções javascript abaixo.

*Não é necessário realizar nos casos de API.

 

SmartHint.Call(‘setOrder’,{
   OrderId : ‘mpj-1535 ab’,
   Total : 162.00,
   Freight : 17.00,
   Discount : 15.00,
   BillingMode : ‘Cartão de Credito’,
   Installments : 2,
   InstallmentsValue : 131.0
});
SmartHint.Call(‘addItemOrder’,{
   Id: ‘1755-m’,
   Name: ‘Camiseta SmartHint Tamanho M’,
   Quantity: 2,
   UnitPrice: 40.00
});
SmartHint.Call(‘addItemOrder’,{
   Id: ‘1755-m’,
   Name: ‘Camiseta SmartHint Tamanho g’,
   Quantity: 2,
   UnitPrice: 40.00
});
SmartHint.Call(‘sendOrder’);

 

Informações de carrinho

 

Em todas as páginas, pode ser inserido o script que reconhece se o carrinho encontra-se vazio. Seu valor pode ser `true` ou `false`

 

SmartHint.Call(‘setProductCart’,{
   empty: false
});

 

Editando o Layout

Com as informações acima, as vitrines já poderão ser exibidas, mas quebradas. Nesse ponto é necessário copiar e editar seu layout para as nossas vitrines.

Isso é realizado utilizando Mustache, que é identificado por chaves para cada campo.

 

Acesse sua conta da Smarthint > Recomendações > Template > Editar.

 

  • A classe `Slick-it` é responsável por formar a vitrine em formato de carrossel, deixe-o na Tag exterior fora de {{#Products}}.

 

Será exibido um layout de exemplo, altere-o colocando o seu modelo e editando as informações pelas seguintes Tags::

 

Campos para criar layout

 

Tags de Layout
Campo Descrição
{{BoxTitle}} Título do box que vem das configurações de cada recomendação
{{#Products}} Forma um loop com a lista de produtos recomendados (caso exista)
{{Title}} Título do produto
{{ProductId}} Identificador do produto
{{Mpn}} MPN do produto
{{Sku}} SKU do produto
{{{Link}}} URL do produto (observar que nesta variável é utilizado três parênteses)
{{{ImageLink}}} URL da imagem do produto (observar que nesta variável é utilizado três parênteses)
{{#SecondImageLink}} Se existir imagem secundária, será executado o código da sequência
{{SecondImageLink}} URL da imagem secundária do produto
{{/SecondImageLink}} Final do bloco de imagem secundária
{{#HasPromotion}} Se existir promoção, será executado o código da sequência
{{PromotionDiscount}} Desconto promocional
{{/HasPromotion}} Final do bloco de promoção
{{#HasDiscount}} Se existir desconto, será executado o código da sequência
{{Discount}} Percentual de desconto (Preço De / Preço Por) convertido para inteiro
{{/HasDiscount}} Final do bloco Desconto
{{#HasSalePrice}} Se existir preço De/Por, será executado o código da sequência
{{Price}} Preço De: (Preço do produto SEM desconto)
{{PriceInteger}} Parte inteira do Preço De: (antes da vírgula)
{{PriceDecimal}} Parte decimal do Preço De: (depois da vírgula)
{{SalePrice}} Preço Por: (Preço do produto COM desconto)
{{SalePriceInteger}} Parte inteira do Preço Por: (antes da virgula)
{{SalePriceDecimal}} Parte decimal do Preço Por: (depois da virgula)
{{^HasSalePrice}} Caso NÃO exista Preço DeEndPor, será executado o código da sequência
{{/HasSalePrice}} Final do bloco Preço De/Por
{{#HasBankSlipPrice}} Se existir preço do boleto (à vista), será executado o código da sequência
{{BankSlipPrice}} Preço Boleto: (Preço à vista)
{{BankSlipPriceInteger}} Parte inteira do Preço Boleto: (antes da virgula)
{{BankSlipPriceDecimal}} Parte decimal do Preço Boleto: (depois da virgula)
{{/HasBankSlipPrice}} Final do bloco Preço do Boleto
{{#HasInstallment}} Se existir Parcelamento, será executado o código da sequência
{{Installment}} Quantidade de Parcelas
{{InstallmentAmount}} Valor da Parcela
{{InstallmentAmountInteger}} Valor inteiro da Parcela (antes da virgula)
{{InstallmentAmountDecimal}} Valor decimal da Parcela (depois da virgula)
{{#HasInterest}} Informa se existe ou não juros no parcelamento
{{/HasInterest}} Final do bloco Juros
{{/HasInstallment}} Final do bloco Parcelamento
{{/Products}} Final do bloco Produtos
{{ReleaseDateDescription}} Apresenta em dias, semanas e meses o tempo do lançamento, Ex. “2 semanas atrás”
{{ItemGroupId}} Exibe o código do produto quando houver variação

 

Alterando posições no portal

 

Podemos indicar onde determinada vitrine ficará exposta no portal da SmartHint. Para isso acesse ‘Recomendação > Template > Scripts’.
O posicionamento é feito através de métodos internos usando como base elemento Jquery indicados pelo Lojista. As vitrines podem ser inseridas entre antes desse elemento (before), após (after), inserido antes do conteúdo (prepend) e inserido internamente no final (append). Segue abaixo exemplo da utilização:

SmartHint.Box.addPosition(jQuery(“.elemento-1”), 1, ‘before’);
SmartHint.Box.addPosition(jQuery(“.elemento-2”), 2, ‘before’);
SmartHint.Box.addPosition(jQuery(“#conteudo”), 3, ‘before’);
SmartHint.Box.addPosition(jQuery(“#conteudo”), 4, ‘before’);
SmartHint.Box.addPosition(jQuery(“#conteudo”), 5, ‘before’);

 

Configurações do Carousel

 

O carousel pode ser editado, exibindo uma quantidade determinada por vitrine, configurando auto execução, botões e outras diversas configurações. Para sua utilização acesse ‘Recomendações > Template > Propriedade’.
– Caso o campo de configurações esteja em branco utilizaremos um padrão de todas as lojas.

Documentação do carousel: http://kenwheeler.github.io/slick/

Exemplo de script a ser inserido no campo:

{
 dots: true,
 infinite: false,
 slidesToShow: 4,
 slidesToScroll: 4,
 responsive: [
   {
     breakpoint: 1024,
     settings: {
       slidesToShow: 3,
       slidesToScroll: 3,
       infinite: true,
     }
   },
   {
     breakpoint: 600,
     settings: {
       slidesToShow: 2,
       slidesToScroll: 2
     }
   },
 ]
}