InPost Pay - Magento

Wstęp

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

Wtyczka: 1.0.12 (17.12.2024 r.)

Changelog

Nowa wersja: 1.0.12 (17.12.2024 r.)
Poprawiono:
- Obsługa produktów typu bundle
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

1 Wstęp
- 1.1 Changelog
2 Wymagania Systemowe
3 Konfiguracja
- 3.1 Mapowanie Metod Dostawy
- 3.2 Ogólne Ustawienia
- 3.3 Sandbox
- 3.4 Ustawienia Autoryzacji
- 3.5 Ustawienia Debuggowania
- 3.6 Ustawienia IZI API
- 3.7 Mapowanie zgód (zmiany od wersji 1.0.8)
- 3.8 Ustawienia wyświetlania
- 3.9 Ustawienia układu przycisków
- 3.10 Ustawienia Cache
- 3.11 Instalacja modułu - dodatkowe informacje
- 3.12 Ustawienia odpytywania Long Polling
- 3.13 Ustawienia Omnibus (zmiany od wersji 1.0.8)
- 3.14 Ustawienia Restrykcji (zmiany od wersji 1.0.8)
4 Instrukcja użytkowania
5 Dokumentacja Techniczna - Backend
- 5.1 Weryfikacja Sygnatury
- 5.2 Connector API
- 5.3 Interfejs Żądań do API InPost
- 5.4 Obsługa żądań do API InPost i formatowanie odpowiedzi
- 5.5 Relacja pomiędzy oficjalną wtyczką Smartmage_Inpost a InPost_InPostPay
- 5.6 Debuggowanie
- 5.7 Kontrolery frontowe
- 5.8 Implementacje REST API Magento
  - 5.8.1 DELETE /v1/izi/basket/:basketId/binding
  - 5.8.2 POST /v1/izi/basket/:basketId/confirmation
  - 5.8.3 GET /v1/izi/basket/:basketId
  - 5.8.4 POST /v1/izi/basket/:basketId/event
  - 5.8.5 POST /v1/izi/order
  - 5.8.6 GET /v1/izi/order/:orderId
  - 5.8.7 POST /v1/izi/order/:orderId/event
- 5.9 Proces Tworzenia Zamówienia
- 5.10 Obiekty zwracane przez API Magento
  - 5.10.1 Koszyk InPost Pay (Basket)
  - 5.10.2 Zamówienie InPost Pay (InPostOrder)
- 5.11 Modyfikacje indywidualne pod Merchanta
- 5.12 Moduł Restrykcji
- 5.13 Czyszczenie atrybutów tekstowych z HTML i znaków specjalnych
- 5.14 Ograniczenie dostaw tylko do PL
- 5.15 Produkty bundle
- 5.16 Generowanie Sygnatury dla zwrotów
6 GraphQL
- 6.1 Query i Mutacje
- 6.2 Testy

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

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

Pamiętaj!
Ustawienia wyświetlania oraz układ przycisków należy skonfigurować zgodnie ze Standardami Implementacji InPost Pay.

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

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

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:

Failed to create InPostPay refund. Check logs for more information.

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

[2024-04-11T11:44:51.500293+00:00] main.DEBUG: [6617cd32b1f4f] SENDING: IZI API request. Context: {"method":"POST","endpoint_url":"https:\/\/sandbox-api.inpost.pl\/v1\/izi\/transaction\/af6e13b6-5f2d-4855-99f6-8c6fbecb9040\/refund","headers":{"Content-Type":"application\/json","Authorization":" Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJkVzROZW9TeXk0OHpCOHg4emdZX2t5dFNiWHY3blZ0eFVGVFpzWV9TUFA4In0.eyJleHAiOjE3MTI4MzYxOTAsImlhdCI6MTcxMjgzNTg5MCwianRpIjoiMmFiNjQzNjctMDZiYy00ZWZkLTgzZjYtZjNiNWY5YTM2ZThjIiwiaXNzIjoiaHR0cHM6Ly9zYW5kYm94LWxvZ2luLmlucG9zdC5wbC9hdXRoL3JlYWxtcy9leHRlcm5hbCIsInN1YiI6Ijg5NzRjMGYyLWMyZjYtNDExMS1iYjJmLWM0ODEzYzUyMDdhNiIsInR5cCI6IkJlYXJlciIsImF6cCI6ImlwX3VhdC0wMDAyNiIsInNjb3BlIjoiaXppOnRyYW5zYWN0aW9uOnJlYWQgaXppOnRyYW5zYWN0aW9uOndyaXRlIGl6aTpvcmRlcjp3cml0ZSBpemk6YmFza2V0OndyaXRlIGl6aTpwYXltZW50LW1ldGhvZHM6cmVhZCBpemk6YnJvd3Nlcjp3cml0ZSIsImNsaWVudElkIjoiaXBfdWF0LTAwMDI2IiwiY2xpZW50SG9zdCI6Ijk1LjIxNi4xNS4yMTYiLCJtZXJjaGFudF9pZCI6IjAwMDI2IiwiY2xpZW50QWRkcmVzcyI6Ijk1LjIxNi4xNS4yMTYifQ.V2CCTXoYxNWWGjV6NcS4mLv8j2aRTjURz8-13TUc6FhRF4VwNnOL0ZUo78jlxZLLQeqBFVeaF53vuGtqi-eH3ViGAW1CCVNwDzw8P0NtYO_KsWAgUWsgE09nPh3LIiU66-QmWjndziQnPSdAM3SkYniLPWkRRLbBymoLhTtV-V73Gxs7VtPnee5VJMrRJeKOLRj6AlKU_rmc3QDkJwN-GDzIwh1rB21lfekWbsBbxmytc-7hBAqOdJ3XRO2qZJcX8eRW9IfUdZt7xssxluqNpoglK2pIJipQ_ADXdKA7uW-McJgOJRxc2W_CCDgJvZU5sgCm6CG-A8zFhZQhuKG23Q","X-Command-ID":"1722c342-7b83-441b-853d-304a3e2e2e8f"},"params":{"x_command_id":"1722c342-7b83-441b-853d-304a3e2e2e8f","transaction_id":"af6e13b6-5f2d-4855-99f6-8c6fbecb9040","external_refund_id":"fd69cab2-2791-4efe-b1c7-7bd3fefa5cf2","refund_amount":51.66,"signature":"SHA-512_5920539498ae32fc42f2cbbfc7a77cddd83b1e91623cbab1b5e113020f7d5b9269d297d2a14538e342779dc5b4ec23e5d33efebf16881f84f8d75beab01e7232","additional_business_data":null}} [] []
[2024-04-11T11:44:56.319862+00:00] main.CRITICAL: [6617cd32b1f4f] InPost API endpoint "https://sandbox-api.inpost.pl/v1/izi/transaction/af6e13b6-5f2d-4855-99f6-8c6fbecb9040/refund" responded[422] with an error: Client error: `POST https://sandbox-api.inpost.pl/v1/izi/transaction/af6e13b6-5f2d-4855-99f6-8c6fbecb9040/refund` resulted in a `422 Unprocessable Entity` response:
{"status":422,"error":"unavailable_balance","message":"Merchant account balance is currently unavailable","details":{}}

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:

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

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.
  \InPost\InPostPay\Service\ApiConnector\TokenGenerator
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.
  \InPost\InPostPay\Provider\PublicKeyProvider
