Kiedy należy przeprowadzić konwersję API?
Aby umożliwić Ci podjęcie samodzielnych kroków, musimy najpierw sami spełnić kilka warunków wstępnych pomyślnej konwersji API. Na początku Twoje konto klienta (wraz ze wszystkimi sklepami) zostanie aktywowane dla środowiska produkcyjnego nowej platformy opinii eTrusted. Jednocześnie ustawimy przekazywanie poprzednio używanych interfejsów API z My Trusted Shops do nowych interfejsów API eTrusted. Umożliwi Ci to dalsze bezproblemowe gromadzenie i wyświetlanie opinii oraz zarządzanie nimi w sklepie, nawet podczas konwersji interfejsów API.
Gdy otrzymasz od nas wiadomość, że Twój sklep został zaktualizowany do eTrusted, przyjdzie pora na konwersję API. Następnie musisz wykonać trzy poniższe kroki, aby skonfigurować swoje interfejsy API eTrusted:
- Na swoim koncie eTrusted przejdź do sekcji API Client Management, aby uzyskać API Client Credentials (Client ID i Client Secret) dla interfejsów API eTrusted. Uwaga: Będzie to możliwe tylko wtedy, gdy masz prawa administratora.
- Skorzystaj z dokumentacji dotyczącej naszych interfejsów API My Trusted Shops, aby dowiedzieć się, którego interfejsu API używasz dotychczas.
- Postępuj zgodnie z poniższymi instrukcjami i skonfiguruj nowe połączenie API.
Konfiguracja i uwierzytelnianie
Natychmiast po otrzymaniu od nas swoich danych logowania do interfejsów API eTrusted możesz uwierzytelnić się na naszym serwerze autoryzacji. Nasze interfejsy API są chronione za pomocą protokołu OAuth2. Uwierzytelnienie odbywa się za pośrednictwem wstępnego wywołania interfejsu API do serwera autoryzacji. W Centrum dla deweloperów możesz zobaczyć, jak musi wyglądać wstępne wywołanie API: Setup and Authentication
Jeśli wywołanie API powiodło się, otrzymasz odpowiedź zawierającą token dostępu. Ten token dostępu musi być przechowywany w nagłówku żądania wszystkich kolejnych wywołań interfejsu API.
Konwersja poprzedniego interfejsu API ReviewRequest do nowego interfejsu API Questionnaire Link
Interfejs API ReviewRequest udostępniony dla My Trusted Shops umożliwiał umieszczanie linków do kwestionariusza opinii Trusted Shops w indywidualnie przygotowanych prośbach o opinie. Jeśli korzystasz z tego interfejsu API, interfejs API Questionnaire Link opracowany dla eTrusted może być używany jako jego zamiennik.
Korzystając z interfejsu API Questionnaire Link, w eTrusted można pobrać linki do wstępnie skonfigurowanych kwestionariuszy dla klientów. Następnie można uwzględnić te linki w e-mailu, SMS-ie lub innym wybranym kanale komunikacji, aby zebrać opinie klientów.
Aby umożliwić Ci natychmiastowe dostrzeżenie różnic między starym interfejsem API ReviewRequest a nowym interfejsem API Questionnaire Link, poniżej przedstawiamy obok siebie dwa przykładowe żądania API. Po lewej stronie widać przykładowe żądanie API ReviewRequest, po prawej przykładowe żądanie API Questionnaire Link.
| 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, dokumentacja |
| Body |
Aby ułatwić Ci zrozumienie koniecznych ustawień, objaśnimy teraz poszczególne parametry. Dowiesz się również, czym parametry obu żądań API różnią się od siebie.
| Parametr interfejsu API ReviewRequest | Parametr interfejsu API Questionnaire Link | Różnice | Objaśnienie |
| tsid | channel.id |
Należy podać nowe/dalsze informacje. |
Stary parametr tsid nie jest już potrzebny dla interfejsu API Questionnaire Link. Zamiast tego każdy z kanałów ma własny identyfikator, który musisz w tym momencie przekazać. Swoje identyfikatory kanałów możesz uzyskać, wysyłając żądanie do naszego interfejsu API Get Channel. Tutaj możesz się dowiedzieć, jak dokładnie powinno wyglądać to żądanie: Channels |
| xxx | channel.type |
Nowy parametr. |
Ten parametr ma stałą wartość: „eTrusted”. |
| xxx | type |
Nowy parametr. |
Parametr typu definiuje zdarzenie, z którym powiązana jest opinia. Ponieważ wszystkie opinie w MyTS były powiązane z koszykiem klienta, wartość tego parametru jest również stała: „koszyk”. Jeśli korzystasz z interfejsu API ReviewRequest w przypadku opinii niezwiązanych z zamówieniami i dlatego chcesz użyć innego punktu kontaktu, napisz do nas na adres productintegration@trustedshops.com. |
| order. orderDate |
transaction. date |
Parametry są równoważne. |
Parametr transaction.date przekazuje czas zamówienia, którego ma dotyczyć ocena. W tym parametrze przekaż wartość, która została wcześniej przekazana w parametrze order.orderDate. |
| order. orderReference |
transaction. reference |
Parametry są równoważne. |
Parametr transaction.reference przekazuje numer zamówienia, którego ma dotyczyć ocena. W parametrze transaction.reference przekaż wartość, która została wcześniej przekazana w parametrze order.orderReference. |
| order. products |
products |
Parametry są równoważne. |
W tym parametrze przekazywane są dane wymagane do prezentowania opinii o produkcie. Funkcja opinii o produkcie zostanie udostępniona w interfejsie API Questionnaire Link w trzecim kwartale 2021 roku. |
| consumer. firstname |
customer. firstname |
Parametry są równoważne. |
Parametr customer.firstname przekazuje imię klienta. W tym parametrze przekaż wartość, która została wcześniej przekazana w parametrze consumer.firstname. |
| consumer. lastname |
customer. lastname |
Parametry są równoważne. |
Parametr customer.lastname przekazuje nazwisko klienta. W tym parametrze przekaż wartość, która została wcześniej przekazana w parametrze consumer.lastname. |
| consumer. contact.email |
customer. |
Parametry są równoważne. |
Parametr customer.email przekazuje adres e-mail klienta. W tym parametrze przekaż wartość, która została wcześniej przekazana w parametrze consumer.contact.email. |
| consumer. contact.language |
xxx |
Parametr już nie istnieje. |
Parametr consumer.contact.language nie jest już używany w interfejsie API Questionnaire Link. Oznacza to, że nie musisz go konfigurować. |
| sender.type | xxx |
Parametr już nie istnieje. |
Parametr sender.type nie jest już używany w interfejsie API Questionnaire Link. Oznacza to, że nie musisz go konfigurować. |
| types.key | xxx |
Parametr jeszcze nie istnieje. |
W tym parametrze przekazywane są dane niezbędne do przedstawiania opinii o produkcie. Funkcja opinii o produkcie zostanie udostępniona w interfejsie API Questionnaire Link w trzecim kwartale 2021 roku. |
| xxx | questionnaire Template.id |
Nowy parametr. |
Ten parametr określa szablon kwestionariusza, z którego generowany jest konkretny kwestionariusz dla klienta. Tutaj dowiesz się się, które szablony kwestionariuszy masz do wyboru: Templates |
| xxx | system |
Nowy parametr. |
Parametr system określa system wysyłający żądanie do interfejsu API Questionnaire Link. Użyj tutaj niepowtarzalnego ciągu, który ułatwi Ci identyfikację komponentu. Ta informacja może być potrzebna do komunikacji z działem wsparcia. |
| xxx | systemVersion |
Nowy parametr. |
W tym parametrze używaj różnych numerów wersji, aby móc zidentyfikować konkretne wdrożenie w kontaktach z działem wsparcia. |
| xxx | metadata |
Nowy parametr. |
Możesz użyć tego nieobowiązkowego parametru, aby podać dodatkowe informacje (np. o kliencie, zdarzeniu itp.) do celów analizy. |
Jeśli Twoje żądanie do interfejsu API Questionnaire Link zakończyło się sukcesem, otrzymasz odpowiedź zgodną z następującym wzorcem:
{
"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"
}
W parametrze link znajdziesz link do wygenerowanego kwestionariusza. Możesz teraz wprowadzić ten link do wybranego kanału komunikacji.
Konwersja poprzedniego interfejsu API ReviewCollector/ReviewTrigger na nowy interfejs API Event
Interfejs API ReviewCollector lub ReviewTrigger udostępniony dla My Trusted Shops pozwalał Ci uruchamiać wysyłanie klientom zaproszenia do wystawienia opinii. W tym przypadku klienci otrzymywali wiadomość e-mail z kwestionariuszem oceny wysłaną przez Trusted Shops. Jeśli dotychczas korzystasz z tego interfejsu API, interfejs API Event opracowany dla eTrusted stanowi odpowiedni w tym przypadku zamiennik. Dzięki interfejsowi API Event możesz powiązać czas wysyłania zaproszeń do wystawienia opinii z dowolnym punktem kontaktu w całym procesie zakupowym.
Aby w sposób maksymalnie przejrzysty przedstawić różnice między starymi interfejsami API ReviewCollector lub ReviewTrigger a nowym interfejsem API Event, poniżej prezentujemy obok siebie dwa przykładowe żądania API. Po lewej stronie widać przykładowe żądanie API ReviewCollector lub ReviewTrigger, po prawej stronie przykładowe żądanie API Event.
| 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, dokumentacja |
| Body |
Wyjaśnimy teraz poszczególne parametry, aby umożliwić Ci zrozumienie różnic i niezbędnych ustawień. Dowiesz się również, czym parametry obu żądań API różnią się od siebie.
|
Parametr API ReviewCollector / ReviewTrigger |
Parametr API Event | Różnice | Objaśnienie |
| tsid | channel.id |
Należy podać nowe/dalsze informacje. |
Stary parametr tsid nie jest już potrzebny w interfejsie API Event. Zamiast tego każdy z kanałów ma własny identyfikator, który należy w tym momencie przekazać. Swoje identyfikatory kanałów możesz uzyskać, wysyłając żądanie do naszego interfejsu API Get Channel. Tutaj możesz się dowiedzieć, jak dokładnie powinno wyglądać to żądanie: Channels |
| xxx | channel.type |
Nowy parametr. |
Ten parametr ma stałą wartość: „eTrusted”. |
| xxx | type |
Nowy parametr. |
Parametr typu definiuje zdarzenie, z którym powiązana jest opinia. Ponieważ wszystkie opinie w MyTS były powiązane z koszykiem klienta, wartość tego parametru jest również stała: „koszyk”. Jeśli korzystasz z interfejsu API ReviewCollector/ReviewTrigger w przypadku opinii niezwiązanych z zamówieniami i dlatego chcesz użyć innego punktu kontaktu, napisz do nas na adres productintegration@trustedshops.com. |
| reminderDate | xxx |
Parametr już nie istnieje. |
Parametr reminderDate nie jest już używany w interfejsie API Event. Oznacza to, że nie musisz go konfigurować. Konkretna data wysyłki zaproszeń jest konfigurowana w Centrum Kontrolnym eTrusted przy użyciu ustawień do zoptymalizowanego gromadzenia opinii. W tym celu przeczytaj ten artykuł: Jak mogę wysyłać do moich klientów automatyczne zaproszenia? |
| template.variant | xxx |
Parametr już nie istnieje. |
Parametr template.variant nie jest już używany w interfejsie API Event. Oznacza to, że nie musisz go konfigurować. Żądany szablon kwestionariusza jest konfigurowany w Centrum Kontrolnym eTrusted przy użyciu ustawień do zoptymalizowanego gromadzenia opinii. W tym celu przeczytaj ten artykuł: Jak mogę wysyłać do moich klientów automatyczne zaproszenia? |
| template. includeWidget |
xxx |
Parametr już nie istnieje. |
Parametr template.includeWidget nie jest już używany w interfejsie API Event. Oznacza to, że nie musisz go konfigurować. |
|
order. |
transaction. |
Parametry są równoważne. |
Parametr transaction.date przekazuje czas zamówienia, którego ma dotyczyć ocena. W tym parametrze przekaż wartość, która została wcześniej przekazana w parametrze order.orderDate. |
|
order. |
transaction. |
Parametry są równoważne. |
Parametr transaction.reference przekazuje numer zamówienia, którego ma dotyczyć ocena. W parametrze transaction.reference przekaż wartość, która została wcześniej przekazana w parametrze order.orderReference. |
|
order. |
products |
Parametry są równoważne. |
W tym parametrze przekazywane są dane wymagane do prezentowania opinii o produkcie. |
|
order. |
xxx |
Parametr już nie istnieje. |
Parametr order.currency nie jest już używany w interfejsie API Event. Oznacza to, że nie musisz go konfigurować. |
|
consumer. |
customer. |
Parametry są równoważne. |
Parametr customer.firstname przekazuje imię klienta. W tym parametrze przekaż wartość, która została wcześniej przekazana w parametrze consumer.firstname. |
|
consumer. |
customer. |
Parametry są równoważne. |
Parametr customer.lastname przekazuje nazwisko klienta. W tym parametrze przekaż wartość, która została wcześniej przekazana w parametrze consumer.lastname. |
|
consumer. |
customer. |
Parametry s�� równoważne. |
Parametr customer.email przekazuje adres e-mail klienta. W tym parametrze przekaż wartość, która została wcześniej przekazana w parametrze consumer.contact.email. |
|
xxx |
systemVersion |
Nowy parametr. |
W tym parametrze użyj różnych numerów wersji, aby móc zidentyfikować konkretne wdrożenie podczas kontaktu z działem wsparcia. |
|
xxx |
metadata |
Nowy parametr. |
Możesz użyć tego nieobowiązkowego parametru, aby podać dodatkowe informacje (np. o kliencie, zdarzeniu itp.) do celów analizy. |
Jeśli Twoje żądanie do interfejsu API Event zakończyło się sukcesem, otrzymasz odpowiedź zgodną z następującym wzorcem:
{
"Message": "Your event (`evt-xxxxxxxx-yyyy-xxxx-yyyy-xxxxxxxxxxxx`) was accepted for processing.",
"EventRef": "evt-xxxxxxxx-yyyy-xxxx-yyyy-xxxxxxxxxxxx"
}
Twój klient otrzyma wówczas zaproszenie do wystawienia opinii.