Powiązanie koszyka

Artykuł zawiera opis metody wykorzystywanej do powiązania koszyka wraz z przykładem implementacji metody w języku PHP.

Na tej stronie:

1 Opis metody
2 Przykład implementacji w PHP

Opis metody

Metoda służąca do inicjalizacji procesu wiązania koszyka z wykorzystaniem jednej z dwóch metod: qrCode lub numer telefonu oraz przekazująca informacje o przeglądarce w celu dodanie przeglądarki do zaufanych.

W danej metodzie wymagamy implementacji wszystkich pól wymienionych w tabeli, ponieważ składają się na całość usługi InPost Pay. Część poniższych pól w kolumnie 'Wymagalność' jest oznaczona jako 'O' tj. opcjonalna ze względu na to, że nie wszystkie produkty/koszyki w sklepach internetowych mają przypisane wszystkie parametry, więc koszyk może zostać utworzony, a zamówienie złożone bez nich. Jednak implementacja/wdrożenie wszystkich pól jest biznesowo WYMAGANE.

Parameters

Nazwa pola	Opis	Typ	Wymagalność	Dodatkowe uwagi
`basket_id`	Unikalny identyfikator koszyka nadawany przez merchanta	string	Y

Request

Nazwa pola	Opis	Typ	Wymagalność	Dodatkowe uwagi
`binding_method`	Wybrana forma wiązania koszyka dostępne dwie metody [ PHONE, DEEP_LINK ]. PHONE – przekazujemy, jeśli widget w metodzie iziGetPayData przekazał parametry prefix- prefiks numeru telefonu; phoneNumber- numer telefonu DEEP_LINK – przekazujemy, jeśli widget w metodzie iziGetPayData nie przekazał prefix i phoneNumber w iziGetPayData	string	O	`"binding_method":"DEEP_LINK"`
`binding_place`	Miejsce wiązania koszyka w sklepie merchanta (miejsce osadzenia widget). Dostępne miejsca: PRODUCT_CARD, BASKET_SUMMARY, ORDER_CREATE, BASKET_POPUP, THANK_YOU_PAGE, LOGIN_PAGE, CHECKOUT_PAGE, REGISTERFORM_PAGE, MINICART_PAGE. Przekazujemy wartość otrzymaną z widget z pola bindingPlace w iziGetPayData. PRODUCT_CARD - karta produktu BASKET_SUMMARY - podsumowanie koszyka ORDER_CREATE - etap tworzenia zamówienia BASKET_POPUP - panel boczny koszyka THANK_YOU_PAGE* - nie jest to miejsce bindowania, ale osadzenia widgetu, który powinien przyjąć dedykowaną formę Thank You Page po złożeniu zamówienia LOGIN_PAGE – strona logowania CHECKOUT_PAGE – stona checkout REGISTERFORM_PAGE – strona rejestracji MINICART_PAGE - minikarta.	string	O	`"binding_place":"PRODUCT_CARD"`
`phone_number`	Obiekt służący do przekazania numeru telefonu, z którym ma być powiązany koszyk. Obiekt obligatoryjny tylko jeśli binding_method= PHONE. Dane pobierane z metody iziGetPayData	object	O	`"phone_number":{"country_prefix":"+48","phone":"600000000"}`
`phone_number.country_prefix`	Prefix. Pobierane z prefix iziGetPayData i przekazywane w formacie z symbolem “+”.	string	Y
`phone_number.phone`	Numer telefonu pobierany z phoneNumber iziGetPayData	string	Y
`browser`	Obiekt służący do przekazania informacji o przeglądarce, z której klient aktualnie korzysta i wykonuje wiązanie koszyka w celu dodania przeglądarki do zaufanych.	object	Y	`"browser":{"user_agent":"Mozilla/5.0 (iPhone; CPU iPhone OS 16_3_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/16.3 Mobile/15E148 Safari/604.1","description":"Safari","platform":"iPhone","architecture":"5.0 (iPhone; CPU iPhone OS 16_3_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/16.3 Mobile/15E148 Safari/604.1","data_time":"2023-08-14T12:47:45.000Z","location":"-","customer_ip":"000.000.000.00","port":"443"}}`
`browser.user_agent`	User agent	string	Y
`browser.description`	Nazwa przeglądarki	string	O
`browser.platform`	Platforma	string	Y
`browser.architecture`	Architektura	string	Y
`browser.data_time`	Data	string($date-time)	Y
`browser.location`	Lokalizacja	string	Y
`browser.customer_ip`	IP klienta	string	Y
`browser.port`	Port	string	Y

Response

202 – pusty response w przypadku, gdy wiązanie następuje z wykorzystaniem numeru telefonu (binding_method= PHONE)

200

Response

