Wstęp

Connect API jest interfejsem programowym platformy Klub Klienta. Umożliwia on wdrożenie programów lojalnościowych opartych na rozwiązaniu Klub Klienta w sklepach internetowych i serwisach sprzedaży towarów i usług on-line (umownie zwanych dalej sklepami internetowymi). Interfejs eliminuje konieczność obsługi programu lojalnościowego przez fizycznego sprzedawcę przez zastąpienie go odpowiednim oprogramowaniem sklepu internetowego.

Interfejs Connect udostępnia funkcjonalność odpowiadającą panelowi sprzedawcy aplikacji mobilnej Klub Klienta Manager w poniższym zakresie:

• udostępnianie klientowi wybranych informacji o programie lojalnościowym;
• generowanie i przekazywanie klientowi punktów za dokonane zakupy;
• wysłanie kodu e-mailem do klienta w przypadku, gdy nie może go natychmiast użyć;
• potwierdzanie realizacji nagród wybranych przez klienta funkcją "Odbierz nagrodę" dostępnej w aplikacji mobilnej Klub Klienta.

Jak zacząć

Jako że interfejs Connect jest rozszerzeniem platformy Klub Klienta, w celu jego użycia należy zdefiniować program lojalnościowy w tej platformie. Analogicznie jak w przypadku wszystkich programów lojalnościowych, należy posłużyć się aplikacją mobilną Klub Klienta Manager. Przy jej użyciu należy wprowadzić firmę, dane punktu lub punktów sprzedaży, zdefiniować punkty za zakupy i katalog nagród.

Do powiązania poszczególnych punktów za zakupy oraz nagród z funkcjonalnością sklepu internetowego należy użyć odpowiednio kodów definicji punktów i kodów nagród. Służą one jako identyfikatory tych elementów w oprogramowaniu sklepu.

Użycie Connect

Connect jest usługą typu RESTful API, dostępną pod adresem https://connect.klubklienta.pl/. Poszczególne podkatalogi w adresie oznaczają odrębne moduły API.

Wywołania Connect

Podstawowy sposób wywołania Connect to metoda POST protokołu HTTP. W adresie URL są przekazane parametry wybranej funkcji w następującym formacie:

https://connect.klubklienta.pl/[moduł]/[metoda]/[parametr1]/[parametr2]…

W wywołaniach poza parametrami przekazanymi w adresie URL, wybrane metody Connect mogą też przyjmować dane POST wysłane przez klienta w formacie JSON.

Format odpowiedzi

W odpowiedzi na wywołania metod Connect zwraca dokument JSON typu application/json z kodowaniem UTF-8. W przypadku wystąpienia błędów wywołania zostanie zwrócona odpowiedź HTTP z określonym statusem HTTP oraz opisem błędu przesłanym w nagłówku oraz treści dokumentu.

Logowanie i autoryzacja

Dostęp do Connect API wymaga zalogowania. Do logowania używane są parametry dostępowe uid oraz key. Aby otrzymać dane do logowania, skontaktuj się z nami.

W procesie logowania Connect API zwraca token autoryzacyjny JWT w formacie tekstowym. Neleży go podawać w nagłówku Authorization kolejnych wywołań metod Connect:

Authorization: Bearer [token]

gdzie [token] jest tokenem JWT zwróconym przez moduł Auth w metodzie login.

Moduły Connect

Poszczególne metody Connect są opisane w działach dotyczących konkretnych modułów.

• Auth - Moduł operacji autoryzacyjnych
• Seller - Moduł sprzedawcy

Scenariusz użycia Connect

Niniejsza sekcja opisuje standardowy scenariusz operacji wykonywanych przy użyciu Connect API w sklepie, w którym wdrożono obsługę programu lojalnościowego z wykorzystaniem platformy Klub Klienta.

1. Wprowadzenie programu lojalnościowego

Jak już wspomniano wcześniej, pierwszym krokiem wdrożenia jest zdefiniowanie programu lojalnościowego w aplikacji Klub Klienta Manager. Zakładamy, że po tej operacji w systemie znajdują się co najmniej następujące dane:

