Integração via API de uma loja e Instalação no Front-end

Este artigo orienta a como seguir na sua integração com nossa API e instalação do Front-end.

Atenção! Para realizar este manual você precisa ter em mãos um "StoreId" e um "StoreToken" fornecido por nossa equipe. 

Ao fim, você será capaz de: 

  • Enviar pedidos para a base RA Trustvox, para que possamos coletar opiniões sobre seu produto;
  • Também exibir as opiniões coletadas nas páginas de sua loja.

   

Bora lá! São dois passos:

1. Integração, responsável por enviar os pedidos para a RA Trustvox:

Sempre que uma venda atinge seu estado final de sucesso (por exemplo: entregue). O endpoint abaixo deve receber uma requisição contendo os dados do pedido que deve ter sua opinião coletada.

Endpoints:  

Obs¹.: Escolha o endpoint de acordo com o ambiente que está realizando a integração, staging ou produção.
Obs².: Na URL do endpoint contén "store_id", no lugar deste, deve estar o número informado por nossa equipe como "StoreId", exemplo: https://staging.trustvox.com.br/api/stores/12345/orders

    

Descritivo sobre os dados da requisição:

  • HTTP Method: POST
  • Request Headers
    • Content-Type: application/json
    • Accept: application/vnd.trustvox.com; version=1
    • Authorization: token StoreToken (Alterar para o StoreToken fornecido por nossa equipe)
  • Request Body
    • order_id (number or string): identificador único do pedido (obrigatório)
    • delivery_date (string): data em que o pedido foi entregue (obrigatório)
    • client (object): dados sobre o consumidor (obrigatório)
      • email (string): e-mail do consumidor (obrigatório)
      • first_name (string): primeiro nome do consumidor (obrigatório)
      • last_name (string): segundo nome do consumidor (obrigatório)
      • phone_number (string): telefone do consumidor (nos 5519900011111, +5519900011111, +55 (19) 900011111) (opcional)
      • tags (array of strings): trata-se de um array de strings sobre o cliente (Ex.: "Sexo/Masc", leia mais em article on structured tags) (opcional)
    • items (array of objects): dados sobre o produto ou serviço
      • id (string): Identificador do produto (deve ser o mesmo entregue no front-end) (obrigatório)
      • url (string): URL do produto (obrigatório)
      • name (string): nome do produto (obrigatório)
      • price (number): preço do produto (opcional)
      • photos_urls (array of strings): array de imagens do produto (opcional porém recomendado)
      • tags (array of strings): trata-se de um array de strings sobre o produto (Ex.: "Marca/Incrível", leia mais em article on structured tags) (opcional)
      • extra (object): campo utilizado para filtragens de produto onde não é permitida a coleta de opiniões (informar nossa equipe) (opcional)
    • seller (object): dados sobre o seller em caso de marketplace
      • id (string): identificador único do seller (obrigatório)
      • name (string): nome do seller (obrigatório)
      • logo (string): logotipo do seller (opcional)
    • tags (array of strings):  trata-se de um array de strings sobre o pedido como um todo (Ex.: "Origem/LojaFisica", leia mais em article on structured tags) (opcional)

Segue um exemplo em cURL:

curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --header "Accept: application/vnd.trustvox.com; version=1" \
     --header "Authorization: token XXXXXXXXXXXXXXXXXXX" \
     --data-binary '{
    "order_id": 1,
    "delivery_date": "2014-02-02T14:26:40+00:00",
    "client": {
        "first_name": "John",
        "last_name": "Buyer",
	"phone_number": "5541994163481",
        "email": "jbuyer@example.com",
	"tags": ["Sex/Male", "Age/21"]
    },
    "items": [
        {
            "name": "Book",
            "id": "5115C",
            "url": "https://store.example.com/book",
            "price": 19.20,
            "photos_urls": ["https://store.example.com/book.png"],
            "tags": ["Brand/AwesomeProduct", "Type/Incredible"],
            "extra": { "category": "health" }
        }
    ],
    "seller": {
      "id": "seller-id-example",
      "name": "Seller Name",
      "logo": "https://seller.logo/example.png"
    },
    "tags": ["Delivery/ClientTakeout", "Channel/OmnichannelSell"]
}' \
'https://staging.trustvox.com.br/api/stores/12345/orders'

Esta requisição precisa ser feita para cada novo pedido finalizado/entregue pela empresa.

Com este, recebemos um(ou mais) pedidos em nossa base, e na sequência vamos coletar opiniões via e-mail, com base nos dados informados no payload da requisição (pedido).

Concluiu este passo? Sugerimos informar nossa equipe para validar se os pedidos encaminhados para nós chegaram até nossa base. :)

Após isto, vamos pro segundo e último passo. ;D


2. Instalação das ferramentas visuais na sua página de produto:

Acessar: https://help.trustvox.com.br/article/388-instalacao-generica-dos-scripts-da-trustvox

No artigo acima você fará a implementação das ferramentas visuais em seu Front-end.

Nele você encontrará os widgets básicos: 

  • Widget de opiniões de produto;
  • Estrelas para vitrines e listagens de produtos;
  • Estrelas para abaixo do nome do produto na página do mesmo;
  • Certificado de reviews verdadeiros (Selo)

Atentando para que, deve-se informar os dados dos produtos (todos dados obrigatórios) dentro dos scripts dos widgets.  

O identificador do produto entregue através de "productId" no front-end, deverá ser o mesmo informado anteriormente na requisição da integração em “item > id”. 


E feito! Com estes dois passos estará tudo certinho.

Você pode pedir para nossa equipe validar. :)

Até mais!