7. Complete API Reference
7.1 HTML Attributes#
Attributes are used for declarative configuration directly in HTML. Values are always strings.| Attribute | Type | Required | Description |
|---|
api-key | string | Yes | API key assigned to the e-shop for authentication |
config | JSON string | No | Widget configuration (see 7.5) |
7.2 JavaScript Properties#
Properties allow passing JS objects directly without JSON serialization.| Property | Type | Access | Description |
|---|
version | string | read-only | Widget version |
widgetConfig | WidgetConfig | undefined | read/write | Widget configuration |
7.3 JavaScript Methods#
| Method | Parameters | Return Type | Description |
|---|
configure(options) | Partial<WidgetConfig> | void | Partial merge configuration — changes only specified parameters, preserves the rest |
open() | — | void | Opens the widget (modal mode only) |
close() | — | void | Closes the widget (modal mode only) |
getSelectedAccessPoint() | — | DetailResponseModel | null | Returns the selected access point or null |
reset() | — | void | Resets the widget to its default state |
7.4 Custom Events#
All events have the prefix ppl-accesspointwidget-, are emitted with bubbles: true and composed: true (pass through Shadow DOM).| Event | Payload (e.detail) | Description |
|---|
ppl-accesspointwidget-select | Access point object (see 7.8) | User selected an access point |
ppl-accesspointwidget-close | null | Widget closed (without selection) |
ppl-accesspointwidget-error | { code: string, message: string } | Error during initialization or API call |
ppl-accesspointwidget-ready | null | Widget successfully initialized |
Complete list of parameters passed via the config attribute or widgetConfig property. Parameters marked (admin) are typically configured in the widget admin by api-key — override them via config only when a specific page must differ from the global setting.General / UI#
| Parameter | Type | Default | Description |
|---|
theme | string | "PPL_THEME" | Widget theme |
viewMode | "inline" | "modal" | "modal" / from admin | (admin) Display mode — widget default is modal; admin can switch to inline. The config attribute on the element takes highest priority. |
closeButtonVisible | boolean | — | Show close button |
defaultLang | string | from admin / "cs" | (admin) Default language (see 7.6) |
langMenu | boolean | — | Show language selection dropdown |
defaultCountry | string | from admin / "CZ" | (admin) Default country (ISO 3166-1 alpha-2) |
allowedCountries | string[] | from admin | (admin) Allowed countries (intersection with server configuration) |
countriesMenuDisabled | boolean | false | Disable the country menu in the filter |
Map Position#
| Parameter | Type | Description |
|---|
centeredToAddress | string | Text address to center the map on |
centeredToLat | number | Latitude (WGS84) |
centeredToLon | number | Longitude (WGS84) |
Package Dimensions#
| Parameter | Type | Description |
|---|
packageWeight | number | Weight in kilograms |
packageWidth | number | Width in centimetres |
packageHeight | number | Height in centimetres |
packageLength | number | Length in centimetres |
Services#
| Parameter | Type | Description |
|---|
ageCheck | boolean | Require age verification |
codRequired | boolean | Cash on delivery required |
Access Points#
| Parameter | Type | Description |
|---|
accessPointCode | string | KM code of the access point to pre-select (format KM + 7 digits, e.g. KM1234567) |
disabledAccessPointTypes | string[] | (admin) Disabled access point types — config is merged with the server list |
economyMode | boolean | (admin) Economy mode (Smart2Box) — server value cannot be overridden |
7.6 Supported Languages (defaultLang)#
| Code | Language |
|---|
bg | Bulgarian |
cs | Czech |
de | German |
en | English |
es | Spanish |
fr | French |
hr | Croatian |
hu | Hungarian |
it | Italian |
nl | Dutch |
no | Norwegian |
pl | Polish |
ro | Romanian |
sk | Slovak |
7.7 Access Point Types#
| Type | Description |
|---|
ParcelShop | Staffed pickup location (PPL Parcel Shop) |
ParcelBox | Self-service parcel locker (PPL Parcel Box) |
AlzaBox | AlzaBox terminal (partner) |
7.8 Selected Access Point Structure (DetailResponseModel)#
Object returned in e.detail of the ppl-accesspointwidget-select event and by the getSelectedAccessPoint() method:Note: All fields are optional (nullable). Always check for the presence of values when processing.
7.9 Configuration Priority#
Configuration is merged according to priority rules. The e-shop cannot extend server restrictions (set by the API key), only narrow them.1.
Server configuration (API claims by api-key) → Default settings from widget admin
2.
Init parameters (config attribute / widgetConfig) → Overrides (or narrows) the default settings
3.
URL parameters → Highest priority
If you specify no parameters in config, the widget uses exclusively the default configuration from the admin — this is sufficient in most cases.
Use the config attribute only for parameters that differ from the default admin settings — typically dynamic cart data, pre-selected access point, map centering, or a page-level viewMode override.
Global settings (default language, country, allowed AP types, viewMode, economyMode) are best managed in the widget admin, not in the integration source code — changes then do not require a deployment.
Narrowing example: The server allows countries ["CZ", "SK", "HU"], the e-shop sets allowedCountries: ["CZ", "DE"] → the result is ["CZ"] (intersection). "DE" is not permitted by the server and will be ignored.
Modified at 2026-04-22 12:04:29
