Introduction

Welcome to Revi API, an API REST to interact with Revi’s reviews platform. It contains resource-oriented URLs, accepts JSON-encoded requests and uses standard HTTP response codes and authentication.

This API will allow you to integrate your custom development to work with Revi. Revi needs some data to manage the review emails and all the next procedures.

Integration workflow

This is the Revi API integration workflow:

Revi sends review emails to every user that places an order. For this reason the first step should be to sync your orders with Revi in order to send the email to the customers. Check the orders section for more info.
Next you can link order products to the orders created in the previous step. This is necessary if you want your customers to review not only their shopping experience but the products too. Check the products and link products to orders sections for more info.
The platform allows you to synchronize orders even when they are not ready to sent yet. The next step would be to update orders as soon as they are ready so that Revi can send the review email. Check the update orders section for more info.
Finally, you can get your reviews filtered with an API call. Check the get reviews section for more info.

Authentication

To authorize, use the X-API-KEY header with your API KEY. You can get it in Revi Dashboard > Configuration > Integration (direct link).

curl "https://api.revi.io/api/v1/api_endpoint_here"
  -H "X-API-KEY: XXXXXXXXXXXXX"

Make sure to replace XXXXXXXXXXXXX with your API key.

You must replace XXXXXXXXXXXXX with your Revi API key.

Knowledge

This section explains some considerations about using the Revi API.

Response structure

API calls may return a JSON object included in this setting:

Calls that send info to Revi

These calls will return a success parameter that confirms the action has been made correctly.

{
  "success": true
}

Calls that get info from Revi

These calls will return the success parameter altogether with a data parameter, containing the information requested.

{
  "success": true,
  "data": {
    "orders": [ ... ] // The resource that has been requested
  }
}

Decimal format

The API expects float numbers to be with 2 fixed decimals.

30.51 <!-- Correct -->
30.5 <!-- Incorrect - Missing one decimal -->
30.50 <!-- Correct -->
30 <!-- Incorrect - Missing both decimals -->
30.00 <!-- Correct -->
30.153 <!-- Incorrect - Too much decimals -->
30. <!-- Incorrect - Invalid format -->

Date format

The API expects dates in MYSQL format YYYY-MM-DD HH:MM:SS.

2019-03-05 15:12:03 <!-- Correct -->
05-03-2019 15:12 <!-- Incorrect -->

Optional parameters

Most of the API calls include optional parameters. This means that the calls will process the parameter only if it’s included in the payload data even if it has an empty value. All parameters not specifying the “optional” label will be mandatory.

Quickstart

In order to test if the connection is successful, Revi API provides the hello_world call. It consists of an easy call to test if your environment is connecting with the Revi API successfully.

HTTP Request

POST https://api.revi.io/api/v1/hello_world

Request Parameters

Parameter	Description
test	A string of your choice

Sample JSON request

{
	"test": "Hello Revi, I'm connecting with you!"
}

Sample response.

{
    "success": true,
    "data": "Hello shop MyShopName, your request was succesful. The content of the test parameter is 'Hello Revi, I'm connecting with you!'"
}

Orders

The order object

{
  "id_store": "s01",
  "id_order": "xx1",
  "lang": "en",
  "customer_name": "Carlos",
  "customer_lastname": "García",
  "email": "example@example.es",
  "currency": "EUR",
  "shipping_cost": "6.00",
  "total_discount": "0.00",
  "taxes": "10.50",
  "vat": "21",
  "total_products": "50",
  "total_paid": "66.50",
  "status": "pending",
  "order_date": "2019-03-05 16:35:12",
  "date_status_upd": "2019-03-08 12:03:54"
}

Field	Description
id_store string (optional)	ID of the store. If you’re not a marketplace leave this empty
id_order string	ID of the order.
email string	Customer’s email.
status string	The order status. One of the following: - pending: Don’t send the review email yet. - ready: Ready to send the review email. - cancelled Order cancelled, don’t ever send email for this order.
order_date datetime	The order date. Check date format
lang string (optional)	ISO 639, 2 characters language code.
customer_name string (optional)	Customer’s name.
customer_lastname string (optional)	Customer’s lastname.
currency string (optional)	The currency in which the order was placed. Expects ISO 4217 Codes.
shipping_cost float (optional)	The shipping amount. Check decimal format
total_discount float (optional)	The discount amount. Check decimal format
taxes float (optional)	The taxes amount. Check decimal format
vat string (optional)	The VAT number without the percentage symbol.
total_paid float (optional)	Total order amount. Check decimal format
date_status_upd datetime (optional)	The last modified date of the order. This is useful to know when the order changes its status. Check date format
delete int (optional)	If you need to delete a previuosly inserted order.

