NAV
bash

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:

  1. 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.
  2. 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.
  3. 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.
  4. 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://test.revi.io/api/v1/api_endpoint_here"
-H "X-API-KEY: XXXXXXXXXXXXX"

Make sure to replace XXXXXXXXXXXXX with your 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.

Production environment

Once your test integration is successful, you can call the production endpoint by just changing the URL from https://test.revi.io/api/ to https://revi.io/api and change the API KEY to the production one.

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://test.revi.io/api/v1/hello_world

Run in Postman

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

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://test.revi.io/api/v1/orders

Run in Postman

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://test.revi.io/api/v1/orders_status

Run in Postman

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"
}
]
}
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.

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

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://test.revi.io/api/v1/products

Run in Postman

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"
}
]
}
]
}

Sample response

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

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

HTTP Request

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

Run in Postman

Request Parameters

Parameter Description
orders_products Array containing id_orders and a nested array with id_products for each order.

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
}
]
}
]
}

Sample response

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

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://test.revi.io/api/v1/product_info

Run in Postman

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

Sample request

GET https://test.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",
"type": "product",
"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
- general: comment about the shop
- product: 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://test.revi.io/api/v1/reviews

Run in Postman

Query parameters (search filters)

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://test.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://test.revi.io/api/v1/shop_info

Run in Postman

Sample response.

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

Stores

The store object

{
"id_store": "s01",
"website": "market.com/shop",
"email": "store@market.com",
"default_language": "en",
"status": 1,
"admin_email": "store_admin@market.com",
"locale": [
{
"lang": "en",
"name" : "My Fancy Shop",
"website": "market.es/shop",
"logo_url": "https://market.com/img/logos/store_en.png",
"business": "Store S.L.",
"address": "2029 Oakdale Avenue, Waldron, Indiana",
"email": "store_support_en@market.com",
"phone": "863-462-9168",
"description": "Example shop",
"active": 1
},
{
"lang": "es",
"name" : "Mi tienda",
"website": "market.es/mitienda",
"logo_url": "https://market.com/img/logos/store_es.png",
"business": "Store S.L.",
"address": "Calle Ejemplo 5, Valencia, España",
"email": "store_support_es@market.com",
"phone": "667667667",
"description": "Tienda de ejemplo",
"active": 1
}
]
}
Field Description
id_store
string
The identifier of the store. Use your own ID, other API calls will need it
website
string
The store website
email
string
The public store email
default_language
string
The store default language. ISO 639, 2 characters language code
status
integer
If the store is active or not. Use 1 for enabled and 2 for disabled
admin_email
string
This email will be used to create the store admin account and Revi communications will be done through this address
locale
array
Array with translated information of the store. See the table below.

Store translatable data

{
"lang": "es",
"name" : "Mi tienda",
"website": "market.es/mitienda",
"logo_url": "https://market.com/img/logos/store_es.png",
"business": "Store S.L.",
"address": "Calle Ejemplo 5, Valencia, España",
"email": "store_support_es@market.com",
"phone": "667667667",
"description": "Tienda de ejemplo",
"active": 1
}
Field Description
lang
string
Language of current translatable data. ISO 639, 2 characters language code
name
string
Shop name
website
string
Website url
logo_url
string
Store logo url. Supported image formats: jpg,jpeg and png
business
string
Business name
address
string
Store address
email
string
Store public email
phone
string
Store public phone
description
string
Store description
active
integer
Store status. Use 1 to enable and 0 to disable this store language.

Create/Update stores

Use this method to create/update your marketplace’s stores. If a id_store is found for the first time the system will create a new store. If the id_store is already at Revi’s database, the system will update that store with the new information provided.

HTTP Request

POST https://test.revi.io/api/v1/stores

Run in Postman

Sample JSON request

{
"stores": [
{
"id_store": "s01",
"website": "market.com/shop",
"email": "store@market.com",
"default_language": "en",
"status": 1,
"admin_email": "store_admin@market.com",
"lang": [
{
"lang": "en",
"name" : "My Fancy Shop",
"website": "market.es/shop",
"logo_url": "https://market.com/img/logos/store_en.png",
"business": "Store S.L.",
"address": "2029 Oakdale Avenue, Waldron, Indiana",
"email": "store_support_en@market.com",
"phone": "863-462-9168",
"description": "Example shop",
"active": 1
},
{
"lang": "es",
"name" : "Mi tienda",
"website": "market.es/mitienda",
"logo_url": "https://market.com/img/logos/store_es.png",
"business": "Store S.L.",
"address": "Calle Ejemplo 5, Valencia, España",
"email": "store_support_es@market.com",
"phone": "667667667",
"description": "Tienda de ejemplo",
"active": 1
}
]
} // Add multiple stores by adding more items to the array
]
}

Sample response

{
"success": true,
"data": {
"stores_inserted": 1,
"stores_updated": 0
}
}

Get store rating info

Use this method if you want to get the number of reviews and average rating of a single store. You can pass more than one id_store separated by commas if more than one store is needed.

HTTP Request

GET https://test.revi.io/api/v1/store_info?id_store=s01,s03

Run in Postman

Sample response.

{
"success": true,
"data": {
"stores": [
{
"id_store": "s01",
"avg_rating": "4.77778",
"num_ratings": "5",
"error": false
},
{
"id_store": "s03",
"error": true,
"errormsg": "Store s03 not found"
}
]
}
}

Polls

If you want to implement Revi polls without using Revi’s design you can develop your own surveys and then send the user’s answers to Revi via API.

The first step is to create a new Poll in the Revi Dashboard. Setup your survey by adding the appropiate questions and then publish it. Then, you can check the poll’s metadata by accessing to the Advanced tab. This information is needed to post the answers.

Post a poll answer

Use this call to send Revi your user’s answers.

HTTP Request

POST https://test.revi.io/api/v1/poll_answer

Run in Postman

Parameters

Field Description
poll_ident
string
You can find it at the poll advanced settings in Revi’s Dashboard
id_store
string (optional)
Fill this to link this poll to a store’s order
id_order
string (optional)
Fill this to link this poll to an order
remote_ip
string (optional)
Remote user’s IP
lang
string (optional)
Language in which the user has answered. ISO 639, 2 characters language code.
answers
Array
Array of answers (see next table to know answer’s structure)

Answer structure

Field Description
id_poll_question The REVI question’s ID. You can check this in poll Advanced tab in Revi’s Dashboard
value The value answer.

- If the question was of type “text” this value is a string with the user’s response.
- If the question was of type “yes or not” this value is a string with ‘yes’ or ‘no’ values.
-If question has a numeric response this value is the number answered.
-If it’s a question that has multiple options this value is the ID of the options as seen in the poll Advanced tab.
-If multiple options can be answered this value will be an array with that option IDs (found at poll Advanced tab).

Sample request

{
"poll_ident": "5ca7319225364",
"id_order": "e516",
"remote_ip": "XX.XX.XX.XX",
"lang": "es",
"answers": [
{
"id_poll_question": 53,
"value": "yes" // 'Yes' or 'no' response
},
{
"id_poll_question": 59,
"value": 4 // Number response
},
{
"id_poll_question": 52,
"value": "I love your shop design!" // Text response
},
{
"id_poll_question": 54,
"value": 53 // One id_option
},
{
"id_poll_question": 55,
"value": [
"55", "57" // Multiple options, array of id_option
]
}
]
}

Sample response.

{
"success": true,
}

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.