How do I set up my API connection after the update to eTrusted?

In this guide we explain how to transfer your API connection for the previous review platform My Trusted Shops to the new platform eTrusted. This article is therefore aimed exclusively at shops that have established an API connection for their work with My Trusted Shops. If your shop belongs to this group, we will inform you in good time by e-mail about the necessary steps. If you do not belong to this group but are generally interested in the eTrusted APIs, you are welcome to visit our Developer Centre to find out more about the existing possibilities: To the Developer Centre
The customisation of your API connection requires prior technical knowledge. Therefore, please forward these instructions to your development department or agency if you do not have such knowledge yourself.

When should I carry out the API conversion?

Before you can take action yourself, a few prerequisites for a successful API conversion must be created from our side. First, your customer account (including all your shops) will be activated for the productive environment of the new review platform eTrusted. At the same time, we will set up API forwarding for the previously used APIs from My Trusted Shops to the new eTrusted APIs. This ensures that you can continue to collect, manage and display reviews in your shop without problems, even during the phase when you are converting your APIs.

As soon as you receive the message from us that your shop has received the update to eTrusted, the time has come for the API conversion. Then, you will need to follow the three steps below to set up your eTrusted APIs:

  1. Navigate to the API Client Management section of your eTrusted account to obtain your API Client Credentials (Client ID and Client Secret) for the eTrusted APIs. Please note the following: This is only possible if you have admin authorisation.
  2. Use the documentation for our My Trusted Shops APIs to find out which API you have been using.
  3. Follow the instructions below and set up your new API connection.
Please note that the API conversion must be implemented by the end of the year. On 31 December 2021, the My Trusted Shops APIs and thus also the established API forwarding will finally be discontinued. If the APIs have not yet been converted at this point, it will no longer be possible to collect reviews.

Setup and authentication

As soon as you have received your login data for the eTrusted APIs from us, you can authenticate yourself to our Authorisation Server. Our APIs are protected via OAuth2. Authentication is done via an initial API call to the Authorisation Server. You can find out what the initial API call must look like in the Developer Centre: Setup and Authentication

If the API call was successful, you will receive a response containing an Access Token. This access token must be stored in the request header of the call for all subsequent API calls.

Have you commissioned service providers who also need to access the platform via the eTrusted APIs? Then please consider that these service providers also have to set up the API connection again. You should therefore inform your service providers in good time and grant them access to your new login data for the eTrusted APIs.
For more detailed information on authentication and the use of the Access Token within the Request Header, please refer to the eTrusted APIs documentation: Authentication

Conversion of the previous ReviewRequest API to the new Questionnaire Link API

With the ReviewRequest API provided for My Trusted Shops, you were able to embed links to the Trusted Shops review questionnaire in individually designed review requests. If you have been using this API, the Questionnaire Link API developed for eTrusted is the appropriate replacement for this use case.

Using the Questionnaire Link API, you can retrieve links to preconfigured questionnaires for your customers at eTrusted. You can then integrate these links into an e-mail, SMS or other communication channel of your choice, to collect customer feedback.

All detailed information about the Questionnaire Link API can be found here in our API documentation: Questionnaires

So that you can see the differences between the old ReviewRequest API and the new Questionnaire Link API at a glance, we show two sample API requests side by side below. On the left you can see an example of a request to the ReviewRequest API, on the right an example request to the Questionnaire Link API.

System My Trusted Shops eTrusted
Auth https://api.trustedshops.com/restricted/v2/shops/{tsId}/reviews/requests https://api.etrusted.com/questionnaire-links
Path HTTP Basic Auth (Username:Password) OAuth2.0 Token, see documentation
Body ReviewRequestAPI.png QuestionnaireLinkAPI.png

To help you understand the necessary settings, we will now explain the individual parameters. You will also find out where the parameters of the two API requests differ from each other.

Parameter ReviewRequest API Parameter Questionnaire Link API Differences Explanation
tsid channel.id New / further information needs to be provided. The old parameter tsid is no longer needed for the Questionnaire Link API. Instead, each of your channels has its own ID that you must pass at this point. You can get your channel IDs by making a request to our Get Channel API. You can find out exactly what this request should look like here: Channels
xxx channel.type New parameter. This parameter has a fixed value: "eTrusted".
xxx type New parameter.

The type parameter defines the event to which the review is linked. Since all reviews in MyTS were linked to the customer's checkout, the value of this parameter is also fixed: "checkout". If you have used the ReviewRequest API for non-order related reviews and therefore want to use a different touchpoint, please contact us at productintegration@trustedshops.com.

order.
orderDate
transaction.
date
Parameters are equivalent. The parameter transaction.date passes the time of the order to be reviewed. In this parameter, pass the value that you previously passed in the order.orderDate parameter.
order.
orderReference
transaction.
reference
Parameters are equivalent.

The parameter transaction.reference passes the order number of the order to be reviewed. In the transaction.reference parameter, pass the value that you previously passed in the order.orderReference parameter.

