Účetní výkazy přes API- věcný obsah

Účetní výkazy přes API budou dostupné v pozdějších verzích systému. Aktuálně je třeba využít původní způsob řešení přes OLE a VBA skripty.

V této kapitole je uveden popis následujících témat týkajících se pořizování účetních výkazů:

Verze účetních výkazů přes API do Microsoft Excel jako alternativa původního řešení účetních výkazů. Nové řešení nahrazuje zastaralou formu doplňku využívající OLE a VBA skripty za moderní přístup postavený na frameworku Office Add-ins a JavaScript API. Moderní řešení umožňuje snadnou instalaci prostřednictvím Microsoft Marketplace, jednoduché rozšiřování a využívá robustního ABRA Web API.

Do adresáře s instalací produktu ABRA Aivabyla přidána nová šablona NxDefVykPodnik2021API.xlsx jako náhrada za NxDefVykPodnik2021.xlsx. Šablona je přizpůsobena novému formátu funkcí přidaných do MS Excel v rámci účetních výkazů přes API.

  1. Otevřete šablonu NxDefVykPodnik2021API.xlsx, která se nachází v kořenové složce aplikace ABRA.

  2. Otevře se MS Excel. Na záložce Domů klikněte v horním panelu na Doplňky a následně dole na Další doplňky.

    Otevře se Microsoft Office Marketplace.

  3. Vyhledejte doplněk s názvem ABRA Účetní výkazy, vyberte doplněk a klikněte na Přidat.

  4. Otevřete postranní panel doplňku kliknutím na nově přidanou ikonu ABRA doplňku.

  5. Vyplňte údaje pro připojení k systému ABRA: adresu API serveru a přihlašovací údaje uživatele s přístupem do API.

  6. Klikněte na Uložit připojení.

Po uložení začnou fungovat ABRA funkce, které prostřednictvím API získávají ze systému ABRA data potřebná pro účetní výkazy. Funkcí Aktualizovat vše provedete přepočet celého sešitu a data se zesynchronizují se systémem.

Nastavení zdaňovacího období

Pokud používáte systémovou šablonu NxDefVykPodnik2021API.xlsx, je potřeba před aktualizací dat ručně upravit první list sešitu EPO, kde se definuje začátek a konec zdaňovacího období. Tyto hodnoty čtou funkce na ostatních listech sešitu a ovlivňují, jaké hodnoty budou načteny ze systému ABRA.

HTTPS

Pro správné fungování doplňku je nutné, aby ABRA Web API server komunikoval prostřednictvím protokolu HTTPS. Doplněk využívá zabezpečené spojení pro veškerou komunikaci s API a bez platného HTTPS certifikátu nebude fungovat.

Pokud server zatím nemá nastavené HTTPS, musí jej nakonfigurovat správce IT nebo konzultant. Konfigurace HTTPS je popsána v kapitole Nastavení Web API.

Povolení CORS

ABRA Web API server musí mít v nastavení CORS (Cross-Origin Resource Sharing) povolenou adresu, ze které je doplněk hostován:

https://vykazy-addin.abra.software

Bez tohoto nastavení bude prohlížeč blokovat požadavky doplňku na API server a doplněk nebude schopen komunikovat se systémem ABRA. Nastavení CORS proveďte v konfiguračním souboru APIServer.yaml přidáním výše uvedené adresy do seznamu povolených zdrojů (allowed origins):

allowedOrigins:
- "https://vykazy-addin.abra.software"

Pro uživatele,. který bude moci účetní výkazy přes API používat je potřeba specifické nastavení práv. Níže uvádíme potřebná nastavení.

Licence: Doplněk je dostupný pro předplatné, tj. produkt ABRA Aiva.

Agenda Uživatel:

  • Uživatel musí mít přístup do API na spojení.
  • Uživatelský API přístup.
  • JWT přihlášení.

Role – práva k objektům:

  • Střediska
  • Řady
  • Účetní řady
  • Definice JWT - musí existovat definice pro Přihlášení do API

Role – práva k funkcím:

  • API Funkce: Zdroje pro funkce v MS Excelu
  • API Funkce: Aktuální uživatel: Vystavit přihlašovací token
  • API Funkce: Dotaz na BO: Vykonat
  • Nastavení: Firemní údaje: Spustit
  • Účetnictví: Účetní deník: Spustit

