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

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áte	Syntaxe	Příklad
E-mailová šablona nebo upomínka	jedna dvojice závorek `{ }`	`{invoiceNumber}`
Interní děkovací stránka FAPI	dvě dvojice závorek `{{ }}`	`{{number}}`
Vlastní externí děkovací stránka	dvě dvojice závorek `{{ }}`	`{{number}}`

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ě.

E-mailové šablony a upomínky

Najdete i v této samostatné nápovědě (bez děkovací stránky):

Zástupné symboly v e-mailových šablonách a upomínkách

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.

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.

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 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
{ifTwisto}...{/ifTwisto} – pouze pro platbu přes Twisto
{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
{itemsList} – zakoupené položky včetně množství jako HTML seznam
{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

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 kartě Prodej > Produkty, levý sloupec 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.

Příklad:

{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.

Před ostrým odesláním doporučujeme šablonu otestovat na skutečné objednávce.

Náhled nemusí vždy věrně nasimulovat odkazy na soubory, vouchery ani podmíněný obsah.

Interní děkovací stránka FAPI

Najdete i v této samostatné nápovědě (bez e-mailů):

Zástupné symboly v děkovací stránce

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.

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í.

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 platbu v děkovací stránce

{{ifCollectOnDelivery}}...{{/ifCollectOnDelivery}} – pouze pro dobírku
{{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 kartě Prodej > Produkty, levý sloupec kód.

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

{{items}} – JSON* pole 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.

Příklad:

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ě.

{{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}}

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.

Praktický příklad pro interní děkovací stránku:

{{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}

První dva bloky zobrazí odpovídající informaci podle stavu objednávky. Třetí blok se zobrazí jen tehdy, pokud objednávka obsahuje produkt s kódem EBOOK .

Vysvětlení pro JSON (*JSON)

Některé zástupné symboly nevypisují jednu jednoduchou hodnotu, ale více údajů najednou ve formátu JSON.

JSON je technický zápis dat, který slouží hlavně pro další zpracování. Pro běžného zákazníka nemusí být čitelný, proto se obvykle nepoužívá přímo jako text na děkovací stránce.

Příklady JSON symbolů:

{{items}} – vypíše zakoupené položky jako JSON pole

{{customFields}} – vypíše vyplněná vlastní pole jako JSON pole

Pokud chcete zákazníkovi zobrazit konkrétní údaj, doporučujeme použít konkrétní zástupný symbol, ne celý JSON výpis.

Například místo:

{{items}}

použijte:

{{items.0.name}}

Tento symbol vypíše název první zakoupené položky.

U položek objednávky se používá číslování od nuly:

{{items.0.name}} – název první položky

{{items.1.name}} – název druhé položky

{{items.2.name}} – název třetí položky

Stejný princip platí i pro vlastní pole:

{{customFields.0.name}} – název prvního vlastního pole

{{customFields.0.value}} – hodnota prvního vlastního pole

JSON symboly využijete hlavně tehdy, pokud s daty dál pracujete technicky, například ve vlastním kódu na děkovací stránce. Pokud chcete zobrazit zákazníkovi běžný text, použijte raději konkrétní symbol s názvem nebo hodnotou.

Vlastní externí děkovací stránka

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.

MioWeb a Konverzky

Pokud editor platformy nepřijme symbol {{orderStatusPage}} přímo do tlačítka nebo odkazu, vložte HTML/Embed element a použijte celý odkaz:

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

SDK a parametr path jsou nutné i v tomto případě.

Více podrobný postup je zde:

Mioweb

Na platformě MioWeb fungují zástupné symboly, s výjimkou přímého vložení symbolu {{orderStatusPage}} do odkazu nebo tlačítka. MioWeb kontroluje vkládané odkazy, proto takto zadaný odkaz na přehled objednávky nefunguje:

Vložte HTML element a do něj tento kód:

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

Kód vytvoří funkční odkaz na přehled objednávky.

Konverzky

Na platformě Konverzky nelze symbol {{orderStatusPage}} vložit přímo do odkazu nebo tlačítka ani přímo vložit platební QR kód, protože Konverzky kontrolují vkládané odkazy:

Vložte Embed komponentu a do ní tento HTML kód:

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

Výsledek je kliknutelný odkaz:

Nejčastější chyby

Symbol se nezobrazil nebo se nenahradil

Zkontrolujte, zda:

používáte správnou syntaxi pro dané místo,
symbol není rozdělený mezerou, zalomením řádku nebo formátováním,
používáte symbol dostupný pro daný kontext,
u vlastní děkovací stránky funguje SDK a parametr path .

V e-mailu se nezobrazil symbol z děkovací stránky

E-mailové šablony a děkovací stránka používají odlišnou syntaxi.

Do e-mailu patří například:

{invoiceNumber}

Na děkovací stránku patří například:

{{number}}

Na vlastní děkovací stránce se data objednávky nenačetla

Zkontrolujte, zda:

stránka běží na HTTPS,
je vložený FAPI SDK script,
ve formuláři je zapnuté vložení identifikátoru objednávky do URL,
v URL zůstal zachovaný parametr path .

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.