Create orders

Method to create orders at Revi. This is the first integration step. Once you have synchronized your shop orders with Revi, the platform will start sending emails and obtaining reviews.

HTTP Request

POST https://api.revi.io/api/v1/orders

Request Parameters

Parameter	Description
orders	Array of order objects.

Sample JSON request

{
  "orders": [
    {
      "id_order": "xx1",
      "lang": "en",
      "customer_name": "John",
      "customer_lastname": "Doe",
      "email": "example@example.es",
      "currency": "EUR",
      "shipping_cost": "6.00",
      "total_discount": "0.00",
      "taxes": "10.50",
      "vat": "21",
      "total_products": "50",
      "total_paid": "66.50",
      "status": "pending",
      "order_date": "2019-03-05 16:35:12",
      "date_status_upd": "2019-03-08 12:03:54"
    },
    {
      "id_order": "xx2",
      "lang": "en",
      "customer_name": "Jane",
      "customer_lastname": "Doe",
      "email": "test@test.es",
      "currency": "EUR",
      "shipping_cost": "6.00",
      "total_discount": "0.00",
      "taxes": "10.50",
      "vat": "21",
      "total_products": "50",
      "total_paid": "66.50",
      "status": "pending",
      "order_date": "2019-03-03 13:12:00",
      "date_status_upd": "2019-03-05 12:00:05"
    }
  ]
}

Sample response

{
    "success": true,
    "order_count": 2
}

Update Status of Orders

Once the orders are synchronized with Revi, the API provides methods to update its status. This is useful if an order was synchronized with pending status and now is ready, permitting Revi to send its review email.

HTTP Request

POST https://api.revi.io/api/v1/orders_status

Request Parameters

This call is a bit different compared to the last, as it needs less order information: id_order, status and date_status_upd.

Parameter	Description
orders	Array of order objects but only including: - id_store string (only marketplaces) - id_order string - status string [‘pending’,’ready’,’cancelled’] - date_status_upd datetime

Sample JSON request

{
  "orders": [
    {
      "id_store": "s01",
      "id_order": "xx1",
      "status": "ready",
      "date_status_upd": "2019-03-08 12:03:54"
    }
  ]
}

Sample response

{
    "success": true,
    "order_count": 1
}

Products

The product object

{
  "id_product": "p01",
  "price": 22.15,
  "ean": "000000000",
  "sku": "000000000",
  "upc": "000000000",
  "jan": "000000000",
  "isbn": "000000000",
  "mpn": "000000000",
  "brand": "ExampleBrand",
  "stock": "20",
  "locale": [
    {
      "lang": "en",
      "name": "Awesome Computer",
      "description": "This super computer will blow your mind!",
      "url": "http://testshop.com/products/awesome-computer",
      "photo_url": "http://testshop.com/img/awesome-computer-p01.jpg"
    },
    {
      "lang": "es",
      "name": "Asombroso ordenador",
      "description": "Este súper ordenador te dejará flipado!",
      "url": "http://testshop.com/productos/asombroso-ordenador",
      "photo_url": "http://testshop.com/img/asombroso-ordenador-p01.jpg"
    }
  ],
  "combinations": [
    {
      "id_shop_product_combination": "p01a",
      "photo_url": "http://testshop.com/img/p01a.jpg"
    },
    {
      "id_shop_product_combination": "p01b",
      "photo_url": "http://testshop.com/img/p01b.jpg"
    }
  ],
}

Field	Description
id_store string (optional)	ID of the store. If you’re not a marketplace leave this empty
id_product string	Product ID
price float	Product price
ean string (optional)	European Product Article Number
sku string (optional)	Product SKU code
upc string (optional)	Universal product code
jan string (optional)	Product JAN code
isbn string (optional)	Product ISBN code
mpn string (optional)	Product MPN code
brand string (optional)	Product brand
stock integer (optional)	Available product stock
locale array	Array with the translated information of the product. For more, see the table below.
combinations array	Array with the available combinations of the product. For more, see the table below.

Product translatable data

Field	Description
lang string	ISO 639, 2 characters language code. Use this to tell the API in which language specified fields are translatable.
name string	Product name. translatable field
Description string (optional)	Product Description. translatable field
url string	Product direct URL. translatable field
photo_url string (optional)	Product Photo URL. translatable field

