InPost Pay - Magento

 

image-20240305-144356.png

 

Wstęp

Niniejsza instrukcja przedstawia proces instalacji oraz konfiguracji wtyczki, umożliwiającej wprowadzenie InPost Pay w sklepie Magento.

 

Wtyczka: 05.12.2024 r.

*Wtyczka obecnie jest jeszcze rozwijana, będą pojawiały się nowe wersje wtyczki, śledź changelog i instaluj nowe wersje, jak tylko będą dostępne.

Changelog

  • Nowa wersja: 1.0.9 (26.09.2024 r.)

  • Poprzednie wersje:

    • 1.0.9 (26.09.2024 r.)

    • 1.0.8 (05.09.2024 r.)

      • Dodano:

        • Omnibus. Konfiguracja pozwalająca na oznaczenie reguł flagą Omnibus i wybranie atrybutu zawierającego najniższą cenę.

      • Zmieniono:

        • Mapowanie zgód. Konfiguracja umożliwia teraz przekazanie więcej niż jednego linku do jednej zgody.

      • Poprawiono:

        • Obsługa produktu niedostępnego. W przypadku zerowej ilości produktu przy składaniu zamówienia w aplikacji mobilnej będzie wyświetlany stosowny komunikat.

    • 08.08.2024 r.

    • 19.07.2024 r.

    • 05.07.2024 r.

    • 27.06.2024 r.

    • 26.06.2024 r.

    • 19.06.2024 r.

    • 28.05.2024 r.

    • 21.05.2024 r.

    • 29.04.2024 r.

    • 05.03.2024 r.

 

 

 

Na tej stronie

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 (Supervisor: A Process Control System — Supervisor 4.0.0.dev0 documentation )


 

Konfiguracja

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-20240212-153840.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.

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

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.

 

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

 

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.

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 (zmiany od wersji 1.0.8)

