Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

W tym rozdziale znajdziesz informacje dotyczące autoryzacji w komunikacji z InPost Pay oraz konfiguracji konta Merchanta i generowania dostępów (client_id i client_secret).

Na tej stronie:

Table of Contents
maxLevel6
minLevel1
include
outlinefalse
indent
exclude
typelist
printablefalse
class

Autoryzacja

Do uwierzytelniania komunikacji klienta z InPost Pay (Basket App) wykorzystany jest standard OAuth 2.0. W przypadku komunikacji service to service – bez kontekstu zalogowanego użytkownika wykorzystany jest client_credentials flow a OAuth (https://www.oauth.com/oauth2-servers/access-tokens/client-credentials/).

  • Merchant otrzymuje swój client_Id i client_Secret client_id i client_secret

Info
  • Pobiera access token

  • Podpisuje każdy request. Access token należy przekazać w nagłówku Authorization: Bearer W-TYM-MIEJSCU-NALEZY-UMIESCIC-TOKEN

  • Serwer zasobów weryfikuje token i identyfikuje klienta

Info

Wszystkie zapytania wysyłane do serwera wymagają podania prawidłowego i ważnego access tokenu, który należy do określonego Użytkownika.

Info

Wygenerowany token ma określoną ważność (zdefiniowana w expires_in, która jest zwracana wraz z tokenem) i nie ma konieczności pobierania nowego tokena przy każdym zapytaniu. 

Token endpoint jest stały i może być parametrem konfiguracyjnym po stronie klienta:

Na tej stronie

Table of Contents

Pobranie tokenu

Request

Code Block
languagejson
curl --location 'https://sandbox-login.inpost.pl/auth/realms/external/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=sandbox' \
--data-urlencode 'client_secret=qwertyuiop' \
--data-urlencode 'grant_type=client_credentials'

Response

Code Block
languagejson
{
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiw...",
    "expires_in": 300,
    "refresh_expires_in": 0,
    "token_type": "Bearer",
    "not-before-policy": 0,
    "scope": "api:inpostpay"
}

Warning

Błędy jakie mogą wystąpić podczas generowania tokenu:

  • Invalid client credentials - W przypadku podania błędnego client_id

  • Invalid client secret - W przypadku podania błędnego client_secret

  • Missing form parameter: grant_type - W przypadku niepodania grant_type:client_credentials


Przykład implementacji w PHP

  • Tworzymy interface serwisu, który będzie odpowiedzialny za pobranie bearer access token.

    Code Block
    languagephp
    <?php
    
    declare(strict_types=1);
    
    namespace Iteo\InpostPayClient\Client;
    
    use Iteo\InpostPayClient\SDK\Core\Exceptions\InpostPayEndpointException;
    
    /**
     * Interface used for creating bearer token, needed to communication with Inpost Pay.
     */
    interface InpostPayBearerServiceInterface
    {
        /**
         * Method that creating bearer access token for given merchant credentials.
         *
         * @return string Bearer access token
         *
         * @throws InpostPayEndpointException
         */
        public function getBearerToken(): string;
    }
    

View file
nameautoryzacjaBearerServiceInterface.txt

  • Tworzymy exception, który będziemy zwracali w przypadku niepowodzenia pobrania tokenu.

    Code Block
    languagephp
    <?php
    
    declare(strict_types=1);
    
    namespace Iteo\InpostPayClient\SDK\Core\Exceptions;
    
    class InpostPayEndpointException extends \Exception
    {
        final public function __construct(string $message = '', int $code = 0, \Throwable $previous = null)
        {
            parent::__construct($message, $code, $previous);
        }
    
        public static function createClientException(\Throwable $throwable): self
        {
            return new static(
                sprintf('InpostPayClient, error occurred when creating http client with bearer token. Exception message: %s', $throwable->getMessage()),
                $throwable->getCode(),
                $throwable
            );
        }
    }

View file
nameautoryzacjaException.txt

  • Tworzymy implementację serwisu, który pobiera access token przy użyciu metody getBearerToken.

    Code Block
    languagephp
    <?php
    
    declare(strict_types=1);
    
    namespace Iteo\InpostPayClient\Client;
    
    use League\OAuth2\Client\Provider\Exception\IdentityProviderException;
    use League\OAuth2\Client\Provider\GenericProvider;
    use Iteo\InpostPayClient\SDK\Core\Exceptions\InpostPayEndpointException;
    
    /**
     * PHP Bearer Service implementation used for creating bearer token, needed to communication with Inpost Pay.
     */
    final class InpostPayBearerService implements InpostPayBearerServiceInterface
    {
        private string $clientId;
        private string $clientSecret;
        private string $urlAccessToken;
        private ?string $urlAuthorize;
        private ?string $urlResourceOwnerDetails;
        
        //Zamienić w zależności od środowiska
        private const URL_ACCESS_TOKEN = 'https://sandbox-login.inpost.pl/auth/realms/external/protocol/openid-connect/token';
    
        public function __construct(string $clientId, string $clientSecret, string $urlAccessToken = self::URL_ACCESS_TOKEN, string $urlAuthorize = null, string $urlResourceOwnerDetails = null)
        {
            $this->clientId = $clientId;
            $this->clientSecret = $clientSecret;
            $this->urlAccessToken = $urlAccessToken;
            $this->urlAuthorize = $urlAuthorize;
            $this->urlResourceOwnerDetails = $urlResourceOwnerDetails;
        }
    
        /**
         * {@inheritdoc}
         */
        public function getBearerToken(): string
        {
            $provider = new GenericProvider([
                'clientId' => $this->clientId,
                'clientSecret' => $this->clientSecret,
                'urlAuthorize' => $this->urlAuthorize,
                'urlAccessToken' => $this->urlAccessToken,
                'urlResourceOwnerDetails' => $this->urlResourceOwnerDetails,
            ]);
    
            try {
                return $provider->getAccessToken('client_credentials')->getToken();
            } catch (IdentityProviderException $exception) {
                throw InpostPayEndpointException::createClientException($exception);
            }
        }
    }
    

View file
nameautoryzacjaBearerServiceInterface.txt


Konfiguracja konta Merchanta - środowisko produkcyjne

Aby uzyskać dostępy do środowiska produkcyjnego podpisz umowę Umowa o obsługę i rozliczanie transakcji.

Jeśli jeszcze nie podpisałeś umowy skontaktuj się ze swoim przedstawicielem handlowym InPost lub skorzystaj z formularza z zakładki zamieszczonego w sekcji "Dla Biznesu" w zakładce "Oferta InPost Pay".  

Po podpisaniu umowy: 

W tej zakładce nie musisz nic wypełniać, możesz jedynie podejrzeć secret lub go zresetować.  
  1. Zaloguj się do serwisu LINK używając danych do logowania w Manager Paczek (system do obsługi umowy logistycznej InPost).  

UWAGA! Uzupełnienie wszystkich informacji jest niezbędne do wygenerowania dostępów (Client_id oraz Client_secret) na środowisko produkcyjne usługi InPost Pay 

  1. Po zalogowaniu zobaczysz menu z poniższymi kategoriami 

    Image Removed
  2. Przejdź do zakładki

    Image Removed

    Dodaj w niej informacje o Twoim sklepie internetowym, które użytkownicy zobaczą w aplikacji InPost mobile podczas dokonywania zakupów. Kliknij przycisk EDYTUJ, aby edytować informacje. 

 

Image Removed

 

Nazwa merchanta – to bardzo istotne pole, w które powinieneś wpisać nazwę sklepu, jaką klienci zobaczą w aplikacji InPost mobile podczas robienia zakupów. 

PRZYKŁAD WIDOKU W APLIKACJI

Image Removed

Logo sklepu – to logo, które klienci zobaczą w aplikacji InPost mobile podczas robienia zakupów, zaraz obok nazwy Twojego sklepu. Logo, powinno być dostosowane do maksymalnej szerokości 72px lub maksymalnej wysokości 32px, aby zapewnić czytelność i odpowiednią wizualizację na różnych urządzeniach. Dodatkowo, prosimy o dostarczenie logo w dwóch wersjach kolorystycznych, light mode oraz dark mode, zoptymalizowane tak, aby zapewnić czytelność i estetykę na jasnym i ciemnym tle. Dzięki dostarczeniu logo w obu tych wersjach kolorystycznych, zapewnimy spójność i estetykę, niezależnie od tego, czy użytkownik korzysta z trybu jasnego czy ciemnego aplikacji. W pole wklej link do swojego logo i użyj przycisku Załaduj – wówczas po prawej stronie zobaczysz poprawnie załadowane logo Twojego sklepu. 

Image Removed

Komunikacja z backendem – to link, który umożliwi wymianę informacji między Twoim sklepem, a naszą usługą. 

  • Jeśli korzystasz z integracji API wklej tam swój dedykowany link. 

  • Jeśli korzystasz z technologii wtyczkowej podaj tu po prostu link do Twojego sklepu 

Dane kontaktowe -  poniższe dane będą prezentowane w szczegółach Twojego sklepu, klienci zobaczą je w aplikacji InPost mobile podczas robienia zakupów.  

  • Numer komórkowy (wymagany) 

  • Numer stacjonarny (niewymagany) 

  • Email do kontaktu (wymagany) 

  • Link do formularza kontaktowego (niewymagany) 

 

Po uzupełnieniu wszystkich danych kliknij przycisk Zapisz zmiany 

Image Removed

Przejdź do zakładki Konfiguracja klienta API

Image RemovedU góry w prawym rogu wybierz przycisk Dodaj nowy sklep
Image Removed

  • Wpisz nazwę Twojego sklepu (ta nazwa jest widoczna tylko dla Ciebie, klienci jej nie zobaczą) 

    Image Removed

    Wprowadź nazwę sklepu i kliknij Zapisz 

  • Na ekranie pojawią się dostępy do środowiska produkcyjnego – skopiuj je i pamiętaj – nie udostępniaj ich nikomu!

    Image Removed
  • Dodany sklep będzie widoczny w tej zakładce wraz z Client_ID, jeśli zapomnisz Client_Secret możesz je odzyskać klikając przycisk Resetuj 

    Image Removed
  • W ostatniej zakładce:

    Image Removed

    Możesz uzyskać secret do Merchant Transaction API (nie każdy potrzebuje tej funkcji) – całościowy opis tej usługi znajdziesz tu Zwroty i transakcje - Developer Documentations - Confluence (atlassian.net)  

    1. https://merchant.inpost.pl używając adresu mailowego, który został podany na umowie w polu ADMINISTRATOR.
      Jeśli to jest Twoje pierwsze logowanie i nie posiadasz konta, zarejestruj nowe konto na adres mailowy administratora podany na umowie i postępuj zgodnie z instrukcją mailową.

    UWAGA! Jeśli nie możesz zalogować się na podany adres mailowy, skontaktuj się ze swoim przedstawicielem handlowym lub napisz na bok.pay@inpost.pl

    1. Po zalogowaniu zobaczysz listę sklepów, dla których została podpisana umowa na usługę.

    Aby wygenerować client_id oraz client_secret należy uzupełnić szczegółowe dane każdego sklepu, korzystając z żółtego przycisku obok nazwy sklepu.

    PAMIĘTAJ! Uzupełnione dane będą widoczne w aplikacji InPost Mobile dla użytkowników, zadbaj o ich poprawność.

    image-20241106-150205.pngImage Added
    1. Uzupełnij wszystkie wymagane dane na formularzu:

      1. Nazwa sklepu – to nazwa, którą chcesz, aby Twoi klienci widzieli w aplikacji InPost Mobile

      2. Technologia – wybierz technologię, na której oparty jest Twój sklep internetowy.
        UWAGA! W przypadku customowej integracji po API wybierz „API Integration” – wówczas należy podać również url do komunikacji z backendem Twojego sklepu, aby mogła nastąpić komunikacja między usługą a Twoim sklepem.

    image-20240311-115124.pngImage Added
    1. Logo Twojego sklepu będzie widoczne w zakładce Partnerzy w aplikacji InPost Mobile, dlatego ważne jest, aby było dodane w poprawnym formacie:

      1. Wklej link do logo, dostępny na publicznym serwerze (nie może to być np. google drive, czy cloud), najlepiej jeśli link prowadzi do logo na stronie Twojego sklepu

      2. Logo nie może być większe niż 50 kb.

      3. Logo musi być zarówno w wersji jasnej, jak i ciemnej (w zależności z jakiej wersji aplikacji korzysta użytkownik)

      4. Aby logo było dobrze widoczne, powinno mieć wymiary dostosowane do minimalnej szerokości 108px i minimalnej wysokości 40px. Upewnij się, że Twój logotyp nie zawiera marginesów dla lepszej widoczności w aplikacji. Możesz załadować w formacie SVG i max wielkość pliku to 50 kb.

      5. Jeżeli logo, które chcesz wskazać ma format SVG upewnij się, że podczas renderowania pliku opcja "Preserve Illustrator Editing Capabilities" nie została zaznaczona.
        UWAGA! Po lewej stronie od linku dostępny jest podgląd logo. Upewnij się, że logo jest poprawne!

        image-20240311-115700.pngImage Added

        PRZYKŁAD WIDOKU LOGO W APLIKACJI

        image-20241119-074405.pngImage Added

    2. Metody kontaktu – użytkownik z poziomu aplikacji InPost Mobile ma możliwość skontaktowania się z Twoim sklepem internetowym za pośrednictwem telefonu, maila lub formularza kontaktowego. Uzupełnij wszystkie te dane.

      image-20240311-115841.pngImage Added

    3. Zapisz uzupełnione dane korzystając z żółtego przycisku ZAPISZ ZMIANY.

    4. Jeśli dane wszystkich sklepów są już uzupełnione, możesz przejść do wygenerowania credentiali. Aby to zrobić skorzystaj ze strzałki ‘rozwiń’ przy sklepie, dla którego chcesz uzyskać dane.

      image-20240311-120013.pngImage Added

    5. Rozwinie się wówczas strona z dodatkowymi informacjami:

      1. Client ID – skopiuj i wklej w panelu swojego sklepu

      2. Client Secret – aby wygenerować skorzystaj z przycisku RESETUJ KLUCZ API

      3. POS ID - skopiuj i wklej w panelu swojego sklepu

      4. Hasło do zwrotów – jeśli integrujesz swój system ERP z API dotyczącym transakcji i zwrotów, będziesz potrzebował tego hasła, w przeciwnym razie ta dana jest dla Ciebie opcjonalna i nie musisz jej wykorzystywać. Całościowy opis tej usługi znajdziesz tu Zwroty i transakcje

      5. W tej zakładce nie musisz nic wypełniać, możesz jedynie podejrzeć secret lub go zresetować.

     PAMIĘTAJ! Aby nie udostępniać powyższych danych osobom postronnym!

    image-20240311-120159.pngImage Added
    1. Client Secret – po skorzystaniu z przycisku RESETUJ KLUCZ API zobaczysz swój Client Secret - skopiuj i wklej w panelu swojego sklepu.

    UWAGA! Każde użycie tego przycisku spowoduje reset Client Secret, co skutkuje koniecznością wprowadzenia nowego Client Secret w panelu Twojego sklepu, do tego czasu użytkownicy nie będą mogli finalizować zakupów poprzez InPost Pay.

    image-20240311-120314.pngImage Added
    1. Merchant Secret to Hasło do zwrotów – jeśli integrujesz swój system ERP z API dotyczącym transakcji i zwrotów, będziesz potrzebował tego hasła, w przeciwnym razie ta dana jest dla Ciebie opcjonalna i nie musisz jej wykorzystywać. Używając tego przycisku możesz zresetować swoje hasło. Całościowy opis tej usługi znajdziesz tu Zwroty i transakcje

    Info

    W celu wygenerowania Hasła do zwrotów po raz pierwszy użyj przycisku Resetuj Merchant Secret.

    UWAGA! Jeśli zresetujesz hasło, skutkuje to koniecznością wpisania nowego w Twoim sklepie internetowym, do tego czasu komunikacja API będzie nieaktywna. Rekomendujemy reset hasła tylko w niezbędnych przypadkach.

    image-20240311-120520.pngImage Added


    Konfiguracja konta Merchanta - środowisko sandbox

    Aby uzyskać dostęp do środowiska Sandbox uzupełnij i wyślij formularz kontaktowy korzystając z opcji Dla Biznesu i zakładki Sandbox.

    Aplikacja testowa InPost Mobile

    Na potrzeby testów udostępniamy Ci też Ci nasze aplikacje testowe InPost Mobile:

    • iOS instalujemy poprzez pobranie aplikacji z linku 

    https://testflight.apple.com/join/ey6Yherd   

    • Android instalujemy poprzez pobranie z linku 

    https://appdistribution.firebase.dev/i/cf11a306c092f437
    • pliku

      View file
      nameInpost sandbox 3.32.0.apk

    Jeśli po pobraniu pliku na urządzenie mobilne został on zapisany jako archiwum o nazwie "Inpost Sandbox [numer_wersji].apk.zip" zmień jego nazwę i usuń rozszerzenie ".zip". Po zapisaniu zmian powinieneś/aś otrzymać plik z rozszerzeniem .apk, który po otwarciu automatycznie zainstaluje/zaktualizuje aplikację. Jeżeli pomimo zmiany nazwy pliku nadal nie możesz zainstalować aplikacji, upewnij się, że w ustawieniach urządzenia zostały przyznane odpowiednie uprawnienia do instalacji aplikacji.

    Pamiętaj, aby przed rozpoczęciem testów upewnić się, że posiadasz najnowszą wersję aplikacji

    Zakres prac implementacyjnych po stronie Merchanta

  • Autoryzacja – implementacja autentykacji i autoryzacji oraz konfiguracji konta.

  • Widget frontend - Implementacja Widgetu InPost Pay Widget - frontend.

  • Widget backend – wystawienie endpointów opisanych w Merchant Backend API, których celem jest obsługa funkcjonalności zgodnie z diagramami sekwencji.

  • Integracja z InPost Pay (Basket App) – integracja z metodami API opisanymi w InPost Pay (Basket App)

    . Zalecamy przed instalacją nowej wersji usunięcie poprzednich wersji aplikacji testowej, które były instalowane na urządzeniu.


    Wymagania techniczne po stronie Merchanta

    Ruch wychodzący od InPost do Merchanta dla IP Proxy InPost 34.118.93.24, 34.116.145.216.


    Mechanizm blokowania komunikacji z Merchantem w przypadku wystąpienia błędów

    Podczas komunikacji synchronicznej z Merchantem może wystąpić szereg problemów związanych z komunikacją pomiędzy systemami, które mają wpływ na konwersje oraz korzystanie z aplikacji InPost Pay przez klienta, do których zaliczyć można:

    • przetwarzanie żądań trwa zbyt długo z powodu spadku przepustowości systemu Merchanta

    • usługa Merchanta może być przeciążona lub czekać na inne zasoby

    • Merchant odpowiada niezgodnie z kontraktem (np. brak wymaganych danych) w wyniku czego występuje błąd walidacyjny

    • Merchant zwraca błąd dotyczący problemów z serwerem (5xx)

    Aplikacja InPost Pay w celu zachowania wysokiej konwersji koszyków i zamówień oraz obsługi klienta w aplikacji ma zaimplementowany mechanizm blokujący komunikacje z Merchantem, w przypadku wystąpienia wyżej wymienionych błędów.

    Reguła blokowania komunikacji aplikacji InPost Pay z Merchantem:

    Jeżeli w przeciągu 120 sekund wystąpi minimum 20 zapytań do Merchanta, w których minimum 90% będzie miało błędy:

    • HttpServerErrorException np. response.status: 500

    • ResourceAccessException np. Merchant timed out

    • ResponseNotValidException np. Merchant odpowiada komunikatem 200, jednakże w przekazanym response.body dana lub dane są niepoprawne (np. brak wymaganych danych) przez co, aplikacja nie może poprawnie przetworzyć komunikatu,

    to aplikacja InPost Pay zablokuje komunikacje z Merchantem.

    W przypadku, gdy Merchant ma zablokowaną komunikacje, to przy próbie wywołania metody do InPost Pay otrzyma błąd 409 z komunikatem:

    { "error_code": "MERCHANT_DISABLE", "error_message": "Merchant with given id: <merchant_id> is DISABLED" }

    W celu odblokowania komunikacji Merchant powinien skontaktować z InPost Pay poprzez zgłoszenie na adres integracjapay@inpost.pl.