Product combinations data

Field	Description
id_shop_product_combination string	ID Product Combination.
name string	Product name. translatable field
ean string (optional)	European Product Article Number
sku string (optional)	Product SKU code
upc string (optional)	Universal product code
jan string (optional)	Product JAN code
isbn string (optional)	Product ISBN code
mpn string (optional)	Product MPN code
brand string (optional)	Product brand
photo_url string (optional)	Product Combination Photo URL

Create products

Revi API needs basic product info to build beautiful and easy recognizable review emails. Without this information Revi couldn’t ask customers about their opinion on bought products and would only ask for a general shopping experience review.

HTTP Request

POST https://api.revi.io/api/v1/products

Request Parameters

Parameter	Description
products	Array of product objects

Sample JSON request

{
  "products": [
    {
      "id_product": "p01",
      "price": 22.15,
      "ean": "49513159135",
      "brand": "ExampleBrand",
      "stock": "20",
      "locale": [
        {
          "lang": "en",
          "name": "Awesome Computer",
          "description": "This super computer will blow your mind!",
          "url": "http://testshop.com/products/awesome-computer",
          "photo_url": "http://testshop.com/img/awesome-computer-p01.jpg"
        },
        {
          "lang": "es",
          "name": "Asombroso ordenador",
          "description": "Este súper ordenador te dejará flipado!",
          "url": "http://testshop.com/productos/asombroso-ordenador",
          "photo_url": "http://testshop.com/img/asombroso-ordenador-p01.jpg"
        }
      ]
    },
    {
      "id_product": "p02",
      "price": 199.98,
      "ean": "13513159879",
      "brand": "TestBrand",
      "stock": "0",
      "locale": [
        {
          "lang": "en",
          "name": "Photo Printer Pro",
          "description": "Photo Printer Pro: Get your photos printed in seconds.",
          "url": "http://testshop.com/products/photo-printer-pro",
          "photo_url": "http://testshop.com/img/photo-printer-pro-126.jpg"
        }
      ],
      "combinations": [
        {
          "id_shop_product_combination": "p02a",
          "photo_url": "http://testshop.com/img/p02a.jpg"
        },
        {
          "id_shop_product_combination": "p02b",
          "photo_url": "http://testshop.com/img/p02b.jpg"
        }
      ],
    }
  ]
}

Sample response

{
    "success": true,
    "product_count": 2
}

Link products to orders

Once the products are synced with the Revi platform the next step is linking the order products to the orders.

HTTP Request

POST https://api.revi.io/api/v1/orders_products

Request Parameters

Parameter	Description
orders_products	Array containing id_orders and a nested array with id_products for each order. Optionally you can add the id_shop_product_combination

Sample JSON request

{
  "orders_products": [
    {
      "id_order": "x0003",
      "products": [
        {
          "id_product": "135" // Product with id 135 bought in id_order x0003
        },
        {
          "id_product": "126" // Product with id 126 bought in id_order x0003
        }
      ]
    },
    {
      "id_order": "x0004",
      "products": [
        {
          "id_product": "126", // Product with id 126 bought in id_order x0004
          "id_shop_product_combination": "3a" // product combination with identifier 3a, child of product id 126
        }
      ]
    }
  ]
}

Sample response

{
    "success": true,
    "product_count": 2
}

Link products to orders, passing full product

Alternatively, you can send the full product object if it was not created previously with the products endpoint.

Sample JSON request

{
  "orders_products": [
    {
      "id_order": "x0003",
      "products": [
        {
          "id_product": "135",
          "price": 22.15,
          "ean": "13513513658",
          "brand": "ExampleBrand",
          "stock": "20",
          "locale": [
            {
              "lang": "es",
              "name": "Awesome Computer",
              "description": "This super computer will blow your mind!",
              "url": "http://testshop.com/products/awesome-computer",
              "photo_url": "http://testshop.com/img/awesome-computer-135.jpg"
            }
          ]
        }
      ]
    }
  ]
}

Sample response

{
    "success": true,
    "product_count": 1
}

Get product review info

With this method you can retrieve the number of reviews and average rating of a product.

HTTP Request

POST https://api.revi.io/api/v1/product_info

Parameter	Description
id_product	ID of the product that is being requested.

Sample request

GET https://api.revi.io/api/v1/product_info?id_product=74

