Podręcznik integracyjny Trusted Shops

Podręcznik integracyjny Trusted Shops Znak jakości, ochrona kupującego EXCELLENCE Wersja 2.0 pl-pl 2015 Trusted Shops GmbH

Spis treści 1. Znak Jakości Trusted Shops z ochroną kupującego EXCELLENCE... 3 1.1 Ochrona Kupującego Trusted Shops EXCELLENCE... 3 1.2 Usługa Web Service Trusted Shops na zawarcie ochrony kupującego... 5 1.3 Obsługa błędów... 9 1.4 Integracja Ochrony Kupującego we frontendzie sklepu... 11 1.5 Widget ze znakiem jakości Trusted Shops... 12 2. Wsparcie techniczne... 12 2015 Trusted Shops GmbH 2

1. Znak Jakości Trusted Shops z ochroną kupującego EXCELLENCE 1.1 Ochrona Kupującego Trusted Shops EXCELLENCE 1.1.1 Sposób funkcjonowania Opcja zawarcia gwarancji Ochrony Kupującego Trusted Shops jest wyświetlana w logo ochrony kupującego przy wyborze sposobu płatności w kasie. Kupujący może aktywować lub dezaktywować ochronę kupującego w sklepie za pomocą pola wyboru. Jeśli klient wybierze Ochronę Kupującego Trusted Shops, zostanie ona dodana do zamówienia jako produkt. Standardowo pole wyboru jest wyłączone, także w przypadku, gdy klient opuścił daną stronę internetową i znów na nią powraca, przykładowo, aby dodać do koszyka więcej produktów. W zależności od wartości koszyka (wartość artykułów i koszty wysyłki) należy wyświetlić odpowiedni produkt Ochrony Kupującego Trusted Shops. Jako odpowiedni uważa się najmniejszy produkt Trusted Shops, który całkowicie zabezpiecza zakup (np. Przy zakupie o wartości 600 PLN za produkt "Ochrona Kupującego Trusted Shops do 1.500 PLN"). Na stronie z przeglądem zamówienia, cena produktu ochrony kupującego jest wliczana do ceny końcowej wraz z zamówionymi artykułami oraz kosztami wysyłki. Po potwierdzeniu zamówienia, usługa internetowa Ochrony Kupującego Trusted Shops zostaje wywołana metodą requestforprotectionv2() za pomocą odpowiednich parametrów. Po krótkim czasie wywołanie getrequeststate() sprawdza, czy przyjęto umowę gwarancyjną Trusted Shops. Gwarancja jest następnie rezerwowana w systemie Trusted Shops i klient zostaje o tym poinformowany za pomocą wiadomości e-mail. Zawarte gwarancje można zobaczyć w strefie dla członków pod adresem https://www.trustedshops.com/de/shop/login.html. Sprzedawca internetowy jest zobowiązany zapewnić, że zapytania o ochronę kupującego przejdą pomyślnie przez interfejs i gwarancje zostaną pomyślnie zawarte. 1.1.2 Schemat procesu w sklepie Ochrona Kupującego Trusted Shops jest oferowana w kasie wraz z wyborem sposobu płatności. Rys. 1: Schematyczne przedstawienie Ochrony Kupującego Trusted Shops w wariancie EXCELLENCE 2015 Trusted Shops GmbH 3

