Wie richte ich nach dem Update auf eTrusted meine API-Anbindung ein?

In dieser Anleitung erklären wir Ihnen, wie Sie Ihre API-Anbindung an die bisherige Bewertungsplattform My Trusted Shops auf die neue Plattform eTrusted übertragen. Daher richtet sich dieser Artikel ausschließlich an Shops, die für Ihre Arbeit mit My Trusted Shops eine API-Anbindung etabliert haben. Sofern Ihr Shop zu dieser Gruppe gehört, werden wir Sie rechtzeitig per E-Mail über die nötigen Schritte informieren. Wenn Sie nicht zu dieser Gruppe gehören, aber allgemein an den eTrusted APIs interessiert sind, können Sie sich gerne in unserem Developer Center über die bestehenden Möglichkeiten informieren: Zum Developer Center
Die Anpassung Ihrer API-Anbindung setzt technisches Vorwissen voraus. Leiten Sie diese Anleitung daher bitte an Ihre Entwicklungsabteilung oder Agentur weiter, sofern Sie nicht selbst über derartige Kenntnisse verfügen.

Wann sollte ich die API-Umstellung durchführen?

Bevor Sie selbst tätig werden können, müssen von unserer Seite ein paar Voraussetzungen für eine erfolgreiche API-Umstellung geschaffen werden. Zunächst wird Ihr Kundenaccount (inklusive all Ihrer Shops) für die Produktivumgebung der neuen Bewertungsplattform eTrusted freigeschaltet. Zeitgleich werden wir ein API-Forwarding der bislang genutzten APIs von My Trusted Shops zu den neuen eTrusted APIs einrichten. Dadurch gewährleisten wir, dass Sie auch während der Phase, in denen Sie Ihre APIs umstellen, reibungslos Bewertungen sammeln, managen und in Ihrem Shop anzeigen können.

Sobald Sie von uns die Nachricht erhalten, dass Ihr Shop das Update auf eTrusted erhalten hat, ist der Zeitpunkt für die API-Umstellung gekommen. Führen Sie nun die drei folgenden Schritte aus, um Ihre eTrusted APIs einzurichten:

  1. Gehen Sie in Ihrem eTrusted-Konto zum Bereich API Client Management, um Ihre API Client Credentials (Client ID und Client Secret) für die eTrusted-APIs zu erhalten. Bitte beachten Sie: Dies ist nur möglich, wenn Sie über Adminrechte verfügen.
  2. Finden Sie mithilfe der Dokumentation unserer My Trusted Shops APIs heraus, welche API Sie bislang verwendet haben.
  3. Folgen Sie der nachstehenden Anleitung und richten Sie Ihre neue API-Anbindung ein.
Beachten Sie bitte, dass die API-Umstellung bis zum Jahresende umgesetzt sein muss. Am 31. Dezember 2021 werden die My Trusted Shops APIs und damit auch das eingerichtete API-Forwarding endgültig eingestellt. Sofern die APIs zu diesem Zeitpunkt noch nicht umgestellt sein sollten, können keine Bewertungen mehr gesammelt werden.

Setup und Authentifizierung

Sobald Sie Ihre Logindaten für die eTrusted APIs von uns erhalten haben, können Sie sich gegenüber unserem Authorization Server authentifizieren. Unsere APIs sind via OAuth2 geschützt. Die Authentifizierung geschieht über einen initialen API-Call an den Authorization Server. Wie der initiale API-Call aussehen muss, erfahren Sie im Developer Center: Setup and Authentication

Sofern der API-Call erfolgreich war, erhalten Sie eine Antwort, die einen Access Token enthält. Dieser Access Token muss für alle nachfolgenden API-Calls im Request Header des Calls hinterlegt sein.

Haben Sie Dienstleister beauftragt, die ebenfalls über die eTrusted APIs auf die Plattform zugreifen müssen? Dann bedenken Sie bitte, dass auch diese Dienstleister die API-Anbindung neu einrichten müssen. Informieren Sie Ihre Dienstleister daher rechtzeitig und gewähren Sie ihnen Zugriff auf Ihre neuen Logindaten für die eTrusted APIs.
Detailliertere Informationen zur Authentifizierung und der Verwendung des Access Tokens innerhalb des Request Headers finden Sie in der Dokumentation der eTrusted APIs: Authentication

Umstellung der bisherigen ReviewRequest API zur neuen Questionnaire Link API

