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:
- 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.
- Use the documentation for our My Trusted Shops APIs to find out which API you have been using.
- Follow the instructions below and set up your new API connection.
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.
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.
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 |
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. |
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.
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.
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 |
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. |
transaction. |
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. |
transaction. |
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 |
Parameters are equivalent. |
The data required for Product Reviews are transferred in this parameter. |
order. |
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. |
customer. |
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. |
customer. |
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. |
customer. |
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.