Dokumentacja Portmonetka

Informacje podstawowe

Portmonetka jest to rozwiązanie typu "fast checkout", usprawniające proces finalizacji transakcji zakupowych na platformach e-commerce (więcej informacji dostępnych na dedykowanej stronie portmonetka.pl). Niniejsza dokumentacja opisuje indywidualny proces wdrożenia rozwiązania Portmonetka na własnej platformie sprzedażowej. Jeżeli szukasz gotowego rozwiązania, sprawdź dostępność wtyczki dla twojej platformy sklepowej w zakładce Sklepy.

Środowiska integracji

Dostępne są dwa środowiska integracji:

Sandbox: https://sandbox.furgonetka.pl - środowisko służy do budowania i testowania integracji

Produkcja: https://furgonetka.pl - środowisko docelowe integracji, wykorzystywane przez klientów

Proces integracji

Połączenie z platformą sprzedażową

W panelu Furgonetka.pl należy skonfigurować integrację własną, która pozwoli na komunikację Portmonetki z twoją platformą sprzedażową (dodawanie zamówień, przekazywanie informacji o płatnościach itd.). Do tego celu niezbędne jest posiadanie konta w serwisie Furgonetka.pl. Do wykonania połączenia konieczne jest wskazanie bazowego adresu URL, pod którym będą dostępne endpoint'y API wykorzystywane przez Portmonetkę. Dodatkowo należy podać niejawny klucz wykorzystywany do autoryzacji, który będzie dołączany do każdego request'a wychodzącego z Portmonetki do platformy sprzedażowej.

Konfiguracja dla środowiska sandbox

Konfiguracja dla środowiska produkcyjnego

Konfiguracja Portmonetki

Na liście integracji w panelu Furgonetka.pl (Sandbox / Produkcja), dla nowo utworzonej integracji własnej należy wybrać opcję "Skonfiguruj teraz" w sekcji Portmonetka. W przypadku środowiska testowego obowiązują dane do testowych środowisk dostawców płatności. Po zapisaniu ustawień, z poziomu listy integracji należy włączyć Portmonetkę dla skonfigurowanej integracji.

Wdrożenie Portmonetki na platformie sprzedażowej

Posiadając skonfigurowaną integrację własną i włączoną Portmonetkę, należy wykonać instalację przycisków Portmonetki po stronie platformy sprzedażowej oraz zaimplementować odpowiednie endpoint'y API zgodnie z dokumentacją.

Instalacja Portmonetki na platformie sprzedażowej

Załadowanie skryptu Portmonetki

Do nagłówka strony HTML należy dodać skrypt Portmonetki. Skrypt powinien być dołączany tylko na tych stronach, gdzie będzie wyświetlany przycisk Portmonetki.

Nazwa skryptu jest różna w zależności od środowiska:

Sandbox: https://furgonetka.pl/js/dist/checkout/universal-checkout-sandbox.js

Produkcja: https://furgonetka.pl/js/dist/checkout/universal-checkout-prod.js

<head>
	<script src="https://furgonetka.pl/js/dist/checkout/universal-checkout-sandbox.js" defer></script>
</head>

Po załadowaniu skryptu, na obiekcie window wywoływane jest zdarzenie JavaScript (Event) furgonetka.checkout.ready, które może zostać wykorzystane do inicjalizacji Portmonetki.

Inicjalizacja Portmonetki

Przygotowanie i wyświetlenie przycisków Portmonetki na platformie sprzedażowej wykonywane jest przez wywołanie metody init z odpowiednimi parametrami na dostarczonym obiekcie JavaScript Furgonetka.Checkout.

Furgonetka.Checkout.init({
	// ...
});

Szczegółowy opis parametrów metody init dostępny jest w definicji TypeScript interfejsu CheckoutInitConfiguration.

Implementacja funkcji dostarczającej dane koszyka (data provider)