Mit der für My Trusted Shops bereitgestellten ReviewRequest API waren Sie in der Lage, Links zum Bewertungsfragebogen von Trusted Shops in individuell gestaltete Bewertungsanfragen einzubetten. Wenn Sie diese API bislang genutzt haben, ist die für eTrusted entwickelte Questionnaire Link API der passende Ersatz für diesen Use Case.

Über die Questionnaire Link API können Sie Links zu vorkonfigurierten Fragebögen für Ihre Kundinnen und Kunden bei eTrusted abrufen. Diese Links können Sie anschließend in eine E-Mail, SMS oder einen anderen Kommunikationskanal Ihrer Wahl integrieren, um auf diese Weise Kundenfeedback zu sammeln.

Sämtliche Detailinformationen zur Questionnaire Link API finden Sie hier in unserer API-Dokumentation: Questionnaires

Damit Sie die Unterschiede zwischen der alten ReviewRequest API und der neuen Questionnaire Link API auf einen Blick erkennen können, stellen wir im Folgenden zwei beispielhafte API-Requests nebeneinander dar. Auf der linken Seite sehen Sie ein Beispiel für einen Request an die ReviewRequest API, auf der rechten Seite einen beispielhaften Request an die 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, siehe Dokumentation
Body ReviewRequestAPI.png QuestionnaireLinkAPI.png

Damit Sie die nötigen Einstellungen besser verstehen, erläutern wir Ihnen nun die einzelnen Parameter. Zudem erfahren Sie, an welchen Stellen sich die Parameter der beiden API-Requests voneinander unterscheiden.

Parameter ReviewRequest API Parameter Questionnaire Link API Unterschiede Erläuterung
tsid channel.id Es müssen neue / weitere Informationen bereitgestellt werden. Der alte Parameter tsid wird für die Questionnaire Link API nicht mehr benötigt. Stattdessen hat jeder Ihrer Channel eine eigene ID, die Sie an dieser Stelle übergeben müssen. Ihre Channel IDs erhalten Sie durch ein Request an unsere Get Channel API. Wie dieser Request genau aussehen muss, erfahren Sie hier: Channels
xxx channel.type Neuer Parameter. Dieser Parameter hat einen festen Wert: "eTrusted".
xxx type Neuer Parameter. Der Parameter type definiert das Event, an das die Bewertung gekoppelt ist. Da alle Bewertungen in MyTS an den Checkout des Kunden gekoppelt waren, ist der Wert dieses Parameters ebenfalls fest: "checkout". Wenn Sie die ReviewRequest API für nicht bestellbezogene Bewertungen genutzt haben und deswegen einen anderen Touchpoint benutzen wollen, melden Sie sich bitte unter productintegration@trustedshops.com bei uns.
order.
orderDate
transaction.
date
Parameter entsprechen einander. Der Parameter transaction.date übergibt den Zeitpunkt der Bestellung, die bewertet werden soll. Übergeben Sie in diesem Parameter den Wert, den Sie vorher im Parameter order.orderDate übergeben haben.
order.
orderReference
transaction.
reference
Parameter entsprechen einander.

Der Parameter transaction.reference übergibt die Bestellnummer der Bestellung, die bewertet werden soll. Übergeben Sie im Parameter transaction.reference den Wert, den Sie vorher im Parameter order.orderReference übergeben haben.

order.
products
products Parameter entsprechen einander. In diesem Parameter werden die für Produktbewertungen nötigen Daten übergeben. Die Funktionalität für Produktbewertungen wird im Laufe des dritten Quartals 2021 für die Questionnaire Link API freigeschaltet.
consumer.
firstname
customer.
firstname
Parameter entsprechen einander. Der Parameter customer.firstname übergibt den Vornamen Ihrer Kundschaft. Übergeben Sie in diesem Parameter den Wert, den Sie vorher im Parameter consumer.firstname übergeben haben.
consumer.
lastname
customer.
lastname
Parameter entsprechen einander.

Der Parameter customer.lastname übergibt den Nachnamen Ihrer Kundschaft. Übergeben Sie in diesem Parameter den Wert, den Sie vorher im Parameter consumer.lastname übergeben haben.

