Jak zintegrować Mapę od Furgonetki przez API?

Ten artykuł jest przeznaczony dla sklepów, które nie korzystają z wtyczek Furgonetka.pl (WooCommerce, PrestaShop, Shoper, Magento, Sellastik) i chcą samodzielnie zintegrować mapę punktów odbioru bezpośrednio w kodzie swojej strony.

Zobacz, jak zintegrować mapę punktów odbioru przez API | Akademia Furgonetki:

Integracja ręczna składa się z czterech kroków:

wygenerowania klucza API
załadowania skryptu mapy
wywołania widgetu z odpowiednimi parametrami
obsługi wybranego punktu przez klienta

Ważne: Jeśli korzystasz z jednej z dostępnych wtyczek Furgonetka.pl, nie musisz nic konfigurować ręcznie. Klucz API jest zarządzany automatycznie przez wtyczkę.

1. Wygeneruj klucz API

Aby mapa działała na Twojej stronie, potrzebujesz klucza API przypisanego do domeny sklepu. Klucz identyfikuje Twój sklep i sprawia, że mapa działa wyłącznie na wskazanych domenach.

Krok 1 Przejdź do dokumentacji API Furgonetka Mapa.

Krok 2 W sekcji Dostęp do mapy kliknij przycisk Zarządzaj klientami mapy,

Krok 3 Zaloguj się do swojego konta na Furgonetka.pl. Jeśli jeszcze nie masz konta, przejdź przez proces jego rejestracji.

Krok 4 Na stronie zarządzania klientami mapy kliknij przycisk Dodaj klienta mapy.

Krok 5 W nowym oknie wpisz domeny swojego sklepu (jedną w każdej linii, bez http / https) i kliknij Zapisz i wygeneruj klucz API.

Krok 6 Po zapisaniu pojawi się okno z kluczem. Skopiuj go i zapisz w bezpiecznym miejscu.

Ważne: Klucz API jest wyświetlany tylko raz, bezpośrednio po wygenerowaniu. Jeśli go utracisz, będziesz musiał wygenerować nowy za pomocą opcji [Generuj token] na liście klientów - poprzedni klucz przestanie działać natychmiast.

2. Załaduj skrypt mapy na swojej stronie

Skrypt mapy należy umieścić w sekcji strony z atrybutem async. Dzięki temu ładuje się asynchronicznie i nie blokuje pozostałej zawartości strony.

<script src="https://furgonetka.pl/js/dist/map/map.js" async></script>

Ważne: Ponieważ skrypt ładuje się asynchronicznie, przed wywołaniem new window.Furgonetka.Map() upewnij się, że obiekt window.Furgonetka jest już dostępny. Wywołanie mapy przed załadowaniem skryptu spowoduje błąd. Sprawdź to warunkiem if (!window.Furgonetka) - przykład w kodzie poniżej.

3. Wywołaj widget mapy

W miejscu, gdzie chcesz uruchomić mapę (np. po kliknięciu przycisku przez użytkownika), dodaj poniższy kod JavaScript. Przekaż klucz API wygenerowany w Kroku 1 jako parametr apiKey.

Najważniejsze parametry:

apiKey - klucz API wygenerowany w Kroku 1 (wymagany).
courierServices - lista przewoźników, których punkty mają być wyświetlane na mapie. Dostępne wartości: allegro, dhl, dpd, fedex, furgonetkapunkt, gls, inpost, meest, orlen, poczta, ups.
callback - funkcja wywoływana po wybraniu punktu przez użytkownika. Jako argument otrzymuje obiekt z danymi wybranego punktu (wymagany).

Pełna lista parametrów dostępna jest w dokumentacji API Furgonetka Mapa.

4. Obsłuż wybrany punkt

Po wybraniu punktu przez użytkownika mapa wywołuje funkcję callback i przekazuje dane wybranego punktu.
Zapisz kod punktu w zamówieniu. Będzie potrzebny do wygenerowania etykiety przewozowej.

callback: (params) => {
const kod = params.point.code; // np. 'AGA01N'
const nazwa = params.point.name; // np. 'InPost Paczkomat AGA01N'
const typ = params.point.type; // np. 'inpost'
// zapisz w formularzu zamowienia lub stanie aplikacji
document.getElementById('punkt-odbioru').value = kod;
}