1.1.3 Proces techniczny Rys. 2: Proces techniczny Ochrony Kupującego Trusted Shops w wariancie EXCELLENCE 1.1.4 Właściwości i obliczanie ceny produktów ochrony kupującego Umowa o Ochronę Kupującego Trusted Shops zostaje zawarta, gdy podczas procesu składania zamówienia do koszyka zostanie dodany produkt ochrony kupującego. Opis produktów ochrony kupującego zawiera zawsze maksymalną wartość zabezpieczenia oraz czas trwania zabezpieczenia. Produkt TS100809_500_30_PLN wskazuje np. Na ochronę kupującego do wartości 500 PLN z okresem gwarancyjny wynoszącym 30 dni. Proszę zapisać następujące produkty Ochrony Kupującego Trusted Shops w sklepie, jeśli nie przekazano Państwu innych produktów. ID produktu Trusted Shops (tsproductid) Cena netto TS100809_500_30_PLN TS100809_1500_30_PLN TS100809_2500_30_PLN TS100809_5000_30_PLN TS100809_10000_30_PLN TS100816_20000_30_PLN 1,62 PLN 2,43 PLN 4,06 PLN 8,12 PLN 16,25 PLN 32,51 PLN Dla produktów ochrony kupującego obowiązują następujące reguły: Produkty Ochrony Kupującego Trusted Shops są zapisywane w sklepie lub bazie danych, ale nie są wyświetlane w normalnym katalogu produktów w sklepie. Produkty ochrony kupującego można zarezerwować wyłącznie w kasie. Produkty ochrony kupującego są dostępne bez ograniczeń. W koszyku może znajdować się maksymalnie jeden produkt ochrony kupującego. Produkty ochrony kupującego zawsze zapisywane są z ceną netto. 2015 Trusted Shops GmbH 4

Do ceny produktów ochrony kupującego należy doliczyć stawkę podatkową, do której przyporządkowana jest całość usługi. Jeśli produkty podlegają jednolitej stawce podatkowej, stawka ta jest decydująca. W przypadku koszyków, w których stosowane są różne stawki podatkowe, zalecamy skorzystanie z wyższej stawki podatkowej. Szczegóły należy omówić indywidualnie z Państwa doradcą podatkowym. Cena produktów ochrony kupującego jest wyświetlana odpowiednio dla pozostałych cen produktów, czyli jako cena brutto w handlu B2C oraz jako cena netto w handlu B2B. Cena produktów Ochrony Kupującego Trusted Shops podwyższa całkowitą kwotę rachunku za zakup. Umowa o Ochronę Kupującego Trusted Shops zabezpiecza jednakże wyłącznie zamówione artykuły i powiązane z nimi usługi transportowe; ochrona kupującego nie zabezpiecza zatem samej siebie. Ewentualne rabaty nie obejmują produktów ochrony kupującego. W następującym przykładzie kwota rachunku wynosi 196.99 PLN; wniosek o Ochronę Kupującego Trusted Shops zostaje złożony na kwotę 195.00 PLN: Przykładowa faktura (z VAT): Produkt 1 Produkt 2 Rabat przy danej metodzie płatności 5% Koszty przesyłki Ochrona Kupującego Trusted Shops do 500 PLN Kwota rachunku 150.00 PLN 50.00 PLN - 10.00 PLN 5.00 PLN 1.99 PLN 196.99 PLN 1.1.5 Zarządzanie certyfikatami Trusted Shops Certyfikat Trusted Shops jest identyfikowany za pomocą klucza alfanumerycznego o długości 33 znaków ID Trusted Shops (TS-ID). Identyfikator Trusted Shops jest przekazywany sprzedawcy internetowemu po dokonaniu rejestracji w Trusted Shops. Identyfikator Trusted Shops obowiązuje zawsze tylko dla jednego adresu URL sklepu w jednym języku. Jeśli w systemie sklepu istnieje kilka sklepów online lub więcej wersji językowych sklepu, każdej wersji przypisuje się własny identyfikator Trusted Shops. Każdemu certyfikatowi Trusted Shops przydziela się login do usług internetowych (WSLogin), za pomocą którego składa się wniosek o ochronę kupującego. 1.2 Usługa Web Service Trusted Shops na zawarcie ochrony kupującego Usługa Web Service dla frontendu sklepu dysponuje dwoma metodami zawierania i sprawdzania umowy o ochronę kupującego. Usługa Web Service do zawierania umowy o ochronę kupującego jest dostępna w Trusted Shops za pomocą następujących URI. (auch im Deutschen Absatz löschen??) Usługa Web Service URI w środowisku testowym ("Sandbox") https://protectionqa.trustedshops.com/ts/protectionservices/applicationrequestservice?wsdl Usługa Web Service URI w środowisku produkcyjnym https://protection.trustedshops.com/ts/protectionservices/applicationreques tservice?wsdl 1.2.1 requestforprotectionv2() Metoda requestforprotectionv2() jest funkcją główną w procesie zawierania gwarancji ochrony kupującego. Wymagane do transakcji dane dotyczące zakupu zostają przekazane do Trusted Shops, usługa Web Service tworzy wniosek o ochronę kupującego. Wnioski są sprawdzane przez Trusted Shops pod kątem ważności formalnej, zapisywane i przetwarzane w regularnych odstępach czasowych. 2015 Trusted Shops GmbH 5

