Hoe kan ik na de update naar eTrusted mijn API-koppeling inrichten?

In deze handleiding leggen we uit hoe je je API-koppeling van het bestaande beoordelingsplatform My Trusted Shops kunt overzetten naar het nieuwe platform eTrusted. Daarom is dit artikel uitsluitend gericht op shops die binnen My Trusted Shops een API-koppeling gebruiken. Als jouw shop tot deze groep behoort, zul je tijdig over de nodige stappen worden geïnformeerd via de mail. Als jij niet tot deze groep behoort maar een algemene interesse hebt in de eTrusted API's, nodigen wij je uit om via ons Developer Center meer te lezen over de bestaande mogelijkheden: Naar het Developer Center
Het gebruik van je API-koppeling vereist technische voorkennis. Als je zelf niet over dergelijke kennis beschikt, adviseren wij je deze handleiding door te geven aan je IT afdeling of de agency die dit voor je uit kan voeren.

Wanneer moet ik de API-omschakeling uitvoeren?

Voordat je zelf aan de slag kunt, moeten wij vanuit onze kant eerst een aantal voorwaarden voor een succesvolle API-koppeling stellen. Vervolgens wordt je account (inclusief al je shops) voor de productie-omgeving van het nieuwe beoordelingsplatform eTrusted vrijgegeven. Tegelijkertijd zullen wij een API-forwarding van de tot dan toe gebruikte API's van My Trusted Shops naar de nieuwe eTrusted API's instellen. Daarmee garanderen wij dat je ook tijdens de fase waarin jij je API's omschakelt, probleemloos beoordelingen kunt verzamelen, beheren en in je shop kunt weergeven.

Zodra je van ons een bericht hebt ontvangen dat je shop de update naar eTrusted heeft gekregen, kun je starten met de omschakeling van de API-koppeling. Voer dan de volgende drie stappen uit om je eTrusted API's in te stellen:

  1. Ga in je eTrusted account naar API Client Management om je API Client Credentials (Client ID en Client Secret) te vinden voor de eTrusted APIs. Let op: Dit is alleen mogelijk als je adminrechten hebt.
  2. Bepaal op basis van de Documentatie over onze My Trusted Shops API's welke API's je tot nu toe hebt gebruikt.
  3. Volg de stappen in de handleiding hieronder om je nieuwe API-koppeling in te stellen.
Wij vragen je de API-omschakeling vóór het einde van dit jaar te realiseren. Op 31 december 2021 worden de My Trusted Shops API's en daarmee ook de ingestelde API-Forwarding definitief stopgezet. Als de API's op deze datum nog niet zijn aangepast, kunnen er geen beoordelingen meer worden verzameld.

Instelling en authenticatie

Zodra je van ons je inloggegevens voor de eTrusted API's hebt ontvangen, kun je je authenticeren bij onze Authorization Server. Onze API's zijn via OAuth2 beveiligd. Deze authenticatie vindt plaats via een initiële API Call naar de Authorization Server. In het Developer Center kun je zien hoe de initiële API Call eruit moet zien: Setup and Authentication

Als de API Call succesvol was, ontvang je een antwoord waarin een Access Token is opgenomen. Deze Access Token moet voor alle navolgende API Calls gekoppeld zijn in de Request Header van de Calls.

Heb je opdracht gegeven aan dienstverleners die ook toegang tot het platform moeten krijgen via de eTrusted API's? Houd er dan rekening mee dat deze dienstverleners ook de API-verbinding opnieuw moeten opzetten. Breng daarom je dienstverleners tijdig op de hoogte en geef hen toegang tot de nieuwe inloggegevens voor de eTrusted API's.
Gedetailleerde informatie over de authenticatie en het gebruik van de Access Token in de Request Header kun je vinden in de eTrusted API documentatie: Authentication

Omschakeling van de huidige ReviewRequest API naar de nieuwe Questionnaire Link API

Met de voor My Trusted Shops beschikbare ReviewRequest API heb je de mogelijkheid om een link naar het beoordelingsformulier van Trusted Shops in een individueel vormgegeven beoordelingsmail te integreren. Als je deze API tot nu toe hebt gebruikt, is de voor eTrusted ontwikkelde Questionnaire Link API de passende vervanging.