Agenda Zpřístupnění položek pro API:

  • Firemní data: Address_ID (Adresa), ID (Vlastní ID), Site (Dat. hnízdo)
  • Adresa: City (Město), Country (Země), CountryCode (Kód země), EMail (E-mail), PhoneNumber1 (Telefon 1.), PhoneNumber2 (Telefon 2.), PostCode (PSČ), Recipient (Adresát), Street (Ulice), ZIP (ZIP kód)
  • NACE kód: Code (Kód), DisplayName (Název), Name (Název NACE)

Doplněk umí z aktuálně otevřeného sešitu připravit XML soubor určený pro načtení do portálu EPO. Export je připravený pro systémovou šablonu NxDefVykPodnik2021API.xlsx, která obsahuje potřebné listy, výpočty a technické značky pro sestavení XML.

Export spustíte v postranním panelu doplňku v části `XML pro portál EPO` tlačítkem `Uložit XML pro EPO`.

XML se sestavuje z údajů v aktuálním sešitu:

List v sešitu Co se z něj použije
EPO Základní údaje pro přiznání, například zdaňovací období, typ přiznání, údaje poplatníka, adresa, kontakt a oprávněná osoba.
ROZP-tisíce/ROZZ-tisíce/ROZM-tisíce Řádky aktiv a pasiv včetně částek za aktuální a minulé období.
ZZP_druh-tisíce/ZZZ_druh-tisíce Řádky výsledovky v druhovém členění.
ZZP_účel-tisíce/ZZZ_účel-tisíce Řádky výsledovky v účelovém členění.

Konkrétní list rozvahy a výsledovky se vybírá podle nastavení na listu `EPO`. Rozsah účetní závěrky určuje, zda se použije plný, zkrácený nebo mikro výkaz. Typ výsledovky určuje, zda se do XML zapíše druhové nebo účelové členění. Hodnoty ve výkazech se do šablony načítají pomocí funkcí doplňku z ABRA Web API. Proto je před uložením XML důležité spustit `Aktualizovat vše` a zkontrolovat, že v buňkách nejsou chyby.

Technické značky v šabloně

Šablona obsahuje skryté technické sloupce se značkami <def>. Tyto značky nejsou určeny pro běžné vyplňování. Slouží doplňku jako orientační body, podle kterých pozná, kde v sešitu najde údaje pro XML.

Na listu `EPO` značky určují, odkud se má vzít konkrétní údaj, například začátek období, konec období, DIČ nebo název poplatníka. Na listech rozvahy a výsledovky určují začátek a konec částí výkazu a sloupce s částkami.

Značky jsou vázané i na konkrétní listy. Stejná značka může mít jiný význam podle toho, zda je na listu rozvahy nebo výsledovky. Technické skryté sloupce, značky `<def>` a názvy listů doporučujeme ponechat beze změny.

Vrátí obrat za zadané období. (využívá API endpoint /bookentries/turnover)

Syntaxe 

=GET_TURNOVER(dateFrom;dateTo;accounts;[firms];[divisions];[includeRequests];[version])

Parametry

Parametr Povinný Popis
dateFrom Ano Počáteční datum období.
dateTo Ano Koncové datum období.
accounts Ano Účet nebo účetní výraz. Podrobná syntaxe je popsána níže u této funkce.
firms Ne Kódy firem. Lze zadat více hodnot oddělených čárkou, středníkem nebo oblastí buněk.
divisions Ne Kódy středisek. Doplňek vždy zahrnuje i podřízená střediska.
includeRequests Ne Pokud je TRUE, zahrnou se i účetní žádosti.
version Ne Verze interpretace stran účtu: 1 nebo 2.

Poznámky

  • Pokud je accounts prázdný, funkce vrátí 0.
  • Pokud dateFrom vypadá jako nevyplněná volba nebo krátký neplatný text, funkce vrátí 0.
  • Parametr firms je dostupný jen zde, nikoli u GET_BALANCE a GET_BEGINNING.

Parametr accounts

Parametr accounts určuje účet nebo kombinaci účtů, pro které se má obrat spočítat. Každý účet ve výrazu může mít prefix a postfix. Zadává se kód účtu z agendy Účtový rozvrh.