Prosimy uwzględnić także informacje o obsłudze błędów, aby upewnić się, że wszystkie wnioski o ochronę kupującego pomyślnie przeszły przez interfejs. 1.2.1.1 Nazwy i rodzaje danych Definicja WSDL: <message name="applicationrequestservice_requestforprotectionv2"> <part name="tsid" type="xsd:string"/> <part name="tsproductid" type="xsd:string"/> <part name="amount" type="xsd:decimal"/> <part name="currency" type="xsd:string"/> <part name="paymenttype" type="xsd:string"/> <part name="buyeremail" type="xsd:string"/> <part name="shopcustomerid" type="xsd:string"/> <part name="shoporderid" type="xsd:string"/> <part name="orderdate" type="xsd:datetime"/> <part name="shopsystemversion" type="xsd:string"/> <part name="wsuser" type="xsd:string"/> <part name="wspassword" type="xsd:string"/> </message> 1.2.1.2 Parametry Parametr Opis Komentarz tsid tsproductid amount currency paymenttype ID certyfikatu Trusted Shops Kod produktu ochrony kupującego Kwota rachunku łącznie z kosztami przesyłki Waluta zakupu, ISO 4217 3- literowa stała metody płatności buyeremail Adres e-mail kupującego Obowiązkowe shopcustomerid Nr klienta shoporderid Nr zamówienia Obowiązkowe orderdate Data zamówienia w sklepie online Obowiązkowe, jest przydzielane przez Trusted Shops dla każdego certyfikatu; każdy język sklepu i każdy oddzielny sklep w tzw. "rozwiązaniu dla wielu sklepów" wymaga posiadania własnego certyfikatu. Obowiązkowe, patrz tabela produkty ochrony kupującego Obowiązkowe, formatowanie za pomocą kropki znaku dziesiętnego, dwa miejsca po przecinku (np. 3130.47) Obowiązkowe, np. Kod ISO dla Euro = EUR Obowiązkowe, specyficzne dla Trusted Shops patrz wykaz dostępnych metod płatności Obowiązkowe, jeśli nie przydzielono umieścić wartość stałą "0" Obowiązkowe, Format: 2011-10-31T09:30:00 shopsystemversion Wersja oprogramowania Obowiązkowo, dowolny łańcuch 2015 Trusted Shops GmbH 6

