7. Kompletní API reference

7.1 HTML atributy

Atributy slouží pro deklarativní konfiguraci přímo v HTML. Hodnoty jsou vždy stringy.

Atribut	Typ	Povinný	Popis
`api-key`	string	Ano	API klíč přidělený e-shopu pro autentizaci
`config`	JSON string	Ne	Konfigurace widgetu (viz 7.5)

7.2 JavaScript properties

Properties umožňují předávat JS objekty přímo bez JSON serializace.

Property	Typ	Přístup	Popis
`version`	string	pouze čtení	Verze widgetu
`widgetConfig`	WidgetConfig \| undefined	čtení/zápis	Konfigurace widgetu

7.3 JavaScript metody

Metoda	Parametry	Návratový typ	Popis
`configure(options)`	`Partial<WidgetConfig>`	void	Partial merge konfigurace — změní pouze zadané parametry, ostatní zachová
`open()`	—	void	Otevře widget (pouze v modal režimu)
`close()`	—	void	Zavře widget (pouze v modal režimu)
`getSelectedAccessPoint()`	—	DetailResponseModel \| null	Vrátí vybrané výdejní místo nebo null
`reset()`	—	void	Resetuje widget do výchozího stavu

7.4 Custom Events

Všechny eventy mají prefix ppl-accesspointwidget-, jsou emitovány s bubbles: true a composed: true (prochází Shadow DOM).

Event	Payload (e.detail)	Popis
`ppl-accesspointwidget-select`	Objekt výdejního místa (viz 7.8)	Uživatel vybral výdejní místo
`ppl-accesspointwidget-close`	null	Widget zavřen (bez výběru)
`ppl-accesspointwidget-error`	`{ code: string, message: string }`	Chyba při inicializaci nebo API volání
`ppl-accesspointwidget-ready`	null	Widget úspěšně inicializován

7.5 Konfigurační parametry (WidgetConfig)

Kompletní seznam parametrů předávaných přes atribut config nebo property widgetConfig. Parametry označené (administrace) obvykle nastavuje administrace widgetu dle api-key — přes config je přepisujte jen když se konkrétní stránka musí lišit od globálního nastavení.

Obecné / UI

Parametr	Typ	Výchozí	Popis
`theme`	string	`"PPL_THEME"`	Téma widgetu
`viewMode`	`"inline" \| "modal"`	`"modal"` / z administrace	(administrace) Režim zobrazení — výchozí hodnota widgetu je modal; administrace může přepnout na inline. Atribut config na elementu má nejvyšší prioritu.
`closeButtonVisible`	boolean	—	Zobrazení tlačítka pro zavření
`defaultLang`	string	z administrace / `"cs"`	(administrace) Výchozí jazyk (viz 7.6)
`langMenu`	boolean	—	Zobrazení dropdown menu pro výběr jazyka
`defaultCountry`	string	z administrace / `"CZ"`	(administrace) Výchozí země (ISO 3166-1 alpha-2)
`allowedCountries`	string[]	z administrace	(administrace) Povolené země (průnik se serverovou konfigurací)
`countriesMenuDisabled`	boolean	`false`	Vypnutí menu se zeměmi ve filtru

Poloha mapy

Parametr	Typ	Popis
`centeredToAddress`	string	Slovní adresa pro vystředění mapy
`centeredToLat`	number	Zeměpisná šířka (WGS84)
`centeredToLon`	number	Zeměpisná délka (WGS84)

Balení zásilky

Parametr	Typ	Popis
`packageWeight`	number	Váha v kilogramech
`packageWidth`	number	Šířka v centimetrech
`packageHeight`	number	Výška v centimetrech
`packageLength`	number	Délka v centimetrech

Služby

Parametr	Typ	Popis
`ageCheck`	boolean	Požadavek na ověření věku
`codRequired`	boolean	Nutnost platby dobírky

Výdejní místa

Parametr	Typ	Popis
`accessPointCode`	string	KM kód výdejního místa pro předvybrání (formát KM + 7 číslic, např. KM1234567)
`disabledAccessPointTypes`	string[]	(administrace) Zakázané typy výdejních míst — config sjednocuje se serverovým seznamem
`economyMode`	boolean	(administrace) Ekonomický režim (Smart2Box) — hodnotu ze serveru nelze přepsat

7.6 Podporované jazyky (defaultLang)

Kód	Jazyk
`bg`	Bulharština
`cs`	Čeština
`de`	Němčina
`en`	Angličtina
`es`	Španělština
`fr`	Francouzština
`hr`	Chorvatština
`hu`	Maďarština
`it`	Italština
`nl`	Nizozemština
`no`	Norština
`pl`	Polština
`ro`	Rumunština
`sk`	Slovenština

7.7 Typy výdejních míst

Typ	Popis
`ParcelShop`	Obsluhované výdejní místo (PPL Parcel Shop)
`ParcelBox`	Samoobslužný výdejní box (PPL Parcel Box)
`AlzaBox`	AlzaBox terminál (partnerský)

7.8 Struktura vybraného výdejního místa (DetailResponseModel)

Objekt vrácený v e.detail události ppl-accesspointwidget-select a metodou getSelectedAccessPoint():

Poznámka: Všechna pole jsou volitelná (nullable). Při zpracování vždy kontrolujte přítomnost hodnot.

7.9 Priorita konfigurace

Konfigurace se slučuje podle pravidel priority. E-shop nemůže rozšířit serverová omezení (daná API klíčem), pouze je zúžit.

Serverová konfigurace (API claims dle api-key) → Výchozí nastavení z administrace widgetu

Init parametry (config atribut / widgetConfig) → Přepisuje (nebo zužuje) výchozí nastavení

URL parametry → Nejvyšší priorita

Doporučení pro integraci:

Pokud neuvedete žádný parametr v config, widget použije výhradně výchozí konfiguraci z administrace — v běžném případě je to dostačující.

Atribut config používejte jen pro parametry, které se liší od výchozího nastavení administrace — typicky dynamická data z košíku, předvybrané místo, vystředění mapy nebo override viewMode pro konkrétní stránku.

Globální nastavení (výchozí jazyk, země, povolené typy AP, viewMode, economyMode) doporučujeme spravovat v administraci widgetu, nikoliv ve zdrojovém kódu integrace — změna pak nevyžaduje deploy.

Příklad omezení (zúžení): Server povoluje země ["CZ", "SK", "HU"], e-shop nastaví allowedCountries: ["CZ", "DE"] → výsledek je ["CZ"] (průnik). Země "DE" není povolena serverem, proto bude ignorována.

7. Kompletní API reference

7.1 HTML atributy#

7.2 JavaScript properties#

7.3 JavaScript metody#

7.4 Custom Events#

7.5 Konfigurační parametry (WidgetConfig)#

Obecné / UI#

Poloha mapy#

Balení zásilky#

Služby#

Výdejní místa#

7.6 Podporované jazyky (defaultLang)#

7.7 Typy výdejních míst#

7.8 Struktura vybraného výdejního místa (DetailResponseModel)#

7.9 Priorita konfigurace#