Technická integrace s platebním systémem FAPI nebo Stripe: Jak přijímat platby od zákazníků

Aby si vaši klienti mohli zakoupit přístup k vašemu AI Expertovi, potřebujete propojit vaši BuddyPro instanci s platebním systémem. To vám umožní automatizovat prodej, správu předplatných a přístupů.

K dispozici jsou dva platební systémy - české FAPI.cz a mezinárodní Stripe.

note

👉

Rozhodněte se, který systém chcete používat a podle toho pokračujte buď krokem 19.1 nebo krokem 19.2.

19.1 Integrace s mezinárodním platebním systémem Stripe

Pokud jste se rozhodli používat pro platby Stripe a ne FAPI, pokračujte podle tohoto návodu.

A) Propojte svůj Stripe účet s vaší BuddyPro instancí:

• Ve vaší BuddyPro instanci (v Telegram chatu s vaším AI Expertem) zadejte následující příkaz:

  /setupStripe

• Po úspěšném zadání tohoto příkazu vám vaše BuddyPro instance pošle odkaz. Klikněte na tento odkaz pro propojení vašeho Stripe účtu s Buddy Pro. Pokud ještě nemáte Stripe účet, budete si ho moci vytvořit.

B) Budou vygenerovány ukázkové produkty Buddy Pro

• Buddy pro vás vygeneruje 4 produkty, společně s ukázkovými cenami a platebními odkazy:
  • Měsíční předplatné: $149 / měsíc → 1000 zpráv měsíčně
  • Čtvrtletní předplatné: $399 / 3 měsíce → 1000 zpráv měsíčně
  • Roční předplatné: $1149 / rok → 1000 zpráv měsíčně
  • Extra zprávy: $69 → 500 dodatečných zpráv bez vypršení platnosti
    • ⚠️ DŮLEŽITÉ: Balíčky jsou pouze pro existující předplatitele, kterým dojdou měsíční zprávy. Nemohou být zakoupeny bez aktivního předplatného
• Vygenerované produkty najdete zde: https://dashboard.stripe.com/products
• Vygenerované platební odkazy najdete zde: https://dashboard.stripe.com/payment-links

C) Upravte ceny, měsíční limity zpráv a názvy produktů podle vašich potřeb. Nebo si vytvořte vlastní produkty a platební odkazy, pokud je potřebujete.

• Pokud chcete změnit cenu ukázkového produktu ve Stripe, vytvořte na něm nový Price objekt a poté vytvořte nový Payment Link, ve kterém vyberete tuto novou cenu.

• Vaše Buddy Pro produkty ve Stripe musí vždy obsahovat tato metadata pole, která je identifikují jako Buddy Pro produkt (již nastaveno pro ukázkové produkty):

  case: buddy_pro
  messages: 200 (jakékoliv číslo, záleží na vás)

  

• Hodnota 'messages' je měsíční limit zpráv v konverzaci (pro předplatné) nebo celkový počet zpráv, které uživatel získá (pro balíčky).

• Do limitu se započítávají jak zprávy od uživatele, tak odpovědi od Buddyho.

• Měsíční limit se uplatňuje i u ročních/čtvrtletních předplatných, aby se zabránilo vyčerpání příliš mnoha zpráv během jednoho měsíce.

• Zprávy zakoupené v balíčku nemají datum expirace.

• ‼️ Pokud vytváříte vlastní produkt pro balíček, musíte v nastavení platebního odkazu povolit Post-payment invoice

  • Jak povolit Post-payment invoice

    1. Po vytvoření produktu a platebního odkazu přejděte do nastavení platebního odkazu a klikněte na Edit:

       

    2. Přejděte na kartu After payment, povolte možnost Create an invoice PDF a klikněte na Update link.

       

D) Další příkazy pro správu plateb:

• /processStripePaymentManually:{paidInvoiceId}
  • Tento příkaz se používá pro ruční zpracování platby, pokud selže automatické zpracování přes webhook. Použijte ho pouze v případě, že vás k tomu vyzve vaše BuddyPro instance nebo podpora.