Wygenerowanie sygnatury na podstawie algorytmu opisanego w dokumentacji InPost oraz porównanie go z odkodowaną wartością sygnatury z nagłówka aktualnie weryfikowanego żądania.
\InPost\InPostPay\Validator\SignatureValidator::validateSignature
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
  \InPost\InPostPay\Validator\SignatureValidator::getOpenSSLAsymmetricKey
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
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.
\InPost\InPostPay\Validator\SignatureValidator::validateSignatureLifetime

Connector API

Interfejs wykorzystywany do realizacji zapytań kierowanych z Magento do API InPost.

\InPost\InPostPay\Api\ApiConnector\ConnectorInterface

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:

\InPost\InPostPay\Api\ApiConnector\RequestInterface

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

\InPost\InPostPay\Api\ApiConnector\RequestInterface

W ramach interfejsu wymagane jest zaimplementowanie metod danego żądania:
getApiUrl

getMethod

getContentType

getBearerToken

getParams

setParams

Aktualna lista żądań:

\InPost\InPostPay\Model\AuthApi\Request\OAuthTokenRequest
\InPost\InPostPay\Model\IziApi\Request\PublicKeyRequest
\InPost\InPostPay\Model\IziApi\Request\BasketBindingVerifyRequest
\InPost\InPostPay\Model\IziApi\Request\BasketBindingRequest
\InPost\InPostPay\Model\IziApi\Request\BasketBindingDeleteRequest
\InPost\InPostPay\Model\IziApi\Request\BasketRequest
\InPost\InPostPay\Model\IziApi\Request\DeleteBrowserBindingRequest
\InPost\InPostPay\Model\IziApi\Request\UpdateOrderRequest

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

\InPost\InPostPay\Api\ApiConnector\RequestInterface

(Lista metod i implementacji: Interfejs Żądań do API InPost )

następnie wysłanie ich poprzez Connector API

\InPost\InPostPay\Api\ApiConnector\ConnectorInterface

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:

\InPost\InPostPay\Service\ApiConnector\TokenGenerator
\InPost\InPostPay\Service\ApiConnector\PublicKeyGenerator
\InPost\InPostPay\Service\ApiConnector\BasketBindingCheck
\InPost\InPostPay\Service\ApiConnector\BasketBindingCreate
\InPost\InPostPay\Service\ApiConnector\BasketBindingDelete
\InPost\InPostPay\Service\ApiConnector\BrowserBinding
\InPost\InPostPay\Service\ApiConnector\CreateOrUpdateBasket
\InPost\InPostPay\Service\ApiConnector\UpdateOrder

Aktualna lista odpowiedzi na żądania:

\InPost\InPostPay\Model\AuthApi\Response\OAuthTokenResponse
\InPost\InPostPay\Model\IziApi\Response\PublicKeyResponse
\InPost\InPostPay\Model\IziApi\Response\BasketResponse
\InPost\InPostPay\Model\IziApi\Response\BasketInformationResponse

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:

quote.inpost_locker_id
sales_order.inpost_locker_id

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:

\Smartmage\Inpost\Observer\SaveOrderBeforeSalesModelQuoteObserver

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:

DEBUG
INFO
NOTICE
WARNING
ERROR
CRITICAL
ALERT
EMERGENCY

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:

<type name="InPost\InPostPay\Validator\SignatureValidator">
        <arguments>
            <argument name="logger" xsi:type="object">InPost\InPostPay\Logger\InPostPayLogger</argument>
        </arguments>
    </type>

W konstruktorze tego obiektu logger to:

private readonly \Psr\Log\LoggerInterface $logger

Poziom logów określa metoda wywołana na obiekcie $logger:

$this->logger->debug(...);
$this->logger->info(...);
...
$this->logger->critical(...);
..
$this->logger->emergency(...);

Przechowywanie logów:

Za miejsce przechowywania logów odpowiada:

\InPost\InPostPay\Logger\Handler

gdzie w konstruktorze budowana jest ścieżka do pliku .log mająca formę opartą o aktualną datę, przykładowo:

{root-magento-2}/var/log/inpost-pay/2023-11-15.log

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:

$this->logger->debug(
  sprintf('API Request for endpoint: %s. Payload: %s', $url, $this->base64serializer->serialize($logData))
);

Przykład logów:

[2023-11-07T15:12:46.500919+00:00] main.DEBUG: [654a53ee7a4c3] API Request for endpoint: https://sandbox-login.inpost.pl/auth/realms/external/protocol/openid-connect/token. Payload: eyJoZWFk ... bHMifX0= [] []
[2023-11-07T15:12:46.848677+00:00] main.DEBUG: [654a53ee7a4c3] API Response:200. Content: eyJib2R5I ... RlXCJ9In0= [] []
[2023-11-07T15:12:46.851369+00:00] main.DEBUG: [654a53ee7a4c3] API Request for endpoint: https://sandbox-api.inpost.pl/v1/izi/signing-keys/public. Payload: eyJoZWFkZXJ... bXMiOltdfQ== [] []
[2023-11-07T15:12:47.228141+00:00] main.DEBUG: [654a53ee7a4c3] API Response:200. Content: eyJib2R5 .. mUwXCJ9In0= [] []
[2023-11-07T15:12:47.232101+00:00] main.ERROR: [654a53ee7a4c3] Signature validation process failed. Reason: Niepoprawna sygnatura [] []

Kontrolery frontowe

Kontrolery wykorzystywane przy komunikacji widgetu frontowego z backendem Magento.

GET  inpostizi/BasketBinding/Delete
GET  inpostizi/BasketConfirmation/Get
POST inpostizi/PayData/Get
GET  inpostizi/MobileLink/Get
GET  inpostizi/OrderComplete/Get/?basketId={basketId}

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

{
  "error_code": "BAD_REQUEST",
  "error_message": "Invalid request."
}

InPost\InPostPay\Exception\InPostPayAuthorizationException 401

{
  "error_code": "UNAUTHORIZED",
  "error_message": "Given user is not authorized to access the resource."
}

InPost\InPostPay\Exception\BasketNotFoundException 404