Prefixy

Prefix Význam
+ Explicitní přičtení výrazu.
- Odečtení výrazu od celku.

Postfixy

Postfix Význam
MD Jen strana Má dáti ve version=1.
D Jen strana Dal ve version=1.
d Jen debitní strana ve version=2.
c Jen kreditní strana ve version=2.
> Jen kladný výsledek daného dílčího výrazu.
< Jen záporný výsledek daného dílčího výrazu.
s Jen krátké částky.
ns Jen dlouhé částky.
t Jen daňové částky.
nt Jen nedaňové částky.

Prefix a postfixy lze řetězit v jednom výrazu, např.:221MD,-221D,+343t,-501nt

Parametr version

Hodnota Význam
prázdné Stejné chování jako 1.
1 Legacy interpretace stran účtu: MD = Má dáti, D = Dal.
2 Moderní interpretace stran účtu: d = debit, c = credit.

Doplňkové informace

  • version=2 mění pouze označení stran účtu.
  • Postfixy >, <, s, ns, t, nt fungují v obou verzích stejně.
  • Pokud se do doplňku zadá jiná hodnota než 1 nebo 2, doplněk ji na backend nepošle a chová se stejně, jako kdyby version nebyla vyplněná.

Jednoduchý obrat za účet:

=GET_TURNOVER("2024-01-01";"2024-12-31";"221")

Obrat za více účtových výrazů:

=GET_TURNOVER("2024-01-01";"2024-12-31";"221MD,-221D,+343t";"";"100";TRUE;1)

Moderní značení stran ve verzi 2:

=GET_TURNOVER("2024-01-01";"2024-12-31";"221d,-221c,+343nt";"";"100";TRUE;2)

Vrátí zůstatek k zadanému datu. (využívá API endpoint /utils/balance)

Syntaxe 

=GET_BALANCE(dateTo;accounts;[divisions];[includeRequests];[version])

Parametry

Parametr Povinný Popis
dateTo Ano Datum, ke kterému se má zůstatek spočítat.
accounts Ano Účet nebo účetní výraz. Používá stejnou syntaxi jako u GET_TURNOVER.
divisions Ne Kódy středisek. Doplňek vždy zahrnuje i podřízená střediska.
includeRequests Ne Pokud je TRUE, zahrnou se i účetní žádosti.
version Ne Verze interpretace stran účtu: 1 nebo 2.

Poznámky

  • Oproti GET_TURNOVER zde není parametr firms.
  • Při použití postfixů > nebo < se po filtraci vrací absolutní hodnota dílčího výsledku.
  • Pokud je accounts prázdný, funkce vrátí 0.

Jednoduchý zůstatek:

=GET_BALANCE("2024-12-31";"321"))

Zůstatek podle střediska:

=GET_BALANCE("2024-12-31";"321";"100";TRUE;1)

Moderní značení stran a řetězení postfixů:

=GET_BALANCE("2024-12-31";"321d,-321c,+343t,-501nt";"100";TRUE;2)

Vrátí zůstatek k počátečnímu datu sledovaného intervalu.

Syntaxe 

=GET_BEGINNING(date;accounts;[divisions];[includeRequests];[version])

Parametry

Parametr Povinný Popis
date Ano Datum, které je předáno do API jako date-to.
accounts Ano Účet nebo účetní výraz. Používá stejnou syntaxi jako u GET_TURNOVER.
divisions Ne Kódy středisek. Doplňek vždy zahrnuje i podřízená střediska.
includeRequests Ne Pokud je TRUE, zahrnou se i účetní žádosti.
version Ne Verze interpretace stran účtu: 1 nebo 2. 

=GET_BEGINNING("2024-01-01";"321";"100";TRUE;1)

Vrátí hlavní telefon z objektu střediska, konkrétně z SiteData a z adresy navázané na středisko (Address_ID.PhoneNumber1).

Syntaxe 

=GET_EPO_PHONE([site])

Parametry

Parametr Povinný Popis
site Ne Kód střediska. Pokud není zadán, použije se 01. Pokud předáte oblast buněk nebo seznam, použije se jen první hodnota. 

=GET_EPO_PHONE("01")

