Kurzy ČNB a ECB

Plugin Exchange Rates načítá denní kurzy České národní banky (ČNB) a Evropské centrální banky (ECB). Kurz, přepočtenou částku nebo celý kurzovní lístek dostanete do proměnné případu dvěma způsoby: Smart Eventem Kurzy měn na úkolu šablony, nebo funkcemi exchangeRates ve výpočtu. Typické použití je faktura v cizí měně, u které potřebujete kurz ke dni vystavení a částku v korunách. Plugin nastavuje administrátor, šablonu konzultant.

Plugin se musí nainstalovat
Kurzy nejsou součástí jádra. Bez nainstalovaného pluginu se Smart Event Kurzy měn v seznamu Smart Eventů nezobrazí a funkce exchangeRates ve výpočtech neexistují. Plugin je určen pro řadu 5.21.

Instalace a nastavení pluginu

  1. Otevřete Administrace › Pluginy a přejděte na záložku Obchod s pluginy. Záložka je vidět, jen když má instalace obchod s pluginy nastavený.
  2. U pluginu Exchange Rates v kategorii Integration klepněte na Instalovat (1).
  3. Restartujte backendy tlačítkem Restartovat na obrazovce Pluginy. Nový plugin se načte až po restartu. Restart zasáhne všechny uživatele, proto ho dělejte mimo pracovní dobu.
  4. Po restartu je plugin v seznamu nainstalovaných pluginů a Smart Event Kurzy měn se nabízí v editoru úkolu.

Plugin funguje bez dalšího nastavení. Na záložce Konfigurace obrazovky Pluginy můžete pro každou banku změnit dvě hodnoty:

PoleK čemu slouží
API URLAdresa, ze které se kurzy stahují. Výchozí ČNB https://api.cnb.cz/cnbapi/exrates/daily, ECB https://data-api.ecb.europa.eu. Měňte ji jen tehdy, když požadavky musí jít přes proxy nebo zrcadlo. Povinné.
Default quotationKotace, která se použije, když ji Smart Event ani výpočet neurčí. Výchozí pro ČNB direct, pro ECB indirect, tedy tak, jak banky kurzy vyhlašují. Povinné.
Přístup na internet
Server TAS musí dosáhnout přes HTTPS na adresy bank (nebo na proxy z API URL). Na odpověď banky čeká nejvýše 10 sekund.

Kotace a měna banky

ČNB vyhlašuje kurzy vůči CZK, ECB vůči EUR. Měna banky je vždy ta, vůči které se počítá.

KotaceVýznamPříklad
directKolik jednotek měny banky stojí 1 jednotka měny. Takto vyhlašuje ČNB.ČNB, EUR: 24,29 (CZK za 1 EUR)
indirectKolik jednotek měny dostanete za 1 jednotku měny banky. Takto vyhlašuje ECB.ECB, USD: kolik USD za 1 EUR

Kurz je vždy za 1 jednotku měny. Měny, které ČNB vyhlašuje za 100 jednotek (například HUF nebo JPY), se přepočítají: řádek „100 HUF = 6,222“ vrátí kurz 0,06222.

Smart Event Kurzy měn

Založte v šabloně úkol typu Smart Event a na záložce Smart Event vyberte Kurzy měn. Ukázka je úkol „Get exchange rate“ v šabloně „Foreign invoice – exchange rate“, který zjistí kurz ČNB měny z proměnné Currency ke dni z proměnné Invoice date.

Č.PrvekK čemu slouží
1Kurzy měnSmart Event pluginu Exchange Rates. Zobrazí se jen při nainstalovaném pluginu.
2VýstupCo dostane proměnná s hodnotou: rate kurz jedné měny (číslo), amount částku přepočtenou z měny do jiné měny (číslo), table celý kurzovní lístek dne jako JSON. Povinné.
3BankaCNB nebo ECB. Povinné.
4MěnaTřípísmenný kód měny, například EUR, nebo proměnná {currency}. Povinné pro výstupy rate a amount. Velikost písmen nevadí.
5ČástkaČástka v měně, kterou chcete přepočítat, například 1250.50 nebo proměnná {amount}. Pole se zobrazí a je povinné jen pro výstup amount. Desetinná čárka není číslo, použijte tečku nebo číselnou proměnnou.
6Cílová měnaMěna, do které se částka přepočítá. Prázdné pole znamená měnu banky (CZK pro ČNB, EUR pro ECB). Jen pro výstup amount. Přepočet funguje i mezi dvěma cizími měnami, například USD na EUR podle lístku ČNB.
7Kotacedirect nebo indirect. Prázdné pole použije výchozí kotaci banky z konfigurace pluginu. Jen pro výstupy rate a table.
8DatumDen kurzu, zadává se datumovou proměnnou, například {invoiceDate}. Prázdné pole znamená dnešek.
9Vložit proměnnouIkona {} vloží do pole proměnnou šablony.
10Uložit stav do proměnnéProměnná pro stav: 200 při úspěchu, 500 při chybě. Povinné.
11Uložit hodnotu do proměnnéProměnná pro výsledek. Pro rate a amount číselná proměnná, pro table textová proměnná. Povinné.
12Vytvořit proměnnouZaloží novou proměnnou šablony přímo z úkolu.

