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:
- 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.
- Bepaal op basis van de Documentatie over onze My Trusted Shops API's welke API's je tot nu toe hebt gebruikt.
- Volg de stappen in de handleiding hieronder om je nieuwe API-koppeling in te stellen.
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.
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.
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 |
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. |
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.
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.
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 |
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 het beoordelingsverzoek wordt in het eTrusted controlecentrum geconfigureerd met behulp van de instellingen voor het geoptimaliseerde verzamelen van beoordelingen. 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 vragenlijstsjabloon wordt in het eTrusted controlecentrum geconfigureerd met behulp van de instellingen voor het geoptimaliseerde verzamelen van beoordelingen. 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. |
transaction. |
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. |
transaction. |
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 |
Parameters komen met elkaar overeen |
Bij deze parameters worden de gegevens ingevoerd die voor de productbeoordelingen nodig zijn. |
|
order. |
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. |
customer. |
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. |
customer. |
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. |
customer. |
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.