Sample response.

{
    "success": true,
    "data": {
        "product": {
            "id_product": "74",
            "id_store": "0",
            "avg_rating": "4.85",
            "num_ratings": "917"
        }
    }
}

Reviews

The review object

{
  "id_comment": "123",
  "id_order": "xx1",
  "id_store": "0",
  "id_product": "0",
  "type": "1",
  "customer_name": "John",
  "customer_lastname": "Doe",
  "email": "test@sampleuser.com",
  "IP": "00.00.00.00",
  "date": "2018-09-20 17:18:05",
  "comment": "I liked it so much!",
  "rating": "5",
  "lang": "en",
  "id_product": "3256"
}

Field	Description
id_comment integer	Revi’s ID of the comment.
id_order string	ID of the order that is being reviewed.
id_store string	ID of the store.
type string	Comment type. One of the following - 1: comment about the shop - 0: comment about a product
customer_name string	Customer name.
customer_lastname string	Customer lastname.
email string	Customer email.
IP string	Customer IPv4 Address.
date datetime	Comment date. Check date format
comment string	Actual comment
rating float	Rating from 1 to 5
lang string	Comment language. ISO 639, 2 characters language code.
id_product string	If the comment type is product this value will be the product ID that is being reviewed.

Get reviews

HTTP Request

GET https://api.revi.io/api/v1/reviews

Filter	Description	Example
from_id	Get reviews with a greater ID than this filter	15
to_id	Get reviews with a lower ID than this filter	15
from_date	Get reviews after this filter’s date	25
to_date	Get reviews before this filter’s date	2019-01-01
equal_to_rating	Get reviews with rating equal to this filter	2019-01-31
greater_than_rating	Get reviews with higher rating to this filter	4.3
id_product	Get reviews of an specific product by ID	135
id_store	For marketplaces. Get reviews of specific store. You can specify multiple store IDs separating them by commas.	s01

Sample request

GET https://api.revi.io/api/v1/reviews?from_date=2018-08-00&limit=2

Sample response.

{
  "success": true,
  "data": {
    "reviews": [
      {
        "id_comment": "20",
        "id_order": "xx1",
        "id_store": "0",
        "type": "product",
        "customer_name": "John",
        "customer_lastname": "Doe",
        "email": "test@testuser.com",
        "IP": "00.00.00.00",
        "date": "2018-09-20 17:18:05",
        "comment": "I liked it so much!",
        "rating": "5",
        "lang": "en",
        "id_product": "135"
      },
      {
        "id_comment": "21",
        "id_order": "xx2",
        "id_store": "0",
        "type": "general",
        "customer_name": "Jane",
        "customer_lastname": "Doe",
        "email": "test@testuser2.com",
        "IP": "00.00.00.00",
        "date": "2018-09-20 17:18:05",
        "comment": "I recommend this shop",
        "rating": "4",
        "lang": "en",
        "id_product": "0"
      }
    ]
  }
}

Shop

Get shop rating info

Use this method if you want to get the number of reviews and average rating of your shop.

HTTP Request

GET https://api.revi.io/api/v1/shop_info

Sample response.

{
    "success": true,
    "data": {
        "shop": {
            "avg_rating": "4.68684",
            "num_ratings": "7263"
        }
    }
}

Errors

The Revi API uses the following error codes:

Error Code	Meaning
200	OK, Everything worked as expected.
400	Bad Request, The request was unacceptable, often due to missing a required parameter.
401	Unauthorized, No valid API key provided.
402	Request Failed, The parameters were valid but the request failed.
403	Forbidden, Forbidden access to this API KEY for this request.
404	Not Found, The requested resource doesn’t exist.
500	Server Errors, Something went wrong on Revi’s end.

Introduction

Integration workflow

Authentication

Knowledge

Response structure

Calls that send info to Revi

Calls that get info from Revi

Decimal format

Date format

Optional parameters

Quickstart

HTTP Request

Request Parameters

Orders

The order object

Create orders

HTTP Request

Request Parameters

Update Status of Orders

HTTP Request

Request Parameters

Products

The product object

Product translatable data

Product combinations data

Create products

HTTP Request

Request Parameters

Link products to orders

HTTP Request

Request Parameters

Link products to orders, passing full product

Get product review info

HTTP Request

Sample request

Reviews

The review object

Get reviews

HTTP Request

Query parameters (search filters)

Sample request

Shop

Get shop rating info

HTTP Request

Errors