This text guides e-commerce platforms developers through the steps required to integrating with Trustvox reviews service.

Integrating with Trustvox

Basic steps for integration are the following ones:

  1. Create store

  2. Import store sales

  3. Control store activity status

You may additionally:

  1. Lookup for existing stores

Create Store

To create a store you should perform a request as given:

  • Endpoint: https://trustvox.com.br/api/stores or https://staging.trustvox.com.br/api/stores

  • HTTP Method: POST

  • Request Headers

    • Accept: application/vnd.trustvox-v2+json

    • Authorization: token your_platform_token IMPORTANT

  • Request Body

    • name (string): store's name Required

    • cnpj (string): store's legal identification Required unless CPF is provided

    • cpf (string): store's owner legal identification Required unless CNPJ is provided

    • email (string): store's owner e-mail Required

    • url (string): store's URL Required Unique

    • photo_url (string): store's photo URL Optional

    • platform_name (string): store's e-commerce platform. Should be one of the following values: "VTEX", "Nuvemshop", "Ciashop", "COMM2", "DLojaVirtual", "Dotstore", "EZCommerce", "Fastcommerce", "Iluria", "Infracommerce", "JetEcommerce", "Loja Integrada", "Magento", "Maxistore", "Moovin", "PrestaShop", "Rakuten", "TrayCommerce", "Vertis", "Outra plataforma", "OpenCart", "Online", "WooCommerce", "Xtech Commerce", "MKX", "Whitelabel LI", "Betalabs", "LojistaOnline", "N2N Virtual", "MercadoShops", "Jet Commerce NEO UOL", "Climba". Optional

  • Success Response HTTP Status: 201 Created

  • Success Response Body:

    • id: Trustvox unique identifier for the newly created store

    • name: store's name

    • created_at: timestamp for store's creation time

    • store_token: access token that must be used for importing store sales IMPORTANT

    • cpf / cnpj: store's legal identification

    • links:

      • self: URL for manipulating store through Trustvox API

      • store_permalink: store's URL as give in the create request

      • user_url: URL for completing user registration within Trustvox for store's owner IMPORTANT

      • photo_url: URL for store's photo

Notice that:

  • You'll need to provide a proper access token within authorization headers

  • Keep the returned store_token: it'is used to import store sales

  • The owner of the store should be pointed to returned user_url URL to complete her user's registration within Trustvox dashboard

cURL Example

Performing the following cURL command

curl --include \
--request POST \
--header "Content-Type: application/json" \
--header "Accept: application/vnd.trustvox-v2+json" \
--header "Authorization: token obscured" \
--data-binary '{
"name": "Store Created Through Trustvox API",
"cnpj": "41.045.503/0001-60",
"url": "https://store.example.com",
"email": "[email protected]",
"photo_url": "https://via.placeholder.com/150C/O"
}' \
'https://staging.trustvox.com.br/api/stores'

Gives the following response body:

{
"id": 283,
"name": "Store Created Through Trustvox API",
"created_at": "2016-11-18T16:54:09.639-02:00",
"cnpj": "41045503000160",
"store_token": "HdpfzGSZU_xyetCDW9DN",
"links": [
{
"rel": "self",
"href": "https://staging.trustvox.com.br/lojas/283"
},
{
"rel": "store_permalink",
"href": "https://store.example.com"
},
{
"rel": "photo_url",
"href": "//s3.trustvox.com.br/trustvox-core-staging-uploads/uploads/store/photo/283/horizontal"
},
{
"rel": "user_url",
"href": "https://staging.trustvox.com.br/usuarios/convite/accept?invitation_token=M5dAJuWzA6YeDE39x3Wa"
}
]
}

Import Store Sales

Importing store sales is nothing more than creating Trustvox sale orders whenever a sale reaches its final success state (e.g.: delivered). It can be accomplished through a request as given:

  • Endpoint: https://trustvox.com.br/api/stores/store_id/orders or https://staging.trustvox.com.br/api/stores/store_id/orders (store_id is a placeholder)

  • HTTP Method: POST

  • Request Headers

    • Content-Type: application/json

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

    • Authorization: token store_token

  • Request Body

    • order_id (number or string): store's identifier for the sale order Required Unique

    • delivery_date (string): date for sale order delivery Required

    • client (object): an object that represents sale order's consumer Required

      • email (string): consumer's e-mail Required

      • first_name (string): consumer's first name Required unless last_name is provided

      • last_name (string): consumer's last name Required unless first_name is provided

      • phone_number (string): consumer's cell phone number(format like 5519900011111, +5519900011111, +55 (19) 900011111 with country code required). Optional

      • tags (array of strings): an array of strings representing any arbitrary information (e.g. sex, age, address etc) about the client (checkout our article on structured tags) Optional

    • items (array of objects): an array of objects representing the sold products Required

      • id (string): store's identifier for the product Required

      • url (string): product's URL Required

      • name (string): product's name Optional

      • price (number): products' price Optional

      • photos_urls (array of strings): an array of strings representing URLs for product's photos Optional

      • tags (array of strings): an array of strings representing any arbitrary information about the product (checkout our article on structured tags) Optional

      • extra (object): an object with arbitrary key-value elements which may be used for filtering products Optional

    • seller (object): an object that represents sale order's seller Optional

      • id (string): external seller identifier Required

      • name (string): seller name Required

      • logo (string): seller logo URL Optional

    • tags (array of strings): an array of strings representing any arbitrary information about the sale (checkout our article on structured tags) Optional

  • Success Response HTTP Status: 201 Created

  • Success Response Body: JSON representation for sale order according to attributes given within request