Ś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 bloku InPost Pay Thank You Page (<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:

Domyślna wartość wariantu kolorystycznego przycisku

Konfiguracja pozwalająca na wybranie opcji wariantu kolorystycznego przycisku.

Dostępne opcje: primary oraz secondary

Wygląd dla:

  • primary

  • secondary

Domyślnie włączony tryb ciemny widgetu

Konfiguracja pozwalająca na włączenie trybu ciemnego.

Dostępne opcje true lub false

Wygląd dla opcji true:

Dla opcji false nic się nie zmienia w wyglądzie.

Maksymalna szerokość widgetu(wartość pomiędzy 220 a 600)

Określa maksymalną szerokość jaką ma zajmować widget. Przyjmuje wartości od 220 do 600.

Minimalna wysokość widgetu(wartość pomiędzy 48 a 64)

Określa minimalną wysokość jaką ma posiadać przycisk
InPost Pay. Przyjmuje wartości w zakresie od 48 do 64.

Styl rogów ramki widgetu

Opcjonalny parametr określający styl rogów ramki widgetu. Domyślnie widget jest prostokątny i jeśli chcemy aby nadal taki był należy wybrać wartość klasyczny. Dostępne wartości:

  • klasyczny - prostokątny

  • małe zaokrąglenie

  • duże zaokrąglenie.

 

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łaczenie 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 InPost Pay w checkout oraz posiadają zmodyfikowany checkout.

Komponent z przyciskiem InPost Pay 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 niekatywnej 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 niekatywnej karty w przeglądarce. Czas podawany jest w milisekundach (domyślnie ustawione 10000)

 

Widok konfiguracji:


Ustawienia Omnibus (zmiany od wersji 1.0.8)

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


Ustawienia Restrykcji (zmiany od wersji 1.0.8)

Ś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:

 


 

 

Instrukcja użytkowania

W tej sekcji dokumentacji zawarte zostały instrukcje dotyczące składania zakupu w sklepie internetowym za pośrednictwem wtyczki InPost Pay i aplikacji Mobilnej.


Zakup na stronie Merchanta przy użyciu InPost Pay

Wymagania

  • serwis z zainstalowanym modułem InPost Pay

  • aplikacja mobilna InPost Mobile

Opis działania

Aby złożyć zamówienie należy przejść do serwisu na stronę produktu na której znajduje się przycisk “Utwórz koszyk z InPostPay“ (Jeśli mamy już produkty w koszyku to zamówienie możemy także złożyć poprzez użycie przycisku InPostPay, który znajduje się także w minikoszyku oraz na stronie koszyka).

Należy kliknąć w podany przycisk aby dodać produkt do koszyka i rozpocząć proces parowania koszyków. Po kliknięciu i dodaniu produktu do koszyka pojawi się popup w którym wybieramy sposób parowania koszyków. Możemy tego dokonać poprzez:

  1. podanie numeru telefonu

Po wpisaniu numeru telefonu i kliknięciu przycisku “Połącz” zmienia się treść w popupie

i rozpoczyna się proces łączenia koszyków w aplikacji InPost Mobile. W aplikacji na urządzeniu mobilnym pojawia się powiadomienie o tym, że w aplikacji czeka na Ciebie koszyk. W tej sytuacji możemy:

  • połączyć koszyk poprzez kliknięcie w aplikacji na koszyku OK

  • możemy wrócić do serwisu i kontynuować zakupy na sklepie poprzez kliknięcie w przycisk “Kontynuuj zakupy na stronie sklepu“.

  1. zeskanowanie kodu QR

Po zeskanowaniu kodu qr w aplikacji InPost Mobile następuje parowanie koszyków i przenosi nas do koszyka.

Po połączeniu koszyków (używając powyższych sposobów) na serwisie znika popup a przycisk zmienia swój wygląd i informuje nas o tym, że koszyki są sparowane.

Na tym etapie mamy możliwość złożenia zamówienia poprzez aplikację jak również dokończenia zamówienie na serwisie. Koszyk w serwisie jest teraz połączony z koszykiem w aplikacji i jakiekolwiek akcje przeprowadzone w koszyku zakupowym (dodanie produktu, usunięcie produktu, zwiększenie ilości produktów) będą synchronizowane między koszykami (na serwisie zaimplementowane jest odpytywanie o status i zsynchronizowanie danych koszykowych może nastąpić maksymalnie po 10 sekundach). Akcją która także jest synchronizowana pomiędzy koszykami jest usunięcie koszyka. Jeśli usuniemy koszyk w aplikacji InPost Mobile usuwane jest wiązanie koszyków ale koszyk w serwisie pozostaje w niezmienionej formie. Ponowne klinięcie w przycisk “Utwórz koszyk InPost Pay” łączy nam koszyki teraz już bez podawania numeru telefonu czy też skanowania kodu qr ponieważ dane zostały już zapisane w serwisie i aplikacji. Procesując zamówienie w aplikacji mamy możliwość wpisywania kodów rabatowych które są dostępne w serwisie.

Wybierając ścieżkę zakupy w aplikacji - po złożeniu zamówienia w aplikacji, na serwisie zostajemy przekierowani do strony z podziękowaniami

Procesując zamówienie na serwisie po złożeniu zamówienia w aplikacji pojawia nam się informacja, że koszyk już nie istnieje lub został usunięty.


Konfiguracja produktów objętych restrykcjami i brakiem możliwości sprzedaży poprzez InPost Pay

Wraz z wtyczką InPost Pay dostarczony jest również moduł pozwalający na zarządzanie tym jakie produkty z przyczyn biznesowych lub logistycznych nie mogą być obsługiwane przez aplikację mobilną InPost Pay.

Konfiguracja:

W Panelu Administracyjnym należy wybrać z Menu bocznego sekcję Stores, a następnie z rozwijanej listy InPost Restrictions->Restriction Rules.

Wyświetli się tabela z listą obecnie skonfigurowanych reguł uniemożliwiających sprzedaż wybranych produktów poprzez aplikację mobilną InPost Pay.

Aby wykluczyć wybrane produkty z obsługi przez InPost Pay należy utworzyć nową regułę przyciskiem w prawym górnym rogu, po czym uzupełnić główną sekcję w formularzu, podając:

  • nazwę reguły, która ma na celu ułatwienie identyfikacji czego reguła dotyczy. Ta nazwa nie wyświetla się klientom.

  • ustawić status reguły, czy ma być włączona czy wyłączona

  • ustawić website, którego reguła ma dotyczyć

  • ustawić której metody dostawy dotyczy reguła (Courier, APM lub Obie metody jednocześnie)

Następnie należy rozwinąć sekcję warunków jakie mają spełniać wykluczone produkty i poprzez charakterystyczny dla Magento konfigurator warunków (podobny do tego z Katalogowych Reguł Promocyjnych) należy wskazać jakie cechy produktów wykluczają go ze sprzedaży poprzez InPost Pay.

Ostatnim krokiem jest zapisanie reguły przyciskiem po prawej stronie u góry. Zapis może zająć od kilku do kilkunastu sekund zależnie od tego ile w Magento skonfigurowano website'ów, store'ów, ile jest produktów, co wynika z budowania listy produktów objętych restrykcjami.


Listę produktów objętych restrykcjami można podejrzeć w zakładce Store->InPost Restrictions->Restricted products


Pomocne informacje dodatkowe:

Proces odświeżania listy wykluczeń może być zautomatyzowany i kontrolowany z poziomu konfiguracji:
Store->Config->Sales->Payments->InPost Pay->Restrictions Settings
Domyślnie odświeżanie włączone jest czterokrotnie w ciągu dnia o godzinach 1:30, 7:30, 13:30 i 19:30 ale w razie potrzeby można te godziny ustawić zgodnie z preferencjami mając jednak na uwadze, że w zależności od dużej ilości produktów w ofercie i skonfigurowanych reguł czas potrzebny na przeprocesowanie odświeżenia listy wykluczeń może wymagać więcej czasu, oraz że pojawienie się lub zniknięcie wykluczenia produktu powoduje wyczyszczenie pamięci FPC strony tego produktu, zatem nie jest rekomendowane ustawianie tego procesu zbyt często chyba, że jest to niezbędne.

Lista atrybutów do wyboru warunków restrykcji zawiera tylko takie cechy produktów, które mają ustawioną dostępność dla filtrów rabatów katalogowych. Jest to konfiguracja każdego atrybutu produktowego. Można to ustawienie zmienić w zakładce: Store->Attributes->Product, edytując atrybut, a wspomniana konfiguracja znajduje się w sekcji Storefront Properties.

Wartość YES spowoduje że dany atrybut będzie mógł służyć jako filtr wykluczenia.

Po ponownym wejściu w formularz edycji lub tworzenia nowej reguły atrybut pojawi się na liście:

Należy pamiętać, że konfigurując warunki wykluczenia można manipulować nie tylko wartością ale i połączeniem warunków oraz operatorem porównania.

W ten sposób można skonfigurować najróżniejsze warunki spełniające wymagania biznesowe jak choćby:

  • produkty z kategorii X lub produkty których cena jest większa niż Y.


Instrukcja tworzenia zwrotu

Aby dokonać zwrotu musimy mieć przeprocesowane (opłacone) zamówienie przez InPost Pay.

Następnie wchodzimy do panelu administratora magento na nasze zamówienie (Sales → Orders → Order View) i klikamy w przycisk Credit Memo:

W kolejnym kroku otworzy nam się widok Credit memo. Klikamy w button Refund Offline - po tej akcji zostanie złożony zwrot w Magento oraz wysłany request do InPost, w celu zwrotu środków z InPost Pay.

Po utworzeniu Creditmemo powinien się do niego dodać komentarz.
Jeśli zwrot zostanie poprawnie utworzony w InPost, to dostaniemy opis w formie podobnej do tego jak poniżej:

[ "InPostPay Transaction Refund.", "External Refund Id: %1", "Status: %1", "Description: %1" ];

Przykład z konkretnego zwrotu:

Jeżeli wystąpi jakiś błąd, to w komentarzu otrzymamy informację jak poniżej:

Dokładne informacje o błędzie można sprawdzić w logach na serwerze, np:
var/log/inpost-pay/2024-04-11.log

 


 

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

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

Kontrolery wykorzystywane przy komunikacji widgetu frontowego z backendem Magento.

 


Implementacje REST API Magento

DELETE /v1/izi/basket/:basketId/binding

Kontroler służący do usunięcia koszyka przez użytkownika w aplikacji InPost Pay.

Request Type – DELETE

Endpoint URL: /v1/izi/basket/:basketId/binding

Response – brak. 200 – oznacza, potwierdzenie otrzymania informacji o usunięciu koszyka.

Możliwe błędy:
InPost\InPostPay\Exception\InPostPayBadRequestException 400

InPost\InPostPay\Exception\InPostPayAuthorizationException 401

InPost\InPostPay\Exception\BasketNotFoundException 404

InPost\InPostPay\Exception\InPostPayInternalException 500

POST /v1/izi/basket/:basketId/confirmation

Endpoint wykorzystywany do potwierdzenia powiązania koszyka w aplikacji InPostPay.

Request Type – POST

Endpoint URL: /v1/izi/basket/:basketId/confirmation

Response – Zwracany jest obiekt typu \InPost\InPostPay\Api\Data\Merchant\BasketInterface
Koszyk InPost Pay (Basket)

Przykładowe zapytanie:

Odpowiedź 200

Możliwe błędy:
InPost\InPostPay\Exception\InPostPayBadRequestException 400

InPost\InPostPay\Exception\InPostPayAuthorizationException 401

InPost\InPostPay\Exception\BasketNotFoundException 404

InPost\InPostPay\Exception\InPostPayInternalException 500

 

GET /v1/izi/basket/:basketId

Endpoint służący do pobrania danych koszyka. 

Request Type – GET

Endpoint URL: /v1/izi/basket/:basketId

Response – Zwracany jest obiekt typu \InPost\InPostPay\Api\Data\Merchant\BasketInterface
Koszyk InPost Pay (Basket)

Odpowiedź 200

Możliwe błędy:
InPost\InPostPay\Exception\InPostPayBadRequestException 400

InPost\InPostPay\Exception\InPostPayAuthorizationException 401

InPost\InPostPay\Exception\BasketNotFoundException 404

InPost\InPostPay\Exception\InPostPayInternalException 500

 

POST /v1/izi/basket/:basketId/event

Endpoint wykorzystywany do aktualizacji koszyka w magento.

Request Type – POST

Endpoint URL: /v1/izi/basket/:basketId/event

Response – Zwracany jest obiekt typu \InPost\InPostPay\Api\Data\Merchant\BasketInterface
Koszyk InPost Pay (Basket)

Przykładowe zapytanie:

Odpowiedź 200:

Możliwe błędy:
InPost\InPostPay\Exception\InPostPayBadRequestException 400

InPost\InPostPay\Exception\InPostPayAuthorizationException 401

InPost\InPostPay\Exception\BasketNotFoundException 404

InPost\InPostPay\Exception\InPostPayInternalException 500

 

POST /v1/izi/order

Endpoint wykorzystywany do utworzenia zamówienia w magento.

Request Type – POST

Endpoint URL: /v1/izi/order

Response – Zwracany jest obiekt typu \InPost\InPostPay\Api\Data\Merchant\OrderInterface
Zamówienie InPost Pay (InPostOrder)

Przykładowe zapytanie:

Odpowiedź 200:

Możliwe błędy:
InPost\InPostPay\Exception\InPostPayBadRequestException 400

InPost\InPostPay\Exception\InPostPayAuthorizationException 401

InPost\InPostPay\Exception\BasketNotFoundException 404

InPost\InPostPay\Exception\InPostPayInternalException 500

\InPost\InPostPay\Exception\OrderNotCreateException 409

 

GET /v1/izi/order/:orderId

Endpoint służący do pobrania danych zamówienia. 

Request Type – GET

Endpoint URL: /v1/izi/order/:orderId

Response – Zwracany jest obiekt typu \InPost\InPostPay\Api\Data\Merchant\OrderInterface
Zamówienie InPost Pay (InPostOrder)

Odpowiedź 200

Możliwe błędy:
InPost\InPostPay\Exception\InPostPayBadRequestException 400

InPost\InPostPay\Exception\InPostPayAuthorizationException 401

InPost\InPostPay\Exception\OrderNotFoundException 404

InPost\InPostPay\Exception\InPostPayInternalException 500

 

POST /v1/izi/order/:orderId/event

Endpoint wykorzystywany do aktualizacji zamówienia w magento.

Request Type – POST

Endpoint URL: /v1/izi/order/:orderId/event

Response – Zwracany jest obiekt typu \InPost\InPostPay\Api\Data\Merchant\OrderUpdateInterface

Przykładowe zapytanie:

Odpowiedź 200:

Możliwe błędy:
InPost\InPostPay\Exception\InPostPayBadRequestException 400

InPost\InPostPay\Exception\InPostPayAuthorizationException 401

InPost\InPostPay\Exception\OrderNotFoundException 404

InPost\InPostPay\Exception\OrderNotUpdateException 409

InPost\InPostPay\Exception\InPostPayInternalException 500


Proces Tworzenia Zamówienia

Tworzenie zamówienia inicjowane jest przez InPost poprzez żądanie: POST /v1/izi/order


Sprawdzenie poprawności danych zamówienia

Przed przystąpieniem do modyfikacji sesji koszyka w celu przekształcenia jej w zamówienie najpierw następuje weryfikacja danych przysłanych z InPost. Odpowiada za to lista walidatorów, które określone są w pliku:

w formie:

Powyższe, wstrzyknięte walidatory odpowiadają między innymi za:

  • sprawdzenie czy zgadza się finalna cena całkowita za towary i przesyłkę uwzględniając rabaty

  • czy forma płatności wybrana w aplikacji Mobilnej jest zgodna z konfiguracją: Ustawienia IZI API

  • czy wybrana dostawa przez aplikację InPost Pay jest dostępna dla tej sesji koszyka w Magento

  • czy zgody wymagane są zaakceptowane

  • poprawność danych rozliczeniowych

  • czy produkty są na stanie

Jeśli w ramach walidacji zamówienia, Merchant będzie potrzebował zmian można łatwo zmodyfikować poprzez pluginy lub dodać kolejne walidatory dedykowane dla tego Merchanta.


Utworzenie zamówienia

Dane przesłane z InPost procesowane są w krokach podobnie do natywnego działania checkoutu.
Kroki określone są w pliku:

w formie:

 

Kroki orderProcessingSteps wzbogacają danymi sesje koszykową o:

  • przypisanie klienta jeśli koszyk był gościa, a mail znajduje się wśród zarejestrowanych

  • uzupełnienie danych adresu rozliczeniowego

  • uzupełnienie danych adresu dostawy

  • ustawienie metody dostawy

  • ustawienie metody płatności

  • przeładowanie sesji koszyka w celu przeliczenia kwoty całkowitej

Jeśli w ramach tworzenia zamówienia, Merchant będzie potrzebował zmian w procesie kroki można łatwo zmodyfikować poprzez pluginy, lub dodać kolejny krok poprzez moduł dedykowany dla tego konkretnego przypadku Merchanta.


Procesowanie nowo utworzonego zamówienia

Po utworzeniu zamówienia konieczne jest wykonaniu kilku kroków określonych w:

w formie:

Kroki orderPostProcessingSteps procesujące czynności po utworzeniu:

  • zainicjowanie rekordu w bazie dla zamówienia z InPost Pay

  • zapisanie wybranego punktu odbioru (jeśli ta metoda została wybrana)

  • zapisanie wybranych opcji dostawy (Paczka w Weekend, Płatność przy odbiorze itd.)

  • zapisanie zaakceptowanych zgód

Jeśli po utworzeniu zamówienia, Merchant będzie potrzebował wykonać jakieś dodatkowe kroki można łatwo wstrzyknąć kolejne kroki procesowania utworzonego zamówienia dedykowane pod konkretnego Merchanta.


Obiekty zwracane przez API Magento

W ramach komunikacji po Rest API Magento zwraca następujące obiekty:

Koszyk: Koszyk InPost Pay (Basket)
Zamówienie: Zamówienie InPost Pay (InPostOrder)


Koszyk InPost Pay (Basket)

Interfejs: \InPost\InPostPay\Api\Data\Merchant\BasketInterface
Implementacja: \InPost\InPostPay\Model\Data\Merchant\Basket

Opis:

Koszyk InPost Pay, w kodzie nazywany jest dla odróżnienia od quote czy cart jako basket.
Obiekt odwzorowuje Magentową sesję koszykową w taki sposób, aby spełniała wymogi komunikacji z API InPost Pay.

 

Obiekt Basket zasilany jest danymi z sesji koszyka poprzez klasę DataTransfer i metodę transfer, która przenosi i przetwarza dane z Magentowej sesji koszyka na obiekt Basket:


Zamówienie InPost Pay (InPostOrder)

Interfejs: \InPost\InPostPay\Api\Data\Merchant\OrderInterface
Implementacja: \InPost\InPostPay\Model\Data\Merchant\Order

Opis:

Obiekt odwzorowuje Magentowe zamówienie w taki sposób, aby spełniało wymogi komunikacji z API InPost Pay.

 

Obiekt zamówienia InPost zasilany jest danymi z zamówienia Magento poprzez klasę DataTransfer i metodę transfer, która przenosi i przetwarza dane na obiekt:


 

Modyfikacje indywidualne pod Merchanta

Moduł InPost_InPostPay był pisany w taki sposób, aby był możliwie łatwy do zmodyfikowania pod indywidualne wymogi różnych Merchantów.

  1. Dane Produktowe wysyłane do aplikacji InPost Pay

Aby zmodyfikować dane produktowe, obsłużyć inaczej przekazywanie atrybutów, zmiany w stanach magazynowych, itp. należy w module dedykowanym dla danego Merchanta dodać w di.xml definicję pluginu klasy:

oraz przygotować klasę Pluginu implementującą metodę afterTransfer lub ewentualnie aroundTransfer dodając indywidualną logikę biznesową.

Uwaga: Dane produktowe generowane poprzez ten mechanizm dotyczą zarówno Koszyka jak i Zamówienia widocznego w aplikacji mobilnej InPost Pay.

 

Analogicznie do danych produktowych w taki sam sposób można dokonać modyfikacji danych dostawy, zgód, produktów powiązanych, zaaplikowanych kodów rabatowych oraz samego podsumowania zamówienia poprzez pluginy do klas:

mając jednak na uwadze, że dane prezentowane w aplikacji mobilnej InPost Pay muszą odpowiadać tym prezentowanym w koszyku Magento, zwłaszcza cen, podatków oraz kosztów dostaw.


  1. Data dostawy

Integracja z API InPost Pay wymaga podania daty dostawy zarówno w koszyku jak i w danych zamówienia. Domyślnie moduł InPost_InPostPay ze względu na uniwersalność nie ma zaimplementowanego wyliczania tej daty na podstawie zmapowanej metody dostawy, różnych stanów magazynowych, opóźnień itp. ze względu na brak dostępu do informacji potrzebnych do wyliczenia takiej daty. W konfiguracji Mapowanie Metod Dostawy znajduje się pole wymagane, na podstawie którego ta data jest wyliczana bez względu na to jaka była wybrana metoda dostawy. W celu wyliczenia daty w oparciu o bardziej indywidualną logikę biznesową należy dodać w di.xml definicję pluginu klasy:

oraz przygotować klasę Pluginu implementującą metodę afterCalculateDeliveryDate lub ewentualnie aroundCalculateDeliveryDate dodając indywidualną logikę biznesową.


  1. Modyfikacje procesu składania zamówienia

Proces tworzenia zamówienia został szczegółowo opisany w rozdziale Proces Tworzenia Zamówienia. W celu dokonania zmian w procesie tworzenia zamówienia lub walidacji wstępnej danych przesyłanych od InPost wystarczy poprzez plik di.xml wstrzyknąć dodatkowe kroki bądź poprzez zdefiniowanie pluginu dla klas walidatora i/lub procesora zamówień:


 

Moduł Restrykcji

Aby umożliwić wykluczanie poszczególnych produktów z obsługi przez InPost Pay powstał osobny dedykowany moduł InPost_Restrictions. Moduł ten wymagany jest przez główną wtyczkę InPost_InPostPay. Konfiguracja restrykcji opisana jest w dziale: Konfiguracja produktów objętych restrykcjami i brakiem możliwości sprzedaży poprzez InPost Pay.

W ramach modułu InPost_Restrictions powstały dwie tabele w bazie danych:

inpost_restrictions_rule - zawiera definicje reguł wykluczeń produktów
inpost_restrictions_rule_product - zawiera produkty spełniające kryteria reguł

Reguły Restrykcji po zapisaniu automatycznie generują listę produktów i zapisują ją w bazie danych. Należy mieć na uwadzę, że natywny mechanizm walidujący zestaw reguł działa w taki sposób, że wszystkie produkty dla wszystkich store w skonfigurowanym website przechodzą przez skonfigurowany filtr i na tej podstawie budowana jest list ID produktów spełniających kryteria. Może to oznaczać, że w przypadku kilkudziesięciu tysięcy produktów dla instancji Magento mającej wiele store dla danego website proces zapisu reguły może być wydłużony od kilku do kilkunastu/kilkudziesięciu sekund. Jest to proces w założeniu jednorazowy i ze względu na maksymalne uproszczenie w instalacji i konfiguracji wtyczki wykonywwany jest synchronicznie, aby uniknąć konieczności wymagania od Merchanta dodawania i pilnowania procesów CRON.*

Na stronie produktowej, tych towarów, których ID znajdują się na liście nie będzie ładowanego widgetu do powiązania koszyka. Jeśli produkt zostanie mimo to dodany do koszyka po jego powiazaniu z aplikacją, w aplikacji powinien wyświetlić się komunikat ostrzegający oraz nie będą dostępne żadne metody dostawy, aby uniemożliwić dokończenie takiego zamówienia w aplikacji.

Informacje związane z optymalizacją:

Aby zminimalizować wszelkie opóźnienia w ładowaniu strony, przy sprawdzaniu czy produkt jest objęty restrykcjami wykorzystywany jest Cache Magento.

W natywnym zarządzaniu cache należy upewnić się, że dla tej pozycji jest on włączony.

Cache restrykcji jak i FPC po tagach produktów objętych restrykcjami automatycznie czyści się dla zapisywanej reguły i jej produktów. Nawet jeśli cache jest wyłączony bądź nie wygrzany kolekcja produktów pobiera się bezpośrednio z jednej tabeli w bazie z indeksowanych kolumn aby zminimalizować opóźnienia w ładowaniu strony wynikające z ustalania czy widget ma się wyświetlić czy nie.

Proces ten zachodzi w obserwerze:


 

Czyszczenie atrybutów tekstowych z HTML i znaków specjalnych

Ze względu na ograniczenia i reguły zabezpień po stronie serwerów API InPost Pay dane wysyłane w żądaniach nie mogą posiadać kodu HTML jak i niektórych znaków specjalnych.
W przypadku wystąpienia niedozwolonego znaku specjalnego, przykładowo w opisie produktu będącego w koszyku synchronizowanym z aplikacją klienta w telefonie, serwer ucina część danych żądania skutkując odpowiedzią kodem 403 - uniemożliwiając komunikację.

W związku z tym, że Magento dla atrybutów typu description implementuje page builder i pozwala na szeroki zakres manipulacji opisem w postacji HTML, został utworzony mechanizm oczyszczania atrybutów tekstowych.

Klasa odpowiedzialna za oczyszczanie tekstu z HTML i znaków specjalnych to:
\InPost\InPostPay\Model\Utils\StringUtils

Metoda cleanUpString wykonuje szereg operacji podmiany tekstu w oparciu o wyrażenia regularne, aby usunąć wszelkie znaczniki, style, tagi, osadzone zdjęcia itp. Oprócz tego klasa ta wykorzystuje dodatkową listę znaków specjalnych, podlegających usunięciu z tekstu, znajdującą się tu:
\InPost\InPostPay\Provider\Description\ForbiddenSignsAndPhrases

Wszyskie wartości z tablicy $forbiddenSignsAndPhrases w powyższej klasie łączone są w wyrażenie regularne, którym następnie oczyszczany jest tekst atrybutów.


 

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

W celu utworzenia zwrotu (transaction refund) w InPost niezbędne jest wygenerowanie sygnatury oraz dołączenie jej wraz z wysyłanym requestem.

Jest to dodatkowy podpis wiadomości wymagany do weryfikacji autentyczności żądania. Obliczany przez połączenie wartości kilku pól. Szczegółowy opis budowania sygnatury można znaleźć w publicznej dokumentacji InPost: Sygnatura dla zwrotów

Do generowania sygnatury służy następujący serwis:
\InPost\InPostPay\Service\Refund\SignatureGenerator

który jako parametr przyjmuje interfejs:

\InPost\InPostPay\Api\Data\Merchant\RefundInterface

 

Na podstawie przekazanych danych:

  • X-Command-ID - pole obowiązkowe

  • transaction_id - pole obowiązkowe

  • external_refund_id - pole opcjonalne

  • refund_amount - pole opcjonalne - jeśli pole będzie puste, to zostanie zwrócona pełna kwota

  • additional_business_data - pole opcjonalne

  • merchantSecret - dodatkowe, obowiązkowe pole, które jest pobierane z konfiguracji
    Stores -> Configuration -> Sales -> Payment Methods -> InPost Pay -> Ustawienia Autoryzacji

jest generowana sygnatura, która jest dołączana do request'u o zwrotu środków za wskazaną transakcję.

Domyślnym algorytmem hash’ującym jest algorytm: sha512 , ale można również użyć innego.

 


 

GraphQL

Dokumentacja poświęcona implementacji wtyczki w środowisku opartym o Magento i PWA.

Query i Mutacje

Lista Query i Mutacji GraphQL obsługiwanych przez Backend Magento w celu zapewnienia funkcjonalności wymaganych przez Widget InPost Pay.

Mutacje:
inPostPayInitBasket - wykorzystywane do zainicjowania powiązania przeglądarki, a potem do przekazania telefonu i prefixu w celu połączenia koszyka Magento z Aplikacją Mobilną InPost Pay.

inPostPayDeleteBrowserBinding - wykorzystywane do usunięcia powiązania zaufanej przeglądarki

inPostPayDeleteBasketBinding - wykorzystywane do usunięcia powiązania koszyka z aplikacji mobilnej (inicjowane w przeglądarce)

Query:

inPostPayGetBasketConfirmation - wykorzystywane do sprawdzenia czy powiązanie koszyka zostało potwierdzone w Aplikacji Mobilnej InPost Pay

inPostPayGetBasketMobileLink - wykorzystywane do pobrania linku do alternatywnego powiązania koszyka z aplikacją poprzez deep link kierujący z przeglądarki w urządzeniu Android/iOS bezpośrednio do aplikacji.

inPostPayGetPlacedOrderData - wykorzystane do sprawdzenia czy zostało złożone zamówienie w Aplikacji Mobilnej InPost Pay zamówienie z powiązanego koszyka.

 

Sposób użycia wyżej wymienionych metod GraphQL najłatwiej przeanalizować na podstawie przykładowych, testowych żądań opisanych w postaci dwóch scenariuszy w dziale: Testy

Testy

Scenariusz testowy do manualnego odtworzenia na środowisku z wykorzystaniem aplikacji Postman (lub podobnej).

Opis scenariusza #1:

Poniższa lista kroków ma sprawdzić pozytywny przebieg zakupowy. Klient dodaje produkt do koszyka, paruje go po numerze telefonu, potwierdza w aplikacji dodanie koszyka, następnie dokonuje zakupu, a backend zwraca dane tego złożonego zamówienia.

 

Opis scenariusza #2:

Poniższa lista kroków ma sprawdzić pozytywny przebieg parowania przeglądarki i koszyka oraz chęć klienta do usunięcia parowania koszyka i zaufanej przeglądarki. Klient dodaje produkt do koszyka, paruje go po numerze telefonu, potwierdza w aplikacji dodanie koszyka, następnie usuwa powiązanie przeglądarki i koszyka.


Scenariusz #1 w Postman:

Krok 1 - zainicjowanie pustego koszyka [natywna funkcjonalność Magento]:
POST: https://inpost.fwc.pl/graphql

Odpowiedź:

Uwagi:
Powyższy identyfikator koszyka kopiujemy i przekazujemy w kolejnych zapytaniach jako cart_id

 

Krok 2 - dodanie do koszyka produktu prostego [natywna funkcjonalność Magento]:

POST: https://inpost.fwc.pl/graphql

Odpowiedź:

 

 

Krok 3 - zainicjowanie powiązania przeglądarki z InPost Pay [funkcjonalność InPost Pay]:
POST: https://inpost.fwc.pl/graphql

Odpowiedź:

Uwagi:
wartość browser to base64 z danych przeglądarki generowana przez JS widgetu. W tym przypadku to:

Przy inicjacji nie są potrzebne dane numeru telefonu, prefix. Będą one potrzebne w kolejnym kroku.

 

Krok 4 - zainicjowanie powiązania koszyka z InPost Pay [funkcjonalność InPost Pay]:
POST: https://inpost.fwc.pl/graphql

Odpowiedź:

Uwagi:
Należy wysłać ponownie ten sam request co w kroku 3. wzbogacony o numer telefonu i prefix kraju docelowo pobrany z formularza od klienta.

 

Krok 5 - sprawdzenie czy klient potwierdził koszyk w aplikacji mobilnej [funkcjonalność InPost Pay]:
POST: https://inpost.fwc.pl/graphql

Odpowiedź (bez potwierdzenia w aplikacji mobilnej):

Uwagi:
Jeśli nie potwierdzono w aplikacji koszyka, odpowiedź serwera w polu action będzie “retry”. Oznacza, że docelowo to żądanie należy powtarzać, aż klient nie potwierdzi koszyka w aplikacji.
Jeśli koszyk zostanie potwierdzony dane jakie zostaną zwrócone będą wyglądać następująco:

Odpowiedź (po potwierdzeniu w aplikacji mobilnej):

Uwagi:
Z informacji zwracanych przez ten endpoint zapisać należy “basket_id” ponieważ będzie potrzebny w celu sprawdzania czy zostało złożone zamówienie na ten powiązany koszyk.

 

Krok 6 - pobranie linku do alternatywnej formy powiązania koszyka [funkcjonalność InPost Pay]:
POST: https://inpost.fwc.pl/graphql

Odpowiedź:

 

 

Krok 7 - sprawdzenie czy zostało złożone zamówienie na powiązany koszyk [funkcjonalność InPost Pay]:
POST: https://inpost.fwc.pl/graphql

Odpowiedź (w przypadku braku złożonego zamówienia w aplikacji na powiązany koszyk):

Uwagi:
Pole action o wartości refresh oznacza, że jeszcze nie zostało złożone zamówienie i docelowo należy powtarzać to zapytanie aż do momentu złożenia zamówienia w aplikacji, co spowoduje zwrócenie danych zamówienia.

Odpowiedź (w przypadku złożonego zamówienia w aplikacji na powiązany koszyk):

Uwagi:
Pole action o wartości redirect wraz z numerem zamówienia i statusem oznacza, że należy przekierować lub wyrenderować “success page” z zamówieniem. Dodatkowe dane zamówienia jeśli wymaga tego projekt wizualny należy pobrać innymi natywnymi lub przygotowanymi query.

 

Pobieranie konfiguracji sposobu wyświetlania widgetu:

POST: https://inpost.fwc.pl/graphql

Odpowiedź (w przypadku braku złożonego zamówienia w aplikacji na powiązany koszyk):

Uwagi:
powyższe wartości odpowiadają następującym konfiguracjom:


Scenariusz #2 w Postman:

Kroki 1,2,3,4 i 5 powtarzamy ze scenariusza #1, potwierdzamy koszyk:
Przykładowy nowy identyfikator uzyskany w wyniku wykonania powyższych kroków:

 

Krok 6 - usunięcie powiązania przeglądarki [natywna funkcjonalność Magento]:
POST: https://inpost.fwc.pl/graphql

Odpowiedź:

 

Krok 7 - usunięcie powiązania [natywna funkcjonalność Magento]:

POST: https://inpost.fwc.pl/graphql

Odpowiedź:

Uwagi:
W rezultacie wykonania powyższych czynności koszyk powinien całkowicie zniknąć z aplikacji.