Via de Questionnaire Link API (eTrusted) kun je een link naar de vooraf ingestelde vragenlijst bij eTrusted opvragen. Deze link kun je vervolgens in een e-mail, sms, of ander communicatiekanaal van je keuze integreren, om op deze manier klantenfeedback te verzamelen.

Gedetailleerde informatie over de Questionnaire Link API kun je hier in onze API-documentatie vinden: Questionnaires

Zodat je het verschil tussen de oude ReviewRequest API (My Trusted Shops) en de nieuwe Questionnaire Link API (eTrusted) in één oogopslag kunt herkennen, geven wij je hieronder twee voorbeelden van API-Requests. Links zie je een voorbeeld van een request aan de ReviewRequest API (My Trusted Shops), rechts zie je een voorbeeld van een request aan de Questionnaire Link API (eTrusted).

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, Documentatie
Body ReviewRequestAPI.png QuestionnaireLinkAPI.png

Om de nodigde instellingen beter te kunnen begrijpen, lichten wij nu de afzonderlijke parameters toe. Bovendien kun je zien op welke plaatsen de parameters van de beide API Requests van elkaar verschillen.

Parameter ReviewRequest API (My Trusted Shops)
Parameter Questionnaire Link API (eTrusted)
Verschillen Toelichting
tsid channel.id

Er moet nieuwe / aanvullende informatie worden verstrekt

De oude parameter 'tsid' is voor de Questionnaire Link API niet meer nodig. In plaats daarvan heeft elk van de door jou gebruikte kanalen (Channels) een eigen ID, die je op deze plaats moet doorgeven. Je ontvangt je Channel ID's door een request naar onze Get Channel API te sturen. Hier kun je zien hoe deze request er exact uit moet zien: Channels

xxx channel.type

Nieuwe parameter

Deze parameter heeft een vaste waarde: 'eTrusted'.

xxx type

Nieuwe parameter

De parameter 'type' definieert het Event waaraan de beoordeling is gekoppeld. Omdat alle beoordelingen in MyTS aan de Checkout van de klant waren gekoppeld, is de waarde van deze parameter standaard: 'checkout'. Als je de ReviewRequest API hebt gebruikt voor het versturen van beoordelingsverzoeken die niet aan een bestelling zijn gerelateerd, neem dan contact op met productintegration@trustedshops.com.

order.
orderDate
transaction.
date

Parameters komen met elkaar overeen

De parameter 'transaction.date' geeft het tijdstip van de bestelling weer waarvoor een beoordelingsverzoek moet worden verzonden. Voer bij deze parameter de waarde in die je eerder had toegekend aan de parameter 'order.orderDate'.

order.
orderReference
transaction.
reference

Parameters komen met elkaar overeen

De parameter 'transaction.reference' geeft het ordernummer weer van de bestelling waarvoor een beoordelingsverzoek moet worden opgesteld. Voer bij de parameter 'transaction.reference' de waarde in die je eerder had toegekend aan de parameter 'order.orderReference'.

order.
products
products

Parameters komen met elkaar overeen

Bij deze parameter worden de gegevens ingevoerd die voor de productbeoordelingen nodig zijn. De functionaliteit voor de productbeoordelingen zal in de loop van het derde kwartaal van 2021 voor de Questionnaire Link API beschikbaar zijn.

consumer.
firstname
customer.
firstname

Parameters komen met elkaar overeen

De parameter 'customer.firstname' toont de voornaam van je klant. Voer bij deze parameter de waarde in die je eerder had toegekend aan de parameter 'consumer.firstname'.

consumer.
lastname
customer.
lastname

Parameters komen met elkaar overeen

De parameter 'customer.lastname' toont de achternaam van je klant. Voer bij deze parameter de waarde in die je eerder had toegekend aan de parameter 'consumer.lastname'.

consumer.
contact.email
customer.
email

Parameters komen met elkaar overeen

De parameter 'customer.email' toont het e-mailadres van je klant. Voer bij deze parameter de waarde in die je eerder had toegekend aan de parameter 'consumer.contact.email'.

consumer.
contact.language
xxx

Deze parameter bestaat niet meer

De parameter 'consumer.contact.language' wordt in de Questionnaire Link API niet meer gebruikt. Daarom hoef je deze ook niet in te stellen.

sender.type xxx

Deze parameter bestaat niet meer