wsuser wspassword sklepu i ewentualnie modułu Trusted Shops: topshop v2.1 Użytkownik usługi Web Service Hasło usługi Web Service znaków Obowiązkowe, przydzielane przez Trusted Shops osobno dla każdego certyfikatu Obowiązkowe, przydzielane przez Trusted Shops osobno dla każdego certyfikatu 1.2.1.3 Wartość zwrotna Pozytywna wartość zwrotna oznacza, że wniosek o usługę Web Service został pomyślnie przetworzony; wartość odpowiada numerowi wniosku o ochronę kupującego. Negatywna wartość zwrotna wskazuje na błąd; wartość reprezentuje kod błędu. 1.2.1.4 Przykład kodu (PHP) Następujący tekst opisuje przykład wywołania interfejsu ochrony kupującego, po zakończeniu zamówienia przez klienta końcowego. Wymagane jest rozszerzenie pliku PHP 5 SOAP. Zaznaczone fragmenty należy dopasować. Przykład kodu źródłowego PHP (należy zastąpić tekst zaznaczony na żółto): define("soap_error", -1); define("ts_server", "protection.trustedshops.com"); # Collect parameters for the webservice call # TS-ID received by Trusted Shops $tsid = "X1234567890ABCDEFGHJKLMNOPQRSTUVW"; # Defined by Trusted Shops, depends on order total amount $tsproductid = "TS100809_500_30_PLN"; $orderdate = date("y-m-d", time()). "T". date("h:i:s", time()); $shopsystemversion = "Shop 4.0 TS.01"; # Collect other parameters $decimalamount = (double) $amount; # # Call TS protection webservice $ini = ini_set("soap.wsdl_cache_enabled", 1); try { $wsdlurl = "https://". TS_SERVER. "/ts/protectionservices/applicationrequestservice?wsdl"; $client = new SoapClient($wsdlUrl); # Set return value for the case if a SOAP exception occurs $returnvalue = SOAP_ERROR; # call WS method $returnvalue = $client-> requestforprotectionv2 ($tsid, $tsproductid, (double)$amount, $currency, $paymenttype, $buyeremail, $shopcustomerid, $shoporderid, $orderdate, $shopsystemversion, $wsuser, $wspassword); } catch (SoapFault $fault) { $errortext = "SOAP Fault: (faultcode: {$fault->faultcode}, faultstring: {$fault- >faultstring})"; echo $errortext; } # Check return value # Negative return value is an error code, positive value is the application number if ($returnvalue == SOAP_ERROR) { echo "SOAP error: $errortext"; 2015 Trusted Shops GmbH 7

} else if ($returnvalue < 0) { error_log "TS Webservice returns error code $returnvalue"; switch ($returnvalue) { case -10001 : echo "Cause: login failed or no valid shop found for tsid '$tsid'"; break; } } else { echo "TS Webservice has successfully returned application number '$returnvalue'"; } 1.2.1.5 Sposoby płatności Przy zawieraniu gwarancji Ochrony Kupującego Trusted Shops metoda płatności wybrana przez klienta jest przekazywana do Trusted Shops. Prosimy o przyporządkowanie metod płatności używanych w sklepie metodom płatności wspieranym przez Trusted Shops. Kod DIRECT_DEBIT CREDIT_CARD INVOICE CASH_ON_DELIVERY PREPAYMENT CHEQUE PAYBOX PAYPAL AMAZON_PAYMENTS CASH_ON_PICKUP FINANCING LEASING T_PAY CLICKANDBUY GIROPAY GOOGLE_CHECKOUT SHOP_CARD DIRECT_E_BANKING MONEYBOOKERS DOTPAY PL polecenie zapłaty karta kredytowa faktura gotówką przy dostawie Przelew Czek Paybox PayPal Amazon Payments Gotówką przy odbiorze Finansowanie Leasing T-Pay Click&Buy Giropay Google Checkout Karta sklepu Bezpośrednio przez e-banking moneybookers.com Dotpay 2015 Trusted Shops GmbH 8

PLATNOSCI PRZELEWY24 OTHER Płatności Przelewy24 Inne 1.2.2 getrequeststate() Za pomocą metody getrequeststate() wyszukuje się status wniosku o gwarancję i w przypadku pomyślnego zaksięgowania zwracany jest numer gwarancji. Pozytywna wartość zwrotna requestforprotectionv2() oznacza, że wniosek o ochronę kupującego został pomyślnie przekazany i znajduje się w kolejce wiadomości w Trusted Shops. Błędy semantyczne (np. brakujący lub podwójny numer zamówienia) są rozpoznawane dopiero podczas przetwarzania wniosku. Poprzez wywołanie getrequeststate() sprawdza się zatem, czy za pomocą requestforprotectionv2() złożone wnioski o gwarancję zostały przyjęte przez Trusted Shops, ponieważ tylko z pomyślnie przetworzonego wniosku powstaje gwarancja Trusted Shops. Trusted Shops zaleca, aby wywołanie zautomatyzować za pomocą cronjob z interwałem co 10 minut. Ponieważ postawienie wniosku o ochronę kupującego w sklepie nie jest jednoczesne z potwierdzeniem przez Trusted Shops, lecz przebiega z przesunięciem czasowym, należy przeprowadzić obsługę błędów. W przypadku przerw w Trusted Shops lub wyjątków SOAP w terminie do 3 dni można ponownie wysłać gwarancję (z naprawionymi danymi transakcji). 1.2.2.1 Nazwy i rodzaje danych Definicja WSDL: <message name="applicationrequestservice_getrequeststate"> <part name="tsid" type="xsd:string"/> <part name="applicationid" type="xsd:long"/> </message> 1.2.2.2 Parametry Parametr Opis Komentarz tsid applicationid ID Trusted Shops dla certyfikatu Numer wniosku o ochronę kupującego Obowiązkowe, jest przydzielane przez Trusted Shops dla każdego certyfikatu; każdy język sklepu i każdy oddzielny sklep w tzw. "rozwiązaniu dla wielu sklepów" wymaga certyfikatu. Obowiązkowe, wartość zwrotna requestforprotectionv2() 1.2.2.3 Wartości zwrotne Pozytywna wartość zwrotna oznacza, że wniosek o usługę internetową został pomyślnie przetworzony, wartość odpowiada numerowi gwarancji. Negatywna wartość zwrotna wskazuje na błąd, wartość reprezentuje kod błędu. 1.3 Obsługa błędów Podczas fazy integracyjnej oraz startu produkcyjnego prosimy o protokołowanie kodów błędów i wyjątków SOAP, aby wcześnie rozpoznać błędy konfiguracyjne lub błędy wdrożenia. W związku z ewentualnie występującymi błędami lub przy braku dostępności strony internetowej Trusted Shops obsługa błędów gwarantuje, że każdy wniosek o ochronę kupującego zostanie dostarczony do Trusted Shops. Sprzedawca internetowy jest odpowiedzialny za przekazanie każdego wniosku 2015 Trusted Shops GmbH 9

