Integração via API da RA Trustvox

Veja como seguir na sua integração com nossa API e instalação do front-end

A
Escrito por Anderson Santos
Atualizado há mais de uma semana

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


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.


Caso queiram realizar a integração no ambiente de staging ( Testes ), clique aqui para acessar documentação.


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.

Endpoint:


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://trustvox.com.br/api/stores/12345/orders

Obs².: StoreID e StoreToken variam de acordo com o ambiente, staging ou produção, os dados serão diferentes.

Descritivo sobre os dados da requisição:

  • HTTP Method: POST

  • Request Headers

    • Content-Type: application/json

    • Accept: application/vnd.trustvox.com; version=1

    • Authorization: Bearer StoreToken (Alterar para o StoreToken fornecido por nossa equipe, este dado será diferente entre ambientes staging e produção.)

  • 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://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

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

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. :)

Ficou com dúvida ou precisa de ajuda?

Entre em contato com a RA Trustvox através do chat 💬 disponível no menu 'Dúvidas e Suporte' no símbolo de interrogação❔ do seu painel (de Segunda a Sábado das 9h às 18h - exceto feriados).

Conte com a gente! 💚

Respondeu à sua pergunta?