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
    • 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",
        "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" }
        }
    ],
    "seller": {
      "id": "seller-id-example",
      "name": "Seller Name",
      "logo" "http://seller.logo/example.png"
    },
    "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",
  "seller": {
    "id": "seller-id-example",
    "name": "Seller Name",
    "logo" "http://seller.logo/example.png"
  },
  "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