o ochronę kupującego do Trusted Shops. Wnioski o ochronę kupującego można powtórzyć w ciągu trzech dni z poprawionymi danymi. Aktualny status gwarancji jest sprawdzany za pomocą metody getrequeststate(). Funkcja Opis Komentarz Obsługa kolejki Protokołowanie 1.3.1 Kody błędów Zapisywanie i przetwarzanie wniosków o gwarancję Rejestracja wniosków o gwarancje, kodów błędów, wyjątków SOAP, itd. Obowiązkowe, np. za pomocą retry maksimum 3 razy z interwałem co 8 godzin, potem przerwanie Obowiązkowe, np. w formie listy zadań zawartych gwarancji na pulpicie w administracji sklepu Kod Wartośc zwrotna Przyczyna -10001 NO_VALID_SHOP Nieważny login do usługi internetowej lub ID-TS -10002 LIMIT_CANCELLED Trusted Shops unieważnił linię gwarancyjną sklepu -10003 DUPLICATE_ORDER_NUMBER Wielokrotnie użyty numer zamówienia -10004 UNSUPPORTED_TS_PRODUCT Nieobsługiwany produkt ochrony kupującego -10005 INACTIVE_PAYMENT_TYPE Nieaktywna metoda płatności -10006 UNSUPPORTED_PAYMENT_TYPE Nieobsługiwana metoda płatności -10007 CURRENCY_MISMATCH Waluta produktu ochrony kupującego nie odpowiada walucie w koszyku -10008 UNSUPPORTED_CURRENCY Wybrana waluta nie jest obsługiwana w tym sklepie -10009 UNSUPPORTED_EXCHANGE_RATE Kurs wymiany waluty nie jest obsługiwany -10010 NOT_PERSISTENT_PAYMENT_TYPE Nieobsługiwana metoda płatności -10011 NO_LIMIT Brak linii gwarancyjnej dla danego certyfikatu -10012 PAST_DELIVERY_DATE Data dostawy jest w przeszłości -10013 TOO_OLD_ORDER Złożono wniosek o gwarancję dla zamówienia starszego niż trzy dni -10014 EMAIL_MALFORMED Błędny format adresu e-mail -10015 ORDER_ID_EMPTY Nie przekazano żadnego numeru zamówienia -10016 CUSTOMER_ID_EMPTY Nie przekazano żadnego numeru klienta -10017 LIMIT_OVERFLOW Linia gwarancyjna dla danego certyfikatu została przekroczona -10018 EMAIL_EMPTY Nie przekazano żadnego adresu e-mail 1.3.2 Typowe wyjątki SOAP Podczas fazy wdrożeniowej i funkcjonowania mogą pojawić się wyjątki SOAP. Typowe błędy wyjątków mają następujące przyczyny: Błąd Przyczyna 2015 Trusted Shops GmbH 10