consumer.
contact.email
customer.
email
Parameter entsprechen einander. Der Parameter customer.email übergibt die E-Mail-Adresse Ihrer Kundschaft. Übergeben Sie in diesem Parameter den Wert, den Sie vorher im Parameter consumer.contact.email übergeben haben.
consumer.
contact.language
xxx Parameter existiert nicht mehr. Der Parameter consumer.contact.language wird in der Questionnaire Link API nicht mehr genutzt. Daher müssen Sie ihn auch nicht einrichten.
sender.type xxx Parameter existiert nicht mehr. Der Parameter sender.type wird in der Questionnaire Link API nicht mehr genutzt. Daher müssen Sie ihn auch nicht einrichten.
types.key xxx Parameter existiert noch nicht. In diesem Parameter werden Daten übergeben, die für Produktbewertungen nötig sind. Die Funktionalität für Produktbewertungen wird im Laufe des dritten Quartals 2021 für die Questionnaire Link API freigeschaltet.
xxx questionnaire
Template.id
Neuer Parameter. In diesem Parameter wird die Fragebogenvorlage identifiziert, aus der der individuelle Fragebogen für Ihre Kundschaft generiert wird. Aus welchen Fragebogenvorlagen Sie wählen können, erfahren Sie hier: Templates
xxx system Neuer Parameter. Der Parameter system identifiziert das System, das den Request an die Questionnaire Link API tätigt. Verwenden Sie an dieser Stelle eine eindeutige Zeichenfolge, die Ihnen hilft, Ihre Komponente zu identifizieren. Diese Informationen werden ggf. für die Support-Kommunikation benötigt.
xxx systemVersion Neuer Parameter.

Verwenden Sie in diesem Parameter verschiedene Versionsnummern, um in Supportfällen Ihre spezifische Implementierung identifizieren zu können.

xxx metadata Neuer Parameter. Diesen nicht obligatorischen Parameter können Sie nutzen, um zu Analysezwecken zusätzliche Informationen (z.B. zum Kunden, zum Event etc.) hinzuzufügen.

Wenn Ihr Request an die Questionnaire Link API erfolgreich war, erhalten Sie eine Antwort nach dem folgenden Muster:

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

Im Parameter link erhalten Sie den Link zum generierten Fragebogen. Diesen Link können Sie nun in den Kommunikationskanal Ihrer Wahl integrieren.

Die Links, die Sie mithilfe der Questionnaire Link API erstellen, sind individuell und für jeweils eine spezifische Kundin oder einen spezifischen Kunden bestimmt. Dies hat zur Folge, dass Sie für jede Bewertungseinladung jeweils einen eigenen Link zum Fragebogen erstellen und in Ihre Kommunikation integrieren müssen.

Umstellung der bisherigen ReviewCollector API / ReviewTrigger API zur neuen Event API

Mit der für My Trusted Shops bereitgestellten ReviewCollector bzw. ReviewTrigger API waren Sie in der Lage, den Versand von Bewertungseinladungen an Ihre Kundschaft auszulösen. Ihre Kundinnen und Kunden erhielten in diesem Fall eine von Trusted Shops versendete E-Mail mit einem Bewertungsfragebogen. Wenn Sie diese API bislang genutzt haben, ist die für eTrusted entwickelte Event API der passende Ersatz für diesen Use Case. Mit der Event API können Sie den Versandzeitpunkt für Ihre Bewertungseinladungen an jeden beliebigen Touchpoint entlang Ihrer Customer Journey koppeln.

Sämtliche Detailinformationen zur Event API finden Sie hier in unserer API-Dokumentation: Events

Um Ihnen die Unterschiede zwischen der alten ReviewCollector bzw. ReviewTrigger API und der neuen Event API möglichst übersichtlich darzustellen, präsentieren wir Ihnen im Folgenden zwei beispielhafte API-Requests nebeneinander. Auf der linken Seite sehen Sie ein Beispiel für einen Request an die ReviewCollector bzw. ReviewTrigger API, auf der rechten Seite einen beispielhaften Request an die 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, siehe Dokumentation
Body ReviewTriggerAPI.png EventAPI.png

Wir erklären Ihnen nun die einzelnen Parameter, um Ihnen die Unterschiede und die nötigen Einstellungen näherzubringen. Zudem erfahren Sie, an welchen Stellen sich die Parameter der beiden API-Requests voneinander unterscheiden.

Parameter ReviewCollector / ReviewTrigger API Parameter Event API Unterschiede Erläuterung
tsid channel.id

Es müssen neue / weitere Informationen bereitgestellt werden.

