Zástupné symboly slouží k automatickému doplnění konkrétních údajů z objednávky, faktury, platby, zákazníka nebo produktu.

Můžete je použít například v e-mailových šablonách, upomínkách nebo na děkovací stránce. Při použití je ale důležité rozlišit, kam symbol vkládáte, protože e-maily a děkovací stránky používají odlišnou syntaxi.

Nejdříve zvolte, kam chcete symbol vložit

Kde symbol používáteSyntaxePříklad
E-mailová šablona nebo upomínkajedna dvojice závorek { }      {invoiceNumber}      
Interní děkovací stránka FAPIdvě dvojice závorek {{ }}      {{number}}      
Vlastní externí děkovací stránkadvě dvojice závorek {{ }}      {{number}}      

Výjimkou jsou produktové podmínky: i na děkovací stránce používají jednu dvojici závorek, například {item-EBOOK}...{/item-EBOOK}.

Pozor:

Symboly pro e-maily a děkovací stránku mezi sebou nezaměňujte.

Symbol s jednou dvojicí závorek, například {invoiceNumber}, patří do e-mailu.

Symbol se dvěma dvojicemi závorek, například {{number}} , patří na děkovací stránku.

Jak zástupné symboly vkládat

V editoru FAPI používejte tlačítko Zástupné symboly.

Symbol musí zůstat jedním nepřerušeným řetězcem. Nevkládejte do něj:

  • mezeru,
  • zalomení řádku,
  • formátování pouze do části symbolu.

Správně například:

Děkujeme za objednávku č. {{number}}.      

Chybně například:

{{ number }}      

nebo symbol rozdělený formátováním či zalomením řádku.

Párové bloky

Některé zástupné symboly, které máte níže blíže popsány fungují jako párové bloky. Používají se například pro podmíněný obsah.

Párové bloky vložte na samostatné řádky. Otevírací a zavírací značku ponechte ve stejném formátování a text mezi nimi vložte do vlastního odstavce.

Příklad:

{{ifPaid}}
<p>Děkujeme, objednávka č. {{number}} je zaplacená.</p>
{{/ifPaid}}

Bloky do sebe nevnořujte.

Videonávod a příklady v editoru

Video je z roku 2023, proto se vzhled editoru může lišit. Platnou syntaxi a aktuální postup vždy ověřte podle pravidel uvedených v této nápovědě.

Tato část platí pro e-mailové šablony a upomínky.

V e-mailech používejte zástupné symboly s jednou dvojicí závorek, například:

{invoiceNumber}      

Symboly vkládejte ideálně přímo z nabídky Zástupné symboly v editoru e-mailové šablony.

Zástupné symboly v e-mailech a děkovací stránce

Na výběr máte několik sekcí zástupných symbolů:

  • Faktura,
  • Platba,
  • Zákazník,
  • Produkt,
  • Podmíněný obsah,
  • Dodavatel,
  • Vlastní pole.

Zástupné symboly v e-mailech a děkovací stránce

Faktura

  • {invoiceNumber} – číslo faktury
  • {variableSymbol} – variabilní symbol
  • {amount} – fakturovaná částka včetně měny
  • {amountWithoutVat} – částka bez DPH včetně měny
  • {createDate} – datum vystavení ve formátu d. m. Y
  • {payDayDate} – datum splatnosti ve formátu d. m. Y
  • {pdf} – odkaz ke stažení PDF faktury
  • {pdfPrinterFriendly} – odkaz ke stažení tiskové verze PDF faktury
  • {project} – název projektu
  • {shipping} – způsob dopravy včetně výdejního místa, pokud je dostupné
  • {packetTrackingLink} – odkaz na sledování zásilky
  • {cancellationReason} – důvod storna
  • {paymentType} – lokalizovaný způsob platby
  • {repaymentNumber} – číslo splátky
  • {countOfRepayments} – počet splátek

