/
InPost Pay - Magento (Widget 2.0)

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

  • Nowa wersja: 2.0.4 (31.01.2025 r.)

    • Ustawienia Ogólne - Przypisywanie koszyków do klienta po adresie email

  • 2.0.3 (17.01.2025 r.)

    • Integracja z Widget 2.0

    • Przekazywanie dwóch numerów zamówienia (numer techniczny i numer wyświetlany dla klienta)

    • Możliwa konfiguracja widoczności widgetu na produkcji tylko dla testerów

    • Wyświetlanie informacji o metodzie płatności zamówienia w panelu administracyjnym Magento

    • Obsługa logów po stronie modułu

    • Przekazywanie po API wersji modułu, która jest aktualnie wykorzystywana.

 

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:


 

 

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.
Bardzo ważne jest to, aby konfigurując to mapowanie cena metody dostawy przypisanej tej opcji była adekwatna do kosztów Paczki w Weekend i opcji Płatności przy odbiorze.

Przykładowo:
Standard - 10zł
Paczka w Weekend - 12zł (w aplikacji opcja +2zł do standardowej wysyłki)
Płatność przy odbiorze - 14zł (w aplikacji opcja +4zł do standardowej wysyłki)
Płatność przy odbiorze w weekend - 16zł (w aplikacji połączenie opcji +2zł i +4zł)

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.
Bardzo ważne jest to, aby konfigurując to mapowanie cena metody dostawy przypisanej tej opcji była adekwatna do kosztów Paczki w Weekend i opcji Płatności przy odbiorze.

Przykładowo:
Standard - 10zł
Paczka w Weekend - 12zł (w aplikacji opcja +2zł do standardowej wysyłki)
Płatność przy odbiorze - 14zł (w aplikacji opcja +4zł do standardowej wysyłki)
Płatność przy odbiorze w weekend - 16zł (w aplikacji połączenie opcji +2zł i +4zł)

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:

image-20250117-144730.png

 


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: ?showInPostPay=true

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:

image-20250203-094156.png

 


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 (<inpost-izi-button ...></inpost-izi-button>) na karcie produktu

Pokaż na koszyku

Konfiguracja pozwalająca na inicjalizację i pokazanie widgetu InPost Pay (<inpost-izi-button ...></inpost-izi-button>) na stronie koszyka

Pokaż w minikoszyku

Konfiguracja pozwalająca na inicjalizację i pokazanie widgetu InPost Pay (<inpost-izi-button ...></inpost-izi-button>) w minikoszyku

Pokaż na stronie z podziękowaniami

Konfiguracja pozwalająca na inicjalizację i pokazanie widgetu InPost Pay (<inpost-thank-you/>) na stronie z podziękowaniami za złożone zamówienie

Pokaż na stronie z logowania

Konfiguracja pozwalająca na inicjalizację i pokazanie widgetu InPost Pay (<inpost-izi-button ...></inpost-izi-button>) na stronie logowania

Pokaż na stronie z rejestracji

Konfiguracja pozwalająca na inicjalizację i pokazanie widgetu InPost Pay (<inpost-izi-button ...></inpost-izi-button>) na stronie rejestracji

Pokaż na checkout

Konfiguracja pozwalająca na inicjalizację i pokazanie widgetu InPost Pay (<inpost-izi-button ...></inpost-izi-button>) na checkout (pod formularzem danych osobowych)

 

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

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:

  • round- maksymalne zaokrąglenie

  • rounded - lekkie zaokrąglenie

  • dark/primary - tryb ciemny lub żółty

Powyżej opisane style można łączyć ze sobą aby uzyskać na przykład tryb zaokrąglony żółty:
round + primary

 

 

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:

  1. 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

  2. Utworzyć nowy Token Integracji z dostępem do określonych zasobów:
    System->Integration->Add New Integration

    Nastę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ć.

  1. 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:

  1. Porównanie hash’u z żądania z wartością pobraną z API InPost będącą kluczem publicznym.

    1. W tym celu następuje najpierw autoryzacja za pomocą danych dostępowych z konfiguracji w celu pobrania tokenu.

    2. Token następnie używany jest jako Bearer Token w żądaniu pobrania danych klucza publicznego z API InPostu.

    3. 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.

  2. Wygenerowanie sygnatury na podstawie algorytmu opisanego w dokumentacji InPost oraz porównanie go z odkodowaną wartością sygnatury z nagłówka aktualnie weryfikowanego żądania.

    1. 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 żądania

      Powyższe dane oddzielone przecinkami, należy zakodować Base64

    2. Należy przygotować asymetryczny klucz publiczny na podstawie treści klucza z danych z punktu 1.c

    3. 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

  3. 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.


 

Related content