Der alte Parameter tsid wird für die Event API nicht mehr benötigt. Stattdessen hat jeder Ihrer Channel eine eigene ID, die Sie an dieser Stelle übergeben müssen. Ihre Channel IDs erhalten Sie durch ein Request an unsere Get Channel API. Wie dieser Request genau aussehen muss, erfahren Sie hier: Channels
xxx channel.type Neuer Parameter. Dieser Parameter hat einen festen Wert: "eTrusted".
xxx type Neuer Parameter. Der Parameter type definiert das Event, an das die Bewertung gekoppelt ist. Da alle Bewertungen in MyTS an den Checkout des Kunden gekoppelt waren, ist der Wert dieses Parameters ebenfalls fest: "checkout". Wenn Sie die ReviewCollector/ReviewTrigger API für nicht bestellbezogene Bewertungen genutzt haben und deswegen einen anderen Touchpoint benutzen wollen, melden Sie sich bitte unter productintegration@trustedshops.com bei uns.
reminderDate xxx Parameter existiert nicht mehr.

Der Parameter reminderDate wird in der Event API nicht mehr genutzt. Daher müssen Sie ihn auch nicht einrichten. Das konkrete Versanddatum der Einladungen wird im eTrusted-Kontrollzentrum mithilfe der Einladungsregeln konfiguriert. Ziehen Sie hierfür bitte diesen Artikel zu Rate: Wie sende ich Einladungen automatisiert an meine Kundschaft?

template.variant xxx Parameter existiert nicht mehr. Der Parameter template.variant wird in der Event API nicht mehr genutzt. Daher müssen Sie ihn auch nicht einrichten. Die gewünschte Fragenbogen-Vorlage wird im eTrusted-Kontrollzentrum mithilfe der Einladungsregeln konfiguriert. Ziehen Sie hierfür bitte diesen Artikel zu Rate: Wie sende ich Einladungen automatisiert an meine Kundschaft?
template.
includeWidget
xxx Parameter existiert nicht mehr. Der Parameter template.includeWidget wird in der Event API nicht mehr genutzt. Daher müssen Sie ihn auch nicht einrichten.

order.
orderDate

transaction.
date

Parameter entsprechen einander.

Der Parameter transaction.date übergibt den Zeitpunkt der Bestellung, die bewertet werden soll. Übergeben Sie in diesem Parameter den Wert, den Sie vorher im Parameter order.orderDate übergeben haben.

order.
orderReference

transaction.
reference

Parameter entsprechen einander.

Der Parameter transaction.reference übergibt die Bestellnummer der Bestellung, die bewertet werden soll. Übergeben Sie im Parameter transaction.reference den Wert, den Sie vorher im Parameter order.orderReference übergeben haben.

order.
products

products

Parameter entsprechen einander.

In diesem Parameter werden die für Produktbewertungen nötigen Daten übergeben.

order.
currency

xxx

Parameter existiert nicht mehr.

Der Parameter order.currency wird in der Event API nicht mehr genutzt. Daher müssen Sie ihn auch nicht einrichten.

consumer.
firstname

customer.
firstname

Parameter entsprechen einander.

Der Parameter customer.firstname übergibt den Vornamen Ihrer Kundschaft. Übergeben Sie in diesem Parameter den Wert, den Sie vorher im Parameter consumer.firstname übergeben haben.

consumer.
lastname

customer.
lastname

Parameter entsprechen einander.

Der Parameter customer.lastname übergibt den Nachnamen Ihrer Kundschaft. Übergeben Sie in diesem Parameter den Wert, den Sie vorher im Parameter consumer.lastname übergeben haben.

consumer.
contact.email

customer.
email

Parameter entsprechen einander.

Der Parameter customer.email übergibt die E-Mail-Adresse Ihrer Kundschaft. Übergeben Sie in diesem Parameter den Wert, den Sie vorher im Parameter consumer.contact.email übergeben haben.

xxx

systemVersion

Neuer Parameter.

Verwenden Sie in diesem Parameter verschiedene Versionsnummern, um in Supportfällen Ihre spezifische Implementierung identifizieren zu können.

xxx

metadata

Neuer Parameter.

Diesen nicht obligatorischen Parameter können Sie nutzen, um zu Analysezwecken zusätzliche Informationen (z.B. zum Kunden, zum Event etc.) hinzuzufügen.

Wenn Ihr Request an die Event API erfolgreich war, erhalten Sie eine Antwort nach dem folgenden Muster:

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

Ihre Kundin oder Ihr Kunde erhält daraufhin eine Bewertungseinladung.

Mit jedem Request an die Event API erzeugen Sie nur ein einzelnes Event, durch das der Versand einer Bewertungseinladung ausgelöst wird. Wenn Sie mehrere Events auf einmal erzeugen möchten, müssen Sie einen Loop erstellen. Dieser Einführungsartikel in unserem Developer Center hilft Ihnen dabei: The experience feedback setup

War der Artikel hilfreich?

1 von 1 fanden dies hilfreich