Integration for e-commerce platforms

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:

Create store
Import store sales
Control store activity status

You may additionally:

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", "Infracommerce", "JetEcommerce", "Loja Integrada", "Magento", "Maxistore", "Moovin", "PrestaShop", "Rakuten", "TrayCommerce", "Vertis", "Outra plataforma", "OpenCart", "Online", "WooCommerce", "MKX", "Whitelabel LI", "Betalabs", "LojistaOnline", "N2N Virtual", "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"
    }
  ]
}