InPost Pay - Magento

Open

Wstęp

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

Wtyczka: (19.07.2024 r.)

Open

*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

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

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ą (https://experienceleague.adobe.com/docs/commerce-operations/configuration-guide/message-queues/manage-message-queues.html ) lub wykorzystać narzędzia typu Supervisord (https://supervisord.readthedocs.io/en/latest/ )

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:

Widok konfiguracji:

Open

Ogólne Ustawienia

Ścieżka konfiguracji:
Store->Configuration->Sales->Payment Methods->InPost Pay->Ustawienia Ogólne

Opis pól konfigurowalnych:

Widok konfiguracji:

Sandbox

Ścieżka konfiguracji:
Store->Configuration->Sales->Payment Methods->InPost Pay->Sandbox

Opis pól konfigurowalnych:

Widok konfiguracji:

Ustawienia Autoryzacji

Ścieżka konfiguracji:
Store->Configuration->Sales->Payment Methods->InPost Pay->Ustawienia Autoryzacji

Opis pól konfigurowalnych:

Widok konfiguracji:

Ustawienia Debuggowania

Ścieżka konfiguracji:
Store->Configuration->Sales->Payment Methods->InPost Pay->Ustawienia Debuggowania

Opis pól konfigurowalnych:

Widok konfiguracji:

Ustawienia IZI API

Ścieżka konfiguracji:
Store->Configuration->Sales->Payment Methods->InPost Pay->Ustawienia IZI API

Opis pól konfigurowalnych:

Widok konfiguracji:

Mapowanie zgód

Ścieżka konfiguracji:
Store->Configuration->Sales->Payment Methods->InPost Pay->Terms and Conditions Mapping Settings

Opis pól konfigurowalnych:

Widok konfiguracji:

Ustawienia wyświetlania

Ścieżka konfiguracji:
Store → Configuration → Sales → Payment Methods → InPost Pay → Ustawienia wyświetlania

Opis pól konfigurowalnych:

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:

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.

Taka zmiana wymagała przekonfigurowania zależności w komponencie paska postępu:

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:

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

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

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:

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:

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.

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

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