# Jak funguje doplněk Sestav si vlastní balíček

> Zákazník si na e-shopu poskládá vlastní balíček se slevou a v košíku z něj je běžný produkt. Vysvětlujeme, co se přitom děje na pozadí.

- **Zdroj:** https://www.webotvurci.cz/navody/sestav-si-vlastni-balicek/jak-funguje-doplnek-sestav-si-vlastni-balicek/
- **Doplněk / kategorie:** Sestav si vlastní balíček (https://www.webotvurci.cz/navody/sestav-si-vlastni-balicek/)
- **Datum:** 2026-08-12
- **Autor:** Webotvůrci (https://www.webotvurci.cz/)

---

Nabídnout zákazníkovi „vyberte si libovolné tři kávy a máte je o 15 % levněji" zní jako triviální akce. Na Shoptetu to ale znamená předem vyrobit každou možnou kombinaci jako samostatnou sadu — a při dvanácti kávách jich jsou dvě stovky. Doplněk **Sestav si vlastní balíček** (interně Multipack) tuhle práci odstraňuje: kombinaci vyrobí až ve chvíli, kdy si ji konkrétní zákazník opravdu složí.

Tenhle text je úvod do mechaniky doplňku. Je psaný tak, aby dával smysl majiteli e-shopu i vývojáři, který zvažuje integraci. Praktické zapojení řeší [navazující návod o nasazení](https://www.webotvurci.cz/navody/sestav-si-vlastni-balicek/nasazeni-balicku-na-shoptet-krok-za-krokem/), technický kontrakt pak [dokumentace API](https://www.webotvurci.cz/navody/sestav-si-vlastni-balicek/api-doplnku-sestav-si-vlastni-balicek-pro-vyvojare/).

## Co doplněk řeší

Na stránce e-shopu se zákazníkovi vykreslí konfigurátor: tolik výběrových míst, kolik má balíček obsahovat. Do každého si vybere jeden produkt z nabídky, kterou předem určil obchodník. U položek vidí fotku, cenu, hodnocení i skladovou dostupnost a při každé změně se přepočítá cena i úspora.

Když zákazník klikne na „Vložit do košíku", vznikne v Shoptetu **skutečná produktová sada** — reálný produkt s vlastním kódem, se zvýhodněnou cenou a s položkami odpovídajícími výběru. Do košíku pak putuje jako jakékoli jiné zboží.

To je celý trik. Sleva není kupón ani cenová hladina, takže se nepere s ostatními akcemi a nevyžaduje žádné výjimky. Košík, doprava, platba, objednávka, faktura, odpisy ze skladu i export do ERP pracují se sadou úplně stejně jako s produktem, který obchodník založil ručně.

### Příklad, který se drží celé dokumentace

Prodejce kávy má konfiguraci **Kávový balíček**: 3 sloty, sleva 15 % a nabídku zrnkových káv a doplňků. Zákazník vybere Brazílii (289 Kč), Etiopii (329 Kč) a Kolumbii (299 Kč). Součet je 917 Kč, po slevě **779,45 Kč**. Vznikne sada s kódem `WT-SET-00042` za 779,45 Kč a ta jde do košíku jako jedna položka.

## Čím se liší od nativních Sad produktů

Shoptet umí sady sám, ale jinak. Rozdíl je v okamžiku vzniku:

| | Nativní sady v Shoptetu | Sestav si vlastní balíček |
|---|---|---|
| Kdo určuje složení | obchodník předem | zákazník při nákupu |
| Kdy sada vzniká | při zakládání v administraci | v okamžiku vložení do košíku |
| Počet položek v katalogu | jedna na každou kombinaci | jedna konfigurace pro všechny kombinace |
| Údržba při změně sortimentu | ruční úprava každé sady | úprava jedné nabídky produktů |

Nativní sady dávají smysl na pevné nabídky typu „startovní set". Jakmile ale chcete nechat výběr na zákazníkovi, počet kombinací roste rychleji, než se dá spravovat, a katalog se zaplní položkami, které si nikdo nikdy neobjedná. Doplněk pracuje obráceně: v katalogu drží jen to, co někdo skutečně sestavil, a i to jen dočasně (viz životní cyklus níž).

Podstatné je, že výsledek je v obou případech tentýž typ produktu. Nekupujete si tedy paralelní svět, který by bylo potřeba ošetřovat ve skladu nebo v účetnictví.

## Pojmy, které se vám budou hodit

- **Konfigurace** — jedno nastavení balíčku v administraci doplňku: název, počet slotů (2 až 5), sleva v procentech, režim seznamů a nabízené produkty. E-shop jich může mít víc vedle sebe (Kávový balíček, Dárkové trio…).
- **Slot** — jedno místo v balíčku, do kterého zákazník vybírá právě jeden produkt. Počet slotů určuje, kolik produktů musí vybrat.
- **Kategorie** — pojmenovaná skupina produktů uvnitř nabídky (Jednodruhová káva, Sirupy). Slouží jen k přehlednosti konfigurátoru, s kategoriemi v katalogu e-shopu nemá nic společného.
- **Shortcode** — veřejný identifikátor konfigurace ve tvaru `w-multipack-ABC12`. V administraci se zobrazuje v hranatých závorkách a v té podobě se vkládá do obsahu stránky: `[w-multipack-ABC12]`.
- **Sada** — produkt typu *product set*, který vznikne v Shoptetu při vložení balíčku do košíku. Má vlastní kód, cenu po slevě a položky odpovídající výběru.
- **Režim seznamů** — `same_lists` znamená, že všechny sloty nabízejí tutéž nabídku („vyberte si libovolné 3 kávy"). `separate_lists` dává každému slotu vlastní nabídku („1× káva + 1× čokoláda + 1× sirup").

## Cesta od kliknutí po objednávku

1. **Načtení stránky.** Skript na stránce najde v obsahu shortcode a vykreslí do jeho místa konfigurátor.
2. **Načtení konfigurace.** Jedním požadavkem na naše API si stáhne počet slotů, výši slevy, režim seznamů a všechny nabízené produkty včetně cen ve všech měnách e-shopu, skladu, hodnocení a obrázků.
3. **Výběr zákazníka.** Skládání balíčku probíhá čistě v prohlížeči nad daty z prvního požadavku. Žádná další komunikace se serverem neprobíhá, takže je výběr okamžitý.
4. **Potvrzení.** Po kliknutí na „Vložit do košíku" odejde na náš backend seznam vybraných produktů.
5. **Založení sady.** Backend spočítá závaznou cenu, přes Shoptet API založí produkt typu sada ve skryté kategorii, doplní obrázek a položky a vrátí zpět kód a cenu. Pokud tutéž kombinaci už někdo sestavil, vrátí existující sadu místo zakládání nové.
6. **Košík.** Frontend předá vrácený kód nativní funkci košíku Shoptetu. Od té chvíle je balíček běžná položka objednávky.

Krok 5 je synchronní a stojí několik volání Shoptet API, takže trvá řádově stovky milisekund až jednotky sekund. Konfigurátor proto musí mít viditelný stav načítání a pojistku proti dvojímu odeslání — na to se v praxi zapomíná nejčastěji.

## Kdo za co odpovídá

Doplněk je **headless**. Naše strana drží konfigurace, synchronizuje produktová data ze Shoptetu, počítá závaznou cenu, zakládá sady a stará se o jejich úklid. Frontend — tedy vzhled konfigurátoru, chování, texty, responzivita a vložení do košíku — je celý na straně e-shopu, respektive agentury, která ho spravuje.

Má to praktický důvod: agentura nemusí do klientovy šablony pouštět cizí kód a může widget vyladit přesně podle designu e-shopu. Kdo nechce začínat od nuly, může si vzít náš hotový starter a upravit ho.

Jedno pravidlo je přitom závazné: **cena, kterou zákazník zaplatí, je vždy ta, kterou vrátí backend při zakládání sady.** Přepočet v konfigurátoru je náhled pro zákazníka, ne obchodní slib. Obě čísla vznikají z trochu jiných vstupů — ceny v nabídce zohledňují měnu a případný ceník zákazníka, zatímco cena sady se skládá ze základních cen v základní měně e-shopu. U e-shopu s jednou měnou a bez ceníků obě čísla sedí; jinde se mohou lišit.

## Životní cyklus sady

Sady vznikají ve skryté kategorii, takže je zákazník nepotká v katalogu ani ve vyhledávání. Sada, ze které vznikla objednávka, v e-shopu zůstává kvůli historii. Sady, které skončily jen v košíku a nikdo je neobjednal, **uklízí každou noc automatický proces** — katalog se tedy nezanáší.

Pro obchodníka je to neviditelné. Pro vývojáře z toho plyne jedno pravidlo: kód sady je dočasný, takže se neukládá do `localStorage`, nepoužívá ve sdílených odkazech ani se z něj nepředvyplňuje košík při další návštěvě. Uložit si jde bez problémů to, **co** si zákazník vybral, a při jeho návratu sadu jednoduše založit znovu.

## Co k tomu potřebujete

- **Shoptet Premium** — doplněk pracuje se Shoptet API a s nativním košíkovým rozhraním šablony, na nižších tarifech nefunguje.
- **Aktivní licenci** doplňku od nás. Součástí je přístup do administrace balíčků a shortcode konfigurace.
- **Vývojáře nebo agenturu** pro frontend, případně převzatý starter.

Kompletní technická dokumentace doplňku je veřejně dostupná na GitHubu v repozitáři [shoptet-premium-multipack](https://github.com/Webotvurci-s-r-o/shoptet-premium-multipack) — včetně popisu architektury, API reference a funkčního ukázkového widgetu. Můžete si ji projít dřív, než se rozhodnete.

## Kam dál

- [Nasazení balíčku na Shoptet krok za krokem](https://www.webotvurci.cz/navody/sestav-si-vlastni-balicek/nasazeni-balicku-na-shoptet-krok-za-krokem/) — praktický postup od FTP po ověřovací checklist.
- [Dokumentace na GitHubu](https://github.com/Webotvurci-s-r-o/shoptet-premium-multipack/blob/main/docs/01-jak-to-funguje.md) — architektura, pojmy a životní cyklus sady v technickém detailu.
- [Sestav si vlastní balíček](https://www.webotvurci.cz/sluzby/shoptet/shoptet-premium-e-shop-bez-limitu/dynamicke-sady-balicky-na-miru/) — produktová stránka doplňku s ukázkou a ceníkem.

Nejste si jistí, jestli dává balíček pro váš sortiment smysl? Napište nám na **jsme@webotvurci.cz**, projdeme to s vámi nezávazně.

---

*Návod pochází z webu Webotvůrci — Zlatý a Premium partner Shoptetu.*
*Všechny návody: https://www.webotvurci.cz/navody/ · Kontakt: jsme@webotvurci.cz*