Platba

  • {orderStatusPage} – přehled objednávky a odkaz na online platbu
  • {bankAccountName} – název bankovního účtu dodavatele
  • {bankAccount} – číslo bankovního účtu dodavatele
  • {iban} – IBAN dodavatele
  • {swift} – BIC/SWIFT dodavatele
  • {qrCode} – obrázek platebního QR kódu

Podmíněné bloky pro platbu v e-mailech

  • {ifCash}...{/ifCash} – pouze pro platbu v hotovosti
  • {ifWire}...{/ifWire} – pouze pro platbu bankovním převodem
  • {ifCreditCard}...{/ifCreditCard} – pouze pro platbu kartou
  • {ifCollectOnDelivery}...{/ifCollectOnDelivery} – pouze pro dobírku
  • {ifSms}...{/ifSms} – pouze pro platbu SMS
  • {ifPaypal}...{/ifPaypal} – pouze pro platbu přes PayPal
  • {ifGopay}...{/ifGopay} – pouze pro platbu přes GoPay
  • {ifWireGopay}...{/ifWireGopay} – pouze pro bankovní převod přes GoPay
  • {ifBitcoin}...{/ifBitcoin} – pouze pro platbu Bitcoinem
  • {ifGpay}...{/ifGpay} – pouze pro platbu přes Google Pay
  • {ifBarter}...{/ifBarter} – pouze pro barterovou platbu
  • {ifApplePay}...{/ifApplePay} – pouze pro platbu přes Apple Pay
  • {ifSkippay}...{/ifSkippay} – pouze pro platbu přes Skip Pay
  • {ifQrCode}...{/ifQrCode} – pouze pro platbu QR kódem
  • {ifKlarna}...{/ifKlarna} – pouze pro platbu přes Klarna
  • {ifNotCollectOnDelivery}...{/ifNotCollectOnDelivery} – pouze pro platby jiné než dobírka

Zákazník

  • {vocativeName} – jméno zákazníka v 5. pádě
  • {vocativeSurname} – příjmení zákazníka v 5. pádě
  • {vocativeFullName} – celé jméno zákazníka v 5. pádě
  • {clientFirstName} – fakturační jméno zákazníka
  • {clientLastName} – fakturační příjmení zákazníka
  • {clientName} – fakturační jméno zákazníka
  • {fullName} – celé jméno zákazníka
  • {clientEmail} – e-mail zákazníka
  • {clientPhone} – telefon zákazníka
  • {company} – firma zákazníka
  • {clientIc} – IČ zákazníka
  • {clientDic} – DIČ zákazníka
  • {clientIcDph} – slovenské IČ DPH zákazníka
  • {clientAddress} – fakturační adresa zákazníka
  • {shippingAddress} – doručovací adresa zákazníka
  • {notes} – poznámka zákazníka k objednávce
  • {clientId} – ID zákazníka

Produkt

  • {items} – názvy zakoupených položek včetně množství, oddělené čárkami; v HTML těle e-mailu také odkazy na soubory těchto produktů po zaplacení
  • {itemsList} – zakoupené položky včetně množství na samostatných řádcích; v HTML těle e-mailu také odkazy na jejich produktové soubory po zaplacení
  • {voucherCodes} – kódy voucherů
  • {voucherQrCodes} – samostatné QR kódy voucherů
  • {voucherQrCodeAllInOne} – jeden QR kód obsahující všechny vouchery
  • {vouchersList} – vouchery jako HTML seznam
  • {voucherExpirations} – data expirace voucherů
  • {subscriptionId} – ID předplatného
  • {subscriptionQrCode} – QR kód předplatného

Produktové soubory se přes {items} a {itemsList} zpřístupní jen u zaplacené, nestornované objednávky a zakoupeného produktu s kladným množstvím. Symbol vložte přímo do těla e-mailu, nikoli do pole URL odkazu. Odkazy můžete doručit běžným E-mailem při zaplacení objednávky bez další akce. Postup najdete v návodu Odesílání e-booků a dalších souborů. Nezaměňujte je se soubory vloženými přímo do šablony pomocí {file:<ID>} ani se symboly děkovací stránky.

