InPost Pay - Magento (Widget 2.0)
Wstęp
Niniejsza instrukcja przedstawia proces instalacji oraz konfiguracji wtyczki, umożliwiającej wprowadzenie InPost Pay w sklepie Magento z obsługą Widget 2.0.
Wtyczka 2.0.4 (31.01.2025 r.)
Magento Community Edition
Commerce Edition
Changelog
Na tej stronie:
- 1 Wstęp
- 1.1 Changelog
- 2 Wymagania Systemowe
- 3 Konfiguracja dla Widget 2.0
- 3.1 Mapowanie Metod Dostawy
- 3.2 Ogólne Ustawienia
- 3.3 Sandbox
- 3.4 Ustawienia Autoryzacji
- 3.5 Ustawienia Debuggowania
- 3.6 Ustawienia IZI API
- 3.7 Mapowanie zgód
- 3.8 Ustawienia wyświetlania
- 3.9 Ustawienia układu przycisków
- 3.10 Ustawienia Cache
- 3.11 Instalacja modułu - dodatkowe informacje
- 3.12 Ustawienia odpytywania Long Polling
- 3.13 Ustawienia Restrykcji
- 3.14 Ustawienia Omnibus
- 3.15 Dostępne promocje w aplikacji
- 3.16 Udostępnienie logów InPost Pay
- 4 Instrukcja użytkowania
- 5 Dokumentacja Techniczna - backend
- 5.1 Weryfikacja Sygnatury
- 5.2 Connector API
- 5.3 Interfejs Żądań do API InPost
- 5.4 Obsługa żądań do API InPost i formatowanie odpowiedzi
- 5.5 Relacja pomiędzy oficjalną wtyczką Smartmage_Inpost a InPost_InPostPay
- 5.6 Debuggowanie
- 5.7 Kontrolery frontowe 2.0
- 5.8 Implementacje REST API Magento
- 5.9 Proces Tworzenia Zamówienia
- 5.10 Obiekty zwracane przez API Magento
- 5.11 Modyfikacje indywidualne pod Merchanta
- 5.12 Moduł Restrykcji
- 5.13 Czyszczenie atrybutów tekstowych z HTML i znaków specjalnych
- 5.14 Ograniczenie dostaw tylko do PL
- 5.15 Produkty bundle
- 5.16 Generowanie Sygnatury dla zwrotów
- 5.17 Zmiany w Widget v 2.0
Wymagania Systemowe
Do poprawnego działania wtyczki InPost_InPostPay wymagane jest spełnienie następujących kryteriów serwerowych:
Magento 2 Community Edition (Open Source) w wersji >=2.4.6
PHP w wersji >=8.2
Composer w wersji >=2.2
oraz wszelkie wymagania narzucane przez Adobe dla zainstalowanej wersji Magento:
System requirements | Adobe Commerce
Opcjonalne funkcjonalności:
Domyślnie - aktualizacje koszyka inicjowane po stronie klienta w przeglądarce wysyłane są synchronicznie na serwer API InPost Pay.
Wtyczka pozwala na skonfigurowanie wysyłki tych danych w sposób asynchroniczny z wykorzystaniem wbudowanego w Magento mechanizmu kolejek opartych o MySQL. Wymaganiem jest poprawne skonfigurowanie CRON aby uruchamiany był proces consumera. Konfigurując uruchamianie procesu consumer’a należy kierować się dokumentacją (Manage message queues | Adobe Commerce ) lub wykorzystać narzędzia typu Supervisord (https://supervisord.readthedocs.io/en/latest/)
Konfiguracja dla Widget 2.0
W tej sekcji dokumentacji zawarta została instrukcja konfiguracji wraz z opisami poszczególnych komponentów wtyczki InPost Pay dedykowanej dla platformy Magento 2.
Mapowanie Metod Dostawy
Ścieżka konfiguracji:
Store->Configuration->Sales->Payment Methods->InPost Pay->Mapowanie Metod Dostawy
Opis pól konfigurowalnych:
Standard Pickup Point Delivery | Konfiguracja pozwalająca na przypisanie metody dostawy odpowiadającej standardowej opcji wysyłki poprzez urządzenie Paczkomat 24/7 InPost w aplikacji Mobilnej InPost Pay |
Pickup Point Weekend Delivery | Konfiguracja pozwalająca na przypisanie metody dostawy odpowiadającej weekendowej opcji wysyłki poprzez urządzenie Paczkomat 24/7 InPost w aplikacji Mobilnej InPost Pay. Uwaga: W aplikacji Mobilnej zmapowana metoda dostawy pokazuje się jako checkbox z dodatkową opłatą będącą wyliczoną różnicą pomiędzy tą przypisaną metodą dostawy, a opcją standardową. |
Pickup Point Delivery - Cash on Delivery | Konfiguracja pozwalająca na przypisanie metody dostawy odpowiadającej opcji wysyłki z płatnością przy odbiorze poprzez urządzenie Paczkomat 24/7 InPost w aplikacji Mobilnej InPost Pay. Uwaga: W aplikacji Mobilnej zmapowana metoda dostawy pokazuje się jako forma płatności (nie dostawy) z dodatkową opłatą będącą wyliczoną różnicą pomiędzy tą przypisaną metodą dostawy, a opcją standardową. |
Pickup Point Weekend Delivery - Cash on Delivery | Konfiguracja pozwalająca na przypisanie metody dostawy odpowiadającej opcji wysyłki z płatnością przy odbiorze w weekend poprzez urządzenie Paczkomat 24/7 InPost w aplikacji Mobilnej InPost Pay. Uwaga: W aplikacji Mobilnej zmapowana metoda dostawy pokazuje się zarówno jako checkbox oraz forma płatności (nie dostawy) z dodatkową opłatą będącą wyliczoną różnicą pomiędzy tą przypisaną metodą dostawy, a opcją standardową. Aby zamówić towar w tej formie klient musi wybrać Standardowy Paczkomat 24/7, zaznaczyć opcję Paczki w Weekend oraz wybrać płatność przy odbiorze. Przykładowo: Skonfigurowanie tej opcji dostawy z cenami bez zgodności spowoduje odrzucenie zamówienia klienta złożonego poprzez aplikację mobilną ze względu na błędną kwotę całościową. |
Standard Courier Delivery | Konfiguracja pozwalająca na przypisanie metody dostawy odpowiadającej Kurierowi InPost w aplikacji Mobilnej InPost Pay. |
Weekend Courier Delivery | Konfiguracja pozwalająca na przypisanie metody dostawy odpowiadającej weekendowej opcji wysyłki poprzez Kuriera InPost w aplikacji Mobilnej InPost Pay. Uwaga: W aplikacji Mobilnej zmapowana metoda dostawy pokazuje się jako checkbox z dodatkową opłatą będącą wyliczoną różnicą pomiędzy tą przypisaną metodą dostawy, a opcją standardową. |
Cash on Delivery Courier | Konfiguracja pozwalająca na przypisanie metody dostawy odpowiadającej opcji wysyłki z płatnością przy odbiorze poprzez Kuriera InPost w aplikacji Mobilnej InPost Pay. Uwaga: W aplikacji Mobilnej zmapowana metoda dostawy pokazuje się jako forma płatności (nie dostawy) z dodatkową opłatą będącą wyliczoną różnicą pomiędzy tą przypisaną metodą dostawy, a opcją standardową. |
Cash on Delivery Courier | Konfiguracja pozwalająca na przypisanie metody dostawy odpowiadającej opcji wysyłki z płatnością przy odbiorze w weekend poprzez Kuriera InPost w aplikacji Mobilnej InPost Pay. Uwaga: W aplikacji Mobilnej zmapowana metoda dostawy pokazuje się zarówno jako checkbox oraz forma płatności (nie dostawy) z dodatkową opłatą będącą wyliczoną różnicą pomiędzy tą przypisaną metodą dostawy, a opcją standardową. Aby zamówić towar w tej formie klient musi wybrać Standardowego Kuriera InPost, zaznaczyć opcję Paczki w Weekend oraz wybrać płatność przy odbiorze. Przykładowo: Skonfigurowanie tej opcji dostawy z cenami bez zgodności spowoduje odrzucenie zamówienia klienta złożonego poprzez aplikację mobilną ze względu na błędną kwotę całościową. |
Delivery Deadline In Days | Wymagana wartość liczbowa potrzebna do wyliczenia maksymalnej daty dostawy. |
Widok konfiguracji:
Ogólne Ustawienia
Ścieżka konfiguracji:
Store->Configuration->Sales->Payment Methods->InPost Pay->Ustawienia Ogólne
Opis pól konfigurowalnych:
Włącz InPost Pay | Umożliwia włączenie lub wyłączenie tej formy płatności. |
Włącz Tryb Testowy | Tryb testowy służy przede wszystkim do testowania produkcji tuż przed globalnym uruchomieniem z prawdziwym zamówieniem oraz płatnością. Włączenie trybu testowego działa tylko przy wyłączonym trybie sandbox. Po włączeniu tej opcji (gdy tryb sandbox jest wyłączony) widget InPost Pay będzie widoczny tylko na stronach gdzie adres URL zawiera parametr: Umożliwia to testowe przeprowadzenie całego zakupu na środowisku produkcyjnym łącznie z opłaceniem zamówienia wykorzystując produkcyjną aplikację InPost Pay na mobilne urządzenia, w taki sposób, aby klienci nie widzieli jeszcze tej funkcjonalności. Po weryfikacji środowiska należy wyłączyć tryb testowy równocześnie. |
Tytuł | Nazwa wyświetlana dla tej formy płatności. |
Status Nowego Zamówienia | Status jaki jest ustawiany gdy zamówienie zostanie utworzone z wykorzystaniem tej formy płatności. |
Akceptacja Płatności z Krajów | Czy płatności mają być akceptowane ze wszystkich krajów, czy z wybranych. |
Akceptacja Płatności z Wymienionych Krajów | Lista krajów używana jeśli w polu Akceptacja Płatności z Krajów zaznaczono akceptacje płatności z wybranych krajów. |
Minimalna Wartość Zamówienia | Minimalna kwota zamówienia dla tej formy płatności |
Maksymalna Wartość Zamówienia | Maksymalna kwota zamówienia dla tej formy płatności. |
Użyj imienia i nazwiska z adresu zamiast imienia i nazwiska klienta | Umożliwia przesyłanie imienia i nazwiska z adresu zamiast imienia i nazwiska klienta do InPost Pay |
Rola obrazu wysyłana do InPost Pay | Lista rozwijana do wyboru który obraz powinien być przesyłany do InPost Pay |
Przypisz Koszyk do Klient po Adresie Email | Domyślna wartość TAK. Jeśli ta konfiguracja jest włączona, koszyki w Sklepie założone przez użytkowników niezalogowanych, powiązane z InPost Pay, w trakcie procesowania zamówienia zostaną przypisane do konta klienta w Magento, o ile takie istnieje, na podstawie adresu mailowego konta w Aplikacji InPost Pay. Jeśli ta konfiguracja jest wyłączona, koszyki w Sklepie założone przez użytkowników niezalogowanych, powiązane z InPost Pay, pozostaną zamówieniami gości nawet jeśli w Sklepie będzie istnieć konto o adresie email takim samym jakie zostało użyte przez klienta w Aplikacji InPost Pay. Powyższa konfiguracja nie ma wpływu na koszyki założone przez zalogowanych klientów Sklepu. Zamówienia z nich złożone bez względu na to ustawienie będą przypisane do konta użytkownika zalogowanego w Sklepie. |
Widok konfiguracji:
Sandbox
Ścieżka konfiguracji:
Store->Configuration->Sales->Payment Methods->InPost Pay->Sandbox
Opis pól konfigurowalnych:
Przełącz InPost Pay w Tryb Sandbox | Konfiguracja umożliwiająca włączenie trybu testowego Sandbox. |
Sandbox Client ID | Identyfikator klienta otrzymany z od InPost używany do autoryzacji w trybie Sandbox. |
Sandbox Client Secret | Wartość Client Secret otrzymana od InPost używana do autoryzacji w trybie Sandbox. |
Sandbox Auth Token URL | Bazowy adres URL InPost, pod którym dokonywana będzie autoryzacja w trybie Sandbox w celu pobrania tokena używanego w dalszej komunikacji z API. |
Sandbox Merchant Secret | Wartość Merchant Secret otrzymana od InPost, potrzebna do tworzenia zwrotów w trybie Sandbox. |
Sandbox POS ID | Identyfikator nadany przez InPost do trybu Sandbox |
Sandbox IZI API URL | Bazowy adres URL InPost, pod którym realizowana będzie integracja koszyka i zamówień w trybie Sandbox. |
Sandbox Client Merchant ID | ID Merchanta nadany przez InPost do trybu Sandbox. |
Widok konfiguracji:
Ustawienia Autoryzacji
Ścieżka konfiguracji:
Store->Configuration->Sales->Payment Methods->InPost Pay->Ustawienia Autoryzacji
Opis pól konfigurowalnych:
Client ID | Identyfikator klienta otrzymany z od InPost używany do autoryzacji. |
Client Secret | Wartość Client Secret otrzymana od InPost używana do autoryzacji. |
Auth Token URL | Bazowy adres URL InPost, pod którym dokonywana będzie autoryzacja w celu pobrania tokena używanego w dalszej komunikacji z API. |
Merchant Secret | Wartość Merchant Secret otrzymana od InPost, potrzebna do tworzenia zwrotów. |
POS ID | Identyfikator nadany przez InPost |
Client Merchant ID | Identyfikator Klienta nadany przez InPost |
Widok konfiguracji:
Ustawienia Debuggowania
Ścieżka konfiguracji:
Store->Configuration->Sales->Payment Methods->InPost Pay->Ustawienia Debuggowania
Opis pól konfigurowalnych:
Log Level | Poziom, od którego informacje zbierane przez wtyczkę będą logowane w plikach od najbardziej szczegółowych informacji: DEBUG do najbardziej krytycznych: EMERGENCY |
Widok konfiguracji:
Ustawienia IZI API
Ścieżka konfiguracji:
Store->Configuration->Sales->Payment Methods->InPost Pay->Ustawienia IZI API
Opis pól konfigurowalnych:
IZI API URL | Adres URL InPost, pod którym dostępne są zasoby API związane z koszykiem i zamówieniami z aplikacji mobilnej InPost Pay. |
Czas życia koszyka | Ilość sekund na podstawie, której obliczana jest data ważności koszyka. Porzucone, nieaktualizowane koszyki będą usuwane przez aplikację InPost Pay po tej dacie. |
Zsynchronizuj dostępne metody płatności | Przycisk pozwalający zsynchronizować metody płatności z api InPost Pay |
Akceptowane Metody Płatności w aplikacji InPost | Lista wielokrotnego wyboru pozwalająca ustalić jakie metody płatności pojawią się w aplikacji Mobilnej dla koszyka. Synchronizacja dostępnych metod płatności odbywa się raz dziennie za pomocą crona. Uwaga: ta konfiguracja musi odpowiadać mapowaniu metod dostaw płatnych przy odbiorze. Jeśli tu forma płatności przy odbiorze jest skonfigurowana to powinna być też tam zmapowana. |
Włącz asynchroniczny eksport koszyka | W przypadku bardzo dużej ilości ruchu, koszyków i problemów z obciążaniem serwera można skonfigurować oddelegowanie żądań aktualizujących koszyki na kolejkę. Uwaga: wykorzystano tu natywną funkcjonalność kolejek Magento opartych o bazę danych, nie Rabbit MQ. Aby funkcjonalność działała poprawnie należy po stronie administracji serwerowej skonfigurować odpalanie procesu konsumowania wiadomości z kolejek. |
Włącz usuwanie znaków specjalnych i kodu HTML z atrybutów produktowych wysyłanych do Aplikacji Mobilnej InPost Pay | API InPost Pay i aplikacja aktualnie nie obsługuje takich znaków. Konfiguracja powinna być ustawiona na TAK jeśli w danych produktów występują takie znaki |
Widok konfiguracji:
Mapowanie zgód
Ścieżka konfiguracji:
Store->Configuration->Sales->Payment Methods->InPost Pay->Terms and Conditions Mapping Settings
Opis pól konfigurowalnych:
Zgody Magento | Select z wyborem zgody. |
Wymagalność | Select z wyborem poziomu wymagalności danej zgody, dostępne opcje to: REQUIRED_ALWAYS, REQUIRED_ONCE, OPTIONAL ADDITIONAL_LINK - specjalna opcja dedykowana kilku zgodą przekazywanym w postaci jednej pozycji do zaznaczenia, posiadającej w treści kilka linków. |
Nadrzędna zgoda | W przypadku Wymagalności ADITIONAL_LINK jest to wskazanie do której zgody nadrzędnej przynależy ten link. |
Link do zgody | link do pełnej treści zgody. |
Tekst linku | W przypadku połączonych zgód przez ADDITIONL_LINK jest to słowo lub fraza która zastąpi “link” do zgody. |
Widok konfiguracji:
Przykłady konfiguracji:
a) Podstawowa konfiguracja:
Wygląd w aplikacji:
Objaśnienie:
W tym przypadku podstawowym nie ma dodatkowych linków podpinanych pod główną zgodę. Występują po prostu dwie osobne zgody, z których jest jest wymagana, druga opcjonalna. Link prowadzący do zgód umieszczany jest na końcu w nawiasie jako “(link)”.
b) Konfiguracja z zagnieżdżeniem zgód
Wygląd w aplikacji:
Objaśnienie:
W tym przypadku mamy do czynienia ze zgodą zawierającą w treści przekazane dodatkowe linki do różnych regulaminów. Aby osiągnąć taki rezultat należy nie tylko odpowiedni skonfigurować samo mapowanie zgód we wtyczce InPost Pay ale również zgody muszą mieć odpowiedni tytuł w natywnej konfiguracji Magento: Store->Terms and Conditions:
Na powyższym fragmencie zrzutu ekranu widać zgodę główną o tytule:
”Potwierdzam, że zapoznałam(em) się z treścią #1 i #6 oraz akceptuję ich postanowienia.”
W której #1 oraz #6 odpowiadają identyfikatorom zgód. W tym przypadku #1 odnosi się do samej siebie, a #6 do zgody “Polityka Prywatności”.
W konfiguracji wtyczki i mapowania zgód widoczne jest ustawienie zgody “Polityka Prywatności” jako ADDITIONAL_LINK
oraz ustawienie jej nadrzędnej zgody
oraz finalnie dodanie tekstu jaki podmieni “(link)“ dając możliwość właściwej odmiany, w tym przypadku “Polityki Prywatności” oraz “Regulaminu”.
Powyższa konfiguracja sprawi, że w Aplikacji InPost Pay nie będzie widać osobno zgody ADDITIONAL_LINK, a zostanie ona podłączona pod #6 jako link w treści zgody nadrzędnej, a jako że zgoda nadrzędna posiada również swój własny identyfikator #1 oraz tekst linku “Regulaminu” finalny efekt prezentowany w aplikacji będzie następujący:
”Potwierdzam, że zapoznałam(em) się z treścią Regulaminu i Polityki Prywatności oraz akceptuję ich postanowienia.”
Gdzie pod tekstem “Regulaminu” oraz “Polityki Prywatności” ukryty jest link do pełnej treści zgody.
Ustawienia wyświetlania
Ścieżka konfiguracji:
Store → Configuration → Sales → Payment Methods → InPost Pay → Ustawienia wyświetlania
Opis pól konfigurowalnych:
Pokaż na karcie produktu | Konfiguracja pozwalająca na inicjalizację i pokazanie widgetu InPost Pay ( |
Pokaż na koszyku | Konfiguracja pozwalająca na inicjalizację i pokazanie widgetu InPost Pay ( |
Pokaż w minikoszyku | Konfiguracja pozwalająca na inicjalizację i pokazanie widgetu InPost Pay ( |
Pokaż na stronie z podziękowaniami | Konfiguracja pozwalająca na inicjalizację i pokazanie widgetu InPost Pay ( |
Pokaż na stronie z logowania | Konfiguracja pozwalająca na inicjalizację i pokazanie widgetu InPost Pay ( |
Pokaż na stronie z rejestracji | Konfiguracja pozwalająca na inicjalizację i pokazanie widgetu InPost Pay ( |
Pokaż na checkout | Konfiguracja pozwalająca na inicjalizację i pokazanie widgetu InPost Pay ( |
Widok konfiguracji:
Ustawienia układu przycisków
Ścieżka konfiguracji:
Store → Configuration → Sales → Payment Methods → InPost Pay → Ustawienia układu przycisków
Opis pól konfigurowalnych:
Rozmiar Widgetu | Konfiguracja pozwalająca na wybranie opcji rozmiaru widgetu i buttona InPost Pay od XS do XL |
---|---|
Style obramowania Widgetu | Pole umożliwia zaznaczenie jednego lub więcej styli z pośród poniżej opisanych:
Powyżej opisane style można łączyć ze sobą aby uzyskać na przykład tryb zaokrąglony żółty:
|
Widok konfiguracji:
Ustawienia Cache
Moduł InPost_InPostPay wykorzystuje natywny mechanizm Cache, aby zoptymalizować proces integracji. W pamięci podręcznej przechowywane są klucze publiczne pobierane w celu weryfikacji sygnatury przy autoryzacji żądań przychodzących od InPost do API Merchanta oraz konfiguracja zgód.
Rekomendowane jest włączenie obsługi tych ustawień pamięci podręcznej. Aby tego dokonać należy w Panelu Administracyjnym rozwinąć panel boczny i pozycję System, a następnie przejść do Zarządzania Pamięcią.
System->Cache Management
Kolejnym krokiem jest zaznaczenie poniższych opcji:
i wybranie z listy rozwijanej opcji włączenia zaznaczonych pozycji:
Instalacja modułu - dodatkowe informacje
W tej części dokumentacji znajduję się dodatkowa informacja dla klientów, którzy będą chcieli włączyć przycisk InpostPay w checkout oraz posiadają zmodyfikowany checkout.
Komponent z przyciskiem InpostPay został na checkout dodany jako kolejny krok (poza dostawą i płatnością). Został on dodany przed powyższymi krokami.
<item name="inpost-pay" xsi:type="array">
...
<item name="sortOrder" xsi:type="string">0</item>
...
</item>
Taka zmiana wymagała przekonfigurowania zależności w komponencie paska postępu:
<item name="progressBar" xsi:type="array">
<item name="config" xsi:type="array">
<item name="deps" xsi:type="array">
<item name="0" xsi:type="string">checkout.steps.inpost-pay</item>
<item name="1" xsi:type="string">checkout.steps.shipping-step.shippingAddress</item>
<item name="2" xsi:type="string">checkout.steps.billing-step.payment</item>
</item>
</item>
</item>
Jeśli klient posiada modyfikacje checkout (dodatkowy krok w checkout np. logowanie/rejestracja, zmodyfikowane zależności w pasku postępu) w tym zakresie należy dostosować checkout i uwzględnić powyższe zmiany.
Ustawienia odpytywania Long Polling
Ścieżka konfiguracji:
Store → Configuration → Sales → Payment Methods → InPost Pay → Polling Settings
Opis pól konfigurowalnych:
Włącz odpytywanie long polling dla nieaktywnej karty przeglądarki | Konfiguracja pozwalająca na włączenie/wyłączenie odpytywania serwera o status łączenia koszyków lub status zamówienia dla nieaktywnej karty przeglądarki (domyślnie włączone) |
Czas odpytywania dla nieaktywnej karty (w milisekundach) | Konfiguracja pozwalająca na zmianę okresu odpytywania serwera o status zamówienia/status łączenia koszyków dla nieaktywnej karty w przeglądarce. Czas podawany jest w milisekundach (domyślnie ustawione 10000) |
Widok konfiguracji:
Ustawienia Restrykcji
Ścieżka konfiguracji:
Store->Configuration->Sales->Payment Methods->InPost Pay->Ustawienia Restrykcji
Opis pól konfigurowalnych:
Uruchom Odświeżanie Restrykcji w CRON | Jeśli to ustawienie jest włączone restrykcje produktowe będą automatycznie odświeżane przez CRON zgodnie z harmonogramem. |
Harmonogram Odświeżania Restrykcji w CRON | Harmonogram w postaci odpowiedniej dla usługi systemowej CRON. 30 1,7,13,19 * * * dla przykładu sprawi, że CRON uruchomi proces codziennie o 1:30, 7:30, 13:30 oraz 19:30 |
Widok konfiguracji:
Ustawienia Omnibus
Ścieżka konfiguracji:
Store → Configuration → Sales → Payment Methods → InPost Pay → Omnibus Promo Settings
Opis pól konfigurowalnych:
Lowest Price Product Attribute | Konfiguracja pozwalająca na ustalenie z jakiego atrybutu produktowego wtyczka InPost Pay może wydobyć kwotę najniższej ceny z ostatnich 30 dni. |
Omnibus Cart Price Rules | Konfiguracja pozwala na wskazanie które reguły koszykowe powiązane są z dyrektywą Omnibus i wymagają pokazania ceny najniższej z ostatnich 30 dni. |
Widok konfiguracji:
Objaśnienie działania konfiguracji:
Domyślnie najniższe ceny z ostatnich 30 dni nie są wysyłane przez wtyczkę InPost Pay do API Aplikacji Mobilnej klientów, nawet jeśli produkty w koszykach klientów mają ustawioną wartość w tym atrybucie. Aby ceny były przekazywane, produkt w koszyku Magento klienta musi mieć zaaplikowaną regułę koszykową będącą oznaczoną w konfiguracji wtyczki InPost Pay jako “Omnibusowa” w postaci wyżej opisanej listy wielokrotnego wyboru. Sama w sobie reguła nie musi dawać rabatu ani obniżać ceny. Wystarczy, że będzie skonfigurowana tak, aby była włączona, a kryteria zarówno koszyka jak i jego zawartości były spełnione przez koszyk klienta, który ma w Aplikacji Mobilnej mieć widoczną cenę najniższą z ostatnich 30 dni.
Dostępne promocje w aplikacji
Ścieżka konfiguracji:
Store->Configuration->Sales->Payment Methods->InPost Pay->Available In-app Promotions
Opis pól konfigurowalnych:
Włącz promocje w aplikacji | Konfiguracja umożliwiająca włączenie wysyłania informacji o promocjach do aplikacji InpostPay. |
Reguła koszykowa Magento z kodem | Lista rozwija z wyborem poziomu reguły koszykowej. W liście rozwijanej dostępne są tylko te reguły koszykowe które posiadają jeden kod kuponu |
Url opisu promocji | Link do opisu danej promocji. |
Widok konfiguracji:
Wygląd w aplikacji:
Dodatkowe informacje:
Do aplikacji przesyłane są tylko reguły koszykowe które:
są aktywne
posiadają jeden kod rabatowy
są ważne, tzn aktualna data mieście się w przedziale “od” “do”
wartość Uses per Coupon jest 0 lub aktualna wartość Uses per Coupon jest większa niż ilość użyć danego kuponu
dodatkowym ograniczeniem jest grupa klientów, aby dany kupon został wysłany do aplikacji właściciel danego koszyka musi być przypisany do grupy klientów dla której dana reguła koszykowa jest przypisana
konfiguracja przesyłania promocji w aplikacji jest włączona(Włącz promocje w aplikacji)
dana reguła jest skonfigurowana w konfiguracji Dostępne promocje w aplikacji
Przykładowa konfiguracja reguły koszykowej, która zostanie wysłana do aplikacji dla klientów niezalogowanych
Jak widać na powyższych screenach reguła koszykowa jest włączona, posiada jeden konkretny kod kuponu, jest przypisana do grupy klientów niezalogowanych, wartość uses per coupon jest wyższa niż aktualna ilość liczby użyć, aktualna data(13.11.2024) mieści się w przedziale 6.11.2024 - 15.11.2025. Dana reguła koszykowa jest skonfigurowana w konfiguracji Dostępne promocje w aplikacji.
Udostępnienie logów InPost Pay
W przypadkach wymagających debuggowania problemów z działaniem wtyczki InPost Pay w Sklepach Merchantów, w celu ułatwienia znalezienia rozwiązania oraz aby nie angażować Merchanta w wyciąganie i przekazywaniem nam każdorazowo plików zawierających logi z integracji Magento z InPost Pay API - przygotowane zostało rozwiązanie udostępniające logi wtyczki InPost Pay przez nowy endpoint REST API działający w oparciu o natywne Webapi platformy Magento 2.
Aby udostępnić logi wtyczki dla Działu Wsparcia InPost Pay należy:
Upewnić się, że włączony został dostęp do Zasobów Magento przez Integrację opartą o Bearer Token. Konfiguracja ta znajduje się pod ścieżką:
Store->Config->Services->OAuth->Consumer Settings->Allow OAuth Access Tokens to be used as standalone Bearer tokens->YES
Utworzyć nowy Token Integracji z dostępem do określonych zasobów:
System->Integration->Add New IntegrationNastępnie w formularzu z Ogólnymi informacjami należy uzupełnić podstawowe, wymagane pola z nazwą integracji oraz potwierdzić formularz hasłem Administratora wprowadzającego te zmiany.
W zakładce API należy wskazać zasoby do jakich będą miały dostęp żądania autoryzujące się tym nowym Tokenem. W przypadku wsparcia wtyczki InPost Pay będzie to zasób: InPost Pay Logs
Nową integrację należy zapisać.
Ostatnim krokiem jest aktywacja nowej integracji z poprzez kliknięcie “Activate” w zakładce z listą integracji. Pojawi się przypomnienie do jakich zasobów aktywowana właśnie integracja będzie miała dostęp. Po potwierdzeniu pojawią się 4x klucze, z których trzeci “Token Dostępu” (lub “Access Token”) należy przekazać do Działu Wsparcia wtyczki InPost Pay.
Uwaga, jeśli okienko z powyższymi kluczami zostało zamknięte, można je wyświetlić ponownie klikając Edytuj (ikona ołówka) z poziomu zakładki z listą integracji. Można też kliknąć w opcję “Reauthorize” aby wygenerować nowe klucze dostępu, a następnie przekazać je do Działu Wsparcia InPost Pay.
Uzyskiwanie dostępu do logów i zakres informacji w ten sposób udostępnianych:
curl --location --request GET 'https://domena-sklepu-merchanta.pl/rest/V1/izi/inpostpaylogs/2024-11-27' \
--header 'Authorization: Bearer 7s1sfjmletrk1a9gveaa2qb6qzdbkei8'
Powyższa komenda wykorzystująca Token autoryzacyjny uzyskany w opisany na wstępie sposób zwróci w formacie JSON następujące dane:
Gdzie log_level
jest poziomem logowania skonfigurowanym w:
Store->Config->Sales->Payment Methods->InPost Pay->Debugging Settings->Log Level
Jest to informacja jak dokładnych logów można oczekiwać.
content
zawiera zakodowaną algorytmem Base64 całą treść pliku logów znajdującą się w ścieżce:
{root Magento2}/var/log/inpost-pay/{YYYY-MM-DD}.log
Gdzie dla każdego dnia tworzone są osobno pliki z logami, a parametr daty przekazywany jest w powyżej podanym przykładzie jako 2024-11-27
.
Uwaga!
Po zakończonym procesie wyjaśniania ewentualnych problemów i finalnym uruchomieniu produkcyjnym integracji z InPost Pay rekomendowane jest usunięcie z listy integracji tej utworzonej na czas debuggowania przez Dział Wsparcia InPost Pay, aby uniemożliwić dalszy dostęp do logów oraz ustawienie wyższego poziomu logowania (na przykład z DEBUG na ERROR).
Instrukcja użytkowania
W sekcji dokumentacji: InPost Pay - Magento | Instrukcja użytkowania zawarte zostały instrukcje dotyczące składania zakupu w sklepie internetowym za pośrednictwem wtyczki InPost Pay i aplikacji Mobilnej.
Dokumentacja Techniczna - backend
W tej sekcji dokumentacji zawarte zostały techniczne informacje dotyczące komunikacji z API InPost, Widgetem frontowym oraz debuggowania procesów zachodzących we wtyczce InPost Pay.
Weryfikacja Sygnatury
Każde żądanie przychodzące od InPost na adresy API Magento wtyczki InPost Pay podlegają weryfikacji sygnatury dla zapewnienia bezpieczeństwa. Szczegółowy opis algorytmu weryfikacji sygnatury można znaleźć w publicznej dokumentacji InPost: Weryfikacja sygnatury
Do weryfikacji sygnatury służy następujący interfejs:
\InPost\InPostPay\Api\Validator\SignatureValidatorInterface
Metoda validate
oczekuje podania następujących parametrów typu tekstowego:
Pierwsze cztery z nich dostępne są w nagłówkach żądania wysyłanego z InPost do Magento. Ostatni jest po prostu całą treścią (content) żądania.
Przebieg weryfikacji sygnatury:
Porównanie hash’u z żądania z wartością pobraną z API InPost będącą kluczem publicznym.
W tym celu następuje najpierw autoryzacja za pomocą danych dostępowych z konfiguracji w celu pobrania tokenu.
Token następnie używany jest jako Bearer Token w żądaniu pobrania danych klucza publicznego z API InPostu.
Odpowiedź z danymi InPostu z kluczami publicznymi zgodnie z wymogiem dokumentacji przechowywana jest w cache Magento pod kluczem będącym wersją przesłaną w nagłówku weryfikowanego żądania.
Wygenerowanie sygnatury na podstawie algorytmu opisanego w dokumentacji InPost oraz porównanie go z odkodowaną wartością sygnatury z nagłówka aktualnie weryfikowanego żądania.
W tym celu należy wyliczyć sygnaturę na podstawie danych:
- treść żądania (SHA256 a następnie base64)
- zewnętrzny ID sklepu dostępny z wymienionego w punkcie 1.c cache
- wersja z żądania
- timestamp z żądaniaPowyższe dane oddzielone przecinkami, należy zakodować Base64
Należy przygotować asymetryczny klucz publiczny na podstawie treści klucza z danych z punktu 1.c
Należy porównać poprzez
openssl_verify
oczekiwaną sygnaturę z punktu 2.a, z wartością sygnatury z żądania aktualnie weryfikowanego używając przygotowanego klucza publicznego z punktu 2.b
Ostatnim krokiem weryfikacji sygnatury jest porównanie czasu żądania wysłanego w nagłówku w UTC z obecnym czasem uwzględniając maksymalnie 240 sekund czasu życia tego żądania.
Connector API
Interfejs wykorzystywany do realizacji zapytań kierowanych z Magento do API InPost.
Implementacja wykorzystuje \GuzzleHttp\Client
w celu realizacji żądań POST/GET/PUT itd. kierowanych na odpowiedni adres URL składający się z bazowego URL danego API oraz URI danego endpointu. Do żądania dodawane są parametry jak i nagłówki.
O tym jakie nagłówki, parametry, bazowy URL i URI endpointu oraz jaki to rodzaj metody GET/POST/PUT itd. decyduje obiekt żądania przekazywany do metody connectora sendRequest
, który musi implementować interfejs żądania zawierający potrzebne do jego wysłania informacje:
(Lista metod i implementacji: Interfejs Żądań do API InPost )
Metoda sendRequest
zawsze zwraca tablicę, jeśli odpowiedzią jest JSON będzie on odkodowany i zwrócony w oryginalnej formie, jeśli nie i w wyniku odkodowania nie powstanie tablica, zwrócona zostanie tablica z kluczem result
i tą wartością.
W zależności od konfiguracji: Ustawienia Debuggowania logowaniu podlega całe żądanie, lub tylko wyjątki z błędami.
Interfejs Żądań do API InPost
Każde żądanie, które ma być użyte przez Connector API musi implementować ten interfejs:
W ramach interfejsu wymagane jest zaimplementowanie metod danego żądania:getApiUrl
getMethod
getContentType
getBearerToken
getParams
setParams
Aktualna lista żądań:
Obsługa żądań do API InPost i formatowanie odpowiedzi
Do pobierania danych z API InPost służą serwisy, w których zadaniem jest utworzenie i zasilenie odpowiednimi parametrami obiektów żądań implementujących interfejs
(Lista metod i implementacji: Interfejs Żądań do API InPost )
następnie wysłanie ich poprzez Connector API
oraz ostateczne nadanie formatu odpowiedzi. To w jakiej formie ma być zwrócona odpowiedź zależy od konkretnej implementacji obsługi danego żądania, standardem jest dodanie metody handle
przyjmującej jako argument tablicę i zwracającej utworzony i zasilony danymi obiekt (DataObject
) odpowiedzi na dane żądanie.
Aktualna lista serwisów:
Aktualna lista odpowiedzi na żądania:
Relacja pomiędzy oficjalną wtyczką Smartmage_Inpost a InPost_InPostPay
Wtyczka InPost_InPostPay nie wymaga do działania oficjalnej wtyczki InPost do obsługi dostaw za pośrednictwem urządzeń Paczkomat 24/7 czy Kuriera InPost ale mogą bezproblemowo razem funkcjonować.
Scenariusz #1: Obydwie wtyczki są zainstalowane na jednej instalacji Magento 2
Wtyczka Smartmage_Inpost dodaje do natywnej tabeli z zamówieniami i koszykami w bazie danych kolumnę, w której przechowuje wybrany Paczkomat 24/7 (kod). Są to kolumny:
Wtyczka Smartmage_Inpost w procesie zamawiania zapisuje najpierw wybrany przez klienta kod urządzenia do tabeli koszyka, a następnie podczas składania zamówienia uruchamiany jest Event Observer:
Wartość wybrana przez klienta widoczna jest w Panelu Administracyjnym w podglądzie zamówienia po prawej stronie pod informacją o wybranej metodzie dostawy:
Wtyczka InPost_InPostPay w analogiczny sposób na tym samym Evencie nasłuchuje procesu zapisu zamówienia i przenosi wartość wybranego kodu urządzenia Paczkomat 24/7 z koszyka na zamówienie jeśli spełnione zostały warunki:
metoda płatności: inpost_pay
quote.inpost_pay_locker_id było uzupełnione
metoda dostawy to ta, która jest zmapowana do Paczkomat 24/7 w konfiguracji mapowania InPost Pay - Mapowanie metod dostawy
W Panelu Administracyjnym w podglądzie zamówienia wartość wybranego kodu urządzenia nie pokazuje się w tym scenariuszu #1 z inicjatywy wtyczki InPost_InPostPay, ze względu na to, że odpowiada za to w tym wypadku wtyczka Smartmage_Inpost.
Scenariusz #2: Tylko wtyczka InPost_InPostPay jest zainstalowana w Magento 2
Blok z identyczną informacją jak w scenariuszu #1 generuje również moduł InPost_InPostPay gdy zachodzą następujące warunki:
metoda płatności: inpost_pay
Moduł Smartmage_Inpost nie jest włączony
Zamówienie nie jest wirtualne
Debuggowanie
Wtyczka InPost_InPostPay posiada własny Log Handler, który ma własną obsługę poziomów logowania opartą o konfigurację: Ustawienia Debuggowania.
Niezależnie od ustawień systemowych logowaniu podlegają wszystkie poziomy od skonfigurowanego do najbardziej krytycznego:
W trakcie przetwarzania danych, procesowania zapytań do API, obsługi błędów itp. w wielu miejscach używany jest wstrzyknięty przez di.xml logger, np:
W konstruktorze tego obiektu logger to:
Poziom logów określa metoda wywołana na obiekcie $logger:
Przechowywanie logów:
Za miejsce przechowywania logów odpowiada:
gdzie w konstruktorze budowana jest ścieżka do pliku .log mająca formę opartą o aktualną datę, przykładowo:
Format logów:
Każdy wpis w logach do którego użyty został ten Handler będzie poprzedzony wygenerowanym w ramach procesu unikalnym ID, dla ułatwienia śledzenia i debuggowania przy większej ilości żądań i równocześnie uruchamianych procesów.
Dodatkowo aby zapewnić z jednej strony pomocne dane, z drugiej strony nie zapisywać jawnie pewnych informacji część logów, które potencjalnie mogą zawierać dane wrażliwe zakodowane są base64.
Przykładem takich logów są dane wysyłane i odbierane z API InPost:
Przykład logów:
Kontrolery frontowe 2.0
Kontrolery wykorzystywane przy komunikacji widgetu frontowego z backendem Magento.
Implementacje REST API Magento
Szczegółowy opis sekcji znajduje się w rozdziale: InPost Pay - Magento | Implementacje REST API Magento.
Proces Tworzenia Zamówienia
Opis sekcji znajduje się w rozdziale:InPost Pay - Magento | Proces Tworzenia Zamówienia.
Obiekty zwracane przez API Magento
Opis obiektów zwracanych przez API Magento znajduje się w rozdziale:InPost Pay - Magento | Obiekty zwracane przez API Magento.
Modyfikacje indywidualne pod Merchanta
Opis sekcji znajduje się pod linkiem: InPost Pay - Magento | Modyfikacje indywidualne pod Merchanta.
Moduł Restrykcji
Opis sekcji znajduje się w rozdziale: InPost Pay - Magento | Moduł Restrykcji.
Czyszczenie atrybutów tekstowych z HTML i znaków specjalnych
Szczegółowy opis dostępny jest się w rozdziale: InPost Pay - Magento | Czyszczenie atrybutów tekstowych z HTML i znaków specjalnych.
Ograniczenie dostaw tylko do PL
Ograniczenie dostawy tylko dla PL jest zależne od zmapowanych metod dostaw dla InPostPay i odbywa się poprzez sprawdzenie aktualnego adresu w koszyku, jeżeli koszyk nie ma przypisanego adresu to automatycznie w kodzie kraj dostawy ustawia się na Polskę co pozwala na złożenie zamówienia w aplikacji.
Jeżeli użytkownik jest zalogowany i nie ma wypełnionego adresu dostawy to przy sprawdzaniu dostępnych metod dostawy brany jest pod uwagę domyślny adres klienta. Jeżeli klient nie ma domyślnego adresu to automatycznie kraj dostawy ustawiany jest na Polskę.
Odbywa się to w klasie
Produkty bundle
Do aplikacji InPostPay jako product_id dla produktów bundle wysyłamy product_id_item_id. Przykład produkt bundle na sklepie ma product_id 45, a w tabeli quote_item dodany produkt ma id 10 to do aplikacji InPostPay zostanie wysłany product_id 45_10 jest to potrzebne do tego aby odróżnić różne konfiguracje tego samego produktu bundle przy aktualizacji produktu z aplikacji InPostPay do magento.
Dodatkowo wybrane opcje produktu bundle są wysyłane jako atrybuty produktu bundle
Generowanie Sygnatury dla zwrotów
Instrukcja znajduje się w rozdziale: InPost Pay - Magento | Generowanie Sygnatury dla zwrotów.
Zmiany w Widget v 2.0
Główną różnicą po wdrożeniu zmian z wydania 1.1.0 (widget v.2.0) jest zmiana w sposobie komunikacji pomiędzy Widgetem InPost Pay osadzanym na stronach Magento (strona produktu, koszyk, minicart, rejestracja, checkout). W starszej wersji Widget komunikował się z Backendem Magento poprzez przygotowane w ramach wtyczki kontrolery odpytując okresowo o to czy dany koszyk został potwierdzony, oraz czy zamówienie dla danego koszyka zostało złożone z poziomu aplikacji. Generowało to sporo żądań pomiędzy przeglądarką, a Backendem Magento. Nowa wersja Widgetu wykorzystuje bardzo ograniczoną liczbę zapytań do Backendu - uzyskuje najpierw jednorazowo dla danego koszyka Binding Api Key, który wykorzystuje w komunikacji z API InPost Pay, następnie, gdy w wyniku złożenia przez klienta zamówienia Widget uzyska taką informację z API InPost, odpytuje jedynie Magento o adres success page potrzebny do przekierowania. Dzięki zastosowaniu tego rozwiązania znacząco została zredukowana ilość zapytań do Backendu Magento przerzucając ruch bezpośrednio na serwery API InPost.