Podczas inicjalizacji Portmonetki należy przekazać implementację funkcji dataProviderCallback zwracającej obietnicę JavaScript (Promise), która dostarcza dane niezbędne do złożenia zamówienia tj. informacje o produktach, dostępnych metodach dostawy i płatności. Szczegółowy opis wymaganych danych dostępny jest w definicji TypeScript interfejsu CheckoutCartData. Sposób w jaki funkcja przygotowuje dane jest dowolny, mogą one zostać pobrane z backend'u platformy sprzedażowej lub w całości zbudowane po stronie JavaScript.

Furgonetka.Checkout.init({
	dataProviderCallback: () => {
		return fetch('/api/cart').then(response => response.json());
	},
	// ...
});

Implementacja przycisku z opcją dodawania do koszyka

Portmonetka dostarcza możliwość konfiguracji przycisku z bezpośrednią opcją dodawania produktów do koszyka na platformie sprzedażowej. Ten rodzaj przycisku znajduje swoje zastosowanie np. na stronach produktów, gdzie przed uruchomieniem Portmonetki może zostać wykonana dodatkowa logika dodająca wybrany produkt do koszyka.

W celu skonfigurowania przycisku należy przekazać dwa parametry: addProductToCartButtonContainer i addProductToCartCallback do metody inicjalizacji Portmonetki. Parametr addProductToCartButtonContainer to selektor kontenera, w którym zostanie umieszczony przycisk, natomiast parametr addProductToCartCallback to implementacja funkcji zawierającej logikę dodawania produktu do koszyka zakupowego. Szczegółowy opis parametrów dostępny jest w definicji TypeScript interfejsu CheckoutInitConfiguration.

Furgonetka.Checkout.init({
	addProductToCartButtonContainer: ".product.card",
	addProductToCartCallback: (event) => {
		const productId; // set product ID
		
		return fetch('/cart/add-product/' + productId, {
			// ...
		}).then(
			response => {
				return true;
			}
		);
	},
	// ...
});

Implementacja funkcji obsługującej zdarzenia Portmonetki

Portmonetka dostarcza możliwość przechwytywania po stronie platformy sprzedażowej zdarzeń powstałych na skutek interakcji użytkownika np. złożenie zamówienia. W celu skonfigurowania obsługi zdarzeń należy przekazać parametr eventsCallback do metody inicjalizacji Portmonetki. Szczegółowy opis parametru dostępny jest w definicji TypeScript interfejsu CheckoutInitConfiguration.

Furgonetka.Checkout.init({
	eventsCallback: ({ type, payload }) => {
		if (type === "ORDER_CREATED") {
			// handle event
		}
	},
	// ...
});

Przygotowanie API na platformie sprzedażowej

Do pełnego funkcjonowania Portmonetki niezbędne jest przygotowanie API, które pozwoli na dostarczenie kluczowych informacji z Portmonetki do platformy sprzedażowej np. dane zamówienia złożonego przez klienta, czy informacje o statusie płatności za zamówienie.

Wszystkie żądania (request) wysyłane do API platformy sprzedażowej opierają się o dane podane w procesie konfiguracji połączenia z platformą sprzedażową (sekcja Połączenie z platformą sprzedażową).

Dokumentacja API

Obsługa dodawania zamówień

Endpoint powinien być wykorzystywany do odbierania informacji o zamówieniu złożonym przez klienta w Portmonetce i zapisywania tych informacji w bazie platformy sprzedażowej. W odpowiedzi należy zwrócić dane opisane w dokumentacji, które są niezbędne do utworzenia zamówienia po stronie Furgonetki.

Dokumentacja

Obsługa statusu płatności dla zamówień

Endpoint powinien być wykorzystywany do odbierania informacji statusie płatności online (np. BLIK) za określone zamówienie złożone przez klienta w Portmonetce i np. odpowiedniego oznaczenia statusu zamówienia po stronie platformy sprzedażowej.

Dokumentacja