{
  "error_code": "BASKET_NOT_FOUND",
  "error_message": "Basket not found."
}

InPost\InPostPay\Exception\InPostPayInternalException 500

{
  "error_code": "INTERNAL_SERVER_ERROR",
  "error_message": "Something went wrong. Please try again later."
}

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:

{
  "status": "string",
  "inpostBasketId": "string",
  "phoneNumber": {
    "country_prefix": "string",
    "phone": "string"
  },
  "browser": {
    "browser_trusted": true,
    "browser_id": "string"
  },
  "maskedPhoneNumber": "string",
  "name": "string",
  "surname": "string"
}

Odpowiedź 200

{
  "browser_id": "string",
  "basket_id": "string",
  "summary": {
    "basket_base_price": {
      "net": 0,
      "gross": 0,
      "vat": 0
    },
    "basket_final_price": {
      "net": 0,
      "gross": 0,
      "vat": 0
    },
    "basket_promo_price": {
      "net": 0,
      "gross": 0,
      "vat": 0
    },
    "currency": "string",
    "basket_additional_information": "string",
    "payment_type": [
      "string"
    ],
    "basket_expiration_date": "string"
  },
  "delivery": [
    {
      "delivery_type": "string",
      "delivery_date": "string",
      "delivery_options": [
        {
          "delivery_name": "string",
          "delivery_code_value": "string",
          "delivery_option_price": {
            "net": 0,
            "gross": 0,
            "vat": 0
          }
        }
      ],
      "delivery_price": {
        "net": 0,
        "gross": 0,
        "vat": 0
      },
      "free_delivery_minimum_gross_price": 0
    }
  ],
  "promo_codes": [
    {
      "name": "string",
      "promo_code_value": "string"
    }
  ],
  "products": [
    {
      "product_id": "string",
      "product_category": "string",
      "ean": "string",
      "product_name": "string",
      "product_description": "string",
      "product_link": "string",
      "product_image": "string",
      "base_price": {
        "net": 0,
        "gross": 0,
        "vat": 0
      },
      "lowest_price": {
        "net": 0,
        "gross": 0,
        "vat": 0
      },
      "promo_price": {
        "net": 0,
        "gross": 0,
        "vat": 0
      },
      "quantity": {
        "quantity": 0,
        "quantity_type": "string",
        "quantity_unit": "string",
        "available_quantity": 0,
        "max_quantity": 0
      },
      "product_attributes": [
        {
          "attribute_name": "string",
          "attribute_value": "string"
        }
      ]
    }
  ],
  "related_products": [
    {
      "product_id": "string",
      "product_category": "string",
      "ean": "string",
      "product_name": "string",
      "product_description": "string",
      "product_link": "string",
      "product_image": "string",
      "base_price": {
        "net": 0,
        "gross": 0,
        "vat": 0
      },
      "lowest_price": {
        "net": 0,
        "gross": 0,
        "vat": 0
      },
      "promo_price": {
        "net": 0,
        "gross": 0,
        "vat": 0
      },
      "quantity": {
        "quantity": 0,
        "quantity_type": "string",
        "quantity_unit": "string",
        "available_quantity": 0,
        "max_quantity": 0
      },
      "product_attributes": [
        {
          "attribute_name": "string",
          "attribute_value": "string"
        }
      ]
    }
  ],
  "consents": [
    {
      "consent_id": "string",
      "consent_link": "string",
      "consent_description": "string",
      "consent_version": "string",
      "requirement_type": "string"
    }
  ],
  "status": "string"
}

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

{
  "error_code": "BAD_REQUEST",
  "error_message": "Invalid request."
}

InPost\InPostPay\Exception\InPostPayAuthorizationException 401

{
  "error_code": "UNAUTHORIZED",
  "error_message": "Given user is not authorized to access the resource."
}

InPost\InPostPay\Exception\BasketNotFoundException 404

{
  "error_code": "BASKET_NOT_FOUND",
  "error_message": "Basket not found."
}

InPost\InPostPay\Exception\InPostPayInternalException 500

{
  "error_code": "INTERNAL_SERVER_ERROR",
  "error_message": "Something went wrong. Please try again later."
}

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

{
  "browser_id": "string",
  "basket_id": "string",
  "summary": {
    "basket_base_price": {
      "net": 0,
      "gross": 0,
      "vat": 0
    },
    "basket_final_price": {
      "net": 0,
      "gross": 0,
      "vat": 0
    },
    "basket_promo_price": {
      "net": 0,
      "gross": 0,
      "vat": 0
    },
    "currency": "string",
    "basket_additional_information": "string",
    "payment_type": [
      "string"
    ],
    "basket_expiration_date": "string"
  },
  "delivery": [
    {
      "delivery_type": "string",
      "delivery_date": "string",
      "delivery_options": [
        {
          "delivery_name": "string",
          "delivery_code_value": "string",
          "delivery_option_price": {
            "net": 0,
            "gross": 0,
            "vat": 0
          }
        }
      ],
      "delivery_price": {
        "net": 0,
        "gross": 0,
        "vat": 0
      },
      "free_delivery_minimum_gross_price": 0
    }
  ],
  "promo_codes": [
    {
      "name": "string",
      "promo_code_value": "string"
    }
  ],
  "products": [
    {
      "product_id": "string",
      "product_category": "string",
      "ean": "string",
      "product_name": "string",
      "product_description": "string",
      "product_link": "string",
      "product_image": "string",
      "base_price": {
        "net": 0,
        "gross": 0,
        "vat": 0
      },
      "lowest_price": {
        "net": 0,
        "gross": 0,
        "vat": 0
      },
      "promo_price": {
        "net": 0,
        "gross": 0,
        "vat": 0
      },
      "quantity": {
        "quantity": 0,
        "quantity_type": "string",
        "quantity_unit": "string",
        "available_quantity": 0,
        "max_quantity": 0
      },
      "product_attributes": [
        {
          "attribute_name": "string",
          "attribute_value": "string"
        }
      ]
    }
  ],
  "related_products": [
    {
      "product_id": "string",
      "product_category": "string",
      "ean": "string",
      "product_name": "string",
      "product_description": "string",
      "product_link": "string",
      "product_image": "string",
      "base_price": {
        "net": 0,
        "gross": 0,
        "vat": 0
      },
      "lowest_price": {
        "net": 0,
        "gross": 0,
        "vat": 0
      },
      "promo_price": {
        "net": 0,
        "gross": 0,
        "vat": 0
      },
      "quantity": {
        "quantity": 0,
        "quantity_type": "string",
        "quantity_unit": "string",
        "available_quantity": 0,
        "max_quantity": 0
      },
      "product_attributes": [
        {
          "attribute_name": "string",
          "attribute_value": "string"
        }
      ]
    }
  ],
  "consents": [
    {
      "consent_id": "string",
      "consent_link": "string",
      "consent_description": "string",
      "consent_version": "string",
      "requirement_type": "string"
    }
  ],
  "status": "string"
}

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

