🖥️ Historical version: send orders via API

You have the ability to submit your proof of purchase/service independently using the API automation method.

Click on the version that matches your menu:

✨ New Platform	🖥️ Historical Platform

Glossary

• Transaction: describes an order, purchase, or rental made by a consumer with your
  brand.
• Product: describes a tangible or intangible product consumed by your buyer, for which a survey will be conducted.

Create an account

1. You must have an Verified Reviews account.
2. Then access your API keys via these main codes: 

Then use the URLs relevant to you when calling our APIs as described in the document “[URL]”:

Here is the list of URLs depending on our sites:
• FR: www.avis-verifies.com
• ES: www.opiniones-verificadas.com
• DE: www.echte-bewertungen.com
• IT: www.recensioni-verificate.com
• NL: www.echte-beoordelingen.com
• UK: www.verified-reviews.co.uk
• US: www.verified-reviews.com
• BR: www.opinioes-verificadas.com.br
• PT: www.opinioes-verificadas.com
• CO: www.opiniones-verificadas.com.co
• PL: www.prawdziwe-opinie.com
• MX: www.opiniones-verificadas.com.mx

To get the full list of URLs, go to our site and use the dropdown to switch to another language.

Find your integration codes 

To find your secret key and your website ID:

1. Go to the left-hand menu in Verified Reviews Account Management, then My Account.
2. The information is then on the right side of the page in the Integration Code section.

Services and data to submit

Verified Reviews allows for a simple integration with a wide variety of connectors.

Here is the list.

Online, in-store, click & collect or other channel/type

Verified Reviews allows you to distinguish purchases made online, in-store, online with a click & collect service (also called webtostore) or in-store with a tablet ordering system (also called storetoweb) in order to tailor the email and form sent to consumers.

Concept of transactions and products

Within the Verified Reviews system, an order/transaction can contain one or multiple products/services, giving you the possibility to ask your consumers about:

• Your website/store/brand
• AND/OR your products/services

Survey your customers with a delay / Survey your customers in two stages

To get relevant feedback from your customers based on their consumption experience, you can survey them using a delay before sending the review request, which applies from the receipt of the transaction by our services. This delay can be configured from your customer area (applies to all orders) or managed per order by specifying the delay when sending the data to our services.
It is also possible to separate the brand review request from the product review request in two delayed emails (note that extra costs may apply, please consult your account manager).

Survey your customers via SMS (depending on commercial offer)

You can survey your customers via SMS; to do this, you need to contact your account manager.

Data to transmit

Below is the exhaustive list of data required by the Verified Reviews standard. Some of these data only apply for certain types of transfer (API, CSV, etc.).

The table below describes the data qualifying the transaction. This data allows Verified Reviews to survey a customer on their experience with your brand only.

Extra transaction-related data:

Verified Reviews allows you, in addition to the standard data, to enrich your transactions with any data specific to your organization. For example, to easily identify the review author within Verified Reviews tools, you can add their ID from your system. To do so, you must provide your Verified Reviews contact with a list specifying the type and whether the data is required. If a required data field is missing, the order will be rejected.

Example below:

In this example, type_civility_customer is mandatory because it is displayed in the review request email « Hello Mr Dupont ».

The table below describes the data qualifying the products associated with the transaction. This data allows Verified Reviews to complete the survey about your store with the purchased products.

You must provide at least one of the following data: GTIN_EAN, GTIN_UPC,
GTIN_JAN, GTIN_ISBN, MPN, sku to allow Google to match our reviews with your products
on Google Shopping

Send your transactions via API/Webservice

Transactions can be sent to Verified Reviews using different methods. This section describes
the API/WebService method.

Sending a Request

Here is the API URL: https://[URL]/index.php?action=act_api_notification_sha1&type=json2 

Request Structure and Sending:

The request must be structured in an array and sent via an HTTP POST request:

API Call:

Below are the data to send via API, making sure the 'message' array
is JSON encoded.