• informacje o firmie będącej organizatorem programu lojalnościowego (nazwa i opis firmy oraz dane podstawowe);
• przynajmniej jeden punkt sprzedaży; jeśli sprzedaż jest prowadzona wyłącznie on-line, punkt sprzedaży należy określić np. jako "Sklep internetowy";
• przynajmniej jedna definicja punktów za zakupy, np. "50 pkt za każde wydane 100 zł"; definicja musi być w aplikacji Klub Klienta Manager oznaczona jako "Aktywne"; każda ze zdefiniowanych definicji powinna mieć wprowadzony kod, który ją identyfikuje;
• przynajmniej jedna nagroda ze statusem "Dostępna"; podobnie jak definicje punktów, każda nagroda powinna mieć wprowadzony unikalny kod.

2. Zaproszenie klienta do programu lojalnościowego

Na dowolnym etapie kontaktu klienta ze sklepem należy zaproponować mu przystąpienie do programu lojalnościowego. Można w tym celu użyć narzędzi promocji dostępnych na platformie Klub Klienta, np.:

• zamieścić w witrynie sklepu banner programu lojalnościowego;
• udostępnić odnośnik do strony informacyjnej programu informacyjnego;
• opublikować opis programu na podstronie witryny sklepu;
• wstawić kod QR z zaproszeniem do programu lojalnościowego.

3. Przydzielenie punktów w procesie sprzedaży

Po dokonaniu przez klienta zakupu oprogramowanie sklepu powinno mu przyznać punkty wynikające z zasad programu lojalnościowego. W tym celu należy wywołać metodę givePoints modułu Seller. Otrzymany kod należy wyświetlić klientowi w postaci numerycznej oraz kodu QR w celu umożliwienia mu wprowadzenia lub zeskanowania go w aplikacji Klub Klienta.

Wygenerowany kod można też:

• zachować na koncie klienta w sklepie internetowym do wykorzystania w terminie 2 tygodni, co wymaga przedłużenia jego ważności przy użyciu metody extendCode modułu Seller;
• wysłać klientowi w wiadomości e-mail wywołując metodę sendCode modułu Seller.

Klient gromadzi punkty uzyskane za zakupy w sklepie na swoim koncie w aplikacji Klub Klienta.

4. Wymiana punktów na nagrodę i realizacja nagrody

Po uzbieraniu odpowiedniej liczby punktów klient może je wymienić na nagrodę. Odbywa się to w aplikacji mobilnej Klub Klienta. Po tej czynności z konta punktowego odejmowane są punkty w liczbie równej wartości punktowej wybranej nagrody. Nagroda jest od tej pory widoczna a aplikacji klienta.

Nagroda może zostać zrealizowana w trakcie kolejnych zakupów w sklepie internetowym. W tym celu klient w aplikacji Klub Klienta klika w nagrodę i wybiera opcję "Odbierz", co skutkuje wygenerowaniem i wyświetleniem klientowi kodu odbioru nagrody. Oprogramowanie sklepu powinno umożliwić klientowi wprowadzenie tego kodu w trakcie dokonywania zakupów.

Wprowadzony kod odbioru nagrody należy zweryfikować wywołując metodę checkCode modułu Seller. Otrzymany z metody rezultat służy do zweryfikowania, czy oprogramowanie w bieżącym kontekście może zrealizować nagrodę (np. udzielić rabatu na zakupy).

Po pozytywnej weryfikacji kodu należy klientowi wyświetlić informacje potwierdzające realizację wybranej nagrody w sklepie. Następnie klient powinien zaakceptować realizację nagrody.

Po akceptacji klienta oprogramowanie sklepu wywołuje metodę confirmCode modułu Seller i realizuje nagrodę w sklepie. Skutkiem wywołania metody confirmCode jest usunięcie nagrody z konta klienta i wyświetlenie mu odpowiedniego komunikatu w aplikacji Klub Klienta.