⚠️ VAROVÁNÍ K RUČNÍM ÚPRAVÁM VE STRIPE: Důrazně nedoporučujeme provádět ruční úpravy ve Stripe u automaticky vystavených (zejména opakujících se) faktur vašim klientům za služby BuddyPro (např. ruční změna fakturačního období, posunutí data splatnosti, úprava ceny na již vystavené faktuře atd. bez hlubokého porozumění toho, jak integrace funguje a jaké mohou být důsledky). Platforma BuddyPro nemusí být o těchto ručních změnách, které ve Stripe provádíte, informována a nemusí se s nimi správně synchronizovat, což může vést k problémům s aktivací nebo deaktivací přístupu pro klienta.

Často kladené otázky (FAQ) pro Stripe:

• Jak je předplatné nebo balíček Buddy Pro doručen uživateli, který si jej zakoupí?
  • Poté, co si uživatel zakoupí vaše předplatné nebo balíček, automaticky mu z našeho serveru zašleme aktivační e-mail s tlačítkem pro aktivaci jeho nákupu.
  • Pokud uživatel nakupuje přímo v Telegram chatu s vaším Buddy Pro, nákup může být aktivován automaticky bez nutnosti kliknout na aktivační e-mail.
• Co když chci nabízet více tarifů na jedné ze svých webových stránek (rozcestník)?
  • Pokud uživatel přichází na váš rozcestník z BuddyPro (např. po vyčerpání zkušební verze), je zásadní, aby byl parametr client_reference_id z původní URL přenesen do platebních odkazů Stripe vedoucích z rozcestníku k jednotlivým Stripe formulářům. Pro podrobnější informace o tomto technickém řešení viz krok 20.3 Důležité řešení pro více-tarifní ROZCESTNÍKY.

---

note

👇

Pokud jste již propojili Stripe, přeskočte následující krok (propojení FAPI) a pokračujte na další stránku.

---

19.2 Integrace s českým platebním systémem FAPI (fapi.cz)

FAPI je robustní česká platforma pro online prodej a fakturaci, která je v současnosti plně integrována s BuddyPro.

A) Příprava na straně FAPI (pokud ještě FAPI nepoužíváte):

1. Založte si účet na FAPI: Pokud jej ještě nemáte, můžete se zaregistrovat přes tento odkaz: https://fapi.cz/
2. Nastavte FAPI: Propojte FAPI s vaší platební bránou (např. Stripe, Comgate apod.). Toto je standardní nastavení FAPI.

tip

Tip: Zkušenosti ukazují, že schvalovací proces GoPay je velmi zdlouhavý. Vyžadují splnění přísných podmínek a celé nastavení může trvat i několik týdnů.

B) Propojení vašeho hlavního FAPI účtu s vaší BuddyPro instancí:

• Ve vaší BuddyPro instanci (v Telegram chatu s vaším AI Expertem) zadejte jednorázově následující příkaz pro základní propojení:

  /setupFapi:{username}:{apikey}

  • Nahraďte {username} vaším přihlašovacím jménem (loginem/emailem) do vašeho FAPI účtu.
  • Nahraďte {apikey} vaším API klíčem z FAPI. API klíč najdete (nebo si můžete nově vygenerovat) ve vašem FAPI účtu v sekci Můj účet > API klíče.

• Po úspěšném zadání tohoto příkazu je vaše BuddyPro instance schopna komunikovat s vaším FAPI účtem.

C) Vytvoření produktů (položek):

• Pro každý váš plánovaný tarif (např. "AI Expert Měsíční Standard", "AI Expert Roční Premium") a pro každý plánovaný balíček extra zpráv ("Balíček 100 extra zpráv") musíte ve FAPI vytvořit Produkt
• Produkt vytvořte ji v sekci FAPI "Prodej" -> "Produkty". Zde definujete název produktu (např. "Předplatné AI Experta - Měsíc") a jeho cenu.

D) Vytvoření prodejních formulářů ve FAPI:

🎥 Podívejte se na krátké videonávody k nastavení prodejních formulářů pro předplatné a také jednorázové balíčky, které vás provedou celým nastavením krok za krokem. Pokud chcete ještě více detailů, najdete je v textovém návodu níže.

https://www.loom.com/share/29126f48666c40e880b53b9e78748e7a?sid=95c55aa7-1564-4cd5-9366-517bf9ea1740