Nazwa pola	Opis	Typ	Wymagalność	Dodatkowe uwagi
`qr_code`	Wygenerowany qrCode	string	O	"qr_code":"iVBORw0KGgoAAAANSUhEUgAAAMgAAADIAQAAAACFI5MzAAABxUlEQVR4Xu2XQa6DMAxEjViw5Ai5CVysEkhcDG6SI7Bkgeo/4wD9rdTt9H+pWUQ0rwvLY48T83fLXg+u9SV/hIxm1nreep+y9euQ8buWksn93k7Zl7XGBuxxpiTZutZ962zwDWHlzdoPkNG2ar2liPIzZE+RmNBHT6jPmKxDZeDL87NyAhI1ipx05/ZcvQISa7fmbmiQah2OEyFBbEhMQkQ3ZMduqVmIhWTKDVsUToH/VCtFOp1CRPajN/oVv2d0bEmRkDh6Azv14WENz2iLPioy+eUUtoVSlatJs/iYGqTIG4dTYDuUExGnKoiN3blVKBNiKWFEKBMkps7NDJFoWFJyJmZu99IgqNYSm4o4HQo+0TMgTgxOcCnZUZmcWSwOfrFaBzGxqIs7Lw3l69BHRjgwcWmYi19buvRREfbpCn+AXyca5UMfHUFbhCp1mduXPjoSYbFP6RnoWHv4tYjAH+pIEQ0r+mWSkli8MyGs8Ay+KaRkNN7fwqFyWCYCHKQkKqTMbR7WfE6IyfmSYJT8eiinJMfEwMD8fXPQkuJQC8yTzq0l1AejkzcWtiiG99WnGhI1OuI9d1ygeakusanIm/Ul/5X8ALFA0R7Pm5CfAAAAAElFTkSuQmCC",
`deep_link`	Deep link na systemy Android/iOs	String	O	`"deep_link":"https://inpost.pl/izilink?binding_id=1ec6fdab-4098-485d-aaac-a7ac986f878f "`
`deep_link_hms`	Deep link na system HMS – obecnie nie wykorzystywany	String	O	`"deep_link_hms":"https://inpost.pl/izilink?binding_id=1ec6fdab-4098-485d-aaac-a7ac986f878f "`

POST /v1/izi/basket/{basket_id}/binding

Przykładowy request

{
  "binding_method": "PHONE",
  "binding_place": "PRODUCT_CARD",
  "phone_number": {
    "country_prefix": "+48",
    "phone": "5xxxxxxxx"
  },
  "browser": {
    "user_agent": "Testzilla 1.0",
    "description": "Test agent",
    "platform": "Ino Linux 2.0",
    "architecture": "x86-646",
    "data_time": "2023-08-24T08:52:01.113Z",
    "location": "-",
    "customer_ip": "127.0.0.1",
    "port": "8080"
  }
}

Przykład implementacji w PHP

Podanie kodu -

W pliku implementacjaKlienta.txt została dodana tylko funkcja postBasketBinding.

/**
 * Client symfony implementation used for communication between Merchant and InPost Pay application.
 *
 * @param InpostPayBearerServiceInterface $inpostPayBearerService <p> Bearer service interface,
 * with contains creating bearer token which is required for communication with Inpost Pay </p>
 *
 */
final class InpostPayClient implements InpostPayClientInterface
{
    private ClientInterface $client;
    private InpostPayURLCreatorInterface $URLCreator;
    private InpostPayBearerServiceInterface $bearerService;

    public function __construct(
        ClientInterface $client,
        InpostPayURLCreatorInterface $URLCreator,
        InpostPayBearerServiceInterface $bearerService
    ) {
        $this->client = $client;
        $this->URLCreator = $URLCreator;
        $this->bearerService = $bearerService;
    }
    
    public function postBasketBinding(string $basketId, BasketBindingRequest $requestBody): ?QrCodeData
    {
        if (BindingMethod::PHONE()->equals($requestBody->getBindingMethod()) && !$requestBody->getPhoneNumber()) {
            throw InpostPayPostBasketBindingException::createNoPhoneForPhoneBindingMethodException();
        }

        $path = sprintf('basket/%s/binding', $basketId);
        $uri = new Uri($this->buildUri($path));
        /** @var string $body */
        $body = json_encode($requestBody);
        $request = new Request(
            'POST',
            $uri,
            $this->provideDefaultClientHeaders(),
            $body
        );

        try {
            $response = $this->client->sendRequest($request);
            $statusCode = $response->getStatusCode();
            $content = $response->getBody()->getContents();

            if (HttpResponseStatus::ACCEPTED()->getValue() === $statusCode) {
                return null;
            }

            if (HttpResponseStatus::OK()->getValue() === $statusCode) {
                /**
                 * @var QrCodeDataArray $data
                 */
                $data = json_decode($content, true, 512, JSON_THROW_ON_ERROR);

                return QrCodeData::fromArray($data);
            }
        } catch (\Throwable $throwable) {
            throw InpostPayPostBasketBindingException::createResponseException($throwable);
        }

        throw InpostPayPostBasketBindingException::createBadStatusCodeException($statusCode, $content);
    }
    
