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()`	—	SelectedAccessPointModel \| 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`	SelectedAccessPointModel (viz 7.8) - stejný tvar bez ohledu na to, odkud uživatel místo vybral	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"`	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
`sl`	Slovinština

Vložení do stránky:

<ppl-access-point-widget
 id="pplWidget"
 api-key="**************************"
 config='{"viewMode":"modal","defaultCountry":"cz","defaultLang":"de"}'
></ppl-access-point-widget>

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 (SelectedAccessPointModel)

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

Objekt má vždy stejnou strukturu bez ohledu na to, odkud uživatel místo vybral (seznam míst v okolí, detail místa, uložená místa, naposledy vybrané místo). Widget ho skládá z údajů společných všem zdrojům, žádný další dotaz na API kvůli tomu neprobíhá.

Poznámka:
• Všechna pole jsou volitelná (nullable). Při zpracování vždy kontrolujte přítomnost hodnot.
• type obsahuje název typu z číselníku výdejních míst (ParcelShop, ParcelBox, AlzaBox), nikoli interní kód API.
• accessPointType je zastaralé a nese vždy stejnou hodnotu jako type. Je ponecháno pro zpětnou kompatibilitu a bude odebráno ve verzi 2.0 — v nových integracích používejte výhradně type.
• Pole additionalNote (poznámka k výdejnímu místu) a urlPath (cesta na detail místa na ppl.cz) jsou rezervovaná — v objektu jsou vždy přítomná, ale zatím nesou null. Tyto údaje vrací pouze část zdrojů, ze kterých widget objekt skládá, takže by se objekt jinak lišil podle způsobu výběru. Jakmile budou dostupné všude, začnou se plnit bez další změny kontraktu. Počítejte s nimi v integraci, ale nespoléhejte zatím na hodnotu.

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 (packageWeight, codRequired, …), předvybrané místo (accessPointCode), vystředění mapy (centeredToAddress) 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 (SelectedAccessPointModel)#

7.9 Priorita konfigurace#