{
  "error_code": "BAD_REQUEST",
  "error_message": "Invalid request."
}

InPost\InPostPay\Exception\InPostPayAuthorizationException 401

{
  "error_code": "UNAUTHORIZED",
  "error_message": "Given user is not authorized to access the resource."
}

InPost\InPostPay\Exception\BasketNotFoundException 404

{
  "error_code": "BASKET_NOT_FOUND",
  "error_message": "Basket not found."
}

InPost\InPostPay\Exception\InPostPayInternalException 500

{
  "error_code": "INTERNAL_SERVER_ERROR",
  "error_message": "Something went wrong. Please try again later."
}

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:

{
  "eventId": "string",
  "eventDataTime": "string",
  "eventType": "string",
  "quantityEventData": [
    {
      "product_id": "string",
      "ean": "string",
      "quantity": {
        "quantity": 0
      }
    }
  ],
  "relatedProductsEventData": [
    {
      "product_id": "string",
      "ean": "string",
      "quantity": {
        "quantity": 0
      }
    }
  ],
  "promoCodesEventData": [
    {
      "name": "string",
      "promo_code_value": "string"
    }
  ]
}

Odpowiedź 200:

{
  "browser_id": "string",
  "basket_id": "string",
  "summary": {
    "basket_base_price": {
      "net": 0,
      "gross": 0,
      "vat": 0
    },
    "basket_final_price": {
      "net": 0,
      "gross": 0,
      "vat": 0
    },
    "basket_promo_price": {
      "net": 0,
      "gross": 0,
      "vat": 0
    },
    "currency": "string",
    "basket_additional_information": "string",
    "payment_type": [
      "string"
    ],
    "basket_expiration_date": "string"
  },
  "delivery": [
    {
      "delivery_type": "string",
      "delivery_date": "string",
      "delivery_options": [
        {
          "delivery_name": "string",
          "delivery_code_value": "string",
          "delivery_option_price": {
            "net": 0,
            "gross": 0,
            "vat": 0
          }
        }
      ],
      "delivery_price": {
        "net": 0,
        "gross": 0,
        "vat": 0
      },
      "free_delivery_minimum_gross_price": 0
    }
  ],
  "promo_codes": [
    {
      "name": "string",
      "promo_code_value": "string"
    }
  ],
  "products": [
    {
      "product_id": "string",
      "product_category": "string",
      "ean": "string",
      "product_name": "string",
      "product_description": "string",
      "product_link": "string",
      "product_image": "string",
      "base_price": {
        "net": 0,
        "gross": 0,
        "vat": 0
      },
      "lowest_price": {
        "net": 0,
        "gross": 0,
        "vat": 0
      },
      "promo_price": {
        "net": 0,
        "gross": 0,
        "vat": 0
      },
      "quantity": {
        "quantity": 0,
        "quantity_type": "string",
        "quantity_unit": "string",
        "available_quantity": 0,
        "max_quantity": 0
      },
      "product_attributes": [
        {
          "attribute_name": "string",
          "attribute_value": "string"
        }
      ]
    }
  ],
  "related_products": [
    {
      "product_id": "string",
      "product_category": "string",
      "ean": "string",
      "product_name": "string",
      "product_description": "string",
      "product_link": "string",
      "product_image": "string",
      "base_price": {
        "net": 0,
        "gross": 0,
        "vat": 0
      },
      "lowest_price": {
        "net": 0,
        "gross": 0,
        "vat": 0
      },
      "promo_price": {
        "net": 0,
        "gross": 0,
        "vat": 0
      },
      "quantity": {
        "quantity": 0,
        "quantity_type": "string",
        "quantity_unit": "string",
        "available_quantity": 0,
        "max_quantity": 0
      },
      "product_attributes": [
        {
          "attribute_name": "string",
          "attribute_value": "string"
        }
      ]
    }
  ],
  "consents": [
    {
      "consent_id": "string",
      "consent_link": "string",
      "consent_description": "string",
      "consent_version": "string",
      "requirement_type": "string"
    }
  ],
  "status": "string"
}

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

{
  "error_code": "BAD_REQUEST",
  "error_message": "Invalid request."
}

InPost\InPostPay\Exception\InPostPayAuthorizationException 401

{
  "error_code": "UNAUTHORIZED",
  "error_message": "Given user is not authorized to access the resource."
}

InPost\InPostPay\Exception\BasketNotFoundException 404

{
  "error_code": "BASKET_NOT_FOUND",
  "error_message": "Basket not found."
}

InPost\InPostPay\Exception\InPostPayInternalException 500

{
  "error_code": "INTERNAL_SERVER_ERROR",
  "error_message": "Something went wrong. Please try again later."
}

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:

{
  "orderDetails": {
    "basket_id": "string",
    "order_id": "string",
    "order_comments": "string",
    "basket_price": {
      "net": 0,
      "gross": 0,
      "vat": 0
    },
    "currency": "string",
    "payment_type": "string",
    "pos_id": "string",
    "order_creation_date": "string",
    "order_merchant_status_description": "string",
    "order_base_price": {
      "net": 0,
      "gross": 0,
      "vat": 0
    },
    "order_final_price": {
      "net": 0,
      "gross": 0,
      "vat": 0
    },
    "delivery_references_list": [
      "string"
    ]
  },
  "accountInfo": {
    "name": "string",
    "surname": "string",
    "phone_number": {
      "country_prefix": "string",
      "phone": "string"
    },
    "mail": "string",
    "client_address": {
      "country_code": "string",
      "address": "string",
      "address_details": {
        "street": "string",
        "building": "string",
        "flat": "string"
      },
      "city": "string",
      "postal_code": "string"
    }
  },
  "delivery": {
    "delivery_type": "string",
    "delivery_codes": [
      "string"
    ],
    "delivery_date": "string",
    "delivery_options": [
      {
        "delivery_name": "string",
        "delivery_code_value": "string",
        "delivery_option_price": {
          "net": 0,
          "gross": 0,
          "vat": 0
        }
      }
    ],
    "delivery_price": {
      "net": 0,
      "gross": 0,
      "vat": 0
    },
    "mail": "string",
    "delivery_point": "string",
    "courier_note": "string",
    "phone_number": {
      "country_prefix": "string",
      "phone": "string"
    },
    "delivery_address": {
      "name": "string",
      "country_code": "string",
      "address": "string",
      "city": "string",
      "postal_code": "string",
      "address_details": {
        "street": "string",
        "building": "string",
        "flat": "string"
      }
    }
  },
  "consents": [
    {
      "consent_id": "string",
      "consent_version": "string",
      "is_accepted": true
    }
  ],
  "invoiceDetails": {
    "legal_form": "string",
    "country_code": "string",
    "tax_id_prefix": "string",
    "tax_id": "string",
    "company_name": "string",
    "name": "string",
    "surname": "string",
    "city": "string",
    "street": "string",
    "building": "string",
    "flat": "string",
    "postal_code": "string",
    "mail": "string",
    "registration_data_edited": "string",
    "additional_information": "string"
  }
}