{
  "idWebsite": "fd5445fb-4468-4947-adb6-5051429d88ad",
  "message": {
    "order_ref": "ref100",
    "firstname": "John",
    "lastname": "Doe",
    "email": "john@doe.com",
    "order_date": "2019-01-01 12:00:00",
    "sign": "5051429d88addsd65247zaedesdw5sdsz561s92eis",
    "PRODUCTS": {
      "0": {
        "id_product": 100,
        "name_product": "My Product 100"
      },
      "1": {
        "id_product": 200,
        "name_product": "My Product 200"
      }
    }
  }
}

Signature Calculation:

The signature is calculated using the SHA1 method from the concatenation of certain data
passed within the message array, to which we add your {secret_key}. The signature must be
included in the 'message' array and allows the API call to be authorized. 

All data must be URL-encoded and UTF-8 encoded beforehand.

Note:

'sign' is the concatenation of 'query' + 'order_ref' + 'email' + 'lastname' + 'firstname' +
'order_date' + 'delay' + 'secret_key', all encoded in SHA1. 'delay' should only be added to the calculation
if it is present in the data. The + signs describe concatenation and should not be
included literally in the calculation.

You will need to verify the compliance of the message in the response.

Decoding a Response Message

The returned information is transmitted directly in an array. You must
decode the returned message in JSON.

List of return codes:

Retrieve the form link WITHOUT sending the review request

Contact your account manager to authorize access to this API.

By adding the parameter noEmail=true at the end of the API URL, the review request will not be
sent, but the API will return the URL of the generated review request in case the email sending
needs to be handled by your services.

Send your orders via CSV export on SFTP

Transactions can be sent to Verified Reviews using different methods. This section describes
the method via CSV export uploaded to an FTP/SFTP.

An SFTP access is dedicated to you, allowing you to upload, at your preferred interval, a CSV file
containing the orders for which we need to send review requests. The SFTP
is read once a day (between 1 a.m. and 3 a.m.) by our system to process the data from
the file(s) uploaded.

File format

Find the data to be transmitted in the previous sections. 

SFTP folder structure

You must upload your exported CSV files to the /orders folder. The /success folder will receive files that have been correctly processed by our system, while the /error folder will receive files that could not be read correctly by our system.

Here is the structure of the file to upload:

• Download an example with product
• Download an example without product
• Download an OFFLINE example with product
• Download an OFFLINE example without product

The exhaustive list of available fields can be found earlier in this document.

Check your file

To check the file format, go to “Integration > Application > Test CSV file”.

Send your orders via Google Tag Manager

Prerequisites