    public function putBasket(string $basketId, Basket $basket): InpostBasketId
    {
        $path = sprintf('basket/%s', $basketId);
        $uri = new Uri($this->buildUri($path));
        /** @var string $body */
        $body = json_encode($basket);
        $request = new Request(
            'PUT',
            $uri,
            $this->provideDefaultClientHeaders(),
            $body
        );

        try {
            $response = $this->client->sendRequest($request);
            $content = $response->getBody()->getContents();
            /**
             * @var array{inpost_basket_id: string} $responseData
             */
            $responseData = json_decode($content, true, 512, JSON_THROW_ON_ERROR);

            return InpostBasketId::fromArray($responseData);
        } catch (\Throwable $throwable) {
            throw InpostPayPutBasketException::createResponseException($throwable);
        }
    }

    public function deleteBasketBinding(string $basketId, bool $ifBasketRealized = null): void
    {
        $path = sprintf('basket/%s/binding', $basketId);
        $uri = (new Uri($this->buildUri($path)))
            ->withQuery(Psr7\Query::build(['if_basket_realized' => $ifBasketRealized]));
        $request = new Request(
            'DELETE',
            $uri,
            $this->provideDefaultClientHeaders()
        );

        try {
            $response = $this->client->sendRequest($request);
            $statusCode = $response->getStatusCode();
            $content = $response->getBody()->getContents();
        } catch (\Throwable $throwable) {
            throw InpostPayDeleteBasketBindingException::createResponseException($throwable);
        }

        if (HttpResponseStatus::NO_CONTENT()->getValue() === $statusCode) {
            return;
        }
        throw InpostPayDeleteBasketBindingException::createBadStatusCodeException($statusCode, $content);
    }
    
    public function deleteBrowserBinding(string $browserId): void
    {
        $path = sprintf('browser/%s/binding', $browserId);
        $uri = new Uri($this->buildUri($path));
        $request = new Request(
            'DELETE',
            $uri,
            $this->provideDefaultClientHeaders()
        );

        try {
            $response = $this->client->sendRequest($request);
            $statusCode = $response->getStatusCode();
            $content = $response->getBody()->getContents();
        } catch (\Throwable $throwable) {
            throw InpostPayDeleteBrowserBindingException::createResponseException($throwable);
        }

        if (HttpResponseStatus::NO_CONTENT()->getValue() === $statusCode) {
            return;
        }
        throw InpostPayDeleteBrowserBindingException::createBadStatusCodeException($statusCode, $content);
    }
    
    public function getSigningKey(string $version): SigningKeyResponse
    {
        $path = sprintf('signing-keys/public/%s', $version);
        $uri = new Uri($this->buildUri($path));
        $request = new Request(
            'GET',
            $uri,
            $this->provideDefaultClientHeaders()
        );

        try {
            $response = $this->client->sendRequest($request);
            $statusCode = $response->getStatusCode();
            $content = $response->getBody()->getContents();

            if (HttpResponseStatus::OK()->getValue() === $statusCode) {
                /**
                 * @var SigningKeyResponseArray $data
                 */
                $data = json_decode($content, true, 512, JSON_THROW_ON_ERROR);

                return SigningKeyResponse::fromArray($data);
            }
        } catch (\Throwable $throwable) {
            throw InpostPayGetSigningKeyException::createResponseException($throwable);
        }

        throw InpostPayGetSigningKeyException::createBadStatusCodeException($statusCode, $content);
    }
    
    public function getSigningKeys(): SigningKeysResponse
    {
        $path = 'signing-keys/public';
        $uri = new Uri($this->buildUri($path));
        $request = new Request(
            'GET',
            $uri,
            $this->provideDefaultClientHeaders()
        );

        try {
            $response = $this->client->sendRequest($request);
            $statusCode = $response->getStatusCode();
            $content = $response->getBody()->getContents();

            if (HttpResponseStatus::OK()->getValue() === $statusCode) {
                /**
                 * @var SigningKeysResponseArray $data
                 */
                $data = json_decode($content, true, 512, JSON_THROW_ON_ERROR);

                return SigningKeysResponse::fromArray($data);
            }
        } catch (\Throwable $throwable) {
            throw InpostPayGetSigningKeysException::createResponseException($throwable);
        }
        throw InpostPayGetSigningKeysException::createBadStatusCodeException($statusCode, $content);
    }

    /**
     * @return array{
     *     Authorization: string,
     *     Content-Type: string
     * }
     *
     * @throws InpostPayEndpointException
     */
    private function provideDefaultClientHeaders(): array
    {
        return [
                'Authorization' => sprintf('Bearer %s', $this->bearerService->getBearerToken()),
                'Content-Type' => 'application/json',
        ];
    }

    private function buildUri(string $path): string
    {
        return sprintf(
            '%s%s',
            $this->URLCreator->create()->getUrl(),
            $path
        );
    }
}

W SDK.zip zawiera się kod zawierający obiekt requestu oraz response endpointu.