Podmíněný obsah

Místo <kód_produktu> vložte kód produktu, nikoli jeho ID. Velikost písmen se nerozlišuje a bloky nevnořujte. Kód produktu najdete ve FAPI v nabídce Prodej → Produkty v levém sloupci Kód.

  • {item-<kód_produktu>}...{/item-<kód_produktu>}        – obsah se zobrazí pouze tehdy, když objednávka obsahuje produkt s daným kódem.
{item-EBOOK}<p>Děkujeme za nákup. Odkaz ke stažení e-booku najdete zde: <a href="{file:123}">Stáhnout e-book</a>.</p>{/item-EBOOK}

Blok se zobrazí jen kupujícímu, jehož objednávka obsahuje produkt s kódem EBOOK       . Číslo 123        v {file:123}        nahraďte ID souboru připojeného k e-mailové šabloně.

Dodavatel

  • {userName} – fakturační jméno dodavatele
  • {userEmail} – e-mail dodavatele
  • {userPhone} – telefon dodavatele
  • {userWeb} – web dodavatele

Vlastní pole

  • {customFieldsList} – vyplněná vlastní pole jako HTML seznam
  • {customField:<ID>} – hodnota vlastního pole faktury se zadaným číselným ID. Místo <id> vložte číselné ID konkrétního vlastního pole, například {customField:123}.
  • {file:<ID>} – zabezpečený odkaz ke stažení souboru šablony se zadaným číselným ID. Místo <ID> vložte číselné ID souboru připojeného k dané šabloně, například {file:123}.
  • {<key>} – vlastní symbol předaný jako dvojice klíč–hodnota přes endpoint, který vlastní symboly podporuje; <key> nahraďte předaným klíčem.

Tato část platí pouze pro obsah interní děkovací stránky FAPI, tedy pro pole thanks_content .

Na interní děkovací stránce FAPI používejte zástupné symboly se dvěma dvojicemi závorek, například:

{{number}}      

FAPI zde objednávku zná automaticky. Nepřidávejte proto SDK script ani identifikátor objednávky do URL.

Zástupné symboly v e-mailech a děkovací stránce

Na interní děkovací stránce vybírejte symboly z aktuální nabídky podle skupin:

  • Objednávka,
  • Platba,
  • Zákazník,
  • Produkt,
  • Podmíněný obsah,
  • Ostatní.
Zástupné symboly v e-mailech a děkovací stránce

Objednávka

  • {{number}} – číslo objednávky
  • {{totalAmount}} – celková částka
  • {{totalAmountIncVat}} – celková částka včetně DPH
  • {{totalAmountWithoutShipping}} – celková částka bez dopravy
  • {{totalAmountWithoutShippingIncVat}} – celková částka včetně DPH bez dopravy
  • {{vatAmount}} – částka DPH
  • {{currencyCode}} – kód měny
  • {{exchangeRate}} – směnný kurz
  • {{statusTranslated}} – lokalizovaný stav faktury
  • {{shippingMethod}} – zvolený způsob dopravy
  • {{discountCode}} – použitý slevový kód
  • {{clientsNote}} – poznámka zákazníka k objednávce
  • {{orderStatusPage}} – odkaz na přehled objednávky
  • {{paid}} – informace, zda je faktura zaplacená
  • {{cancelled}} – informace, zda je objednávka stornovaná
  • {{status}} – surový stav faktury
  • {{createDate}} – datum vystavení faktury
  • {{paidOn}} – datum zaplacení faktury

Platba

  • {{paymentMethod}} - zvolená platební metoda
  • {{bankAccountName}} – název bankovního účtu dodavatele
  • {{iban}} – IBAN dodavatele
  • {{swift}} – BIC/SWIFT dodavatele
  • {{accountNumber}} – číslo bankovního účtu dodavatele
  • {{qrCodeImage}} – obrázek platebního QR kódu
  • {qrCodePath}} – identifikátor platebního QR kódu
  • {{qrCodeUrl}} – URL platebního QR kódu

