Vouchery

Po dokončení tohoto návodu budete vědět, jak vytvořit voucherový produkt, jak se generují a posílají kódy, jak je vystavovat ručně bez online platby, jak posílat platební odkazy pro nezaplacené voucherové objednávky, jak funguje dialog pro disponování s vouchery při refundu / zrušení / smazání objednávky a jak zákazníci i administrátoři vouchery uplatňují.

Co je voucher?

Voucher je řádek v tabulce vouchers vytvořený, když zákazník zaplatí voucherový produkt. Každý řádek obsahuje:

• Jedinečný kód ve formátu [PREFIX-]XXXX-XXXX (8 náhodných Crockford Base32 znaků; abeceda vynechává I L O U, aby se kódy snadno diktovaly)
• Hodnotu + měnu uložené z produktu v okamžiku vystavení
• Stav: paid (aktivní, uplatnitelný), redeemed (uplatněn), expired (vypršel), cancelled (zrušen)
• Volitelné expires_at datum platnosti
• Odkaz zpět na ProductOrder, který ho vytvořil (jedna objednávka → N voucherů, jeden na množství)

Kódy se hostovi zobrazují v potvrzovacím e-mailu a na úspěšné stránce platby.

Krok 1: Vytvoření voucherového produktu

V postranní nabídce → Produkty → + → vyplňte formulář nového produktu:

Klikněte Uložit. Otevře se detail produktu. V postranní nabídce se objeví dětská cesta Vouchery pod tímto produktem (jen voucherové produkty ji mají).

Režim možností + vouchery. Každý řádek možnosti funguje jako vlastní tier voucheru. Pokud host koupí 2× voucher 500 Kč + 1× voucher 1 000 Kč, jsou to tři voucherové řádky: dva s hodnotou 500 a jeden s hodnotou 1000. Každý dostane vlastní unikátní kód a vlastní čárkovaný rámeček v potvrzovacím e-mailu.

Krok 2: Tlačítko Checkout

Nastavte Checkout přesně stejně jako u běžného produktu (viz Přehled Produktů Krok 2). Text tlačítka může inzerovat hodnotu: Koupit voucher za 500 Kč.

Limity množství z produktu platí: např. min=1, default=1, max=10 umožní zákazníkovi koupit až 10 voucherů v jednom checkoutu, každý dostane vlastní kód.

Krok 3: Jak host kupuje voucher

Identický 4krokový dialog jako u kteréhokoli produktu:

1. Množství
   • Voucherové produkty s jednou cenou: jeden krokový volič pro počet voucherů.
   • Voucherové produkty s možnostmi: jeden krokový volič na tier voucheru (např. 500 Kč ×2, 1 000 Kč ×1). Celkem = Σ (cena × množství).
2. Vlastní pole — jméno + e-mail (povinné); přidejte přes editor polí třeba pole pro dárkovou zprávu / jméno obdarovaného.
3. Shrnutí — celkem. U režimu možností rozpis ukazuje každý tier s množstvím.
4. Zaplatit — Stripe Checkout.

Po úspěšné platbě:

• Vloží se jeden voucherový řádek na zakoupenou jednotku — v režimu možností je value řádku snímkem ceny z té možnosti, ze které byl vygenerován. Kódy jsou unikátní, měna je snímek, expires_at se řídí nastavením platnosti produktu.
• Potvrzovací e-mail hosta vypíše každý kód jako čárkovaný rámeček s kódem, hodnotou a (pokud je nastaveno) platností.
• Vám přijde standardní upozornění o nové objednávce.

Pokud vystavení voucheru z jakéhokoli důvodu selže, webhook vrátí 5xx a Stripe se pokusí znovu. Stav objednávky paid se nastaví až po vystavení VŠECH očekávaných kódů, takže částečný stav se sám zhojí při opakování.

Krok 4: Zobrazení + správa vystavených voucherů

V postranní nabídce → Produkty → {voucherový produkt} → Vouchery.

Dvě záložky nahoře:

• Aktivní — status = paid. Vouchery stále uplatnitelné.
• Vypršelé — status IN (expired, redeemed, cancelled). Archivní sběrná koše.

Každý řádek ukazuje: jméno zákazníka + e-mail, vystaveno (relativně), platnost do (nebo "Bez omezení"), kód propojené objednávky, chip s voucherovým kódem, stavový pill, dropdown akcí (Zrušit / Zobrazit) + šipku na detail.

Kliknutím přejdete na Detail voucheru:

• Kód jako titulek stránky
• Řádek info ve 3 sloupcích — Hodnota / Vystaveno / Platnost
• Karta propojené objednávky s veřejným referenčním kódem
• Karta Uplatněno proti — po uplatnění zobrazuje, na jakou rezervaci/objednávku byl voucher použit a kdy
• Nebezpečná zóna — ruční zrušení (jen pokud status = paid)

Krok 5: Ruční vystavení voucherů

Pro dárkové kódy, prodej naživo nebo comp kódy, kde neproběhne online platba.

Cesta: V postranní nabídce → Produkty → {voucherový produkt} → Vouchery → klikněte Vytvořit voucher v hlavičce.

Pole formuláře:

Odešlete. cabintale vytvoří syntetickou ProductOrder s payment_status='manual' pojmenovanou "Voucher order" a vloží N voucherových řádků. Budete přesměrováni na záložku Aktivní s úspěšným hlášením, kolik bylo vystaveno.

Syntetická objednávka se zobrazí v seznamu objednávek (kvůli účetní čistotě), ale neexistuje žádná Stripe transakce — není co refundovat. Pro deaktivaci ručního voucheru použijte řádkové Zrušit buď z dropdownu v seznamu Voucherů, nebo z panelu Vystavené vouchery v detailu objednávky.

