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.03.2024 r.) wersja pilotażowa*

 

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

 

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:
https://experienceleague.adobe.com/docs/commerce-operations/installation-guide/system-requirements.html?lang=en

 

Opcjonalne funkcjonalności:


 

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.

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

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.

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.

 

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

Link do zgody

link do pełnej treści zgody.

 

Widok konfiguracji:


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:

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

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:

 


 

 

 

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ć

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:

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.


 

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:

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:

$requestSignature, $requestSignatureTimestamp, $requestPublicKeyVersion, $requestPublicKeyHash, $requestBody

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.

    \InPost\InPostPay\Validator\SignatureValidator::validateRequestPublicKeyBase64Hash
    1. W tym celu następuje najpierw autoryzacja za pomocą danych dostępowych z konfiguracji w celu pobrania tokenu.

      \InPost\InPostPay\Service\ApiConnector\PublicKeyGenerator
    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