Podmíněné bloky pro platbu v děkovací stránce

  • {{ifCash}}...{{/ifCash}} – pouze pro platbu v hotovosti
  • {{ifWire}}...{{/ifWire}} – pouze pro platbu bankovním převodem
  • {{ifCreditCard}}...{{/ifCreditCard}} – pouze pro platbu kartou
  • {{ifCollectOnDelivery}}...{{/ifCollectOnDelivery}} – pouze pro dobírku
  • {{ifSms}}...{{/ifSms}} – pouze pro platbu SMS
  • {{ifPaypal}}...{{/ifPaypal}} – pouze pro platbu přes PayPal
  • {{ifGopay}}...{{/ifGopay}} – pouze pro platbu přes GoPay
  • {{ifWireGopay}}...{{/ifWireGopay}} – pouze pro bankovní převod přes GoPay
  • {{ifBitcoin}}...{{/ifBitcoin}} – pouze pro platbu Bitcoinem
  • {{ifGpay}}...{{/ifGpay}} – pouze pro platbu přes Google Pay
  • {{ifBarter}}...{{/ifBarter}} – pouze pro barterovou platbu
  • {{ifApplePay}}...{{/ifApplePay}} – pouze pro platbu přes Apple Pay
  • {{ifSkippay}}...{{/ifSkippay}} – pouze pro platbu přes Skip Pay
  • {{ifQrCode}}...{{/ifQrCode}} – pouze pro platbu QR kódem
  • {{ifKlarna}}...{{/ifKlarna}} – pouze pro platbu přes Klarna
  • {{ifNotCollectOnDelivery}}...{{/ifNotCollectOnDelivery}} – pouze pro platby jiné než dobírka

Zákazník

  • {{customerInvoiceEmail}} – e-mail zákazníka
  • {{customerInvoicePhone}} – telefon zákazníka
  • {{customerInvoiceAddressName}} – jméno na fakturační adrese
  • {{customerInvoiceAddressStreet}} – ulice fakturační adresy
  • {{customerInvoiceAddressCity}} – město fakturační adresy
  • {{customerInvoiceAddressZip}} – PSČ fakturační adresy
  • {{customerInvoiceAddressCountry}} – stát fakturační adresy
  • {{customerInvoiceAddressIc}} – IČ zákazníka
  • {{customerInvoiceAddressDic}} – DIČ zákazníka
  • {{customerInvoiceAddressIcDph}} – slovenské IČ DPH zákazníka
  • {{customerShippingAddressName}} – jméno na doručovací adrese
  • {{customerShippingAddressStreet}} – ulice doručovací adresy
  • {{customerShippingAddressCity}} – město doručovací adresy
  • {{customerShippingAddressZip}} – PSČ doručovací adresy
  • {{customerShippingAddressCountry}} – stát doručovací adresy

Produkt

Index je číslovaný od nuly: první položka používá index 0 , druhá index 1.

Místo <kód_produktu> vložte kód produktu, nikoli jeho ID. Velikost písmen se nerozlišuje a bloky nevnořujte.

Kód produktu najdete ve FAPI v nabídce Prodej → Produkty v levém sloupci Kód.

Zástupné symboly v e-mailech a děkovací stránce

Například {{items.0.name}} vypíše název první zakoupené položky.

  • {{items}} – JSON* pole zakoupených položek
  • {{itemList}} –  seznam zakoupených položek
  • {{items.<index>}} – jedna zakoupená položka na daném indexu ve formátu JSON*
  • {{items.<index>.name}} – název zakoupené položky
  • {{items.<index>.code}} – kód zakoupeného produktu
  • {{items.<index>.count}} – množství zakoupené položky
  • {{items.<index>.type}} – typ zakoupené položky
  • {{items.<index>.vat}} – sazba DPH zakoupené položky
  • {{items.<index>.unitPrice}} – jednotková cena bez DPH
  • {{items.<index>.unitPriceIncDph}} – jednotková cena včetně DPH
  • {{subscriptionId}} – ID předplatného
  • {{subscriptionQrCode}} – QR kód předplatného

