lang_en lang_pl
Dokumentacja Web API ver. 2 - Integracja mapy

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:

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:

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.: dostepni 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. Po wybraniu punktu przez użytkownika w pole INPUT zostanie wstawiony identyfikator wybranego pola.

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
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

Przykładowe kryteria dla punktów odbioru:

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.

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".

Przykład integracji z formularzem

Ulica:

Miasto:

Przewoźnik:

Punkt dostawy:

Changelog
1.0.0 - 2019-11-07
  • Pierwsza wersja API do integracji mapy