Invalid number of payload elements: 12 Error code: env:server java.lang.numberformatexception Date value does not follow the format... String index out of range: 0 Sprawdzić ilość i kolejność przekazanych parametrów nieważna kwota pieniężna nieważna data pusta data 1.3.3 Dane do logowania do środowiska testowego Dane do logowania do środowiska produkcyjnego zostaną przesłane do Państwa w momencie aktywacji przez Trusted Shops. Podczas fazy implementacji należy użyć następujących danych do logowania: Dane do logowania do środowiska testowego: ID Trusted Shops XD1200DB48E44EF913BF04398A194ECB8 Nazwa użytkownika (wsuser): testexcellencepartnerpl Hasło (wspassword): test12345678 1.4 Integracja Ochrony Kupującego we frontendzie sklepu 1.4.1 Pozycja logo Ochrony Kupującego Trusted Shops Logo Ochrony Kupującego Trusted Shops należy umieścić w dobrze widocznym miejscu przy wyborze metody płatności w kasie. 1.4.2 Teksty w logo Ochrony Kupującego Trusted Shops Rys. 3: Przykład logo Ochrony Kupującego w wariancie EXCELLENCE W logo ochrony kupującego dla każdego języka sklepu używane są następujące teksty. Informacja o zawartym podatku od obrotów przebiega zwykle bez podania stawki podatkowej, czyli z dodatkiem "łącznie z podatkiem VAT (lub bez podatku VAT w handlu B2B). Specyficzny tekst dla danego kraju dla języka PL (zastąpić tekst zaznaczony na żółto): [ ] Ochrona Kupującego Trusted Shops (zalecana) Ochrona Kupującego do 500 PLN (1,99 PLN z VAT) Ochrona Kupującego Trusted Shops zabezpiecza Twoje zakupy internetowe. Wyrażam zgodę na przekazywanie i zapisywanie mojego adresu e-mail przez Trusted Shops w celu realizacji usługi Ochrony Kupującego. Warunki gwarancji dla Ochrony Kupującego. 1.4.3 Zalinkowanie logo ochrony kupującego Logo Trusted Shops oraz zaznaczone na żółto elementy należy zalinkować niezależnie od wersji językowej. Parametr shop_id odpowiada ID Trusted Shops dla certyfikatu. Dla linków należy użyć odpowiedniego parametru linka target= _blank, który otwiera stronę w nowym oknie lub nowej karcie przeglądarki. 2015 Trusted Shops GmbH 11

Logo URL linku dla Znaku Jakości Trusted Shops (zastąpić tekst zaznaczony na żółto): https://www.trustedshops.com/shop/certificate.php?shop_id=shop_id Link URL Link "Zapisywanie (zastąpić tekst zaznaczony na żółto): http://www.trustedshops.com/shop/data_privacy.php?shop_id=shop_id Link URL "Warunki gwarancji" (zastąpić tekst zaznaczony na żółto): http://www.trustedshops.com/shop/protection_conditions.php?shop_id=shop_id 1.5 Widget ze znakiem jakości Trusted Shops Firma Trusted Shops opracowała nowoczesną metodę integracji (tzw. trustbadge), która umożliwia członkom Trusted Shops jeszcze skuteczniejsze komunikowanie swojej wiarygodności i prezentację znaku jakości Trusted Shops w przyciągający uwagę sposób. Zachęcamy do odwiedzenia strony http://www.trustedshops.pl/handlowcy/integracja/trustbadge.html, na której można wygenerować kod trustbadge oraz zapoznać się z informacjami na temat sposobu jego integracji ze stroną sklepu. Na stronie dostępna jest także funkcja podglądu, dzięki której możliwe jest przetestowanie różnych wariantów trustbadge'a z uwzględnieniem oryginalnego układu graficznego strony danego sklepu. URL strony z informacjami o integracji trustbadge: http://www.trustedshops.pl/handlowcy/integracja/trustbadge.html 2. Wsparcie techniczne W razie pytań związanych z integracją Znaku Jakości Trusted Shops,ochrony kupującego lub systemem opinii o sklepie prosimy o kontakt z: Trusted Shops GmbH Serwis e-mail: members@trustedshops.pl 2015 Trusted Shops GmbH 12