Como integrar com a SmartHint

Introdução

A integração com a SmartHint é realizada em duas implementações a serem descritas nesse documento, sendo a primeira de API onde são obtidas 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 enviado 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/ProductList/ (recebe uma lista/array de produtos)

https://api.smarthint.co/api/ProductPartial/ (recebe uma lista/array de produtos parciais)
https://api.smarthint.co/api/Order/
https://api.smarthint.co/api/Category/

https://api.smarthint.co/api/CategoryList/ (recebe uma lista/array de categorias)

** para os métodos de lista, recomendamos separar em listas menores (por exemplo 20 produtos/categorias)

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 (selecionando Public API), você deve gerar um código de autorização, 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 gerar o código/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.

Especificando início e fim do processamento de produtos

Em todos os processamentos dos produtos, deve-se realizar a chamada (utilizando GET) do endpoint que registra o início e o fim da atualização. Antes de inicializar o envio das listas dos produtos, chamar a url https://api.smarthint.co/api/Process/ProductProcessStart?token={TOKEN} passando como parâmetro o token da loja dentro da SmartHint, o mesmo utilizado ao enviar os produtos. Exemplo:

https://api.smarthint.co/api/Process/ProductProcessStart?token=1234567890

Essa requisição terá como retorno (header “sh-import-product-process-id”) o id do processamento, que deverá ser informado na chamada de finalização do processo.

Ao terminar o envio de todos os produtos, deve-se chamar o endpoint de finalização do processo

https://api.smarthint.co/api/Process/ProductProcessFinish?token={TOKEN}&processId={PROCESSID}&success={SUCCESS}&moduleResponse={MODULERESPONSE}&messageOwner=””

• TOKEN = token de API da SmartHint

• PROCESSID = id retornado da chamada do ProcessStart

• SUCCESS = true determina se o processamento foi finalizado com sucesso e sem erros

• MODULERESPONSE = 200 para confirmar que processamento finalizou sem erros quando for processamento completo, 206 quando o processamento finalizar sem erros e for um processamento parcial

** quando for utilizado 200 como status, os produtos que não forem enviados nesse processamento serão automaticamente marcados como excluído na nossa base.

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

*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”: “Masculino > Acessórios > Óculos de sol”,

“Categories”: [

“Masculino“,

“Masculino > Acessórios“,“Masculino > Acessórios > Óculos de sol“

],

“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

},




“Tags”: [
“sol“,
“sem grau“
],

“Variations“: [

{

“NameId“: “92”,

“Name“: “color”,

“ValueId“: “26”,

“Value“: “Indigo”

},

{

“NameId“: “180”,

“Name“: “size”,

“ValueId“: “78”,

“Value“: “L”

}

],

“aditionalfeatures”: {
“addtocart“: “http://loja.com/checkout/123654”,
“imagethumbnail“: “http://loja.com/produto/foto2”
}
}

Produto Parcial

No processo de envio dos produtos, é possível enviar apenas alguns campos para serem atualizados, e unicamente com este objetivo. Um exemplo de uso deste endpoint é o caso de atualização de preços, ao invés de enviar todo o produto, pode-se enviar apenas os campos que foram alterados. A estrutura enviada deve seguir a nomenclatura dos campos descritos na seção acima, além de enviar um campo para identificação do produto.

Exemplo 1: Supondo que o produto cuja URL é “http://www.loja.com.br/produto-1”  tenha tido seu preço alterado para R$ 2,99 e que seu Product Type tenha sido alterado para Produto > Teste. Não é necessário enviar todo o produto novamente basta enviar um produto parcial da seguinte maneira:

{

“FieldSourceIdentifier”: “Link”,

“FieldSourceValue”: “http://www.loja.com.br/produto-1“,

“Values”:[




“Price“: 2.99,
“ProductType”: “Produto > Teste”

]
}

Exemplo 2: Supondo que o produto cujo ProductId é “aaa-232”  tenha entrado em promoção, e o preço de ficou em R$ 67.99 e o preço por ficou R$ 49,99. Basta enviar o seguinte produto parcial.

{

“FieldSourceIdentifier”: “ProductId”,

“FieldSourceValue”: “aaa-232“,

“Values”:[




“Price“: 67.99,
“SalePrice”: 49.99

]
}

Excluindo Produto 

Sempre que um produto é removido da base do cliente, deve-se realizar uma chamada na API para indicar que aquele produto não deve mais ser mostrado, evitando que produtos por exemplo continuem sendo recomendados e acabem ocasionando erros de Page Not Found (404). Para realizar esta operação deve-se usar o verbo HTTP “DELETE” no endpoint:

https://api.smarthint.co/api/Product?id={ProductId}

• ProductId = o mesmo valor de ProductId que é usado no envio do produto na atualização e em todas as outras opções.

Em caso de sucesso a api retorna 200 e uma mensagem contendo a Url do produto removido. Caso o produto não seja encontrado, a API irá retornar 400 (Bad Request) com uma mensagem de “Product Not Found”.

Ordem ou pedido (pode ser feito via Script)

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

{

“OrderId”: “1234”,

“Date”: “2018-06-06”,

“Discount”: 0.0,

“Freight”: 17.76,

“Total”: 195.6,“session”:enviar somente a string contida no valor do cookie SmartHint-Session( chamar SmartHint.Framework.GetSession()),

“anonymousConsumer”: enviar somente a string contida no valor do cookie SmartHint-AnonymousConsumer( chamar SmartHint.Framework.GetCookie(“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

*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

}

{

“CategoryId”: “11”,

“CategoryParentId”: “10”,

“Name”: “Calças”,

“Url”: “https://www.dominio.com.br/outlet/calcas”,

“FullPath”: “Outlet > Calças”,

“Level”: 1

}

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>

*** O valor “{0}” da variável “smarthintkey” deve ser substituído pelo SH da conta criada para a loja (esse código pode ser consultado no Admin da SmartHint, em Minha Conta / Loja Virtual, selecionando a plataforma Public API).

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:

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:

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

• category;

• search;

• searchWithResults;

• 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: “termo digitado pelo cliente” } })




SmartHint.Call(‘setPage’,{type:’searchWithResults’, data: { content: “termo digitado pelo cliente” } })

Category – >

SmartHint.Call(‘setPage’,{type:’category’, data: { content: “Calçados > Femininos > Social” } })

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

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:

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

}

},

]

}

Adicionando cupom ao Carrinho

Para que funcione o Overlay de promoção corretamente, deve-se criar uma função que insira o cupom na página do carrinho ou checkout. Para isso, utilize a função reservada SmartHint.Custom.CheckCoupon. Siga com o exemplo:

SmartHint.Custom.CheckCoupon = function () {

//Obtem o cupom e faz a ação de click

var couponEncoded = SmartHint.Framework.GetCookie(“SmartHint-Coupon”);

if (couponEncoded != undefined) {

couponEncoded = decodeURIComponent(couponEncoded);

var coupon = window.atob(couponEncoded);

jQuery(“#cupom”).val(coupon);

jQuery(“#botao-cupom”).click();

}

};