Při výstupu amount se ve formuláři objeví pole Částka a Cílová měna a pole Kotace zmizí. Přepočet bere kurzy tak, jak je banka vyhlásila, a výsledek nezaokrouhluje.

Výsledek v případu

Smart Event se spustí, jakmile případ dojde k úkolu, a úkol se sám splní. Další úkol pak už kurz vidí. Na obrázku je úkol „Approve invoice“ s fakturou na 12 480 EUR ze dne 5. 11. 2026, kurzem ČNB 24,29 a částkou v CZK.

Víkendy, svátky a chyby

  • Víkend nebo svátek: když banka v daný den lístek nevyhlásila, použije se poslední lístek vyhlášený před ním. Faktura ze soboty tak dostane páteční kurz.
  • Banka pro daný den ani dříve žádný lístek nevyhlásila: stav 500.
  • Měna, kterou banka nevyhlašuje: stav 500, v textu chyby je seznam měn, které lístek obsahuje.
  • Banka neodpovídá nebo vrátí chybu: stav 500, v textu chyby je odpověď banky.
  • Částka, která není číslo, nebo neplatné datum: stav 500 s popisem, co je špatně.

Při chybě se úkol přesto splní a případ pokračuje. Textová proměnná pro hodnotu dostane text chyby, který začíná „Exchange rate lookup failed:“, číselná zůstane prázdná. Za úkol proto dejte vazby s podmínkou na proměnnou se stavem: 200 pokračuje dál, ostatní stavy vedou na úkol pro ruční doplnění kurzu.

Když chybí povinný údaj (například proměnná Měna je prázdná), Smart Event se vůbec nespustí a skončí chybou už akce, která úkol aktivovala, například splnění předchozího úkolu.

Kurzy se ukládají na hodinu
Stažený lístek pro jednu banku a jeden den si TAS hodinu pamatuje. Další dotazy na stejný den v té době banku znovu nevolají.

Kurzy ve výpočtech

Plugin přidává do výpočtů objekt exchangeRates se třemi funkcemi. Všechny jsou asynchronní, volejte je s await. Volba bank je vždy povinná. Datum se předává jako hodnota datumové proměnné nebo objekt Date, bez data nebo s null se použije dnešek. Pro víkendy a svátky platí stejné pravidlo jako u Smart Eventu.

FunkceCo vrátíVolby
exchangeRates.getRate(měna, volby)Kurz jedné měny za 1 jednotku (číslo).bank, date, quotation
exchangeRates.getRates(volby)Celý lístek { bank, quotation, requestedDate, rates }, kde rates mapuje kód měny na kurz. Měna banky v rates není.bank, date, quotation
exchangeRates.convert(částka, z, do, volby)Přepočtenou částku (číslo, nezaokrouhlené). Funguje i mezi dvěma cizími měnami.bank, date

Příklad: kurz a částka v CZK ke dni faktury.

const day = vars.invoiceDate.getValue();
const rate = await exchangeRates.getRate(vars.currency.getValue(), { bank: 'CNB', date: day });
const czk = await exchangeRates.convert(vars.amount.getValue(), vars.currency.getValue(), 'CZK', { bank: 'CNB', date: day });

Na rozdíl od Smart Eventu chyba ve výpočtu (neznámá měna, nedostupná banka, chybějící bank, částka, která není číslo) výpočet zastaví. Pokud má případ pokračovat i bez kurzu, obalte volání do try / catch.

Jak nastavit šablonu s kurzem

  1. Nainstalujte plugin (viz výše).
  2. V šabloně založte proměnné pro měnu (text nebo seznam), datum, kurz (číslo) a stav (text nebo číslo), případně částku a částku v CZK.
  3. Za úkol, kde uživatel zadá fakturu, přidejte úkol typu Smart Event a vyberte Kurzy měn.
  4. Nastavte Výstup, Banku, Měnu a Datum. Hodnoty z případu vkládejte ikonou {}.
  5. Vyberte proměnné pro stav a hodnotu a uložte úkol.
  6. Pro částku v CZK přidejte druhý Smart Event s výstupem amount, nebo kurz přepočítejte výpočtem.
  7. Na vazby za úkolem dejte podmínku podle proměnné se stavem.

Související: Smart Event úkol, Výpočty na úkolu, ERP a další integrace.

ERP a další integrace

Smart Events pro integrace
Team assistant (opens in a new tab)

Powered by HelpDocs (opens in a new tab)