De parameter 'sender.type' wordt in de Questionnaire Link API niet meer gebruikt. Daarom hoef je deze ook niet in te stellen.

types.key xxx

Deze parameter bestaat niet meer

In deze parameter worden de voor de productbeoordelingen benodigde gegevens ingevoerd. De functionaliteit voor de productbeoordelingen zal in de loop van het derde kwartaal van 2021 voor de Questionnaire Link API beschikbaar zijn.

xxx questionnaire
Template.id

Nieuwe parameter

In deze parameter wordt de template van de vragenlijst geïdentificeerd, op basis waarvan de individuele vragenlijst voor je klant wordt gegenereerd. Hier kun je zien uit welke templates je een keuze kunt maken: Templates

xxx system

Nieuwe parameter

De parameter 'system' identificeert het systeem dat de Request voor de Questionnaire Link API activeert. Gebruik hier een unieke string die je helpt om de componenten te identificeren. Deze informatie is mogelijk vereist voor de communicatie met het support team.

xxx systemVersion

Nieuwe parameter

Gebruik in deze parameter verschillende versienummers, zodat ons support team je specifieke implementatie kan identificeren, mocht dat nodig zijn.

xxx metadata

Nieuwe parameter

Deze niet-verplichte parameter kun je gebruiken voor het toevoegen van extra informatie voor je eigen analyses (zoals over klanten, voor een Event enz.).

Als je request aan de Questionnaire Link API succesvol is, ontvang je een antwoord dat er ongeveer als volgt uit zal zien:

{
 "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 de parameter 'link' ontvang je de link naar de aangemaakte vragenlijst. Deze link kun je vervolgens in het communicatiekanaal naar keuze integreren.

De links die je met behulp van de Questionnaire Link API instelt, zijn individueel en altijd bestemd voor een specifieke klant. Dit heeft tot gevolg dat voor elk beoordelingsverzoek een unieke link naar de vragenlijst moet worden aangemaakt en in je communicatie moet worden geïntegreerd.

Omschakeling van de bestaande ReviewCollector API / ReviewTrigger API naar de nieuwe Event API

Met de voor My Trusted Shops beschikbare ReviewCollector resp. ReviewTrigger API had je de mogelijkheid om de verzending van de beoordelingsverzoeken naar je klanten zelf te triggeren op een moment naar keuze. Je klanten zullen in dit geval een door Trusted Shops verzonden e-mail ontvangen met het beoordelingsverzoek. Als je tot nu toe deze API hebt gebruikt, is de voor eTrusted ontwikkelde Event API de passende vervanging. Met de Event API kun je het tijdstip van de verzending van je beoordelingsverzoeken aan elk willekeurig contactmoment van de Customer Journey koppelen.

Gedetailleerde informatie over de Event API kun je in onze API-documentatie vinden: Events

Om op een zo goed en overzichtelijk mogelijke manier de verschillen tussen de oude ReviewCollector resp. ReviewTrigger API en de nieuwe Event API te tonen, hebben wij onderstaand als voorbeeld twee API-Requests naast elkaar weergegeven. Links zie je een voorbeeld van een request aan de ReviewCollector resp. ReviewTrigger API, rechts zie je een voorbeeld van een request aan de 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, Documentatie
Body ReviewTriggerAPI.png EventAPI.png

Om de nodige instellingen beter te kunnen begrijpen, lichten wij nu de afzonderlijke parameters en hun verschillen toe. Bovendien kun je zien op welke plaatsen de parameters van de beide API Requests van elkaar verschillen.

Parameter ReviewCollector / ReviewTrigger API Parameter Event API Verschillen Toelichting
tsid channel.id

Er moet nieuwe / aanvullende informatie worden verstrekt

De oude parameter 'tsid' is voor de Event API niet meer nodig. In plaats daarvan heeft elk van de door jou gebruikte kanalen (Channels) een eigen ID, die je op deze plaats moet doorgeven. Je ontvangt je Channel ID's door een request naar onze Get Channel API te sturen. Hier kun je zien hoe deze Request er exact uit moet zien: Channels

xxx channel.type

Nieuwe parameter

Deze parameter heeft een vaste waarde: 'eTrusted'.

xxx type

Nieuwe parameter

De parameter 'type' definieert het Event waaraan de beoordeling is gekoppeld. Omdat alle beoordelingen in MyTS aan de Checkout van de klant waren gekoppeld, is de waarde van deze parameter standaard: 'checkout'. Als je de ReviewCollector/ReviewTrigger API voor niet aan bestellingen gerelateerde beoordelingsverzoeken hebt gebruikt en om deze reden een ander contactmoment wilt gebruiken, neem dan contact op met productintegration@trustedshops.com.

reminderDate xxx

Deze parameter bestaat niet meer

De parameter 'reminderDate' wordt in de Event API niet meer gebruikt. Daarom hoef je deze ook niet in te stellen. De concrete verzenddatum van de beoordelingsverzoeken wordt in het controlecentrum van eTrusted op basis van de Invite Rules voor de beoordelingsverzoeken geconfigureerd. Meer informatie kun je in dit artikel vinden: Hoe kan ik automatisch beoordelingsverzoeken versturen aan mijn klanten?

template.variant xxx

Deze parameter bestaat niet meer

De parameter 'template.variant' wordt in de Event API niet meer gebruikt. Daarom hoef je deze ook niet in te stellen. De gewenste template voor de vragenlijst wordt in het controlecentrum van eTrusted op basis van de Invite Rules voor de beoordelingsverzoeken geconfigureerd. Meer informatie hierover kun je in dit artikel vinden: Hoe kan ik automatisch beoordelingsverzoeken versturen aan mijn klanten? 

template.
includeWidget
xxx

Deze parameter bestaat niet meer

De parameter 'template.includeWidget' wordt in de Event API niet meer gebruikt. Daarom hoef je deze ook niet in te stellen.

order.
orderDate

transaction.
date

Parameters komen met elkaar overeen

De parameter 'transaction.date' geeft het tijdstip van de bestelling weer waarvoor een beoordelingsverzoek moet worden verzonden. Voer bij deze parameter de waarde in die je eerder had toegekend aan de parameter 'order.orderDate'.

order.
orderReference

transaction.
reference

Parameters komen met elkaar overeen

De parameter 'transaction.reference' geeft het bestelnummer weer van de bestelling waarvoor een beoordelingsverzoek moet worden opgesteld. Voer bij de parameter 'transaction.reference' de waarde in die je eerder had toegekend aan de parameter 'order.orderReference'.

order.
products

products

Parameters komen met elkaar overeen

Bij deze parameters worden de gegevens ingevoerd die voor de productbeoordelingen nodig zijn.

order.
currency

xxx

Deze parameter bestaat niet meer

De parameter 'order.currency' wordt in de Event API niet meer gebruikt. Daarom hoef je deze ook niet in te stellen.

consumer.
firstname

customer.
firstname

Parameters komen met elkaar overeen

De parameter 'customer.firstname' toont de voornaam van je klant. Voer bij deze parameter de waarde in die je eerder had toegekend aan de parameter 'consumer.firstname'.

consumer.
lastname

customer.
lastname

Parameters komen met elkaar overeen

De parameter 'customer.lastname' toont de achternaam van je klant. Voer bij deze parameter de waarde in die je eerder had toegekend aan de parameter 'consumer.lastname'.

consumer.
contact.email

customer.
email

Parameters komen met elkaar overeen

De parameter 'customer.email' toont het e-mailadres van je klant. Voer bij deze parameter de waarde in die je eerder had toegekend aan de parameter 'consumer.contact.email'.

xxx

systemVersion

Nieuwe parameter

Gebruik in deze parameter verschillende versienummers, zodat ons support team je specifieke implementatie kan identificeren, mocht dat nodig zijn.

xxx

metadata

Nieuwe parameter

Deze niet-verplichte parameter kun je gebruiken voor het toevoegen van extra informatie voor je eigen analyses (zoals over klanten, voor een Event enz.).

Als je Request aan de Event API succesvol is geweest, ontvang je een antwoord dat er ongeveer als volgt uit zal zien:

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

Je klant ontvangt vervolgens een beoordelingsverzoek.

Met elke Request aan de Event API creëer je een afzonderlijk Event, waardoor de verzending van een beoordelingsverzoek wort geactiveerd. Als je in een enkele keer meerdere Events wilt creëren, moet je een loop instellen. Dit artikel in ons Developer Center helpt je daarbij: The experience feedback setup

Was dit artikel nuttig?

Aantal gebruikers dat dit nuttig vond: 1 van 1