Notice that:

  • You'll need to replace store_id in the endpoint URL

  • You'll need to provide the proper store token within request authorization headers

  • Sent tags replace existing ones (if any) for their target product, sale or client. This makes possible to add new, remove or edit existing tags

  • For the seller option to work, you must open a ticket to be enabled for your store.

  • In case you do not use seller, it is not necessary to add the parameter.

cURL Example

The following cURL command:

curl --include \
--request POST \
--header "Content-Type: application/json" \
--header "Accept: application/vnd.trustvox.com; version=1" \
--header "Authorization: token obscured" \
--data-binary '{
"order_id": 2,
"delivery_date": "2014-02-02T14:26:40+00:00",
"client": {
"first_name": "John",
"last_name": "Buyer",
"phone_number": "5541994163481",
"email": "[email protected]",
"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/286/orders'

Results in:

{
"order_id": 1,
"client": {
"first_name": "John",
"last_name": "Buyer",<br> "phone_number": "5541994163481",
"email": "[email protected]",
"tags": ["Sex/Male", "Age/21"]
},
"delivery_date": "2014-02-02",
"seller": {
"id": "seller-id-example",
"name": "Seller Name",
"logo" "https://seller.logo/example.png"
},
"items": [
{
"id": "5115C",
"name": "Book",
"url": "https://store.example.com/book",
"price": "19.2"
}
]
}

Control store activity status

In order to let Trustvox know whether users uninstalled or reinstalled the app within the e-commerce platform, an update should be issued to API according to the following request:

  • Endpoint: https://trustvox.com.br/api/stores/store_id or https://staging.trustvox.com.br/api/stores/store_id (store_id is a placeholder)

  • HTTP Method: PATCH

  • Request Headers

    • Accept: application/vnd.trustvox-v2+json

    • Authorization: token your_platform_token IMPORTANT

  • Request Body

    • active (string): boolean representing Trustvox status within user's store (true means it is currently installed). Required

  • Success Response HTTP Status: 204 No Content

  • Success Response Body: None

Notice that:

  • You'll need to replace store_id in the endpoint URL

  • You'll need to provide a proper access token within authorization headers

cURL Example

The following cURL command:

curl --include \
--request PATCH \
--header "Content-Type: application/json" \
--header "Accept: application/vnd.trustvox-v2+json" \
--header "Authorization: token obscured" \
--data-binary '{
"active": "false"
}' \
'https://trustvox.com.br/api/stores/5'

Results in:

HTTP/1.1 204 No Content

Lookup for existing stores

You may retrieve a store that was created earlier by performing a request with following attributes:

  • Endpoint: https://trustvox.com.br/api/stores or https://staging.trustvox.com.br/api/stores

  • HTTP Method: GET

  • Request Headers

    • Accept: application/vnd.trustvox-v2+json

    • Authorization: token your_platform_token IMPORTANT

  • Parameters

    • url (string): the URL used to previously create the store

    • admin (string): mail of administrator (example: [email protected])

  • Success Response HTTP Status: 200 Ok

  • Success Response Body: JSON representation for the store

Notice that:

  • Fetching a store for which owner hasn't accepted Trustvox invitation yet will generate a new user_url (returned within response body) that must be used for registering store's owner within Trustvox. Former user_url won't work anymore IMPORTANT

  • There will be no user_url within response if owner has already accepted her invitation

  • You'll need to provide the URL for an existing store that you've created. Server will respond with 404 Not Found otherwise

  • You'll need to provide a proper access token within authorization headers

cURL example

Following cURL command:

curl --include \
--request GET \
--header "Accept: application/vnd.trustvox-v2+json" \
--header "Authorization: token obscured" \
'https://staging.trustvox.com.br/api/stores?url=https://store.example.com'

Results in:

{
"id": 431,
"name": "Store Created Through Trustvox API",
"created_at": "2017-01-26T10:29:37.000-02:00",
"cnpj": "41045503000160",
"store_token": obscured,
"links": [
{
"rel": "self",
"href": "https://staging.trustvox.com.br/lojas/431"
},
{
"rel": "store_permalink",
"href": "https://store.example.com"
},
{
"rel": "photo_url",
"href": "//s3.trustvox.com.br/trustvox-core-staging-uploads/uploads/store/photo/431/horizontal"
}
]
}
Encontrou sua resposta?