Vrátí název ulice bez čísla domu z objektu střediska, konkrétně z SiteData a z adresy navázané na středisko.

Syntaxe 

=GET_EPO_STREET([site])

Parametry

Stejné jako u funkce GET_EPO_PHONE.

Vrátí číslo domu z objektu střediska, konkrétně z SiteData a z adresy navázané na středisko.

Syntaxe 

=GET_EPO_STREET_NUMBER([site])

Parametry

Stejné jako u funkce GET_EPO_PHONE.

Vrátí město z objektu střediska, konkrétně z SiteData a z adresy navázané na středisko.

Syntaxe 

=GET_EPO_CITY([site])

Parametry

Stejné jako u funkce GET_EPO_PHONE.

Vrátí PSČ z objektu střediska, konkrétně z SiteData a z adresy navázané na středisko.

Syntaxe 

=GET_EPO_POSTCODE([site])

Parametry

Stejné jako u funkce GET_EPO_PHONE.

Vrátí kód státu z objektu střediska, konkrétně z SiteData a z adresy navázané na středisko.

Syntaxe 

=GET_EPO_COUNTRY_CODE([site])

Parametry

Stejné jako u funkce GET_EPO_PHONE.

Vrátí e-mail z objektu střediska, konkrétně z SiteData a z adresy navázané na středisko.

Syntaxe 

=GET_EPO_EMAIL([site])

Parametry

Stejné jako u funkce GET_EPO_PHONE.

Vrátí DIČ účetní jednotky z globálních dat.

Syntaxe 

=GET_VAT_IDENT_NUMBER()

Vrátí právní formu účetní jednotky z globálních dat.

Syntaxe 

=GET_LEGAL_FORM()

Vrátí hlavní předmět podnikání z globálních dat.

Syntaxe 

=GET_SUBJECT_OF_ENTERPRISE()

Vrátí název poplatníka nebo firmy z globálních dat.

Syntaxe 

=GET_TAXPAYER_NAME()

Vrátí název hlavního CZ-NACE z globálních dat.

Syntaxe 

=GET_MAIN_NACE_NAME()

Bezpečné dělení dvou hodnot.

Syntaxe 

=DIVIDING(dividend;divider)

Parametry

Parametr Povinný Popis
dividend Ano Dělenec.
divider Ano Dělitel. 

=DIVIDING(100;4)

Chyba: Buňka nenačetla správně data - obsahuje ERROR.

Pokud buňka, která načítá data ze systému ABRA obsahuje “ERROR: …”, tak to znamená, že zadaný uživatel nemá potřebná API práva pro danou funkci. Samotný text chyby často napoví, jaká práva je nutné doplnit. Podrobný přehled potřebných uživatelských oprávnění je zapsán výše.

Chyba: V panelu doplňku nejde přihlášení - Network/CORS/SSL error.

Pokud při pokusu o přihlášení dostáváte chybovou hlášku obsahující Network/CORS/SSL error, tak zkontrolujte že:

  • API server běží na zadané adrese

  • API server má nastavenou komunikaci přes HTTPS

  • API server má správně přidanou adresu doplňku "https://vykazy-addin.abra.software" v sekci allowedOrigins v APIServer.yaml

ABRA Účetní výkazy add-in je doplněk pro Microsoft Excel poskytovaný společností ABRA Software s.r.o. Doplněk slouží k připojení sešitu Excel k ABRA Gen přes ABRA API, k načítání účetních dat do buněk sešitu a k přípravě XML exportu účetních výkazů pro portál EPO.

Jaká data doplněk používá

Doplněk pracuje s údaji, které uživatel zadá v panelu doplňku nebo které jsou obsaženy v otevřeném sešitu Excel. Jedná se zejména o:

  • URL adresu ABRA API serveru,
  • uživatelské jméno pro připojení k ABRA Aiva
  • volitelný kód JWT definice,
  • přístupový token získaný z ABRA API,
  • hodnoty z buněk sešitu potřebné pro výpočet účetních výkazů a XML export,
  • parametry výpočtů, například období, účty, firmy, střediska a nastavení zahrnutí žádostí,
  • údaje načtené z ABRA Aiva potřebné pro účetní výkazy a EPO export, například obraty, zůstatky, údaje účetní jednotky, adresní údaje střediska, DIČ, právní forma, název poplatníka nebo CZ-NACE.