order.
products
products Parameters are equivalent. The data required for Product Reviews are transferred in this parameter. The functionality for Product Reviews will be released for the Questionnaire Link API during the third quarter of 2021.
consumer.
firstname
customer.
firstname
Parameters are equivalent. The parameter customer.firstname passes the first name of your customer. In this parameter, pass the value that you previously passed in the consumer.firstname parameter.
consumer.
lastname
customer.
lastname
Parameters are equivalent.

The parameter customer.lastname passes the last name of your customer. In this parameter, pass the value that you previously passed in the consumer.lastname parameter.

consumer.
contact.email
customer.
email
Parameters are equivalent. The parameter customer.email passes the email address of your customer. In this parameter, pass the value that you previously passed in the consumer.contact.email parameter.
consumer.
contact.language
xxx Parameter no longer exists. The consumer.contact.language parameter is no longer used in the Questionnaire Link API. This means you do not need to set it up.
sender.type xxx Parameter no longer exists. The sender.type parameter is no longer used in the Questionnaire Link API. This means you do not need to set it up.
types.key xxx Parameter does not yet exist. In this parameter, data is transferred that is necessary for Product Reviews. The functionality for Product Reviews will be released for the Questionnaire Link API during the third quarter of 2021.
xxx questionnaire
Template.id
New parameter. This parameter identifies the questionnaire template from which the individual questionnaire for your customer is generated. You can find out which questionnaire templates you have to choose from here: Templates
xxx system New parameter. The system parameter identifies the system making the request to the Questionnaire Link API. Use a unique string at this point to help you identify your component. This information may be required for support communication.
xxx systemVersion New parameter.

Use different version numbers in this parameter to be able to identify your specific implementation in support cases.

xxx metadata New parameter. You can use this non-mandatory parameter to add additional information (e.g. about the customer, the event, etc.) for analysis purposes.

If your request to the Questionnaire Link API was successful, you will receive a response according to the following pattern:

{
 "id": "qre-xxxxxxxx-yyyy-xxxx-yyyy-xxxxxxxxxxxx",
 "link": "https://etru.st/imo2h79nl",
 "token": "eyJraWQiOiIvdG1wbHMvand0X3B1YmxpY19rZXkvZDRhMmQ2YjYtNzRjNS00NjZlLWI3M
WQtNTQ1NTk4OGY0YjliIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYifQ.
eyJxdWVzdGlvbm5haXJ
lUmVmIjoicXJlLTdjMGJkNzM4LTM3NWItNDk4Ni05N2E2LTlhZjg2OThlMjRmMiIsImlzcyI6I
mh0dHBzOi8vd3d3LmV0cnVzdGVkLmNvbSIsImV2ZW50UmVmIjoiZXZ0LTBjYTk1MTU2L
WE5NDQtNDhlNC04Mjc1LTdlZGViMTY2MGUyYyIsInF1ZXN0aW9ubmFpcmVMb2NhbGUi
OiJlbl9HQiIsInN5c3RlbVZlcnNpb24iOiIxLjAuMCIsImF1ZCI6Imh0dHBzOi8vZmVlZGJhY2su
ZXRydXN0ZWQuY29tIiwicXVlc3Rpb25uYWlyZVRlbXBsYXRlUmVmIjoicXJ0LTRhNjFkN2J
mLTVkYTMtNDE4Yi1hOThmLWU2MDM1MzRkOWZkNV9lbi1HQiIsInN5c3RlbSI6ImN1c3R
vbWVyX3N5c3RlbV9uYW1lIiwiYXBpVmVyc2lvbiI6IjEuMS4wIiwiY29sbGVjdGlvblByb2Nlc3
MiOiJDTE9TRURfRkVFREJBQ0siLCJjaGFubmVsUmVmIjoiY2hsLTRiOTQxYjEzLWJiMDEt
NDBhOS1iZGZkLWE2ZjA0ZTVjYTEwZSIsImFjY291bnRSZWYiOiJhY2MtODYzYzlkOGQtM
TEwOC00NTkxLTg2OGQtNWUwYWFhZDI2Y2Y0IiwiaWF0IjoxNTM2NzY5NjQ3fQ.A8EZkvj
UEwFXT_U9bgVgIKfQkyxFY3K3G4YNN3tZzoc50eG1ggYsKzj-
_XLnN9tpDnyQXENFz4g8yY9kUK43LLvFxOHdWOjlF0X4ZPngyd4eSgBQTYyofeI39vKzc9
EPN9oajrqgog8jHMq4Y7oBa9Z2J4s21Q6N-hCp2vS128f5Wma12Wa9YExPV1Tf21P-
v5MMjYiqNan_oxX_3ENjJ07kzxP8SGN5QSbVUgZGmw6y213VDCGpopzm_cTkf67YKpW
n4wPNOeo_LDX5P6T85kyZC-F6g9R- uEFUtY_wBv1FrIBokfVfVQWJnbIajUjM21Z3_W5Am3JUyHxPcxnSMg"
}

In the parameter link you will get the link to the generated questionnaire. You can now integrate this link into the communication channel of your choice.