Odpowiedź 200:

{
  "order_details": {
    "basket_id": "string",
    "order_id": "string",
    "order_comments": "string",
    "basket_price": {
      "net": 0,
      "gross": 0,
      "vat": 0
    },
    "currency": "string",
    "payment_type": "string",
    "pos_id": "string",
    "order_creation_date": "string",
    "order_merchant_status_description": "string",
    "order_base_price": {
      "net": 0,
      "gross": 0,
      "vat": 0
    },
    "order_final_price": {
      "net": 0,
      "gross": 0,
      "vat": 0
    },
    "delivery_references_list": [
      "string"
    ]
  },
  "invoice_details": {
    "legal_form": "string",
    "country_code": "string",
    "tax_id_prefix": "string",
    "tax_id": "string",
    "company_name": "string",
    "name": "string",
    "surname": "string",
    "city": "string",
    "street": "string",
    "building": "string",
    "flat": "string",
    "postal_code": "string",
    "mail": "string",
    "registration_data_edited": "string",
    "additional_information": "string"
  },
  "account_info": {
    "name": "string",
    "surname": "string",
    "phone_number": {
      "country_prefix": "string",
      "phone": "string"
    },
    "mail": "string",
    "client_address": {
      "country_code": "string",
      "address": "string",
      "address_details": {
        "street": "string",
        "building": "string",
        "flat": "string"
      },
      "city": "string",
      "postal_code": "string"
    }
  },
  "delivery": {
    "delivery_type": "string",
    "delivery_codes": [
      "string"
    ],
    "delivery_date": "string",
    "delivery_options": [
      {
        "delivery_name": "string",
        "delivery_code_value": "string",
        "delivery_option_price": {
          "net": 0,
          "gross": 0,
          "vat": 0
        }
      }
    ],
    "delivery_price": {
      "net": 0,
      "gross": 0,
      "vat": 0
    },
    "mail": "string",
    "delivery_point": "string",
    "courier_note": "string",
    "phone_number": {
      "country_prefix": "string",
      "phone": "string"
    },
    "delivery_address": {
      "name": "string",
      "country_code": "string",
      "address": "string",
      "city": "string",
      "postal_code": "string",
      "address_details": {
        "street": "string",
        "building": "string",
        "flat": "string"
      }
    }
  },
  "consents": [
    {
      "consent_id": "string",
      "consent_version": "string",
      "is_accepted": true
    }
  ],
  "products": [
    {
      "product_id": "string",
      "product_category": "string",
      "ean": "string",
      "product_name": "string",
      "product_description": "string",
      "product_link": "string",
      "product_image": "string",
      "base_price": {
        "net": 0,
        "gross": 0,
        "vat": 0
      },
      "lowest_price": {
        "net": 0,
        "gross": 0,
        "vat": 0
      },
      "promo_price": {
        "net": 0,
        "gross": 0,
        "vat": 0
      },
      "quantity": {
        "quantity": 0,
        "quantity_type": "string",
        "quantity_unit": "string",
        "available_quantity": 0,
        "max_quantity": 0
      },
      "product_attributes": [
        {
          "attribute_name": "string",
          "attribute_value": "string"
        }
      ]
    }
  ]
}

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

{
  "error_code": "BAD_REQUEST",
  "error_message": "Invalid request."
}

InPost\InPostPay\Exception\InPostPayAuthorizationException 401

{
  "error_code": "UNAUTHORIZED",
  "error_message": "Given user is not authorized to access the resource."
}

InPost\InPostPay\Exception\BasketNotFoundException 404

{
  "error_code": "BASKET_NOT_FOUND",
  "error_message": "Basket not found."
}

InPost\InPostPay\Exception\InPostPayInternalException 500

{
  "error_code": "INTERNAL_SERVER_ERROR",
  "error_message": "Something went wrong. Please try again later."
}

\InPost\InPostPay\Exception\OrderNotCreateException 409