1. First, have a Google Tag Manager account and have installed the GTM tag on your site: https://tagmanager.google.com
2. We strongly recommend reading the official documentation to understand how to use this service: (https://www.google.fr/analytics/tag-manager/).

Creating Variables

In the Google Tag Manager administration, you must create 7 variables. To do this:

1. Go to the Variables section.
2. In the User-Defined Variables section, click New, choose the type Data Layer Variable, and simply fill in the name of the variable, leaving the other parameters as default (notably version 2 of the data layer).
3. You must create 7 data layer variables:

• netreviews.idWebsite
• netreviews.order_ref
• netreviews.firstname
• netreviews.lastname
• netreviews.email
• netreviews.products
• netreviews.token

Creating the Trigger

In the Google Tag Manager administration:

1. Click on the Triggers section, then on the New button.
2. Fill in the trigger as follows:
   • Choose the “Page View” event
   • Choose the “DOM Ready” trigger type
3. Configure your filter to target the desired page: it must be the order confirmation page and contain the data related to the order and the buyer.

Creating the Tag

In the Google Tag Manager administration:

1. Go to the Tags section.
2. Click on New.

3. Then fill in the form as follows:
   • Choose the product “Custom HTML Tag” (button at the bottom of the “More” link)
   • Paste the following script: Example Script

   <script type="text/javascript">
   var iframe= document.createElement("iframe");
   iframe.style = "border:0; height:0; width:0;";
   iframe.src = "//[URL]/index.php?action=act_google_tag_manager";
   iframe.src +=
   "&idWebsite="+{{netreviews.idWebsite}}+"&order_ref="+{{netreviews.orderRef}}
   +"&firstname="+{{netreviews.firstname}}+"&lastname="+{{netreviews.lastname}}
   +"&email="+{{netreviews.email}}+"&token="+{{netreviews.token}};
   if(typeof {{netreviews.products}} != "undefined" && {{netreviews.products}}
   != null && {{netreviews.products}}.length > 0)
   iframe.src +=
   "&products="+encodeURIComponent(JSON.stringify({{netreviews.products}}));
   document.body.appendChild(iframe);
   </script>

4. Choose the previously created trigger.

Adding Dynamic Data

In the HTML code of your confirmation page, add the data to the dataLayer:

<script type="text/javascript">
window.dataLayer = window.dataLayer || [];
dataLayer.push({
'netreviews' : {
'idWebsite' : 'XXXXXXXX-1234-abcd-5678-XXXXXXXXXXXX',
'order_ref' : '12345',
'firstname' : 'John',
'lastname' : 'Doe',
'email' : 'john@doe.com',
'products' : [{
 'name_product' : 'product_name_1',
 'id_product' : 'REF_01'
},{
 'name_product' : 'product_name_2',
 'id_product' : 'REF_02',
 'url_product' : 'http://www.shop.com/product2',
 'url_image_product' : 'http://www.shop.com/product2/image.png',
 'GTIN_EAN' : '6598745632153'
}],
'token' : 'YOUR_TOKEN'
}
});
</script>

The token is a mandatory encrypted key for security reasons, generated as follows: sha1(idWebsite . secretKey . order_ref)

Note that apart from the static idWebsite, which you can retrieve from your Verified Reviews account,
all parameters must be included dynamically. The dots indicate concatenation and
must therefore not be part of the token.

Retrieve Your Reviews

Verified Reviews offers different methods to retrieve collected reviews. These different methods allow easy integration into your tools, leaving your team free to choose the method best suited to their infrastructure.

Retrieving reviews can serve different purposes:

• Data analysis by data analysts
• Public display of reviews
• Internal display of reviews

How It Works and Available Data

An interface allows you to configure the retrieval of product reviews and brand reviews using the different methods described below.

1. Standard Data

Here is the exhaustive list of standard data, with a few notes:

• The “action” data will only be present in synchronization files; it
  is not present in Web resources
• In orange, data present only in the product review feed.

2. Non-Standard Data

As mentioned earlier in the “transmitted data” section, Verified Reviews allows you to enter data specific to your organization within transaction data. This data can be included in the output feeds using the same label as the input. To do this, go to the “Customization – Site/Product Reviews” tab.

This interface allows you to add and name the output data.

Retrieve Reviews via Synchronization Files

How it works:

1. Go to the “Configuration” tab to select the desired data feeds and configure the destination FTP/SFTP.
   ★ We can create an FTP/SFTP on our servers if needed—contact us.

   Every night (between 1 a.m. and 3 a.m. France time) we place on the FTP account you have previously configured below a CSV or XML file containing new brand and/or product reviews, updates to brand and/or product reviews, as well as deletions of brand and/or product reviews from the previous day.

   The two forms are similar and allow you to retrieve brand reviews separately from product reviews.

   Label	Value	Comment
   Format	CSV / XML	We offer two formats: CSV and XML. These two formats will be detailed later in this document.
   Transfer Method	FTP / SFTP	We provide two file transfer methods: FTP and SFTP. Make sure to change the Port according to your server.
   Server	IP Address or Host	Definition of the IP address or Host to which we will connect.
   Username	Login	FTP/SFTP login to your server (we must have write permissions).
   Password	Password	Password to access your FTP/SFTP account.
   Port	Number	Listening port of your FTP/SFTP service.
   Directory Path	Path	Path where we will place your files.

2. “Test the connection”: Immediately test that we can connect to your FTP/SFTP account. (We do not check write permissions).
3. “Test the reviews feed”: Immediately send a data feed to the FTP/SFTP (daily or complete).

Interpreting a NEW, DELETE, and UPDATE action:

Each line (or XML node) in the synchronization files has a type indicating the action to be performed within your database:

CSV Format:

XML Format:

All data is enclosed within CDATA tags to avoid being blocked by special characters.

File Naming:

“Retail reviews” files are named following this format:

“Product reviews” files are named following this format:

Examples:

• reviews_598b6360-e762-cf54-790a-85cfdcb0bdc1_20130523.csv
• reviews_product_598b6360-e762-cf54-790a-85cfdcb0bdc1_20130523.xml

Via Web Resources

You can use Web resources accessible via http or https. These resources are updated nightly between 1 a.m. and 3 a.m.

Files are generated every night. However, if you have just activated generation, please wait a few minutes.

How Product Review Web Resources Work

We provide several resources with different purposes, all available in XML, JSON, and CSV formats. Go to the "Product API" tab to activate their generation.

Get the average rating and number of reviews via a file containing all products

This resource lists all id_product values with at least one review and indicates the rating and number of reviews. Use this resource to display ratings on a product list, for example.

JSON example:

{
 "3819": {
   "id_product": "3819",
   "rate": "5",
   "nb_reviews": "1"
 },
 "50404": {
   "id_product": "50404",
   "rate": "1",
   "nb_reviews": "1"
 }
}

Access URL: //cl.avis-verifies.com/code_lang/cache/x/x/x/xxxxxxx-x-x  xxxxxxxxxx/AWS/PRODUCT_API/AVERAGE/all_products.[format]

Get the average rating and number of reviews per product, one file per product

These resources identified by id_product allow you to get the rating and number of reviews for a product.

Use this resource to display the rating and number of reviews of a product at the top of the product page or to feed your rich content (rich snippets), for example.

JSON example:

{
  "rate": "1",
  "count": "1"
}

Access URL: //cl.avis-verifies.com/code_lang/cache/x/x/x/xxxxxxx-x-x-xxxxxxxxxx/AWS/PRODUCT_API/AVERAGE/[id_product].[format]

Get the list of reviews per product, one file per product

These resources list the reviews collected for a product that you can display publicly. These reviews have passed our moderation filters and are anonymized (first letter of first and last name). Use this resource to display reviews on a product page.

For an example, visit your client area.

Access URL: //cl.avis-verifies.com/code_lang/cache/x/x/x/xxxxxxx-x-x-xxxxxxxxxx/AWS/PRODUCT_API/REVIEWS/[id_product].[format]

Get the list of products with at least one review and the update date

This resource (CSV only) lists products with at least one review and the last update date. Use this resource to know which products have reviews before calling one of the resources described above. The last update date allows you to update your local cache only if the product’s rating or number of reviews has changed.

50404;2017-08-23
10;2017-08-23
  

Access URL: //cl.avis-verifies.com/code_lang/cache/x/x/x/xxxxxxx-x-x-xxxxxxxxxx/AWS/PRODUCT_API/AVERAGE/files_list.txt

How Brand Review Web Resources Work

1. Go to the "Site API" tab. Find the access URLs for files and examples from this interface.
2. Activate the generation of a file containing the list of published reviews.
3. Choose the date range, from 1 to 12 months.

Available formats: JSON, XML, CSV, RSS

Access URL: //cl.avis-verifies.com/code_lang/cache/x/x/x/xxxxxxx-x-x-xxxxxxxxxx/AWS/WEBSITE_API/reviews.[format]

How Store Web Resources Work 

If stores are listed in your Verified Reviews account, the following link allows you to get the average rating and number of reviews for each store.

• id_shop: store identifier
• name_shop: store name
• review_number: number of reviews published for this store
• rating: rating obtained (4 digits after the decimal point)
• certificate_url: certificate URL

Access URL: //cl.avis-verifies.com/code_lang/cache/x/x/x/xxxxxxx-x-x-xxxxxxxxxx/AWS/xxxx_infoshops.txt 

Via API

Avis Vérifiés provides an API that allows filtering the content of the web resources described above. Therefore, web resources must be enabled to use this API.

Store Reviews

https://awsapis3.netreviews.eu/website

Here is the list of GET parameters for filtering:

Examples for listing store reviews:

• Sort by review date
• 200 results from page 3 (page=2)

https://awsapis3.netreviews.eu/website?idWebsite=xxxxxxxx&format=json&order_by

• On Opiniones Verificadas (Spanish platform)
• Filter by store_id=503
• First 200 results

https://awsapis3.netreviews.eu/website?idWebsite=xxxxxxxx&format=json&iso_code

Product Reviews

https://awsapis3.netreviews.eu/product

You must make a POST or GET call with a JSON array containing all required parameters. Below is the list of parameters for contacting the API.

To get the average ratings and number of reviews for each product:

Example request:

{
 "idWebsite": "xxxxx-xxxxxx-xxxxxxx-xxxxxxx",
 "query": "average",
 "plateforme": "fr",
 "products": "all"
}
  

To get the list of reviews for a product:

Example request:

{
 "idWebsite": "xxxxx-xxxxxx-xxxxxxx-xxxxxxx",
 "query": "reviews",
 "plateforme": "fr",
 "product": "SKU12",
 "order": "date_desc",
 "offset": "0",
 "limit": "5"
}
  

Deliverability feed

You can get a daily CSV data feed containing the list of emails for which we could not send a review request. This feed is placed on an SFTP/FTP of your choice.

Helpful Review Yes/No Feature

You can allow visitors to your site to rate the usefulness of reviews left on your products. The user has two possible choices: Was this review helpful to you?

• Yes
• No

This feature requires using a webservice provided by Verified Reviews that allows you to send us your users’ votes and thus centralize this data alongside your reviews on our platform.

Using the Webservice

The webservice is accessible via the following URL: https://[URL]/index.phpaction=act_api_product_reviews_helpful

The parameters detailed below must be sent via POST.

You can download a PHP sample webservice call example.

Recording a User's Vote

To record a user's vote, you must make a webservice call sending the following POST parameters:

Modifying a User's Vote

To modify a user's vote, simply make a new call to the 'create' method, changing the value of the "isHelpful" parameter to indicate the user's new choice.

The "fingerPrint" parameter allows recognizing the user and updating the existing review.

Cancelling a User's Vote

You can allow the user to cancel their vote. To do so, make a webservice call sending the following POST parameters:

Calculating the Sign Parameter

The sign parameter allows Verified Reviews to verify the source of the webservice call. Use the following method to generate this parameter in PHP: $sign = sha1($idWebsite.$idProduct.$ip.$secretKey);

The secretKey is the Verified Reviews secret key for the merchant account, which can be found in your client space under the " Config > My account" menu.

Service Response

In response to your call, the web service will return a JSON response. You should handle these responses to ensure that the vote has been properly recorded or canceled, depending on the scenario. 

You can use this response to display a confirmation to the user, for example.

1. Success Response

{
  "success": 1,
  "method": "xxxxxx",
  "idWebsite": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
  "idProduct": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
  "fingerPrint": "xxxxxxx",
  "isHelpful": "1",
  "isActive": 1,
  "message": "Thank you, your vote will be published shortly."
}
  

 2. Error Response 

{
  "success": 0,
  "idProduct": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx",
  "errorCode": 1000,
  "errorMessage": "Technical details of the encountered error",
  "message": "An error occurred."
}
  

The "message" field in the web service response can be used to display a confirmation message to the user.

You can also choose to display your own custom confirmation message.

The "errorMessage" field contains the technical details of the encountered error and should not be shown to the user.

Manage your reviews via a third-party solution

Verified Reviews offers connectors with third-party “voice of the customer” management solutions to
help you centralize your review handling. Currently, we have connectors for:

• SalesForce
• Zendesk

Contact your account manager to complete the configuration.