Podmíněný obsah

  • {item-<kód_produktu>}...{/item-<kód_produktu>} – obsah se zobrazí pouze tehdy, když objednávka obsahuje produkt s daným kódem. Produktové bloky mají jednu dvojici závorek; stavové a platební bloky na děkovací stránce mají dvě.

Blok se zobrazí jen kupujícímu, jehož objednávka obsahuje produkt s kódem EBOOK. Vložte do něj text určený pro tento produkt.

{item-EBOOK}
<p>Děkujeme za nákup e-booku.</p>
{/item-EBOOK}

Ostatní

  • {{formName}} – název prodejního formuláře
  • {{userName}} – jméno dodavatele
  • {{customFields}} – JSON* pole vyplněných vlastních polí
  • {{customFields.<index>}} – jedno vlastní pole na daném indexu ve formátu JSON*
  • {{customFields.<index>.name}} – název vlastního pole
  • {{customFields.<index>.value}} – hodnota vlastního pole

Podmíněné bloky na děkovací stránce

  • {{ifPaid}}...{{/ifPaid}} – pouze pokud je faktura zaplacená
  • {{ifIssued}}...{{/ifIssued}} – pouze pokud je faktura vystavená a nezaplacená
  • {{ifCancelled}}...{{/ifCancelled}} – pouze pokud je objednávka stornovaná

Párové bloky vložte na samostatné řádky. Otevírací a zavírací značku ponechte ve stejném formátování. Text mezi nimi vložte do vlastního odstavce.

Bloky nevnořujte.

{{ifPaid}}
<p>Děkujeme, objednávka č. {{number}} je zaplacená.</p>
{{/ifPaid}}

{{ifIssued}}
<p>Objednávka č. {{number}} čeká na úhradu. Zaplatit můžete zde: <a href="{{orderStatusPage}}">Přejít na přehled objednávky</a>.</p>
{{/ifIssued}}

{item-EBOOK}
<p>Odkaz ke stažení e-booku zobrazte zde.</p>
{/item-EBOOK}

Vlastní externí děkovací stránka není interní děkovací stránka FAPI.

Pokud používáte vlastní děkovací stránku přes thanks_url , musí být splněné podmínky pro načtení dat objednávky. Bez nich se zástupné symboly nenahradí.

Co je potřeba

Vlastní děkovací stránka musí:

  • používat HTTPS,
  • mít vložené FAPI SDK,
  • zachovat parametr path v URL,
  • mít ve formuláři zapnuté vložení identifikátoru objednávky do URL.

Do patičky vlastní stránky vložte jednou tento script:

<script src="https://web.fapi.cz/js/sdk/fapi.js"></script>

FAPI k URL přidá parametr path      . Podle něj SDK načte data objednávky a zástupné symboly nahradí.

Parametr path       nemažte, nepřejmenovávejte, nevytvářejte ručně a odkaz s tímto parametrem nikomu neposílejte.

<p style="text-align: center;"><a href="{{orderStatusPage}}">Zaplatit online</a></p>

<p style="text-align: center;"><a href="{{orderStatusPage}}">Zaplatit online</a></p>

<p style="text-align: center;"><a href="{{orderStatusPage}}">Zaplatit online</a></p>

Shrnutí

Zástupné symboly vždy vybírejte podle toho, kde je chcete použít.

Pro e-mailové šablony a upomínky používejte symboly s jednou dvojicí závorek, například {invoiceNumber} .

Pro interní děkovací stránku FAPI používejte symboly se dvěma dvojicemi závorek, například {{number}} .

Pro vlastní externí děkovací stránku je potřeba navíc HTTPS, FAPI SDK script a zachovaný parametr path .

Před ostrým použitím doporučujeme vše otestovat na skutečné objednávce.