https://www.loom.com/share/403adf74d70e440b8a4af4864ec66081?sid=ded4343f-fba8-4035-8276-abe744c18404

• Pro každý váš plánovaný tarif (např. "AI Expert Měsíční Standard", "AI Expert Roční Premium") a pro každý plánovaný balíček extra zpráv ("Balíček 100 extra zpráv") musíte ve FAPI vytvořit také Prodejní formulář
• Prodejní formulář vytvořte jej v sekci FAPI "Prodej" -> "Prodejní formuláře". Formulář nastavíte v následujících 6 krocích.

  1. Základní nastavení

     • zde zadáte název prodejního formuláře a nastavíte režim formuláře jako produkční

  2. Položky a ceny

     • zde vyberte produkt, který jste vytvořili pro toto předplatné či balíček

  3. Platba, doprava a fakturace

     • vyberte platební bránu
     • pokud nastavujete formulář pro jednorázový balíček, stačí pouze vybrat platební bránu a pokračovat dalším krokem
     • pro předplatná je dále potřeba se ujistit, že ve Způsobu platby není zaškrtnutý bankovní převod (platby bankovním převodem jsou u předplatných problematické)
     • Pravidelná fakturace – pokud se jedná o předplatné, je potřeba zaškrtnout ✅ Vystavovat pravidelné faktury
     • objeví se políčko pro nastavení periody, zde si zvolíte, jak často se budou strhávat platby
     • zaškrtněte ✅ Zapnout automatické strhávání z karty

  4. Akce

     • vyberte sadu šablon zpráv nebo si vytvořte novou sadu šablon zpráv
     • rozklikněte E-mail při zaplacení objednávky, otevře se vám v nové záložce

     

     • do Textu zprávy E-mailu při zaplacení objednávky bude potřeba zadat váš unikátní aktivační odkaz. Tento aktivační odkaz bude obsahovat zástupný symbol pro číslo faktury ve formátu {invoiceNumber}. Je naprosto klíčové, aby tento zástupný symbol byl v odkazu přesně takto! FAPI ho pak automaticky nahradí skutečným číslem vystavené faktury.

     • odkaz získáte pomocí příkazu /fapiActivationLinks:

       

     • zkontrolujte, že odkaz je ve formátu https://t.me/{botUsername}?start=FAPI_{invoiceNumber}

     • vložte odkaz kamkoliv do Textu zprávy

       

     • uložte šablonu a vraťte se k nastavení formuláře

  5. Děkovací stránka

     • ❌ ujistěte se, že Použít vlastní děkovací stránku není zaškrtnuté

     • Obsah děkovací stránky musí také obsahovat aktivační odkaz, ten má ale jiný formát. Tento aktivační odkaz bude obsahovat zástupný symbol pro číslo faktury ve formátu {{number}}. Je naprosto klíčové, aby tento zástupný symbol byl v odkazu přesně takto! FAPI ho pak automaticky nahradí skutečným číslem vystavené faktury.

     • odkaz opět získáte pomocí příkazu /fapiActivationLinks:

       

     • vložte odkaz do Obsahu děkovací stránky mezi tagy {{ifPaid}}…{{/ifPaid}}

       

     • Proč je toto tak důležité? Kliknutím na tento speciální aktivační odkaz (který obsahuje unikátní identifikátory platby) se uživatel přesměruje do Telegramu, kde BuddyPro platforma rozpozná, že platba proběhla, identifikuje uživatele (nebo mu umožní propojit platbu s jeho Telegram účtem, pokud nakupoval "anonymně" bez předchozí interakce s vaší AI) a automaticky mu aktivuje příslušný tarif nebo balíček zpráv. Bez tohoto kliknutí se přístup neaktivuje automaticky!

  6. Vzhled

     • vzhled formuláře nastavte podle vlastní potřeby

E) Propojení konkrétního FAPI prodejního formuláře s konkrétním tarifem/balíčkem ve vaší BuddyPro instanci:

• Pro každý jednotlivý FAPI prodejní formulář, který jste vytvořili (tj. pro každý tarif a každý balíček zpráv), musíte ve své BuddyPro instanci zadat specifický propojovací příkaz:

  /connectForm:{id}:{productId}:{type}:{messages}

  • Nahraďte {id} skutečným ID vašeho FAPI formuláře. Toto ID najdete snadno – když máte daný formulář otevřený v administraci FAPI, podívejte se na URL adresu v prohlížeči. Bude vypadat nějak takto: https://web.fapi.cz/forms/preview/12345 (nebo může obsahovat .../update/12345). Číslo na konci (v tomto příkladu 12345) je ID formuláře.
  • Nahraďte {productId} skutečným ID produktu (položky) ve FAPI, který je na tomto konkrétním formuláři prodáván. ID produktu najdete ve FAPI v sekci "Šablony" -> "Položky" v seznamu vašich vytvořených produktů.
  • Nahraďte {type} typem produktu, který se na tomto formuláři prodává:
    • subscription – pokud se jedná o pravidelné (měsíční, roční atd.) předplatné.
    • package – pokud se jedná o jednorázový nákup balíčku extra zpráv.
  • Nahraďte {messages} počtem zpráv, které uživatel získá zakoupením tohoto produktu:
    • Pro typ subscription: Zadejte měsíční počet zpráv (např. 1000). Tento měsíční limit platí i v případě, že se jedná o roční předplatné (limit se každý měsíc obnovuje).
    • Pro typ package: Zadejte celkový počet zpráv obsažených v tomto jednorázovém balíčku (např. 200).

• Příklad propojení formuláře pro měsíční předplatné s 1000 zprávami: /connectForm:12345:67890:subscription:1000

• Po úspěšném zadání tohoto příkazu BuddyPro ověří existenci formuláře a produktu ve vašem FAPI a uloží si toto propojení. Zároveň vám v odpovědi zobrazí informaci, že je potřeba správně nastavit děkovací stránku a email ve FAPI (viz následující klíčový bod).

F) Další příkazy pro správu již propojených FAPI formulářů (zadáváte do vaší BuddyPro instance):

• /getFormMessages:{id_formuláře}
  • Zobrazí vám, jaký maximální počet zpráv je aktuálně nastaven pro FAPI formulář s daným {id_formuláře}.
• /updateFormMessages:{id_formuláře}:{nový_počet_zpráv}
  • Umožňuje vám změnit maximální počet zpráv pro již propojený FAPI formulář.
  • Důležité: Tato změna se projeví pouze pro nové uživatele, kteří si produkt přes tento formulář zakoupí až po provedení této změny. Neovlivní to limity zpráv u stávajících uživatelů, kteří si produkt zakoupili dříve s původním nastavením.
• /processFapiPaymentManually:{paidInvoiceNumber}
  • Tento příkaz slouží k manuálnímu zpracování platby, pokud by automatické zpracování přes webhook z nějakého důvodu selhalo. Používejte ho pouze, pokud vás k tomu vaše BuddyPro instance nebo podpora vyzve.

⚠️ UPOZORNĚNÍ K MANUÁLNÍM ÚPRAVÁM VE FAPI: Důrazně nedoporučujeme provádět ve FAPI manuální úpravy v automaticky vystavených (zejména pravidelných) fakturách vašim klientům za BuddyPro služby (např. ručně měnit periodu fakturace, posouvat datum splatnosti, upravovat cenu na již vystavené faktuře apod. bez hlubokého pochopení, jak funguje integrace a jaké to může mít důsledky). BuddyPro platforma nemusí mít o těchto vašich manuálních změnách ve FAPI přehled a nemusí se s nimi správně synchronizovat, což může vést k problémům s aktivací nebo deaktivací přístupu pro klienta. Vždy se snažte spravovat tarify a platby primárně přes standardní rozhraní FAPI a propojovací příkazy v BuddyPro.

Prodej předplatného za zvýhodněnou cenu v prvním období

Tento model znamená, že zákazník dostane levnější cenu jen na určité úvodní období (např. 14 dní, první měsíc, tři měsíce nebo půlrok). Po skončení této zvýhodněné fáze se předplatné automaticky pokračuje za běžnou cenu.

Typické scénáře:

• První měsíc za 1 € → poté za plnou cenu každé další období.
• První platba na 6 měsíců → poté se přepne na opakované měsíční platby.