Krok 6: Platební odkaz pro nezaplacenou voucherovou objednávku

Pokud zákazník začal voucherový checkout, ale platbu nedokončil, můžete poslat odkaz na zaplacení bez nutnosti opět zadávat údaje:

1. Otevřete detail objednávky v Objednávky.
2. V sekci Platby klikněte Odeslat platební odkaz.
3. cabintale vytvoří čekající Stripe Checkout relaci a zkopíruje URL do schránky. Vložte do chatu / e-mailu.
4. Zákazník zaplatí přes /pay/{token}. Vouchery se po úspěchu vygenerují jako obvykle.

Tlačítko je skryté, pokud produkt nemá nastavenou bránu nebo je objednávka už zaplacená.

Krok 7: Storno / Refund / Smazání — dialog pro disponování s vouchery

Když provedete destruktivní akci na voucherové objednávce, cabintale se zeptá, co se zaplacenými vouchery na ní. Dialog se objeví ve třech místech:

• Po refundu transakce v tabulce Platby
• Při změně stavu objednávky na Zrušená a uložení
• Při smazání objednávky z Nebezpečné zóny

Dvě tlačítka:

• Zrušit všechny vouchery — každý zaplacený voucher na objednávce se překlopí na cancelled (držitel je už neuplatní).
• Ponechat vouchery — vouchery zůstávají platné + uplatnitelné. Mění se jen stav objednávky.

Při Smazat + Ponechat se objednávka tvrdě smaže; voucherům se product_order_id nastaví na NULL, ale řádek voucheru zůstává platný — kódy stále fungují, hodnota a platnost se nemění.

Krok 8: Zrušení jednotlivého voucheru

Ze dvou míst:

• Seznam voucherů → dropdown řádku → Zrušit voucher
• Detail objednávky → panel Vystavené vouchery → ikona koše na řádku

Oba způsoby otevřou potvrzovací modál. Po potvrzení se stav překlopí na cancelled (bez volání brány). Pro vrácení peněz zákazníkovi místo zrušení refundujte podkladovou transakci z tabulky Platby — dialog pro disponování s vouchery se pak zeptá, zda chcete vouchery také zrušit.

Krok 9: Uplatnění voucheru

Voucherové kódy lze použít jako platbu za rezervaci místa, rezervaci služby nebo produktovou objednávku (bez voucherových produktů). Kódy jsou case-insensitive a tolerantní k pomlčkám — SUNNY-RDX9-RPMS, sunnyrDx9rPms i SUNNY RDX9 RPMS vedou na stejný voucher.

Měna + účet musí souhlasit. CZK voucherem nelze platit EUR rezervaci. Voucher od jednoho hostitele nelze uplatnit u jiného.

Cesta hosta (BookingDialog)

1. V kroku Shrnutí se pod přehledem ceny zobrazí odkaz „Použít voucher".
2. Klikněte, zadejte kód a stiskněte Použít. cabintale ověří kód a vrátí hodnotu voucheru.
3. Pokud voucher pokryje celou částku: tlačítko se změní na Potvrdit rezervaci a žádná platba kartou neproběhne.
4. Pokud voucher pokryje část částky: v přehledu se zobrazí sleva a řádek „K úhradě" pro zbývající část. Host zaplatí přes Stripe jen zbytek.

Voucher se spotřebuje celý v obou případech — žádná zbývající hodnota se neukládá.

Cesta administrátora (Přidat platbu → Voucher)

1. Otevřete detail rezervace nebo objednávky ve správě.
2. V sekci Platby klikněte Přidat platbu.
3. Nastavte Typ na Voucher, zadejte kód a odešlete.
4. cabintale kód ověří, aplikuje a označí voucher jako uplatněný. Stripe transakce se nespouští.

Stavy voucheru

• paid → voucher je aktivní a uplatnitelný.
• pending_use → zákazník probíhá checkoutem se zamčeným voucherem (jen u částečného pokrytí; plné pokrytí se commituje okamžitě). Zámek se uvolní automaticky po dokončení nebo vypršení checkoutu.
• redeemed → voucher byl uplatněn. Na Detailu voucheru vidíte, na jakou rezervaci/objednávku byl použit a kdy.

Pokud Stripe session vyprší bez platby, voucher se automaticky vrátí do stavu paid. Administrátor může uvázlý zámek pending_use uvolnit ručně tlačítkem Uvolnit zámek na Detailu voucheru.

Aktuální omezení

• Jeden nominál na řádek možnosti. Voucherové produkty s jednou cenou vystavují kódy v jedné hodnotě. Pro prodej více nominálů z jednoho tlačítka přepněte produkt do režimu Možnosti a přidejte jeden řádek na nominál.
• Bez hromadného exportu. Kódy vidíte ve správě a v e-mailu zákazníka; pokud potřebujete CSV, napište.
• Skládání více voucherů není podporováno. Na jednu rezervaci nebo objednávku lze uplatnit jen jeden voucherový kód.
• Bez uchování zbývající hodnoty. Vouchery se spotřebují celé — žádný zůstatek se neukládá.
• Bez přenosu voucheru. Kódy jsou vázány na vydávající účet; neexistuje mechanismus pro přiřazení kódu jinému držiteli.

Související návody

• Přehled Produktů (Checkout tlačítka, embed, platby) — Přehled Produktů
• Nastavení platební brány — Platební brány
• Refundy a storna — Vrácení a zrušení rezervací
• E-mailová oznámení — E-mailová oznámení