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:

  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: http://trustvox.com.br/api/stores or http://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" 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" : "http://store.example.com",
    "email" : "owner@store.example.com"
}' \
'http://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": "http://staging.trustvox.com.br/lojas/283"
    },
    {
      "rel": "store_permalink",
      "href": "http://store.example.com"
    },
    {
      "rel": "photo_url",
      "href": "//s3.trustvox.com.br/trustvox-core-staging-uploads/uploads/store/photo/283/horizontal"
    },
    {
      "rel": "user_url",
      "href": "http://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: http://trustvox.com.br/api/stores/store_id/orders or http://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 tagsOptional
    • 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
    • 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

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",
        "email": "jbuyer@example.com",
	"tags": ["Sex/Male", "Age/21"]
    },
    "items": [
        {
            "name": "Book",
            "id": "5115C",
            "url": "http://store.example.com/book",
            "price": 19.20,
            "photos_urls": ["http://store.example.com/book.png"],
            "tags": ["Brand/AwesomeProduct", "Type/Incredible"],
            "extra": { "category": "health" }
        }
    ],
    "tags": ["Delivery/ClientTakeout", "Channel/OmnichannelSell"]
}' \
'http://staging.trustvox.com.br/api/stores/286/orders'

Results in:

{
  "order_id": 1,
  "client": {
    "first_name": "John",
    "last_name": "Buyer",
    "email": "jbuyer@example.com",
    "tags": ["Sex/Male", "Age/21"]
  },
  "delivery_date": "2014-02-02",
  "items": [
    {
      "id": "5115C",
      "name": "Book",
      "url": "http://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: http://trustvox.com.br/api/stores/store_id or http://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"
}' \
'http://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: http://trustvox.com.br/api/stores or http://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: admin@admin.com.br)
  • 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" \
'http://staging.trustvox.com.br/api/stores?url=http://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": "http://staging.trustvox.com.br/lojas/431"
    },
    {
      "rel": "store_permalink",
      "href": "http://store.example.com"
    },
    {
      "rel": "photo_url",
      "href": "//s3.trustvox.com.br/trustvox-core-staging-uploads/uploads/store/photo/431/horizontal"
    }
  ]
}

Ainda precisa de ajuda? Entre em contato Entre em contato