Dokumentacja Web API ver. 2

Wprowadzenie

Mapę z punktami odbioru można osadzić na własnej stronie na 2 sposoby:

  • wywołanie JavaScript do otworzenia mapy
  • integracja z formularzem poprzez osadzenie pola INPUT z rozwijalną listą punktów i przyciskiem otwierania mapy

Pierwszą rzeczą do wykonania jest załadowanie biblioteki. W sekcji HEAD lub przed pierwszym użyciem strony należy załadować kod biblioteki:

 

<script src="https://mapa.apaczka.pl/client/apaczka.map.js"></script>

Przed rozpoczęciem integracji należy wygenerować unikalne App ID dla domeny na której będzie osadzana mapa.

Otworzenie mapy

Proste otworzenie mapy możemy zrealizować poprzez:

<script type="application/javascript">
var apaczkaMap = new ApaczkaMap({
    app_id : '{APP_ID}',
    onChange : function( record) {
        if (record) {
            alert('Wybrano: ' + (record.foreign_access_point_id);
        }
    }
});
</script >
<a href="javascript:apaczkaMap.show({});">Otwórz mapę </a>

Otwórz mapę

Instancję mapy można otwierać wielokrotnie metodą show(). Przy każdym wywołaniu mogą zostać przekazane zmienione parametry wywołania, jak np.: dostępni przewoźnicy.

 Integracja z formularzem

Poniższy kod wyszuka element INPUT o podanym id, ukryje go i w jego miejscu wstawi pole rozwijalne z przyciskiem otwierania mapy. Ewentualna wartość z pola INPUT zostanie wykorzystana jako wartość początkowa pola. Po wybraniu punktu przez użytkownika w pole INPUT zostanie wstawiony identyfikator wybranego pola.

<input type="text" value="WAW53AP" id="demo">
<script type="application/javascript">
    var apaczkaMap2 = new ApaczkaMap({
        app_id : 'demo123'
    });
    apaczkaMap2.combobox({
        point_id : 'demo'
    });
</script>

Możliwe jest również poprzez dodatkowe parametry podłączenie pól miasta i ulicy z formularza, tak aby mapa otworzyła się automatycznie na podanej przez użytkownika lokalizacji. Można również sformatować informacje wyświetlane w widocznym polu.

 Parametry ogólne

Parametry, które można przekazać tworząc obiekt ApaczkaMap.

Parametr Typ Opis
app_id string Identyfikator aplikacji wygenerowany w panelu klienta
onChange function Metoda zwrotna, która zostanie wywołana po wybraniu (anulowaniu wyboru) przez użytkownika
criteria array Tablica kryteriów ograniczających dostępne punkty. Patrz poniżej.
center array Tablica dwuelementowa: [latitude, longitude] z domyślnym centrum mapy. Domyślnie: [52.226376, 21.009979]
zoom integer Domyślny zoom mapy. Domyślnie: 12
hideServicesCod bool Opcjonalne ukrycie przycisku filtrowania punktów obsługujących pobranie. Może na przykład zostać wykorzystane razem z kryterium ograniczającym tylko do punktów obsługujących pobranie.

Kryteria

Kryteria podajemy jako tablicę obiektów z poniższymi parametrami.

Nazwa pola Opis
field Nazwa pola z bazy punktów
operator Operator do ograniczenia. Dostępne operatory:
  • eq – równość
  • in – wartość z tablicy
value Wartość ograniczająca pole wg operatora

Pola dostępne przy budowaniu kryteriów.

Nazwa pola Typ pola Opis
services_sender bool Punkt nadania
services_receiver bool Punkt odbioru
services_cod bool Punkt obsługujący pobranie

Przykładowe kryteria dla punktów odbioru:

{field: 'services_receiver', operator: 'eq', value: true}

Parametry mapy

Parametry do otwierania mapy przekazywane w metodzie show().

Parametr Typ Opis
center array Tablica dwuelementowa: [latitude, longitude] z domyślnym centrum mapy. Domyślnie: [52.226376, 21.009979]
zoom integer Domyślny zoom mapy. Domyślnie: 12
point object Obiekt z informacją o punkcie, który ma zostać zaznaczony na mapie. Obiekt wymaga dwóch parametrów:
  • foreign_access_point_id – Identyfikator punktu
  • supplier – Nazwa kodowa dostawcy
address object Obiekt z informacją o adresie, który zostanie wyszukany i na nim zostanie otworzona mapa. Obiekt wymaga dwóch parametrów:
  • street – Nazwa ulicy
  • city – Nazwa miasta

Parametry listy rozwijanej

Parametry do integracji z formularzem przekazywane w metodzie combobox().

Parametr Typ Opis
point_id string ID elementu INPUT z identyfikatorem wybranego pola. Pole zostanie ukryte i w to miejsce wstawiona lista rozwijana. Po wybnraniu punktu przez użytkownika wskazany element INPUT otrzyma nowy identyfikator wybranego pola.
supplier_id string ID elementu INPUT/SELECT z nazwą kodową przewoźnika. Przy wyświetlaniu mapy z wybranym punktem z tego pola zostanie pobrana nazwa kodowa przewoźnika. Po wybraniu punktu pole zostanie również zaktualizowane.
street_id string ID elementu INPUT z nazwą ulicy adresu. Przy wyświetlaniu mapy bez wybranego punktu z tego pola jak i pola z miastem zostanie pobrany domyślny obszar mapy do wyświetlenia. Do wykorzystania gdy klient podał swój adres i umozliwiamy mu znalezienie najbliższego punktu odbioru. Pole nie jest modyfikowane.
city_id string ID elementu INPUT z nazwą miasta adresu. Przy wyświetlaniu mapy bez wybranego punktu z tego pola jak i pola z ulicy zostanie pobrany domyślny obszar mapy do wyświetlenia. Do wykorzystania gdy klient podał swój adres i umozliwiamy mu znalezienie najbliższego punktu odbioru. Pole nie jest modyfikowane.
height integer Wysokość rozwijanej listy. Domyślnie: 300
placeholder string Tekst wyświetlany w polu, gdy żaden punkt nie został jeszcze wybrany.
formatDisplay function Metoda do formatowania pola wyświetlającego wybrany punkt. Domyślnie wyświetlany jest tylko numer punktu. Metoda dostaje w parametrze rekord ze wszystkimi informacjami wybranego punktu i powinna zwrócić wartość string do wyświetlenia.

Lista przewoźników

Poprzez metodę setFilterSupplierAllowed() można zmodyfikować listę dostępnych przewoźników. W pierwszym parametrze przekazywana jest tablica dostępnych przewoźników, a w drugim opcjonalnie ograniczona tablica domyślnie aktywnych przewoźników.

apaczkaMap. setFilterSupplierAllowed(
    ['DHL_PARCEL', 'DPD', 'INPOST', 'POCZTA', 'UPS'],
    ['INPOST']
);
Nazwa kodowa przewoźnika
DHL_PARCEL
DPD
INPOST
POCZTA
UPS

Poprzez metodę setSupplier() można ustawić aktualnie wybranego przewoźnika. W takiej sytuacji użytkownikowi przy innym przewoźniku pojawi się przycisk „Wybierz i zmień przewoźnika” zamiast „Wybierz”.

apaczkaMap3.setSupplier('INPOST');

Przykład integracji z formularzem

Ulica:

Miasto:

Przewoźnik:

Punkt dostawy:

Wybierz punkt dostawy…
<p>
    Ulica: <input type="text" id="demo3_street" value="Klimczaka 1">
</p>
<p>
    Miasto: <input type="text" id="demo3_city" value="Warszawa">
</p>
<p>
    Przewoźnik: <input id="demo3_supplier" readonly></input>
</p>
<p>
    Punkt dostawy: <input type="text" id="demo3_foreign_access_point">

<script type="application/javascript"> var apaczkaMap3 = new ApaczkaMap({ app_id : 'demo123', criteria : [ {field: 'services_receiver', operator: 'eq', value: true} ] }); apaczkaMap3.combobox({ point_id : 'demo3_foreign_access_point', supplier_id : 'demo3_supplier', street_id : 'demo3_street', city_id : 'demo3_city', placeholder: 'Wybierz punkt dostawy...', formatDisplay : ( record) => { let display = record.foreign_access_point_id; if ( record .name && record.name.length > 0) { display += ' - ' + record.name; } return display; } }); apaczkaMap3.setSupplier('INPOST'); apaczkaMap3.setFilterSupplierAllowed( ['DHL_PARCEL', 'DPD', 'INPOST', 'POCZTA'], ['INPOST'] ); </script >

Changelog

1.0.1 – 2020-01-02
  • Możliwość ukrycia filtru na pobranie
1.0.0 – 2019-11-07
  • Pierwsza wersja API do integracji mapy

Adres kontaktowy

Informujemy, że Administratorem danych osobowych jest R2G Polska Sp. z o.o. z siedzibą w Warszawie (02-797), ul. Klimczaka 1. Dane będą przetwarzane w celu wykonania postanowień regulaminu oraz marketingu własnego. Każdy ma prawo wglądu do treści danych oraz ich poprawiania. Dane są podane dobrowolnie, lecz są warunkiem świadczenia usługi.

Copyright @ 2020 apaczka.pl

Adres kontaktowy

Informujemy, że Administratorem danych osobowych jest R2G Polska Sp. z o.o. z siedzibą w Warszawie (02-797), ul. Klimczaka 1. Dane będą przetwarzane w celu wykonania postanowień regulaminu oraz marketingu własnego. Każdy ma prawo wglądu do treści danych oraz ich poprawiania. Dane są podane dobrowolnie, lecz są warunkiem świadczenia usługi.

Copyright @ 2020 apaczka.pl.

Adres kontaktowy

Informujemy, że Administratorem danych osobowych jest R2G Polska Sp. z o.o. z siedzibą w Warszawie (02-797), ul. Klimczaka 1. Dane będą przetwarzane w celu wykonania postanowień regulaminu oraz marketingu własnego. Każdy ma prawo wglądu do treści danych oraz ich poprawiania. Dane są podane dobrowolnie, lecz są warunkiem świadczenia usługi.

Copyright @ 2020 apaczka.pl.