{
  "error_code": "ORDER_NOT_CREATE",
  "error_message": "Order not create."

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

{
  "order_details": {
    "basket_id": "string",
    "order_id": "string",
    "order_comments": "string",
    "basket_price": {
      "net": 0,
      "gross": 0,
      "vat": 0
    },
    "currency": "string",
    "payment_type": "string",
    "pos_id": "string",
    "order_creation_date": "string",
    "order_merchant_status_description": "string",
    "order_base_price": {
      "net": 0,
      "gross": 0,
      "vat": 0
    },
    "order_final_price": {
      "net": 0,
      "gross": 0,
      "vat": 0
    },
    "delivery_references_list": [
      "string"
    ]
  },
  "invoice_details": {
    "legal_form": "string",
    "country_code": "string",
    "tax_id_prefix": "string",
    "tax_id": "string",
    "company_name": "string",
    "name": "string",
    "surname": "string",
    "city": "string",
    "street": "string",
    "building": "string",
    "flat": "string",
    "postal_code": "string",
    "mail": "string",
    "registration_data_edited": "string",
    "additional_information": "string"
  },
  "account_info": {
    "name": "string",
    "surname": "string",
    "phone_number": {
      "country_prefix": "string",
      "phone": "string"
    },
    "mail": "string",
    "client_address": {
      "country_code": "string",
      "address": "string",
      "address_details": {
        "street": "string",
        "building": "string",
        "flat": "string"
      },
      "city": "string",
      "postal_code": "string"
    }
  },
  "delivery": {
    "delivery_type": "string",
    "delivery_codes": [
      "string"
    ],
    "delivery_date": "string",
    "delivery_options": [
      {
        "delivery_name": "string",
        "delivery_code_value": "string",
        "delivery_option_price": {
          "net": 0,
          "gross": 0,
          "vat": 0
        }
      }
    ],
    "delivery_price": {
      "net": 0,
      "gross": 0,
      "vat": 0
    },
    "mail": "string",
    "delivery_point": "string",
    "courier_note": "string",
    "phone_number": {
      "country_prefix": "string",
      "phone": "string"
    },
    "delivery_address": {
      "name": "string",
      "country_code": "string",
      "address": "string",
      "city": "string",
      "postal_code": "string",
      "address_details": {
        "street": "string",
        "building": "string",
        "flat": "string"
      }
    }
  },
  "consents": [
    {
      "consent_id": "string",
      "consent_version": "string",
      "is_accepted": true
    }
  ],
  "products": [
    {
      "product_id": "string",
      "product_category": "string",
      "ean": "string",
      "product_name": "string",
      "product_description": "string",
      "product_link": "string",
      "product_image": "string",
      "base_price": {
        "net": 0,
        "gross": 0,
        "vat": 0
      },
      "lowest_price": {
        "net": 0,
        "gross": 0,
        "vat": 0
      },
      "promo_price": {
        "net": 0,
        "gross": 0,
        "vat": 0
      },
      "quantity": {
        "quantity": 0,
        "quantity_type": "string",
        "quantity_unit": "string",
        "available_quantity": 0,
        "max_quantity": 0
      },
      "product_attributes": [
        {
          "attribute_name": "string",
          "attribute_value": "string"
        }
      ]
    }
  ]
}

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

{
  "error_code": "BAD_REQUEST",
  "error_message": "Invalid request."
}

InPost\InPostPay\Exception\InPostPayAuthorizationException 401

{
  "error_code": "UNAUTHORIZED",
  "error_message": "Given user is not authorized to access the resource."
}

InPost\InPostPay\Exception\OrderNotFoundException 404

{
  "error_code": "ORDER_NOT_FOUND",
  "error_message": "Order not found."
}

InPost\InPostPay\Exception\InPostPayInternalException 500

{
  "error_code": "INTERNAL_SERVER_ERROR",
  "error_message": "Something went wrong. Please try again later."
}

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:

{
  "eventId": "string",
  "eventDataTime": "string",
  "eventData": {
    "payment_status": "string",
    "payment_id": "string",
    "payment_reference": "string",
    "payment_type": "string",
    "order_status": "string"
  },
  "phoneNumber": {
    "country_prefix": "string",
    "phone": "string"
  }
}

Odpowiedź 200:

{
  "order_status": "string",
  "order_merchant_status_description": "string",
  "delivery_references_list": [
    "string"
  ]
}

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

{
  "error_code": "BAD_REQUEST",
  "error_message": "Invalid request."
}

InPost\InPostPay\Exception\InPostPayAuthorizationException 401

{
  "error_code": "UNAUTHORIZED",
  "error_message": "Given user is not authorized to access the resource."
}

InPost\InPostPay\Exception\OrderNotFoundException 404

{
  "error_code": "ORDER_NOT_FOUND",
  "error_message": "Order not found."
}

InPost\InPostPay\Exception\OrderNotUpdateException 409

{
  "error_code": "ORDER_NOT_UPDATE",
  "error_message": "Order not update."
}

InPost\InPostPay\Exception\InPostPayInternalException 500

{
  "error_code": "INTERNAL_SERVER_ERROR",
  "error_message": "Something went wrong. Please try again later."
}

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:

app/code/InPost/InPostPay/etc/di.xml

w formie:

<type name="InPost\InPostPay\Validator\OrderValidator">
        <arguments>
            <argument name="orderValidators" xsi:type="array">
                <item name="basket_price" xsi:type="object">InPost\InPostPay\Validator\Order\BasketPriceValidator</item>
                <item name="payment_type" xsi:type="object">InPost\InPostPay\Validator\Order\PaymentTypeValidator</item>
                <item name="delivery" xsi:type="object">InPost\InPostPay\Validator\Order\DeliveryValidator</item>
                <item name="consents" xsi:type="object">InPost\InPostPay\Validator\Order\ConsentsValidator</item>
                <item name="billing_information" xsi:type="object">InPost\InPostPay\Validator\Order\BillingInformationValidator</item>
                <item name="stock" xsi:type="object">InPost\InPostPay\Validator\Order\StockValidator</item>
            </argument>
        </arguments>
    </type>

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:

app/code/InPost/InPostPay/etc/di.xml

w formie:

<type name="InPost\InPostPay\Service\Order\Creator\OrderProcessor">
        <arguments>
            <argument name="orderProcessingSteps" xsi:type="array">
                <item name="assign_customer" xsi:type="object">InPost\InPostPay\Service\Order\Creator\Steps\AssignCustomerStep</item>
                <item name="billing_address" xsi:type="object">InPost\InPostPay\Service\Order\Creator\Steps\BillingAddressStep</item>
                <item name="shipping_address" xsi:type="object">InPost\InPostPay\Service\Order\Creator\Steps\ShippingAddressStep</item>
                <item name="delivery_method" xsi:type="object">InPost\InPostPay\Service\Order\Creator\Steps\DeliveryMethodStep</item>
                <item name="payment_method" xsi:type="object">InPost\InPostPay\Service\Order\Creator\Steps\PaymentMethodStep</item>
                <item name="reload_quote" xsi:type="object">InPost\InPostPay\Service\Order\Creator\Steps\ReloadQuoteStep</item>
            </argument>
            ...
        </arguments>
    </type>

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:

app/code/InPost/InPostPay/etc/di.xml

w formie:

<type name="InPost\InPostPay\Service\Order\Creator\OrderProcessor">
        <arguments>
            ...
            <argument name="orderPostProcessingSteps" xsi:type="array">
                <item name="init_inpost_pay_order" xsi:type="object">InPost\InPostPay\Service\Order\Updater\Steps\InitInPostPayOrderStep</item>
                <item name="save_pickup_point" xsi:type="object">InPost\InPostPay\Service\Order\Updater\Steps\SavePickupPointStep</item>
                <item name="save_delivery_options" xsi:type="object">InPost\InPostPay\Service\Order\Updater\Steps\SaveDeliveryOptionsStep</item>
                <item name="save_accepted_consents" xsi:type="object">InPost\InPostPay\Service\Order\Updater\Steps\SaveAcceptedConsentsStep</item>
            </argument>
        </arguments>
    </type>

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:

\InPost\InPostPay\Service\DataTransfer\QuoteToBasketDataTransfer::transfer

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:

\InPost\InPostPay\Service\DataTransfer\OrderToInPostOrderDataTransfer::transfer

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.

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:

\InPost\InPostPay\Service\DataTransfer\ProductToInPostProduct\ProductToInPostProductDataTransfer

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:

\InPost\InPostPay\Service\DataTransfer\QuoteToBasket\QuoteToBasketDeliveryDataTransfer::transfer
\InPost\InPostPay\Service\DataTransfer\QuoteToBasket\QuoteToBasketConsentsDataTransfer::transfer
\InPost\InPostPay\Service\DataTransfer\QuoteToBasket\QuoteToBasketRelatedProductsDataTransfer::transfer
\InPost\InPostPay\Service\DataTransfer\QuoteToBasket\QuoteToBasketPromoCodesDataTransfer
\InPost\InPostPay\Service\DataTransfer\QuoteToBasket\QuoteToBasketSummaryDataTransfer

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.

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:

\InPost\InPostPay\Provider\Delivery\DeliveryDateProvider

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

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

\InPost\InPostPay\Validator\OrderValidator
\InPost\InPostPay\Service\Order\Creator\OrderProcessor

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:

\InPost\Restrictions\Observer\GenerateRestrictedProductsListObserver

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

InPost/InPostPay/Service/DataTransfer/QuoteToBasket/QuoteToBasketDeliveryDataTransfer.php

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

"product_attributes": [
	{
		"attribute_name": "Sprite Stasis Ball",
		"attribute_value": "1 x Sprite Stasis Ball 55 cm 23 zł"
	},
	{
		"attribute_name": "Sprite Foam Yoga Brick",
		"attribute_value": "1 x Sprite Foam Yoga Brick 5 zł"
	},
	{
		"attribute_name": "Sprite Yoga Strap",
		"attribute_value": "1 x Sprite Yoga Strap 6 foot 14 zł"
	},
	{
		"attribute_name": "Sprite Foam Roller",
		"attribute_value": "1 x Sprite Foam Roller 19 zł"
	}

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

{
    ...
    $intermediateSignature = sprintf(
        '%s%s%s%s%s%s',
        $xCommandId,
        $transactionId,
        $additionalBusinessData,
        $externalRefundId,
        $refundAmount,
        $merchantSecret
    );
    $signature = hash('sha512', $intermediateSignature);

    return "SHA-512_$signature";
}

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

mutation {
  createEmptyCart
}

Odpowiedź:

{
    "data": {
        "createEmptyCart": "WUvtAjFJeF53D7UsYhG9ur4gnkZjYPyv"
    }
}

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

mutation {
  addSimpleProductsToCart(
    input: {
      cart_id: "WUvtAjFJeF53D7UsYhG9ur4gnkZjYPyv"
      cart_items: [
        {
          data: {
            quantity: 1
            sku: "24-MB05"
          }
        }
      ]
    }
  ) {
    cart {
      items {
        id
        product {
          sku
          stock_status
        }
        quantity
      }
    }
  }
}

Odpowiedź:

{
    "data": {
        "addSimpleProductsToCart": {
            "cart": {
                "items": [
                    {
                        "id": "3213",
                        "product": {
                            "sku": "24-MB05",
                            "stock_status": "IN_STOCK"
                        },
                        "quantity": 1
                    }
                ]
            }
        }
    }
}

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

mutation {
    inPostPayInitBasket(
        input:{
            binding_place: "PRODUCT_CARD"
            browser:"eyJ1c2VyX2FnZW50IjoiTW96aWxsYS81LjAgKFgxMTsgTGludXggeDg2XzY0KSBBcHBsZVdlYktpdC81MzcuMzYgKEtIVE1MLCBsaWtlIEdlY2tvKSBDaHJvbWUvMTEyLjAuMC4wIFNhZmFyaS81MzcuMzYiLCJkZXNjcmlwdGlvbiI6IkNocm9tZSIsInBsYXRmb3JtIjoiTGludXgiLCJhcmNoaXRlY3R1cmUiOiI1LjAgKFgxMTsgTGludXggeDg2XzY0KSBBcHBsZVdlYktpdC81MzcuMzYgKEtIVE1MLCBsaWtlIEdlY2tvKSBDaHJvbWUvMTEyLjAuMC4wIFNhZmFyaS81MzcuMzYifQ=="
            cart_id: "WUvtAjFJeF53D7UsYhG9ur4gnkZjYPyv"
            number: "",
            prefix: ""    
        }
    ){
        basket_id
        qr_code
        deep_link
        deep_link_hms
        error_message
        action
    }
}

Odpowiedź:

{
    "data": {
        "inPostPayInitBasket": {
            "basket_id": "zxp6ScHnDTQNnLFStAXj1v2A5p6OPvRk",
            "qr_code": "iVBORw0KGgoAAAANSUhEUgAAAMgAAADIAQAAAACFI5MzAAABxklEQVR4Xu2XMY6EMAxFjShScoTcBC6GBBIXY27CEShTILz/G5jdmdW0f3alSYFIHsWX/W0H81fLng/u60P+CBnNrPGldHhLt3VYsK+lZHLfm2nxnfuZb3GmJIu1jXvp1tpLBW3FmjeQ0Urlm5XW6jeRLSNE7sl/aVMQ5mfM1lqf/ea+PGZOQMKj01La6/HoXgGJtVlidOjR80RIoK01yyjRPpfzbVCTCjahL5ZwyFGxQuI8pC/W3o78VKc2FUFC4EznITuFWfnRLSVkM1YJOgW0HfVSrVoCbcDsFJNb4DCqkCA1sw3O6oQ5WCo7tloSWYk6TbP1FgNETGgOBibDHD3y41oCh9yuAkk7Q+Tf3pGQMaewBAMTKtkutIQjG7XRoU3hmzEH1hKYY2NtjKhT5oe3GCXBhY29yjpkKgRie2iTEY9hwYsT+2YY5siPjjh7Fe2Jbwy36PbsFDqSmJWQxbmNEN2joyGx4hqJXsXUwLJagpuD0Z7zEZ2azXOQkol3WM4soz35O3HNbRlhYCbac8weUrtLm5REfvjY0CnwwRtI4bg6/ig5xqWE+WGjpDajNjvntoqER09t8WN7v8OqyIv1If+VfAGaOvztkzA9dwAAAABJRU5ErkJggg==",
            "deep_link": "inpost://izilinksandbox?binding_id=6a4c2e04-7c1b-4fb9-8cfb-d5976e77d563",
            "deep_link_hms": "inpost://izilinksandbox?binding_id=6a4c2e04-7c1b-4fb9-8cfb-d5976e77d563",
            "error_message": null,
            "action": null
        }
    }
}

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

{"user_agent":"Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/112.0.0.0 Safari/537.36","description":"Chrome","platform":"Linux","architecture":"5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/112.0.0.0 Safari/537.36"}

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

mutation {
    inPostPayInitBasket(
        input:{
            binding_place: "PRODUCT_CARD"
            browser:"eyJ1c2VyX2FnZW50IjoiTW96aWxsYS81LjAgKFgxMTsgTGludXggeDg2XzY0KSBBcHBsZVdlYktpdC81MzcuMzYgKEtIVE1MLCBsaWtlIEdlY2tvKSBDaHJvbWUvMTEyLjAuMC4wIFNhZmFyaS81MzcuMzYiLCJkZXNjcmlwdGlvbiI6IkNocm9tZSIsInBsYXRmb3JtIjoiTGludXgiLCJhcmNoaXRlY3R1cmUiOiI1LjAgKFgxMTsgTGludXggeDg2XzY0KSBBcHBsZVdlYktpdC81MzcuMzYgKEtIVE1MLCBsaWtlIEdlY2tvKSBDaHJvbWUvMTEyLjAuMC4wIFNhZmFyaS81MzcuMzYifQ=="
            cart_id: "WUvtAjFJeF53D7UsYhG9ur4gnkZjYPyv"
            number: "123123123",
            prefix: "+48"    
        }
    ){
        basket_id
        error_message
        action
    }
}

Odpowiedź:

{
    "data": {
        "inPostPayInitBasket": {
            "basket_id": "zxp6ScHnDTQNnLFStAXj1v2A5p6OPvRk",
            "error_message": null,
            "action": null
        }
    }
}

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

{
  inPostPayGetBasketConfirmation(
        cart_id: "5Ko6osrJVxRNbvDG5x9AKrA8UFgWWePV"
    )
    {
        basket_id
        status
        phone_number {
            country_prefix
            phone
        }
        browser {
            browser_id
            browser_trusted
        }
        name
        surname
        masked_phone_number
        error_message
        action
  }
}

Odpowiedź (bez potwierdzenia w aplikacji mobilnej):

{
    "data": {
        "inPostPayGetBasketConfirmation": {
            "basket_id": null,
            "status": null,
            "phone_number": null,
            "browser": null,
            "name": null,
            "surname": null,
            "masked_phone_number": null,
            "error_message": null,
            "action": "retry"
        }
    }
}

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

{
    "data": {
        "inPostPayGetBasketConfirmation": {
            "basket_id": "zxp6ScHnDTQNnLFStAXj1v2A5p6OPvRk",
            "status": "SUCCESS",
            "phone_number": {
                "country_prefix": "+48",
                "phone": "123123123"
            },
            "browser": {
                "browser_id": "b0548dcd-502d-4918-a1a3-fc9538e8fdcc",
                "browser_trusted": true
            },
            "name": "John",
            "surname": "Doe",
            "masked_phone_number": "12*****23",
            "error_message": null,
            "action": null
        }
    }
}

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

{
  inPostPayGetBasketMobileLink  (
        cart_id: "WUvtAjFJeF53D7UsYhG9ur4gnkZjYPyv"
    )
    {
        link
        error_message
  }
}

Odpowiedź:

{
    "data": {
        "inPostPayGetBasketMobileLink": {
            "link": "inpost://izilinksandbox?basket_id=6180f39f-99d2-4a18-87b6-cba4c17b9856",
            "error_message": null
        }
    }
}

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

{
  inPostPayGetPlacedOrderData  (
        basket_id: "zxp6ScHnDTQNnLFStAXj1v2A5p6OPvRk"
    )
    {
        action
        order_id
        status
        status_label
        error_message
  }
}

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

{
    "data": {
        "inPostPayGetPlacedOrderData": {
            "action": "refresh",
            "order_id": null,
            "status": null,
            "status_label": null,
            "error_message": null
        }
    }
}

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

{
    "data": {
        "inPostPayGetPlacedOrderData": {
            "action": "redirect",
            "order_id": "000000171",
            "status": "processing",
            "status_label": "Processing",
            "error_message": null
        }
    }
}

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

query getStoreConfigData {
        storeConfig {
            inpost_pay_show_on_product_cart
            inpost_pay_show_on_cart
            inpost_pay_show_in_minicart
            inpost_pay_show_on_success_page
            inpost_pay_widget_color_variant
            inpost_pay_widget_dark_mode
            inpost_pay_widget_max_width
            inpost_pay_widget_frame_style
        }
    }

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

{
    "data": {
        "storeConfig": {
            "inpost_pay_show_on_product_cart": "1",
            "inpost_pay_show_on_cart": "1",
            "inpost_pay_show_in_minicart": "1",
            "inpost_pay_show_on_success_page": "1",
            "inpost_pay_widget_color_variant": "primary",
            "inpost_pay_widget_dark_mode": "0",
            "inpost_pay_widget_max_width": null,
            "inpost_pay_widget_frame_style": "classic"
        }
    }
}

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:

cart_id = "5Ko6osrJVxRNbvDG5x9AKrA8UFgWWePV"

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

mutation {
    inPostPayDeleteBrowserBinding(
        cart_id: "5Ko6osrJVxRNbvDG5x9AKrA8UFgWWePV"
    ){
        success
        error_message
    }
}

Odpowiedź:

{
    "data": {
        "inPostPayDeleteBrowserBinding": {
            "success": true,
            "error_message": null
        }
    }
}

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

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

mutation {
    inPostPayDeleteBasketBinding(
        cart_id: "5Ko6osrJVxRNbvDG5x9AKrA8UFgWWePV"
    ){
        success
        error_message
    }
}

Odpowiedź:

{
    "data": {
        "inPostPayDeleteBasketBinding": {
            "success": true,
            "error_message": null
        }
    }
}

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

InPost Pay - Magento

Wstęp

Changelog

Wymagania Systemowe

Konfiguracja

Mapowanie Metod Dostawy

Ogólne Ustawienia

Sandbox

Ustawienia Autoryzacji

Ustawienia Debuggowania

Ustawienia IZI API

Mapowanie zgód (zmiany od wersji 1.0.8)

Ustawienia wyświetlania

Ustawienia układu przycisków

Ustawienia Cache

Instalacja modułu - dodatkowe informacje

Ustawienia odpytywania Long Polling

Ustawienia Omnibus (zmiany od wersji 1.0.8)

Ustawienia Restrykcji (zmiany od wersji 1.0.8)

Instrukcja użytkowania

Zakup na stronie Merchanta przy użyciu InPost Pay

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

Instrukcja tworzenia zwrotu

Dokumentacja Techniczna - Backend

Weryfikacja Sygnatury

Connector API

Interfejs Żądań do API InPost

Obsługa żądań do API InPost i formatowanie odpowiedzi

Relacja pomiędzy oficjalną wtyczką Smartmage_Inpost a InPost_InPostPay

Debuggowanie

Kontrolery frontowe

Implementacje REST API Magento

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

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

GET /v1/izi/basket/:basketId

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

POST /v1/izi/order

GET /v1/izi/order/:orderId

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

Proces Tworzenia Zamówienia

Obiekty zwracane przez API Magento

Koszyk InPost Pay (Basket)

Zamówienie InPost Pay (InPostOrder)

Modyfikacje indywidualne pod Merchanta

Moduł Restrykcji

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

Ograniczenie dostaw tylko do PL

Produkty bundle

Generowanie Sygnatury dla zwrotów

GraphQL

Query i Mutacje

Testy

Related content