Parametry zwracane przez callback:

point.code - kod wybranego punktu (format zależny od przewoźnika, szczegóły w dokumentacji API).
point.name - pełna nazwa punktu.
point.type - identyfikator przewoźnika (np. inpost, dpd, orlen).
point.country_code - kod kraju punktu (np. PL).
point.furgonetka_point - informacja czy punkt należy do sieci Furgonetka.
point.cod - informacja czy punkt obsługuje płatność za pobraniem.

Instalacja i uruchomienie

Integracja mapy z Twoją stroną wymaga dwóch kroków: załadowania skryptu mapy oraz wywołania jej w odpowiednim momencie, np. po kliknięciu przycisku przez użytkownika.

Skrypt mapy należy umieścić w sekcji <head> strony z atrybutem async - dzięki temu nie blokuje on ładowania pozostałej zawartości. Ponieważ skrypt ładuje się asynchronicznie, przed wywołaniem mapy należy upewnić się, że obiekt window.Furgonetka jest już dostępny.

Poniższy przykład przedstawia kompletną, minimalną implementację - od załadowania skryptu po obsługę wybranego punktu:

<!DOCTYPE html>
<html lang="pl">
<head>
    <meta charset="UTF-8">
    <script src="https://furgonetka.pl/js/dist/map/map.js" async></script>
</head>
<body>
    <button id="show-map">Wybierz punkt odbioru</button>

    <script>
        document.getElementById('show-map').addEventListener('click', () => {
            if (!window.Furgonetka) {
                console.error('Skrypt mapy nie został jeszcze załadowany.');
                return;
            }

            new window.Furgonetka.Map({
                apiKey: 'TWOJ_KLUCZ_API',
                courierServices: ['inpost', 'poczta'],
                callback: (params) => {
                    console.log('Wybrany punkt:', params.point.code, params.point.name);
                },
            }).show();
        });
    </script>
</body>
</html>

Najczęstsze pytania

Co zrobić, jeśli mapa nie wyświetla się po wdrożeniu?

Sprawdź czy:

domena w przeglądarce dokładnie zgadza się z domeną podaną przy generowaniu klucza
klucz API jest poprawnie przekazany jako parametr apiKey (bez spacji i dodatkowych znaków)
skrypt mapy jest załadowany zanim wywołasz new window.Furgonetka.Map()
klient mapy ma status Aktywny na liście klientów w panelu

Co zrobić, jeśli zgubię klucz API?

Wejdź na stronę zarządzania klientami mapy, znajdź odpowiedni wpis i kliknij Generuj token. Nowy klucz zostanie wygenerowany, a poprzedni przestanie działać natychmiast. Zaktualizuj klucz we wszystkich miejscach, gdzie był używany.

Ile domen mogę przypisać do jednego klucza?

Możesz przypisać wiele domen do jednego klucza - wpisz każdą w osobnej linii. Przydatne gdy sklep działa pod kilkoma adresami, np. z www i bez www.

Ile kluczy API mogę mieć na jednym koncie?

Możesz posiadać maksymalnie 5 aktywnych klientów mapy na jednym koncie Furgonetka.pl.

Jak działa mapa gdy klient wybierze płatność za pobraniem?

Mapa automatycznie ukrywa punkty nieobsługujące płatności za pobraniem, jeśli przekażesz odpowiedni parametr. Szczegóły w dokumentacji API - parametr pointTypesFilter.

Jak możemy Ci pomóc?

Pomoc

Jak zintegrować Mapę od Furgonetki przez API?

Powiązane artykuły

Najpopularniejsze tematy

Skontaktuj się z nami

Nie można załączyć plików:

Upuść pliki, aby je załączyć

Pomoc i kontakt

Kategorie najczęściej zadawanych pytań

Zobacz DEMO

Pomoc

Jak zintegrować Mapę od Furgonetki przez API?

Powiązane artykuły

Najpopularniejsze tematy

Skontaktuj się z nami

Nie można załączyć plików:

Upuść pliki, aby je załączyć

Kategorie najczęściej
zadawanych pytań