The links you create using the Questionnaire Link API are individual and intended for a specific customer. As a result, you have to create a separate link to the questionnaire for each Review Invite and integrate it into your communication.

Conversion of the previous ReviewCollector API/ReviewTrigger API to the new Event API

With the ReviewCollector or ReviewTrigger API provided for My Trusted Shops, you were able to trigger the sending of Review Invites to your customers. In this case, your customers received an e-mail sent by Trusted Shops with a rating questionnaire. If you have been using this API, the Event API developed for eTrusted is the appropriate replacement for this use case. With the Event API, you can link the sending time for your Review Invites to any touchpoint along your customer journey.

All detailed information about the Event API can be found here in our API documentation: Events

In order to show you the differences between the old ReviewCollector or ReviewTrigger API and the new Event API as clearly as possible, we show two sample API requests side by side below. On the left side you can see an example of a request to the ReviewCollector or ReviewTrigger API, on the right side an example of a request to the Event API.

System My Trusted Shops eTrusted
Path https://api.trustedshops.com/restricted/v2/shops/{tsId}/reviewcollector https://api.etrusted.com/event
Auth HTTP Basic Auth (Username:Password) OAuth2.0 Token, see documentation
Body ReviewTriggerAPI.png EventAPI.png

We will now explain the individual parameters to give you an understanding of the differences and the necessary settings. You will also find out where the parameters of the two API requests differ from each other.

Parameter ReviewCollector / ReviewTrigger API Parameter Event API Differences Explanation
tsid channel.id

New / further information needs to be provided.

The old parameter tsid is no longer needed for the Event API. Instead, each of your channels has its own ID that you must pass at this point. You can get your channel IDs by making a request to our Get Channel API. You can find out exactly what this request should look like here: Channels
xxx channel.type New parameter. This parameter has a fixed value: "eTrusted".
xxx type New parameter.

The type parameter defines the event to which the review is linked. Since all reviews in MyTS were linked to the customer's checkout, the value of this parameter is also fixed: "checkout". If you have used the ReviewCollector/ReviewTrigger API for non-order related reviews and therefore want to use a different touchpoint, please contact us at productintegration@trustedshops.com.

reminderDate xxx Parameter no longer exists.

The parameter reminderDate is no longer used in the Event API. This means you do not need to set it up. The concrete invite sending date is configured in the eTrusted Control Centre using the settings for optimised review collection. For this, please consult this article: How to send invites to my customers automatically?

template.variant xxx Parameter no longer exists. The template.variant parameter is no longer used in the Event API. This means you do not need to set it up. The desired questionnaire template is configured in the eTrusted Control Centre using the settings for optimised review collection. For this, please consult this article: How to send invites to my customers automatically?
template.
includeWidget
xxx Parameter no longer exists. The parameter template.includeWidget is no longer used in the Event API. This means you do not need to set it up.

order.
orderDate

transaction.
date

Parameters are equivalent.

The parameter transaction.date passes the time of the order to be reviewed. In this parameter, pass the value that you previously passed in the order.orderDate parameter.

order.
orderReference

transaction.
reference

Parameters are equivalent.

The parameter transaction.reference passes the order number of the order to be reviewed. In the transaction.reference parameter, pass the value that you previously passed in the order.orderReference parameter.

order.
products

products

Parameters are equivalent.

The data required for Product Reviews are transferred in this parameter.

order.
currency

xxx

Parameter no longer exists.

The parameter order.currency is no longer used in the Event API. This means you do not need to set it up.

consumer.
firstname

customer.
firstname

Parameters are equivalent.

The parameter customer.firstname passes the first name of your customer. In this parameter, pass the value that you previously passed in the consumer.firstname parameter.

consumer.
lastname

customer.
lastname

Parameters are equivalent.

The parameter customer.lastname passes the last name of your customer. In this parameter, pass the value that you previously passed in the consumer.lastname parameter.

consumer.
contact.email

customer.
email

Parameters are equivalent.

The parameter customer.email passes the email address of your customer. In this parameter, pass the value that you previously passed in the consumer.contact.email parameter.

xxx

systemVersion

New parameter.

Use different version numbers in this parameter to be able to identify your specific implementation in support cases.

xxx

metadata

New parameter.

You can use this non-mandatory parameter to add additional information (e.g. about the customer, the event, etc.) for analysis purposes.

If your request to the Event API was successful, you will receive a response according to the following pattern:

{
 "Message": "Your event (`evt-xxxxxxxx-yyyy-xxxx-yyyy-xxxxxxxxxxxx`) was accepted for processing.",
 "EventRef": "evt-xxxxxxxx-yyyy-xxxx-yyyy-xxxxxxxxxxxx"
}

Your customer will then receive a Review Invite.

With each request to the Event API, you create only a single event that triggers the sending of a Review Invite. If you want to create several events at once, you will need to make a loop. This introductory article in our Developer Centre will help you: The experience feedback setup

Was this article helpful?

2 out of 2 found this helpful