https://www.loom.com/share/cb555eacc4b849b3badecde6b15f7575

Prodej Buddyho jako nepovinné položky nebo upsellu ve FAPI

Buddyho můžete ve FAPI prodávat jako volitelnou položku nebo upsell k jinému produktu (například ke kurzu nebo programu).

note

‼️

Nastavení formuláře se v tomto případě liší od běžného předplatného, kde je buddy jako povinná položka

• ❌ aktivační odkaz se nedává na děkovací stránku ani do e-mailu při zaplacení objednávky
• ✅ aktivační odkaz se místo toho dává do e-mailu, který se odesílá po zaplacení položky pro předplatné Buddyho

warning

Prodej Buddyho jako miniupsell zatím nepodporujeme.

Podrobné postupy najdete ve videích:

🎥 Nepovinná položka:

https://www.loom.com/share/5094425c79124ddd8c1fd1ff62e3fb32

🎥 Upsell:

https://www.loom.com/share/8562205eb7184c2ba23a2f0ea3120979

I v těchto případech lze předplatné Buddyho nastavit za výhodnější cenu pro první období s následnými opakovanými platbami za jinou cenu – stačí vytvořit dvě položky pro toto předplatné a ve 3. kroku nastavení formuláře nahradit první položku předplatného za výhodnou cenu druhou položkou za plnou cenu.

---

---

Často kladené otázky (FAQ) k propojení s FAPI:

Často kladené otázky (FAQ) k tomuto kroku:

• Proč je nutné mít samostatný FAPI prodejní formulář pro každý tarif nebo balíček zpráv?
  • Příkaz /connectForm umožňuje propojit vždy jen jeden konkrétní FAPI formulář s jedním konkrétním nastavením počtu zpráv a typem produktu (předplatné/balíček) v BuddyPro. Pro správné fungování a rozlišení, co si klient kupuje, je tedy nutné mít pro každý nabízený plán samostatný formulář.
• Co když omylem zadám špatný počet zpráv v příkazu /connectForm?
  • Jednoduše zadejte příkaz /updateFormMessages:{id}:{messages} se správnými údaji. Toto přepíše počet zpráv pro daný ID formuláře.
• Musím aktivační odkaz dávat na děkovací stránku FAPI I do potvrzovacího emailu FAPI?
  • Ano, pokud nejde o volitelnou položku. Poskytnete tak uživateli dvě možnosti, jak přístup aktivovat, a minimalizujete riziko, že by odkaz přehlédl nebo ztratil.
• Funguje jiná proměnná než {invoiceNumber} v aktivačním odkazu pro FAPI?
  • Ne, pro správnou funkci propojení s FAPI musí aktivační odkaz obsahovat zástupný symbol přesně ve formátu {invoiceNumber}.
• Co když chci nabízet více tarifů na jedné mé webové stránce (rozcestník)?
  • Pokud uživatel přichází na váš rozcestník z BuddyPro (např. po vyčerpání trialu), je klíčové, aby se parametr userId z původní URL přenesl i na odkazy vedoucí z rozcestníku na jednotlivé FAPI formuláře. Podrobnější informace k tomuto technickému řešení najdete v kroku 20.3 Důležité řešení pro ROZCESTNÍKY s více tarify.
• Kde přesně najdu ID formuláře a ID produktu ve FAPI?
  • ID Formuláře: V administraci FAPI přejděte do sekce "Formuláře". V seznamu vašich formulářů nebo při editaci konkrétního formuláře uvidíte jeho ID v URL adrese prohlížeče (např. https://web.fapi.cz/forms/view/XXXXX, kde XXXXX je ID).
  • ID Produktu (Položky): V administraci FAPI přejděte do sekce "Prodej" -> "Produkty". V seznamu vašich produktů (položek) uvidíte jejich ID.
• Můžu propojit více FAPI účtů?
  • Ano, stačí zadat znovu /setupFapi s přihlašovacím emailem a API klíčem pro váš nový FAPI účet. Dejte si pozor na aktivační odkazy pro email a děkovací stránku - liší se pro jednotlivé FAPI účty!
  • Aktivační odkazy pro vaše FAPI účty zobrazíte pomocí /fapiActivationLinks

---

---