Dokumentacja Furgonetka Koszyk

Informacje podstawowe

Furgonetka Koszyk 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 furgonetka.pl/koszyk). Niniejsza dokumentacja opisuje indywidualny proces wdrożenia rozwiązania Furgonetka Koszyk 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ę Furgonetka Koszyk 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 Furgonetka Koszyk. Dodatkowo należy podać niejawny klucz wykorzystywany do autoryzacji, który będzie dołączany do każdego request'a wychodzącego z Furgonetka Koszyk do platformy sprzedażowej.

Konfiguracja dla środowiska sandbox

Konfiguracja dla środowiska produkcyjnego

Konfiguracja Furgonetka Koszyk

Na liście integracji w panelu Furgonetka.pl (Sandbox / Produkcja), dla nowo utworzonej integracji własnej należy skonfigurować "Koszyk" oraz "Metody płatności". 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ć Furgonetka Koszyk dla skonfigurowanej integracji.

Wdrożenie Furgonetka Koszyk na platformie sprzedażowej

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

Instalacja Furgonetka Koszyk na platformie sprzedażowej

Załadowanie skryptu Furgonetka Koszyk

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

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 Furgonetka Koszyk.

Inicjalizacja Furgonetka Koszyk

Przygotowanie i wyświetlenie przycisków Furgonetka Koszyk 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 Furgonetka Koszyk 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

Furgonetka Koszyk 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 Furgonetka Koszyk 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 Furgonetka Koszyk. 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 Furgonetka Koszyk

Furgonetka Koszyk 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 Furgonetka Koszyk. 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 Furgonetka Koszyk niezbędne jest przygotowanie API, które pozwoli na dostarczenie kluczowych informacji z Furgonetka Koszyk 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 Furgonetka Koszyk 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 Furgonetka Koszyk i np. odpowiedniego oznaczenia statusu zamówienia po stronie platformy sprzedażowej.

Dokumentacja