Doplněk nevyžaduje přihlášení k samostatné službě ABRA Software. Připojuje se k ABRA API serveru, jehož adresu zadá uživatel nebo správce zákaznického prostředí.

Jaká data doplněk používá

Doplněk ukládá do lokálního úložiště Office doplňku tyto údaje:

  • URL adresu ABRA API,
  • uživatelské jméno,
  • volitelný kód JWT definice,
  • přístupový token pro ABRA API.

Heslo zadané při přihlášení se neukládá. Použije se pouze pro získání přístupového tokenu z ABRA API a po úspěšném uložení připojení je odstraněno z formuláře doplňku.

Doplněk dále ukládá lokálně informaci o zvoleném jazyku uživatelského rozhraní.

Předávání dat

Doplněk odesílá údaje pouze na ABRA API server, který uživatel nastaví v doplňku. Při připojení odešle přihlašovací údaje na tento server za účelem získání přístupového tokenu. Při práci se sešitem následně odesílá na ABRA API pouze požadavky potřebné pro výpočty a načtení dat do účetních výkazů.

ABRA Účetní výkazy add-in sám neodesílá obsah sešitu, účetní výkazy ani vygenerované XML soubory na servery ABRA Software. XML export pro portál EPO se vytváří v prostředí Excelu a ukládá se do umístění zvoleného uživatelem.

Doplněk neobsahuje vlastní analytiku, marketingové sledování ani reklamní funkce.

Hosting doplňku

Soubory doplňku mohou být načítány z webového hostingu používaného společností ABRA Software. Při načtení doplňku může hostingová infrastruktura technicky zpracovat běžné provozní údaje nezbytné pro doručení webového obsahu, například IP adresu, čas požadavku, požadovanou URL adresu, typ prohlížeče nebo technické chybové záznamy. Tyto údaje nejsou používány funkcemi doplňku k profilování uživatele.

Účel zpracování

  • navázání spojení mezi Excelem a ABRA Aiva,
  • ověření přístupu uživatele k ABRA API,
  • výpočtu účetních hodnot v sešitu,
  • načtení údajů potřebných pro účetní výkazy,
  • vytvoření XML exportu pro portál EPO,
  • uložení nastavení připojení pro další použití doplňku.

Role zákazníka a ABRA Software

Účetní a osobní údaje uložené v ABRA Aiva spravuje zákazník ve svém prostředí. Doplněk funguje jako klientský nástroj, který na pokyn uživatele přistupuje k ABRA API a zobrazuje nebo zpracovává data v Excelu.

ABRA Software s.r.o. nezískává prostřednictvím běžného používání doplňku kopii zákaznických účetních dat, pokud je uživatel samostatně neposkytne například v rámci podpory, servisního požadavku nebo jiné smluvní komunikace.

Zabezpečení

Doplněk komunikuje s ABRA API přes adresu nastavenou uživatelem. Pro produkční používání musí být použito zabezpečené připojení HTTPS a důvěryhodný certifikát. Přístup k datům v ABRA Aiva se řídí oprávněními uživatele a nastavením ABRA API.

Uživatel nebo správce zákaznického prostředí odpovídá za správné nastavení ABRA API serveru, přístupových práv, CORS pravidel a certifikátů.

Uchování údajů

Údaje uložené lokálně doplňkem zůstávají v úložišti Office doplňku, dokud nejsou přepsány, odstraněny uživatelem, odstraněny správcem prostředí nebo smazány společně s daty aplikace Office/prohlížeče podle nastavení daného zařízení.

Účetní data načtená do sešitu Excel jsou součástí příslušného sešitu a jejich uchování se řídí tím, jak uživatel nebo organizace s tímto sešitem nakládá.

Práva subjektů údajů

Pokud při používání doplňku dochází ke zpracování osobních údajů obsažených v ABRA Aiva nebo v sešitu Excel, je primárním správcem těchto údajů zákazník, který dané prostředí ABRA Aiva používá.

Obecné informace o zpracování osobních údajů společností ABRA Software s.r.o. jsou uvedeny v zásadách ochrany soukromí společnosti ABRA Software s.r.o.