Zaúčtování prodejek REST API dovoluje vykonat službu Zaúčtovat prodejky voláním PUT nebo POST na adresu /c/{firma}/pokladni-pohyb/zauctovat-prodejky.[json|xml]?datum=2019-12-31&kasa=35&pokladna=2&typPokDokl=5'. Parametry datum - v GUI pole „Zaúčtování prodejek z data“ (povinné) - formát yyyy-mm-dd kasa - v GUI pole „Prodejky z kasy“ (povinné) - ID z evidence typ-prodejky pokladna - v GUI pole „Pokladna“ (povinné) - ID z evidence pokladna typPokDokl - v GUI pole „Typ pokladního dokladu“ (povinné) - ID z evidence typ-pokladni-pohyb cisRada - není povinný parametr, je vyžadován, pokud není nalezena číselná řada odpovídající pokladně a typu pokladního dokladu - ID z evidence /rada-pokladni-pohyb Pro všechny parametry identifikující záznam, lze kromě číselného ID použít i ostatní podporované typy identifikátorů (např. &kasa=code:KASA).
Import EET certifikátů EET certifikáty je možné importovat v API rozhraní. Import certifikátů: Způsob volání Lze využít HTTP metodu: PUT nebo POST. Služba je dostupná na adrese: /c/{firma}/certifikat-eet/import, kde {firma} je databázový idenfitikátor firmy. Jsou podporovány výstupní formáty: XML nebo JSON. Příklad volání: curl -sk -u jmeno:heslo -T {jmeno_souboru} -X PUT(/POST) "https://localhost:5434/c/{firma}/certifikat-eet/import?heslo={heslo}&provozovna={provozovna}" -H 'Content-Type: {content-type}' -H 'Accept: {application/xml | application/json}' Parametry Oba parametry (heslo, provozovna) jsou povinné, parametr heslo slouží k odemčení certifikátu a provozovna je označení Vaší EET provozovny. Při špatném hesle a neplatné (či chybějící) provozovně dojde k chybě, operace skončí kódem 400. Dále je nutné uvést v hlavičce atribut Content-Type, tato hodnota se řídí koncovkou zasílaného certifikátu: - application/x-x509-ca-cert - pro koncovky .crt a .der - application/x-pem-file - pro koncovku .pem - application/x-pkcs12 - pro koncovky .p12 a .pfx - application/pkix-cert - pro koncovku .cer
Příkaz k úhradě Příkaz k úhradě lze vytvářet přes REST API klasicky HTTP operací PUT nebo POST na evidenci /c/{firma}/prikaz-k-uhrade. Ukázka vytvoření příkazu ve formátu XML: <winstrom version="1.0"> <!-- Příkazy k úhradě --> <prikaz-k-uhrade> <banka>code:BANKOVNÍ ÚČET</banka> <polozky> <!-- Položky --> <prikaz-k-uhrade-polozka> <buc>123456</buc> <castka>1200.0</castka> <smerKod>code:0100</smerKod> </prikaz-k-uhrade-polozka> <!-- Položka uhrazující zadaný doklad --> <prikaz-k-uhrade-polozka> <doklFak>code:PF1478/2020</doklFak> </prikaz-k-uhrade-polozka> </polozky> </prikaz-k-uhrade> </winstrom> Pokročilejší operace GET /c/{firma}/prikaz-k-uhrade/{id}/stazeni ?dat-splat-z-hlavicky= možnosti: true, false Získá soubor s elektronickým popisem příkazu k úhradě vhodný k odeslání do banky. Volitelným parametrem dat-splat-z-hlavicky lze ovlivnit nastavení volby data splatnosti z hlavičce příkazu. GET /c/{firma}/prikaz-k-uhrade/{id}/odeslani-fio ?dat-splat-z-hlavicky= možnosti: true, false Provede online odeslání příkazu k úhradě (pouze Fio banka s online napojením). Volitelným parametrem dat-splat-z-hlavicky lze ovlivnit nastavení volby data splatnosti z hlavičce příkazu. PUT/POST /c/{firma}/prikaz-k-uhrade/{id}/zrusit-odeslani Zruší stav odeslání příkazu.
Uživatelské mailové šablony Přes REST API (i webové rozhraní) lze vytvořit a získat mailové šablony pro posílání dokladů a Aktualizaci mezd. Tato evidence je dostupná pouze pro licenci Premium. Chceme-li získat šablonu, použijeme standardně URL /c/{firma}/sablona-mail/{id}. Lze samozřejmě použít i úroveň detailu. Pro vytvoření šablony pošleme XML/JSON na URL /c/{firma}/sablona-mail. Chceme-li šablonu připojit k typu dokladu (zde konkrétně typ faktury vydané), na výše zmíněné URL pošleme například takovéto XML: <winstrom version="1.0"> <typ-faktury-vydane> <kod>{kod}</kod> <nazev>FAV se šablonou</nazev> <modul>FAV</modul> <radaPrijem>code:FAKTURA-STANDARD</radaPrijem> <typDoklK>typDokladu.faktura</typDoklK> <sablonaMail> {text-sablony} </sablonaMail> <poznam>Šablona pro faktury vydané</poznam> </typ-faktury-vydane> </winstrom> Příklad šablony a Freemarker proměnné Využívá se šablonovací systém FreeMarker. Před uložením šablony program zkontroluje, zda šablona neobsahuje nepovolené výrazy. V šablonách je možné použít následující proměnné: ${application} - Název aplikace, tedy "ABRA Flexibee" ${user} - Objekt uživatele, se kterým můžeme dále pracovat ${company} - Nastavení firmy ${uzivatelJmeno} - Vaše křestní jméno ${uzivatelPrijmeni} - Vaše příjmení ${titulJmenoPrijmeni} - Vaše celé jméno, včetně dosažených titulů ${nazevFirmy} - Název firmy ${object} - Obecný přístup na předávaný objekt ${doklad} - Doklad určený k odeslání Příklad použití těchto proměnných v šabloně Dobrý den, zasílám Vám doklad ${doklad}, jehož interní číslo je ${doklad.kod}. Jmenuji se ${uzivatelJmeno} ${uzivatelPrijmeni}, včetně mého titulu ${titulJmenoPrijmeni}, pracuji pro ${nazevFirmy}. Mé telefonní číslo je ${user.mobil}, DIČ firmy je ${company.dic}.
Vytvoření a zrušení účelu GDPR Účel GDPR pro záznam lze přes XML vytvořit následujícím způsobem: <winstrom version="1.0"> <faktura-vydana> <!-- záznam, může být z kterékoliv podporované evidence" --> <id>code:FAKTURA1</id> <!-- lze normálně uvést další vlastnosti záznamu jako při běžném importu --> <vytvor-ucel> <definiceUcelu>code:DEFINICE</definiceUcelu> <poznam>Uživatelská poznámka</poznam> <!-- nepovinné --> </vytvor-ucel> </faktura-vydana> </winstrom> Účel GDPR lze také odvázat a smazat: <winstrom version="1.0"> <faktura-vydana> <!-- záznam, může být z kterékoliv podporované evidence" --> <id>code:FAKTURA1</id> <!-- lze normálně uvést další vlastnosti záznamu jako při běžném importu --> <zrus-ucel> <id>1</id> </zrus-ucel> </faktura-vydana> </winstrom> Identifikátor účelu se získá dotazem na konkrétní evidenci. Ty, které podporují GDPR, obsahují relaci "ucely".
Aktualizace požadavků na výdej V případě, že je v nastavení firmy povolené generování požadavků na výdej, tak lze pomocí REST API volat službu Aktualizace skladových požadavků na výdej. Způsob volání Lze využít HTTP metodu: PUT nebo POST. Služba je dostupná na adrese: /c/{firma}/sklad/aktualizace-pozadavku, kde {firma} je databázový idenfitikátor firmy. Jsou podporovány výstupní formáty: XML nebo JSON. Parametry Služba neočekává parametry. Výsledek Pro rozpoznání, zda byla služba vykonána úspěšně, lze kontrolovat HTTP status odpovědi nebo vlastnost success v získaném dokumentu. Úspěšné volání V případě úspěšného vykonání služby je vracen HTTP status 200 a dokument odpovídající požadovanému formátu: XML <winstrom version="1.0"> <success>true</success> </winstrom> JSON { "winstrom": { "@version": "1.0", "success": "true" } } Neúspěšné volání HTTP status odpovědi je 4xx nebo 5xx. A například v případě, že firma nemá povolené generování požadavků na výdej, získáme výsledný dokument: XML <winstrom version="1.0"> <success>false</success> <message>Není povoleno generování požadavků na výdej.</message> </winstrom> JSON { "winstrom": { "@version": "1.0", "success": "false", "message": "Není povoleno generování požadavků na výdej." } } Ukázky volání PUT /c/demo/sklad/aktualizace-pozadavku.xml PUT /c/demo/sklad/aktualizace-pozadavku.json PUT /c/demo/sklad/aktualizace-pozadavku (s hlavičkou Accept: application/xml nebo Accept: application/json) POST /c/demo/sklad/aktualizace-pozadavku.xml POST /c/demo/sklad/aktualizace-pozadavku.json POST /c/demo/sklad/aktualizace-pozadavku (s hlavičkou Accept: application/xml nebo Accept: application/json)
Vazby ZDD Přes REST-API je možné provázat zálohový daňový doklad ZDD s platbou bankovního nebo pokladního dokladu uhrazující zálohu. <!-- vytvoření vazby zdd mezi zdd a bankou --> <winstrom version="1.0"> <faktura-vydana> <!-- zálohový daňový doklad --> <id>code:VF1-0001/2017</id> <!-- lze normálně uvést další vlastnosti dokladu jako při běžném importu --> <vytvor-vazbu-zdd> <uhrada type="banka">code:B+0001/2017</uhrada> </vytvor-vazbu-zdd> </faktura-vydana> </winstrom> <!-- vytvoření vazby zdd mezi zdd a pokladnou --> <winstrom version="1.0"> <faktura-vydana> <!-- zálohový daňový doklad --> <id>code:VF1-0001/2017</id> <!-- lze normálně uvést další vlastnosti dokladu jako při běžném importu --> <vytvor-vazbu-zdd> <uhrada type="pokladni-pohyb">code:P+0001/2017</uhrada> </vytvor-vazbu-zdd> </faktura-vydana> </winstrom> Identifikátor platebního dokladu (tag <uhrada>) lze uvést podle obvyklých pravidel. Pokud tento platební doklad není nalezen, import skončí s chybou. Pokud není uveden typ úhrady (atribut type) má se za to, že typ úhrady je bankovní doklad. <!-- vytvoření vazby zdd mezi zdd a úhradou bez uvedením typu platby --> <winstrom version="1.0"> <faktura-vydana> <!-- zálohový daňový doklad --> <id>code:VF1-0001/2017</id> <!-- lze normálně uvést další vlastnosti dokladu jako při běžném importu --> <vytvor-vazbu-zdd> <uhrada>code:B+0001/2017</uhrada> </vytvor-vazbu-zdd> </faktura-vydana> </winstrom> Jeden ZDD je možné navázat pouze na jednu platbu a na jednu platbu může být navázán pouze jeden ZDD. V případě, že je již ZDD navázán na nějakou paltbu a mělo by dojít k navázání na nějakou jinou, import skončí s chybou. Stejně tak v případě, že je již platba navázána na nějaký ZDD a mělo by dojít k navázání téže platby na nějaký jiný ZDD, import také skončí s chybou. Přes REST-API je také možné vazbu ZDD zrušit. <!-- zrušení vazby zdd --> <winstrom version="1.0"> <faktura-vydana> <!-- zálohový daňový doklad --> <id>code:VF1-0001/2017</id> <!-- lze normálně uvést další vlastnosti dokladu jako při běžném importu --> <zrus-vazbu-zdd/> </faktura-vydana> </winstrom>
Zápočty Vzájemný zápočet je fiktivní bankovní výpis, kterým jsou prováděny zejména úhrady pohledávek a závazků na principu vzájemných zápočtů. <winstrom version="1.0"> <faktura-vydana> <id>code:FAV1</id> <typDokl>code:FAKTURA</typDokl> <bezPolozek>true</bezPolozek> <sumOsv>100.0</sumOsv> </faktura-vydana> <faktura-prijata> <id>code:FAP1</id> <typDokl>code:FAKTURA</typDokl> <cisDosle>F123</cisDosle> <datSplat>2017-12-31+01:00</datSplat> <bezPolozek>true</bezPolozek> <sumOsv>100.0</sumOsv> </faktura-prijata> </winstrom> Pro připravené faktury lze provést zápočet následujícím způsobem: <winstrom version="1.0"> <vzajemny-zapocet> <id>code:ZAP+0016/2017</id> <typDokl>code:ZAPOCET</typDokl> <typPohybuK>typPohybu.prijem</typPohybuK> <!-- částka úhrady --> <sumOsv>1.0</sumOsv> <bezPolozek>true</bezPolozek> <sparovani> <uhrazovanaFak type="faktura-vydana">code:FAV1</uhrazovanaFak> <zbytek>castecnaUhrada</zbytek> </sparovani> <!-- číslo zápočtu --> <cisSouhrnne>ZAP-123</cisSouhrnne> </vzajemny-zapocet> <vzajemny-zapocet> <id>code:ZAP+0017/2017</id> <typDokl>code:ZAPOCET</typDokl> <typPohybuK>typPohybu.vydej</typPohybuK> <sumOsv>1.0</sumOsv> <bezPolozek>true</bezPolozek> <sparovani> <uhrazovanaFak type="faktura-prijata">code:FAP1</uhrazovanaFak> <zbytek>castecnaUhrada</zbytek> </sparovani> <cisSouhrnne>ZAP-123</cisSouhrnne> </vzajemny-zapocet> </winstrom> Může se stát, že částky na uhrazujícím a uhrazovaném dokladu nesouhlasí (zbývá část doplatit), v takovém případě se import řídí hodnotou v tagu zbytek. Lze zvolit tyto hodnoty: ne: zbytek nesmí nastat; pokud k němu dojde, jedná se o chybu castecnaUhrada: pokud je částka na uhrazujícím dokladu menší než na uhrazovaném, jedná se o částečnou úhradu Analogicky lze provádět i odpárování: <winstrom version="1.0"> <vzajemny-zapocet> <id>code:ZAP+0016/2017</id> <odparovani> <uhrazovanaFak type="faktura-vydana">code:FAV1</uhrazovanaFak> </odparovani> </vzajemny-zapocet> </winstrom>
Stavy účtů Přes REST API (i webové rozhraní) lze získat Stavy účtů. Chceme-li získat Stavy účtů pro účetní období platné k aktuálnímu datu, použijeme URL .../c/{firma}/stav-uctu[.xml]. Lze samozřejmě použít i úroveň detailu a filtraci. Pokud potřebujeme stavu pro jiné než aktuální účetní období je nutné do URL doplnit parametr ucetniObdobi. Hodnotou tohoto parametru je zkratka požadovaného účetního období. Výsledné URL tedy bude vypadat například .../c/{firma}/stav-uctu[.xml]?ucetniObdobi=2016. Další možností, jak získat stavy účtů pro jiné než aktuální účetní období, je doplnit parametr idUcetniObdobi. Tento parametr umožňuje využití identifikátorů účetního období. Pokud je tento parametr použit, má přednost před parametrem ucetniObdobi. /c/{firma}/stav-uctu[.xml]Stavy účtů pro aktuální účetní obdobi /c/{firma}/stav-uctu[.xml]?idUcetniObdobi=3Stavy účtů pro účetní období s ID 3 /c/{firma}/stav-uctu[.xml]?idUcetniObdobi=code:2016Stavy účtů pro účetní období se zkratkou 2016 /c/{firma}/stav-uctu[.xml]?ucetniObdobi=2016Stavy účtů pro účetní období se zkratkou 2016
Dobropisy Přes REST-API je možné provázat dobropis s fakturou. <winstrom version="1.0"> <faktura-vydana> <!-- dobropis; může být i "faktura-prijata" --> <id>code:DOBROPIS1</id> <!-- lze normálně uvést další vlastnosti dokladu jako při běžném importu --> <vytvor-vazbu-dobropis> <dobropisovanyDokl>code:FAKTURA1</dobropisovanyDokl> <!-- identifikátor dobropisovaného dokladu--> </vytvor-vazbu-dobropis> </faktura-vydana> </winstrom> Lze uvést ID dobropisované faktury (tag <dobropisovanyDokl>) podle obvyklých pravidel. Pokud tato faktura není nalezena, import skončí s chybou. Jeden dobropis je možné navázat jen na jednu fakturu. Na jednu fakturu ale může být navázáno více dobropisů. V případě, že je již dobropis navázán na nějakou fakturu a mělo by dojít k navázání na nějakou jinou, import skončí s chybou. Přes REST-API je také možné vazbu dobropisu zrušit. <winstrom version="1.0"> <faktura-vydana> <!-- dobropis; může být i "faktura-prijata" --> <id>code:DOBROPIS1</id> <zrus-vazbu-dobropis></zrus-vazbu-dobropis> </faktura-vydana> </winstrom> Důležitá upozornění Služba vytváří pouze vazbu, dobropisující doklad musí mít správně vytvořené položky. Vytvořená vazba přidává pouze propojení hlaviček dokladů, neřeší propojení položek. Nákupní cena uvedená na položkách by měla odpovídat skladové ceně zboží z dobropisovaného dokladu, jinak nebude sedět stav skladu. Pokud není uvedena nákupní cena, použije se aktuální skladová cena! Pokud není zboží skladem, použije se nákupní cena z ceníku!
Uživatelské tlačítko Uživatelské tlačítko Možnosti použití Uživatelské tlačítko slouží k přizpůsobení ABRA Flexi, když dává vývojářům a uživatelům možnost definovat vlastní akci ve formě tlačítka. Po aktivaci tlačítka dojde k zobrazení panelu v ABRA Flexi či otevření webového prohlížeče, v obou případech s libovolnou webovou stránkou. Pomocí uživatelského tlačítka může být zobrazena relevantní část intranetového informační systému, vyhledáno zboží ve srovnávači cen, otevřena příslušná část webového rozhraní ABRA Flexi či vyvolána akce prostřednictvím našeho REST-API. Do adresy webové stránky je možné dynamicky vkládat parametry jako např. IČ právě upravované firmy či EAN zobrazeného zboží. Způsob použití Parametry uživatelského tlačítka jako např. jeho text, cílové URL či umístění v ABRA Flexi se zapíší do definice tlačítka, souboru ve formátu XML. Vytvořená definice uživatelského tlačítka se načte do ABRA Flexi importem z XML souboru a při opětovném připojení k firmě bude tlačítko součástí uživatelského rozhraní (ať již klientské aplikace či webového rozhraní). Definice uživatelského tlačítka Uvedení některých prvků je povinné (nepovinný prvek je browser), každý prvek může být v rámci definice jednoho tlačítka uveden nanejvýše jednou (výjimkou je prvek id). Soubor může obsahovat definici více uživatelských tlačítek, při vícenásobném uvedení definice tlačítka se jednotlivé definice považují za jeho aktualizaci a fakticky se projeví poslední aktualizace jeho vlastnosti. Nevyhovující definice uživatelského tlačítka bude odmítnuta již při importu do ABRA Flexi. id Identifikátory záznamu slouží pro přidělení kódu/zkratky při vytváření a pro přesné určení uživatelského tlačítka při jeho pozdější aktualizaci či mazání. Pro identifikaci uživatelského tlačítka je možné použít: Kód/zkratku – uživatelské označení (prefix code:) Externí identifikátor – identifikátor z externí aplikace (prefix ext:) Identifikátor ABRA Flexi – číselný neměnný identifikátor přidělovaný aplikací (bez prefixu) Povinný prvek, při vytváření uživatelského tlačítka musí být prvek uveden s kódem (zkratkou). Podrobnější informace o použití prvku naleznete v části Identifikátory záznamů. url Určuje URL webové stránky či síťového zdroje, které bude po stisku tlačítka otevíráno. URL musí být uvedeno v plném, absolutním tvaru, tj. musí obsahovat schéma a doménovou adresu serveru (např. https://www.flexibee.eu/). URL doporučujeme zadávat v <![CDATA[ ]]>, aby přítomnost znaku '&' nezpůsobila nevalidní XML. V hodnotě URL není podporováno URI schéma file používané pro přístup k lokálně uloženým souborům. Definice uživatelských tlačítek obsahující URL s file:// budou při importu odmítnuty jako nepovolené. Při konstrukci URL je možné uvést proměnné, které budou vyhodnoceny FreeMarkerem při běhu aplikace a zajistí předání hodnot z aplikace. Např. zápis ${object.ic} slouží pro získání IČ partnera v adresáři. Řetězec object je v názvu proměnných povinný, pomocí něj je odkazováno na aktuální záznam zobrazené evidence. Seznam dostupných atributů jednotlivých evidencí lze zobrazit ve webovém rozhraní (adresy jako https://localhost:5434/c/mojefirma/adresar/properties). Podporované proměnné: object – aktuální záznam (viz předchozí bod). objectIds – seznam ID vybraných záznamů oddělených čárkou. user – aktuálně přihlášený uživatel (viz https://localhost:5434/c/mojefirma/uzivatel/properties). url – úplná URL adresa objektu, na kterém bylo tlačítko vyvoláno (např. https://instance.flexibee.eu/c/demo/adresar/1). companyUrl – adresa API rozhraní firmy, ve které je tlačítko umístěno (např. https://instance.flexibee.eu/c/demo). evidence – jméno evidence, na které je tlačítko umístěno. authSessionId – autentizační token k aktuálnímu sezení uživatele. Po dobu platnosti sezení lze využít k autentizace dotazů. Viz využití autentizačního tokenu v popisu Autentizace. customerNo – číslo zákazníka odpovídající licenci. licenseId – identifikátor licence. Pozor: Proměnné object a objectIds se vzájemně vylučují! evidence Určuje evidenci, popř. konkrétní vazbu (relaci) evidence ABRA Flexi, pro kterou má být tlačítko zobrazováno. Např. adresar pro evidenci obchodních partnerů, faktura-vydana pro evidenci faktur vydaných, atd. Ve variantě pro vazby určité evidence pak např. faktura-vydana-polozka pro položky faktury vydané či majetek-zapujcka pro zápůjčky v evidenci majetku atd. Pro evidence obecně použijte řetězec zobrazovaný v URL webového rozhraní v sekci evidence (https://localhost:5434/c/mojefirma/cenik). Seznam všech evidencí je k dispozici na adrese https://localhost:5434/c/mojefirma/evidence-list Pro vazby evidencí obecně použijte řetězec evidence (viz výše) doplněný o spojovník (pomlčku) a řetězec vazby zjištěný na přehledu vazeb evidence (https://localhost:5434/c/mojefirma/cenik/relations). location Určuje zobrazení tlačítka na přehledu záznamů nebo na kartě konkrétního záznamu. Přípustné hodnoty: list – pro přehled záznamů detail – pro konkrétní záznam Má-li být tlačítko dostupné v nástrojové liště na přehledu záznamů a zároveň na kartě konkrétního záznamu, je nezbytné připravit dvě definice uživatelského tlačítka, které se budou lišit hodnotou prvku location. title Text zobrazený na tlačítku. description Detailní popis tlačítka zobrazovaný v bublině. browser Určuje prohlížeč, ve kterém se URL otevře. Interní prohlížeč se zobrazí rychleji, ale nemusí obsahovat uživatelské přizpůsobení a data (hesla, cookies, data formulářů, navštívené odkazy). Externí prohlížeč je prostředím, na které je uživatel zvyklý. Nepovinný prvek, výchozí hodnotou je automatic. Z podstaty webového rozhraní je v něm nastavení prvku browser ignorováno. Přípustné hodnoty: desktop – externí prohlížeč automatic – interní prohlížeč; není-li dostupný, otevře se externí prohlížeč Příklad vytvoření <winstrom version="1.0"> <custom-button> <id>code:JUSTICECZ</id> <url> <![CDATA[https://or.justice.cz/ias/ui/rejstrik-$firma?ico=${object.ic}&jenPlatne=VSECHNY]]> </url> <title>Obch. rejstřík</title> <description>Zobraz záznam firmy v obchodním rejstříku justice.cz</description> <evidence>adresar</evidence> <location>detail</location> <browser>desktop</browser> </custom-button> </winstrom> Příklad aktualizace tlačítka Uvedete-li v definici jednoznačnou identifikaci existujícího tlačítka, můžete jej aktualizovat. ABRA Flexi umožňuje částečné aktualizace záznamů, takže při změně adresy obchodního rejstříku ve výše uvedeném příkladu stačí uživatelské tlačítko identifikovat a uvést novou hodnotu URL: <winstrom version="1.0"> <custom-button> <id>code:JUSTICECZ</id> <url> <![CDATA[https://or.justice.cz/ias/ui/rejstrik-$firma?ico=${object.ic}&jenPlatne=VSECHNY&polozek=500]]> </url> </custom-button> </winstrom> Příklad smazání tlačítka Pro smazání existujícího tlačítka je potřeba použít atribut action (více o jeho použití naleznete v části Provádění akcí). Uživatelské tlačítko z výše uvedeného příkladu lze smazat pomocí: <winstrom version="1.0"> <custom-button action="delete"> <id>code:JUSTICECZ</id> </custom-button> </winstrom>
Autentizace kontaktu Ekonomický systém ABRA Flexi umožňuje použít kontakty uložené v databázi k autentizaci. Pomocí API je nejdříve nutné kontaktu nastavit jméno a heslo. Existují dva způsoby: Heslo je možné zaslat ve formě plain-text: POST /c/firma/kontakty/1.xml <kontakt> <username>jan</username> <password hash="" salt="">heslo</password> </kontakt> Heslo, zaslané jako plain-text, je v ABRA Flexi uložené v bezpečné formě pomocí hash funkce. Heslo je možné zaslat ve formě výsledku volání hash funkce. V tomto případě jsou povinné parametry salt a typ hash funkce: POST /c/firma/kontakty/1.xml <kontakt> <username>jan</username> <password hash="sha256" salt="abcd">ed9bddc9f20f1aa3587979c9536c625d485</password> </kontakt> Hodnota elementu <password> je zde výsledek hash funkce aplikované na řetězec vzniklý spojením hesla a hodnoty salt. Původní heslo v tomto případě není nutné zasílat. Podporované typy hash funckí: sha1 sha256 sha512 pbkdf2 md5 Poté je možné pomocí API autentizovat kontakt voláním: POST /c/firma/kontakty/1/authenticate Accept: application/xml Content-Type: application/x-www-form-urlencoded username=jan&password=heslo Autentizace funguje také na obecné URL kontaktů: POST /c/firma/kontakt/authenticate Accept: application/xml Content-Type: application/x-www-form-urlencoded username=jan&password=heslo Výsledkem je vždy odpověď s HTTP status kódem 200, výsledek je uvedený v těle odpovědi: Úspěšná autentizace: <?xml version="1.0" ?> <winstrom version="1.0"> <success>true</success> <message></message> </winstrom> Neúspěšná autentizace: <winstrom version="1.0"> <success>false</success> <message>Bylo zadáno chybné uživatelské jméno či heslo.</message> </winstrom>
Příkaz k inkasu Příkaz k inkasu lze vytvářet přes REST API jednoduchým voláním metodou PUT nebo POST: /c/{firma}/bankovni-ucet/{id}/prikaz-k-inkasu Pro zadaný bankovní účet vytvoří příkaz k inkasu ze všech dosud neuhrazených dokladů. /c/{firma}/bankovni-ucet/{id}/prikaz-k-inkasu?splatnost=2014-10-14&datVystOd=2014-09-01&datVystDo=2014-09-31 Pro zadaný bankovní účet vytvoří příkaz k inkasu se zadanou splatností ze všech dosud neuhrazených dokladů v uvedeném období. Vstupy Zpracování poadavku se řídí těmito parametry: parametrtyppopisvýchozí hodnota splatnost datum yyyy-mm-dd datum splatnosti příkazu následující všední den datVystOd datum yyyy-mm-dd datum vystavení nejstaršího hrazeného dokladu neomezeno datVystDo datum yyyy-mm-dd datum vystavení nejmladšího hrazeného dokladu aktuální datum Do vytvářeného příkazu k inkasu jsou zahrnuty doklady splňující tyto podmínky: doklad je typu vydaná faktura nebo pohledávka s kladnou (nenulovou) hodnotou, doklad je typu přijatá faktura nebo závazek se zápornou (nenulovou) hodnotou, nejedná se o zálohový daňový doklad, forma úhrady dokladu je "převodem", doklad má vyplněné bankovní spojení (číslo účtu), měna dokladu je shodná s měnou účtu, doklad ještě není zcela uhrazen (může být částečně), doklad se dosud nevyskytuje na příkazu k inkasu, na dokladu není nastaven zákaz proplacení (faktura přijatá), doklad je schválen k platbě, je-li vyžadován podpis před vystavením příkazu k úhradě, datum vystavení dokladu vyhovuje zadaným kritériím (viz parametry datVystOd a datVystDo). Výstupy Úspěšné zpracování požadavku může vracet tyto stavy: 200Nebyly nalezený žádné vhodné doklady pro vytvoření příkazu. 201Příkaz k inkasu byl vytvořen, URL je uvedeno v hlavičce Location.
Adresář pro vývojářské přizpůsobení Pro některé účely mohou programátoři přizpůsobit nastavení systému. K tomu je nutné nastavit: Je potřeba upravit flexibee-server.xml (kde jej najít?) a přidat tam <entry key="developerDirectory">/devel/</entry> Místo /devel/ dejte adresář, kde budou data pro modifikaci (např. C:ProjektyFlexiBee). Restartovat ABRA Flexi V daném adresáři je potřeba vytvořit adresář "default" (tzv. výchozí instance - jiná hodnota má smysl pouze v cloudovém provozu) a v něm adresář s identifikátorem firmy (ten je stejný jako přes webové rozhraní). Případně je možné použít speciální identifikátor "!all" (bez uvozovek).
Načítání bankovních výpisů Bankovní výpisy lze načíst jednoduchým požadavkem přes REST API: soubor s výpisem je třeba poslat metodou PUT nebo POST na URL /c/{firma}/bankovni-ucet/{id}/nacteni-vypisu. U bankovního účtu musí být nastaveny příslušné vlastnosti týkající se elektronického bankovnictví (formát výpisu atd.). Pokud se výpis načte správně, odpověď je 200. Tělo odpovědi může obsahovat informaci, že některé doklady už byly načteny: Výpis 223 pro účet 0000001000 - Načítání proběhlo úspěšně. Počet položek 6 položka s popisem POPLATEK - Tento doklad byl již načten. položka s popisem VYBER HOTOVOSTI - Tento doklad byl již načten. V případě chyby je odpověď 400 a tělo odpovědi obsahuje popis problému. Např.: Výpis 223 pro účet 0000001000 - Pro tento výpis nebyl nalezen bankovní účet. Počet položek 6 Nebo: U bankovního účtu není definován formát elektronického výpisu. Tělo odpovědi, pokud je uvedeno, je momentálně vždy textové, ačkoliv požadujete XML nebo JSON. Tento problém bude v budoucnosti opraven. Načítání výpisů online Pomocí REST-API je možné také spustit načítání online výpisů. Pro spuštění je nutné odeslat požadavek metodou PUT nebo POST na URL /c/{firma}/banka/nacteni-vypisu-online. Bankovní účet, pro který se mají výpisy stahovat, musí být správně nastaven a banka musí online výpisy podporovat.
Web Hooks Web Hooks Web Hooks jsou způsob, jak se ve Vaší aplikaci v reálném čase dozvědět o změně v ABRA Flexi. Princip je jednoduchý: když dojde v databázi ABRA Flexi ke změně, je (obvykle v řádu několika málo vteřin) odeslán POST HTTP request na všechna zaregistrovaná URL. Obsahem požadavku je výpis změn najednou od posledního zavolání hooku, a to ve stejném formátu, jaký získáte od ABRA Flexi přes rozhraní Changes API. Postup Musí být zapnuto Changes API (sledování změn). Také musí být hooky povoleny v konfiguračním souboru ABRA Flexi Serveru flexibee-server.xml (umístění adresářů s flexibee-server.xml): ... <entry key="enableHooks">true</entry> ... Důvodem je, že při startu serveru je potřeba ihned nastartovat jádro (vizte též automatické startování jádra), což je časově náročná operace. Pozn.: pokud máte nastaveno enableHooks na true, není už třeba nastavovat startKernel. Hook se zaregistruje PUT (příp. POST) požadavkem na adresu /c/{firma}/hooks s následujícími parametry: povinné ?url=http://muj.server.cz/hook.phpURL, které se má zavolat ?format=XMLFormát dat (možné hodnoty jsou XML a JSON) volitelné ?lastVersion=123Verze od které započne posílání následujích změn, tj. od nejbližší vyšší verze. Defaultní hodnota je rovna aktuální globální verzi (globalVersion) v momentě registrace hooku. Přípustné hodnoty jsou z intervalu: [0, globalVersion]. ?secKey=MyHookSecretToken0687Libovolný řetězec, který bude odesílán s každou notifikací změn v HTTP hlavičce. Slouží k jednoduchému ověření, zda patří příchozí notifikace Vámi registrovanému hooku. Název klíče v HTTP hlavičce je X-FB-Hook-SecKey. ?skipUrlTest=truePotlačení testu funkčnosti předaného URL. Např.: curl -u uzivatel:heslo -L -k -X PUT "https://localhost:5434/c/{firma}/hooks.xml?url=http://muj.server.cz/hook.php&format=XML&lastVersion=123&secKey=MyHookSecretToken0687" Registrace provádí test předaného URL odesláním prázdné notifikace. Při návratovém kódu jiném než 2xx nebude hook zaregistrován. Provedení testu lze potlačit parametrem skipUrlTest. ABRA Flexi od verze 2017.1.1 podporuje SNI. To znamená, že je možně registrovat hooky směřující na HTTPS virtuální host. Prozatím není možné specifikovat, kterých evidencí se má hook týkat, vždy je upozorněn na všechny změny, které v ABRA Flexi nastanou. Jako obvykle, úspěch je oznámen stavovým kódem 200 a neúspěch kódem 400 (v odpovědi je textový popis příčiny). Výpis zaregistrovaných hooků je na adrese /c/{firma}/hooks, odregistrovat hook lze DELETE požadavkem na adresu /c/{firma}/hooks/{id}. Chování hooku při chybě Pokud nastává chyba při zpracování hooku, pokouší se server zasílat požadavky opakovaně. Pokud hook i nadále selhává, začne docházet ke zpožďování volání hooků. Typicky v případě, že je služba zcela nedostupná začne každé volání později. Pro tyto účely se používá penalty, která reprezentuje dobu mezi jednotlivými pokusy. Aktuální penalizaci můžete získat pomocí GET: curl -u uzivatel:heslo -L -k "https://localhost:5434/c/{firma}/hooks/{id}.xml" Vynulování penalizace a okamžité zavolání hooku zajistí PUT požadavek: curl -u uzivatel:heslo -L -k -X PUT "https://localhost:5434/c/{firma}/hooks/{id}/retry" Registrované hooky jsou ukládány v databázi a tak dojde k odeslání hooku i po restartování serveru. Služba garantuje, že se žádná změna neztratí a všechny jsou předány registrovanému hooku. Doporučení pro implementaci hooku Celý mechanismus funguje na principu best effort. To znamená, že i když se snažíme doručovat oznámení co nejdříve a vyhýbat se duplicitám, je potřeba počítat s tím, že zpoždění nebo duplicita mohou nastat (prostě stejný požadavek doručíme vícekrát). Pro eliminaci duplicit můžete zpracovávat globalVersion. Zpracování hooku by mělo trvat co nejkratší dobu (< 15 sekund) a rozhodně nesmí přesáhnout 30 sekund, jinak se považuje volání za neúspěšné. Odpověď musí mít status kód 200 (resp. 2xx) a neměla by obsahovat žádné tělo. Pokud je některá z těchto podmínek porušena, daný hook je penalizován (tj. nějakou dobu nebude vůbec zavolán) a v krajním případě může dojít i k jeho úplnému vypnutí. Ideální implementace hooku provádí pouze persistenci přijatých změn s případnou rychlou filtrací na relevatní změny a s přeskakovaním duplicit (již zpracovaných změn). Vlastní zpracování přijatých změn by mělo běžet asynchronně v nezávislém vlákně. Další podporované stavové kódy odpovědí Zpracování hooku podporuje v odpovědích, kromě klasického potvrzení statusem 200, ještě následující možnosti: 301 (Moved Permanently) / 308 (Permanent Redirect) V případě, že přesměrování vede na validní URL, tak proběhne aktualizace adresy registrovaného hooku a po krátké penalizaci již proběhne notifikace změn na nově evidovanou adresu. 410 (Gone) Předpokládá se, že byl daný hook permanentně zrušen, a na straně ABRA Flexi proběhne jeho automatická odregistrace.
Provádění akcí Při importu lze namísto běžného vytvoření či změny záznamu provést jinou akci, např. smazání či storno dokladu. K tomu slouží atribut action: <winstrom version="1.0"> <faktura-vydana action="delete"> <id>123</id> <id>uuid:123456</id> </faktura-vydana> </winstrom> Akce Popis Smazání (delete) Záznam bude smazán. Storno (storno) Záznam bude stornován. Lze použít pouze pro doklady. Při provádění akcí nejsou záznamy jinak modifikovány, nemá tedy smysl uvádět jiné elementy než id. Zároveň musí záznamy již existovat, nelze např. vytvořit novou smazanou fakturu. Akce na položkách Akce lze vyvolávat také na položkách dokladu. Jen ne přímo, ale stejně jako při aktualizaci, je zapotřebí uvést požadavek prostřednictvím kolekce položek na odpovídajícím dokladu. Ukázka pro smazání položky s ID rovno 456 v XML a JSON formátu: <winstrom version="1.0"> <faktura-vydana> <id>123</id> <polozkyFaktury> <faktura-vydana-polozka id="456" action="delete" /> </polozkyFaktury> </faktura-vydana> </winstrom> { "winstrom": { "@version": "1.0", "faktura-vydana": [{ "id": "123", "polozkyFaktury": [{ "id": "456", "@action": "delete" }] }] } }
Stav skladu k datu Přes REST API lze zjišťovat stav skladu na URL: /c/{firma}/stav-skladu-k-datu, kde {firma} je databázový idenfitikátor firmy. Parametry Parametr * Popis Výchozí hodnota sklad × Identifikátor skladu, který lze zadat jako: celočíselný identifikátor vyhledávací kód (code:KOD_SKLADU) datum Datum k němuž se provádí zjištění stavu skladu. Do výpočtu jsou zahrnuty skladové pohyby s datem vystavení do zadaného data včetně. Aktuální den * = povinný parametr Ukázky GET /c/demo/stav-skladu-k-datu?sklad=4 GET /c/demo/stav-skladu-k-datu?sklad=code:SKLAD&datum=2012-12-12
Individuální ceník Přes REST API (i webové rozhraní) lze získat individuální ceník pro danou firmu či danou ceníkovou skupinu. Chceme-li např. získat individuální ceník pro firmu, která má kód FIRMA, použijeme URL .../c/{firma}/adresar/code:FIRMA/individualni-cenik[.xml]. Jako obvykle dojde k přesměrování na číselné ID záznamu, výsledné URL je .../c/{firma}/adresar/400/individualni-cenik (pokud má firma FIRMA interní ID 400). Lze samozřejmě použít i úroveň detailu. /c/{firma}/adresar/400/individualni-cenikIndividuální ceník pro firmu, která má ID 400 /c/{firma}/cenikova-skupina/2/individualni-cenikIndividuální ceník pro ceníkovou skupinu, která má ID 2 Parametry Parametrem date v URL (formát YYYY-MM-DD) se nastaví, pro jaké datum se má individuální ceník vyexportovat. Není-li parametr uveden, použije se aktuální datum. Parametrem currency v URL se nastaví, pro jakou měnu se má individuální ceník vyexportovat. Není-li parametr uveden, použije se tuzemská měna. Hodnotou tohoto parametru je zkratka požadované měny. Parametrem centre v URL se nastaví, pro jaké středisko se má individuální ceník vyexportovat. Není-li parametr uveden, vyexportují se nějlepší ceny bez ohledu na středisko. Hodnotou tohoto parametru je zkratka požadovaného střediska. ?date=2011-12-01Individuální ceník k datu 1. prosince 2011. ?currency=EURIndividuální ceník v jiné měně než v tuzemské. V tomto případě EUR. ?centre=CIndividuální ceník pro konkrétí středisko. V tomto případě středisko se zkratkou C. Hledání obecné ceny pro zákazníka Obdobně lze získat všechny varianty cen zboží pro všechny firmy a ceníkové skupiny: /c/{firma}/individualni-cenikKompletní přehled cen Při hledání ceny v případě, že máte staženou celou tabulku "individualni-cenik" je nutné postupovat podle těchto kroků: vyhledat cenu pro konkrétní firmu a zboží vyhledat cenu pro cenovou úroveň a zboží (cenovou úroveň lze nalézt u firmy v adresáři) použít standardní cenu zboží z ceníku na výslednou cenu je nutné aplikovat procentuální slevu firmy (je u firmy v adresáři)
Sestavování URL Struktura URL pro ABRA Flexi se skládá z několika částí: /c/<identifikátor firmy>/<evidence>/<ID záznamu>.<výstupní formát> <identifikátor firmy>: jednoznačná identifikace firmy <evidence>: typ evidence (adresář, objednávka, faktura, ...) <ID záznamu>: identifikátor záznamu <výstupní formát>: výstupní formát (XML, JSON, ...). Pokud není uvedeno zohledňuje se hlavička Accept, případně je vrácena HTML forma. Výpis evidence Pokud chcete výpis položek evidence (viz výpis), neuvádějte žádný identifikátor záznamu: /c/<identifikátor firmy>/<evidence> Je také možné použít filtraci: /c/<identifikátor firmy>/<evidence>/(<filtr>) Sumace záznamů Pokud potřebujete získat základní sumace o dané evidenci, použijte sumaci: /c/<identifikátor firmy>/<evidence>/$sum Je také možné kombinovat filtraci a sumaci: /c/<identifikátor firmy>/<evidence>/(<filtr>)/$sum Přehled atributů Pro každou evidenci je možné získat seznam atributů, které tato evidence podporuje. Tento přehled zohledňuje přístupová práva a licencování. /c/<identifikátor firmy>/<evidence>/properties Přehled tiskových reportů U evidence si můžete zobrazit seznam podporovaných reportů pro tisk do PDF: /c/<identifikátor firmy>/<evidence>/reports Přehled podevidencí Každá evidence může mít podevidenci (relaci). Příkladem může být položka faktury nebo kontakty u adresáře. Tyto záznamy jsou obvykle přístupné i přímo jako evidence. Rozdíl je v tom, že podevidence je filtrována danou relací. Přehled podevidencí lze získat takto: /c/<identifikátor firmy>/<evidence>/relations S podevidencemi lze pak pracovat stejně jako s evidencí: /c/<identifikátor firmy>/<evidence>/<ID záznamu>/<podevidence> Pokud chcete při exportu z ABRA Flexi exportovat se záznamem i jeho podevidence, použijte parametr ?relations=vazby,prilohy,bankovniSpojeni. Všechny podporované parametry ABRA Flexi podporuje mnoho atributů a na této stránce je jejich popis. ?dry-run=true
Analýza nákupu / prodeje Pro dotazy na analýzu nákupu a prodeje přes REST API slouží tato dvě URL: Analýza nákupu - /c/{firma}/analyza-nakupu Analýza prodeje - /c/{firma}/analyza-prodeje Parametr {firma} označuje databázový identifikátor firmy. Parametry Parametry jsou až na drobné odchylky pro obě analýzy shodné: Parametr * Popis Možnosti Výchozí hodnota analyzovat × Určuje co je cílem prováděné analýzy: cenik - pohyb zboží skupZboz - pohyb sumárně dle skupin zboží sklad - obraty skladů stredisko - obraty středisek zakazka - obraty na zakázky adresar - obraty podle firem skupFir - obraty sumárně dle skupin firem mistUrc - obraty dle míst určení (pouze pro analýzu prodeje) clenit Stanovuje další členění analyzovaných dat: cenik - podle zboží skupZboz - podle skupin zboží sklad - podle skladů stredisko - dělení podle středisek zakazka - dělení na zakázky adresar - kterým firmám skupFir - kterým skupinám firem mistUrc - dle míst určení (pouze pro analýzu prodeje) Žádné další členění. datumOd Spodní hranice data (zaúčtování) analyzovaných dokladů. Žádné omezení data nejstaršího dokladu. datumDo Horní hranice data (zaúčtování) analyzovaných dokladů. Žádné omezení data nejnovějšího dokladu. datumyUcetne Určuje zda se zadaná data dokladů berou jako datumy zaúčtování. Při false hodnotě se berou datumy jako data vystavení. true/false true (doklady hledat dle data zaúčtování) neucetniDoklady Ovlivňuje zda se budou do analýzy zahrnovat neúčetní doklady. true/false true (zahrnout i neúčetní doklady) mesicniSumace Nastavuje zda se mají provádět měsíční sumace obratů. true/false true (provádět měsíční sumace) stredisko Omezuje analýzu pouze na vybrané středisko. Pro více středisek lze parametr dotazu uvést vícekrát. Identifikátor střediska (celočíselné ID případně kód). Analýza všech středisek bez omezení. Platí pouze pro analyzovat=adresar nebo analyzovat=skupFir nekatalogovePolozky Určuje zda se mají do analýzy zahrnout i nekatalogové položky. Má význam pouze při analýze dle firem nebo dle skupin firem. true/false false (zahrnovat pouze katalogové položky) Platí pouze pro analyzovat=cenik cenik Omezí analýzu zboží na vybranou položku. Identifikátor požadované ceníkové položky. Analýza všech ceníkových položek bez omezení. Platí pouze pro analyzovat=adresar firma Omezí analýzu podle firem na vybranou společnost. Identifikátor požadované společnosti. Analyzovat podle všech firem bez omezení. * = povinný parametr Ukázky GET /c/demo/analyza-prodeje?analyzovat=cenik GET /c/demo/analyza-nakupu?analyzovat=adresar&datumOd=2012-01-01&datumDo=2012-12-31&datumyUcetne=false GET /c/demo/analyza-prodeje?analyzovat=skupFir&nekatalogovePolozky=false&stredisko=code:A&stredisko=code:B GET /c/demo/analyza-nakupu?analyzovat=adresar&clenit=skupZboz&datumOd=2012-01-01&mesicniSumace=true
Režim individuálních kódů ceníkových položek V případě importu dokladů s položkami s vazbou na ceník lze aktivovat režim individuálních kódů odběratele / dodavatele. V tomto režimu lze na všech položkách dokladu ve vazbách na ceník použít místo obvyklého kódu zadaného prefixem "code:" také individuální kód odběratele (resp. dodavatele). Individuální kód je třeba také uvádět s prefixem "code:" a musí být pro daného odběratele / dodavatele unikátní. <winstrom version="1.0" article-individual-codes="true"> <objednavka-prijata> <kod>OBP0004/2014</kod> <datVyst>2014-02-17</datVyst> <firma>code:FLEXIBEE</firma> ⋮ <polozkyObchDokladu> <objednavka-prijata-polozka> <typPolozkyK>typPolozky.katalog</typPolozkyK> <mnozMj>1.0</mnozMj> <sklad>code:SKLAD</sklad> <cenik>code:S001</cenik><!-- vyhledávání primárně dle kódu v individuálním ceníku odběratele --> </objednavka-prijata-polozka> </polozkyObchDokladu> </objednavka-prijata> </winstrom> Při vytváření objednávky se vyhledává položka nejprve v individuálním ceníku odběratele "FLEXIBEE" podle kódu "S001". Pokud v individuálním ceníku takový záznam neexistuje, pokračuje vyhledání ceníkové položky standardním způsobem.
Tvorba nabídky/objednávky z poptávky/nabídky Přes REST API lze z poptávky vytvořit nabídku a to takto: <poptavka-prijata> <id>code:POP0001/2013</id> <nabidni> <id>ext:NABIDKA</id> <!-- nepovinný externí identifikátor vytvořené nabídky --> <typDokl>code:NAV</typDokl> <!-- typ dokladu vytvořené nabídky, pokud není zadaný bere se z nastavení --> </nabidni> </poptavka-prijata> Obdobně je možno z poptávky i nabídky vytvořit objednávku: <poptavka-prijata> <id>code:POP0001/2013</id> <objednej> <id>ext:OBJEDNAVKA</id> <!-- nepovinný externí identifikátor vytvořené objednávky --> <typDokl>code:OBP</typDokl> <!-- typ dokladu vytvořené objednávky, pokud není zadaný bere se z nastavení --> </objednej> </poptavka-prijata>
Sumace Pokud potřebujete získat základní sumace o dané evidenci, použijte sumaci: /c/<identifikátor firmy>/<evidence>/$sum Je také možné kombinovat filtraci a sumaci: /c/<identifikátor firmy>/<evidence>/(<filtr>)/$sum Sumaci lze exportovat do těchto formátů: XML: /c/<identifikátor firmy>/<evidence>/$sum.xml JSON: /c/<identifikátor firmy>/<evidence>/$sum.json Poznámka: sumace lze provádět jen nad doklady (faktury, objednávky, poptávky, pokladní pohyby, skladové pohyby, ...). Sumace mohou obsahovat pokročilé parametry (použitelné momentálně pouze nad obraty na účtech), které je nutno nad některými agendami použít. Mohou to být např.: period: (rokMesic,2020-01-01,2020-12-31) - za jaké období fields: obrDal,obrMd - jaké se sumují group-by: rokMesic, quarter(rokMesic) - jak grupovat Výsledná URL adresa může poté vypadat např. takto: $sum.xml?period=(rokMesic,2020-01-01,2020-12-31)&fields=obrDal,obrMd&group-by=rokMesic
Výpis záznamů V ABRA Flexi je možné vypisovat základní data z aplikace. Obecně rozlišujeme výpis a detail. Výpis Jedná se o výpis více záznamů. Lze jej stránkovat, filtrovat, řadit a určovat úroveň detailu. Výstup lze vypisovat ve více formátech. Detail Detail vždy reprezentuje jen jeden záznam, který může být identifikován různými způsoby a zapsán ve více formátech. Výpis mnoha konkrétních záznamů Pokud potřebujete získat více konkrétních záznamů, u nichž znáte identifikátor (typicky externí ID), máte několik možností. Můžete každý záznam získat samostatně, takto: GET /c/firma/faktura-vydana/1 GET /c/firma/faktura-vydana/code:2 GET /c/firma/faktura-vydana/ext:SYS:3 Pozor na to, že v tomto příkladu bude první odpovědí na druhý a třetí požadavek přesměrování na adresu, která obsahuje číselné ID. Na tu je pak třeba poslat nový požadavek. Knihovny pro práci s HTTP obvykle umí následovat přesměrování automaticky, ale může být potřeba to zapnout. Můžete použít filtraci, takto: GET /c/firma/faktura-vydana/(id in (1, 'code:2', 'ext:SYS:3')) Pozor na to, že příliš dlouhá URL mohou způsobovat problémy (ať už ve webových prohlížečích nebo na nejrůznějších proxy serverech). Můžete použít funkci hromadného získání záznamů podle ID zadaných v XML dokumentu. POST /c/firma/faktura-vydana/get.xml Content-Type: application/xml <winstrom> <id>1</id> <id>code:2</id> <id>ext:SYS:3</id> </winstrom> Zde není problém s délkou URL, takže takto lze získat i několik set či tisíc záznamů zároveň. Pokud je uveden neexistující identifikátor, bude ignorován. Pokud je uveden jeden identifikátor vícekrát, příp. pokud je uvedeno více identifikátorů, které ukazují na stejný záznam, budou na výstupu duplicity. Kromě XML lze použít i JSON, kromě metody POST lze i PUT: PUT /c/firma/faktura-vydana/get.json Content-Type: application/json { "winstrom": { "id": [1, "code:2", "ext:SYS:3"] } }
Řazení záznamů Záznamy lze samozřejmě řadit. Seznam hodnot, podle kterých lze řadit, je závislé na konkrétní evidenci. Řazení je řízeno parametrem URL order. Tento parameter lze uvést opakovaně. Ukázka: /c/firma/adresar?order=nazev Lze řídit, zda řadit sestupně (order=nazev@A) nebo vzestupně (/c/firma/adresar?order=nazev@D). Kvůli kompatibilitě s některými implementacemi, lze také použít parametr sort a dir (nabývá hodnot ASC a DESC).
Úhrada faktury z přeplatků v pokladně a bance Jednou z funkcí ABRA Flexi je možnost uhradit fakturu z přeplatků v bance nebo pokladně. Při párování úhrady na fakturu je vyplněna firma a pokud je úhrada větší než faktura, zůstane přeplatek. Ten je pak možné automaticky pomocí této funkce napárovat na fakturu. K tomu slouží akce uhrad-preplatky takto: <winstrom version="1.0"> <faktura-vydana action="uhrad-preplatky"> <id>17</id> </faktura-vydana> </winstrom> Akci lze vyvolat i dávkově nad skupinou dokladů pomocí filtru: <winstrom version="1.0"> <faktura-vydana action="uhrad-preplatky" filter="not stavUhrK begins 'stavUhr.uhrazeno' and typDokl = 'code:INTERNET'"> </faktura-vydana> </winstrom>
Hotovostní úhrada Fakturu vydanou nebo přijatou lze přes XML hotovostně uhradit následujícím způsobem: <winstrom version="1.0"> <faktura-vydana> <!-- uhrazovaný doklad; může být i "faktura-prijata" --> <id>code:FAKTURA1</id> <!-- lze normálně uvést další vlastnosti dokladu jako při běžném importu --> <hotovostni-uhrada> <uhrazujiciDokl>code:UHRADA1</uhrazujiciDokl> <!-- nepovinné --> <pokladna>code:POKLADNA KČ</pokladna> <!-- nepovinné, pokud je vyplněné a je true, použije se kurz platný k datu úhrady, jinak se použije kurz převzatý z uhrazované faktury --> <kurzKDatuUhrady>true/false</kurzKDatuUhrady> <typDokl>code:STANDARD</typDokl> <!-- typ vytvářeného pokladního dokladu --> <castka>1000</castka> <datumUhrady>2011-01-01</datumUhrady> </hotovostni-uhrada> </faktura-vydana> </winstrom> Lze uvést ID uhrazujícího pokladního dokladu (tag <uhrazujiciDokl>) podle obvyklých pravidel a funguje následovně: Nová úhrada: Pokud uvedeno není, vždy se vytvoří nový pokladní doklad, takže pokud naimportujete XML dvakrát, vytvoří se dvě úhrady. Pokud je uvedeno a doklad s daným ID neexistuje, založí se. Aktualizace: Pokud existuje, musí uhrazovat danou fakturu (jinak jde o chybu) a znamená to, že se má úhrada pouze zaktualizovat dostupnou částkou na uhrazujícím dokladě. Ostatní parametry úhrady se ignorují. V tagu <hotovostni-uhrada> lze uvést ještě dokladovou řadu pro vytvářený pokladní doklad. Není to povinné a standardně se bere z vybraného typu dokladu, případně z vybrané pokladny. <rada>code:POKLADNA+</rada>
Výpočet Daně z přidané hodnoty (DPH) DPH je jednou z věcí, kterou ABRA Flexi dokáže vypočítat sám. Nicméně existuje několik metod výpočtu (tzv. shora a zdola) a také jej ovlivňuje zaokrouhlování. Proto má ABRA Flexi několik metod pro ovlivňování DPH. Vždy platí, že DPH u položkového dokladu je součtem DPH jednotlivých položek a na výsledek je aplikováno zaokrouhlení. To zda se má DPH výpočítat shora nebo zdola se řídí tím, které parametry uvedete (např. základ → dojde k výpočtu DPH a výsledku). Můžete také uvést všechny parametry a ABRA Flexi uvede jejich kontrolu. Kontrolní výpočty ABRA Flexi při výpočtech kontroluje vzájemné vazby mezi položkami. Musí platit tato pravidla (mohou se lišit o zaokrouhlování): sumDphCelkem = sumDphSniz + sumDphZakl sumCelkem = sumOsv + sumZklSniz * sazbaDphSniz + sumZklZakl * sumDphZakl sumCelkZakl = sumZklZakl * sumDphZakl sumCelkSniz = sumZklSniz * sumDphSniz sumZklCelkem = sumOsv + sumZklSniz + sumZklZakl Pokud tedy ABRA Flexi vypíše chybu: Zadaná hodnota [9999.99] vlastnosti [sumCelkem] se liší od vypočtené hodnoty [9999.99] znamená to, že jste tyto kontrolní mechanizmy nedodržely. Obvykle se jedná o chybný výpočet DPH a nebo chybu vstupních dat. Obvykle stačí uvádět pouze základy a nechat vše ostatní ABRA Flexi dopočítat. To samé pak platí o měně, kde navíc musí odpovídat i hodnoty mezi základní měnou a měnou. ABRA Flexi v těchto případech lehce upraví kurz, aby se zamezilo zaokrouhlovací chybě. sumDphCelkemMen = sumDphSnizMen + sumDphZaklMen sumCelkemMen = sumOsvMen + sumZklSnizMen * sazbaDphSniz + sumZklZaklMen * sumDphZakl sumCelkZaklMen = sumZklZaklMen * sumDphZakl sumCelkSnizMen = sumZklSnizMen * sumDphSniz sumZklCelkemMen = sumOsvMen + sumZklSnizMen + sumZklZaklMen
ABRA Flexi XML Základem komunikace s ABRA Flexi je ABRA Flexi XML. Ta může být ve formátu XML nebo JSON. V obou případech je pak struktura shodná. Rozdíl je jen ve způsobu uložení atributů do JSON. Jsou pak uloženy jako záznam s zavináčem: @rowCount. Důležitou vlastností pro ABRA Flexi XML je inkrementální aktualizace, požadované atributy, identifikátory záznamů a typy proměnných. Velikosti písmen Velikosti písmen v názvech tagů a atributů jsou ignorovány a tak je možné používat libovolnou kombinaci. Používané atributy Přehled atributů, které daná evidence podporuje se podívejte buď do ukázkového XML (první záznam je vždy okomentovaný) nebo do dokumentace u konkrétní evidence. Všechny atributy mají vnitřní vazby a tak není nutné uvádět všechny atributy, protože ostatní se buď automaticky dopočtou, jsou převzaty z typu dokladu a nebo jsou určeny jinou vazbou (např. u faktury vybráním firmy dojde k vyplnění i IČ, adresy apod.). Typy proměnných Identifikátory záznamů Inkrementální aktualizace Povinnost atributů Vnitřní vazby při ukládání Režim pro založení/změnu Provádění akcí Datum poslední změny Výpočet Daně z přidané hodnoty (DPH) Práce s uživateli Předchozí hodnoty - způsob reakce na změnu Dávkové operace Transakční zpracování XML Schéma (XSD)
Odesílání dokladů e-mailem Přes REST API (i přes webové rozhraní) lze odeslat doklad e-mailem. Aby to fungovalo, je třeba nastavit připojení k SMTP serveru. Do souboru flexibee-server.xml (na Linuxu v /etc/flexibee/flexibee-server.xml) doplňte následující hodnoty: smtp.hostAdresa SMTP serveru, typicky localhost (SMTP server běží na stejném stroji jako ABRA Flexi Server) smtp.portPort SMTP serveru, typicky 25; nepovinné smtp.defaultFromVýchozí e-mailová adresa odesílatele smtp.encryptionRežim zabezpečení SMTP komunikace: nonebez zabezpečení (výchozí) starttlszabezpečená komunikace, pokud ji server podporuje (příkaz STARTTLS) tlsvyžadované přepnutí na zabezpečenou komunikaci (TLS) sslplně zabezpečená komunikace (SSL) smtp.auth.userPřihlašovací jméno, pokud SMTP server vyžaduje autentizaci; nepovinné smtp.auth.passwordHeslo; nepovinné Pozn.: pokud potřebujete nějaké další konfigurační hodnoty, např. pro SSL, dejte nám vědět. Odeslání dokladu přes REST API na správně nakonfigurovaném serveru pak znamená PUT (resp. POST) na URL /c/firma/faktura-vydana/1/odeslani-dokladu.xml s následujícími parametry: ?to=email@example.comAdresát; parametrů to lze uvést více ?cc=email@example.comKopie; parametrů cc lze uvést více ?subject=Doklad ABCPředmět e-mailu Musí být zadán alespoň jeden adresát nebo adresát na kopii, předmět je také povinný. Jako odesílatel (hlavička From) bude uveden aktuální uživatel, pod kterým odeslání provádíte, případně výchozí hodnota z konfigurace. V těle požadavku musí být tělo e-mailu v textové podobě kódované v UTF-8. E-mail bude odeslán v textové i HTML variantě podle šablony, která je momentálně součástí ABRA Flexi. Do budoucna plánujeme možnost uživatelských šablon. Jako součást e-mailu bude v příloze odeslána PDF a případně i ISDOC podoba dokladu. Kompletní příklad odeslání dokladu z příkazové řádky použitím nástroje curl: curl -k -L -u uzivatel:heslo -X PUT -d 'Dobrý den, zasíláme Vám slíbený dokument. S pozdravem ...' "https://localhost:5434/c/firma/faktura-vydana/1/odeslani-dokladu.xml?to=email@example.com&subject=Doklad%20ABC" Všimněte si zejm. předmětu – jako obvykle, parametry v URL musí být správně zakódovány. Poznámka: je nutné uvést buď odeslani-dokladu.xml nebo hlavičku Accept: text/xml. Přizpůsobování e-mailových zpráv V ABRA Flexi lze upravovat zasílané zprávy takto: Přizpůsobení textu – lze upravit v typu dokladu výchozí text, který bude použit pro zasílání dokladů. Přizpůsobení šablony Přizpůsobení šablony e-mailové zprávy Základem je zapnutí vývojářeského adresáře (developerDirectory). Kompletní popis je delší, ale nás zajímá pouze část s nastavením a následně úpravou šablony: Je potřeba upravit flexibee-server.xml (kde jej najít?) a přidat tam <entry key="developerDirectory">/devel/</entry> Místo /devel/ dejte adresář, kde budou data pro modifikaci (např. C:ProjektyFlexiBee). Restartovat ABRA Flexi V daném adresáři je potřeba vytvořit adresář "default" (tzv. výchozí instance - jiná hodnota má smysl pouze v cloudovém provozu) a v něm adresář s identifikátorem firmy (ten je stejný jako přes webové rozhraní). Případně je možné použít speciální identifikátor "!all" (bez uvozovek). Nakopírovat ukázkové skripty do $developerDirectory/$instance/!all a pro nás jsou důležité soubory z adresáře mail-templates. Automatické odeslání dokladů ABRA Flexi podporuje automatické odeslání všech neodeslaných dokladů, které jsou označené k odeslání. Odeslání lze vynutít příkazem: curl -H "Accept: application/xml" -u winstrom:winstrom -X PUT -L https://demo.flexibee.eu:5434/c/demo/faktura-vydana/automaticky-odeslat-neodeslane
Odpočet záloh Při vytváření dokladů (např. faktur) je potřeba umožnit odpočet jiným dokladem (např. zálohovou platbou). <winstrom version="1.0"> <faktura-vydana> <!-- Typ faktury (objekt) - max. délka: 20 --> <typDokl>code:FAKTURA</typDokl> <!-- Firma (objekt) - max. délka: 20 --> <firma>code:PBENDA</firma> <!-- Bezpol. dokl. (logická hodnota) - --> <bezPolozek>true</bezPolozek> <!-- Základ DPH zákl. [Kč] (destinné číslo) - počet číslic: 15 --> <sumZklZakl>1000.0</sumZklZakl> <odpocty> <odpocet> <castkaMen>1200.0</castkaMen> <!-- částka v měně určená pro odpočet --> <doklad>code:ZDD0001/2010</doklad> <!-- identifikátor dokladu pro odpočet --> </odpocet> </odpocty> </faktura-vydana> </winstrom> Pozor: nyní není možné udělat částečný odpočet zálohy. <castkaMen/> musí vždy odpovídat celé částce odpočítaného dokladu.
Changes API Changes API (sledování změn) Je-li zapnuté, ABRA Flexi zaznamenává všechny změny provedené v databázi firmy do changelogu a umožňuje seznam změn zpětně získat. Změny jsou vzestupně číslované, takže firma má v každém okamžiku dobře definovanou globální verzi. (Čísla verzí nemusí následovat těsně po sobě, v řadě mohou být z technických důvodů mezery. Vždy je však číslo verze unikátní a rostoucí.) Toho lze využít k automatizované synchronizaci externích systémů s ABRA Flexi a také jde o základ pro funkci okamžitého upozorňování na změny (Web Hooks). Licence ABRA Flexi musí mít aktivní REST API minimálně pro čtení. Zjištění stavu a zapnutí / vypnutí lze provést nejsnáze ve webovém rozhraní na adrese /c/{firma}/changes/control. Případně lze zapnout PUT requestem na adresu /c/{firma}/changes/enable.xml a vypnout taktéž PUT requestem na adresu /c/{firma}/changes/disable.xml. Kromě PUT lze použít také POST. Pokud nemáte aktivní REST API pro čtení nebo pro zápis, odpověď je 403 Forbidden. Ukázka aktivace pomocí programu curl: curl -k -L -u jmeno:heslo -X PUT https://localhost:5434/c/{firma}/changes/enable.xml -H Content-Length:0 Získání aktuální globální verze Do jakéhokoliv XML (resp. JSON) exportu získaného přes REST API lze doplnit aktuální globání verzi přidáním parametru ?add-global-version=true. Odpověď bude vypadat takto: <winstrom version="1.0" globalVersion="6"> ... </winstrom> Získání záznamů o změnách Na adrese /c/firma/changes.xml se nachází seznam všech změn od začátku jejich sledování. Výpis vypadá takto: <winstrom version="1.0" globalVersion="6"> <faktura-vydana in-version="3" operation="create" timestamp="2019-01-01 00:00:00.0"> <id>1</id> </faktura-vydana> <faktura-vydana-polozka in-version="4" operation="create" timestamp="2019-06-07 12:34:56.7"> <id>1</id> </faktura-vydana-polozka> <faktura-vydana in-version="5" operation="update" timestamp="2019-06-07 12:34:56.7"> <id>1</id> <id>code:VF1-0001/2012</id> </faktura-vydana> <next>6</next> </winstrom> Uvedeno je vždy číselné ID objektu (<id>1</id>) a kód (<id>code:KÓD</id>); pokud měl objekt v době provádění operace i nějaká externí ID, pak jsou uvedena i ta (<id>ext:...</id>). V atributech každého elementu je uvedeno, v jaké verzi k operaci došlo (in-version) a o jakou operaci šlo (operation; možné hodnoty jsou create, update a delete). Vždy je přítomen atribut globalVersion. Posledním elementem ve výpisu je vždy next, který udává číslo verze, kterou by tento výpis pokračoval, případně none, pokud žádné další změny nejsou. Výpis lze upravit následujícími parametry: ?start=123Od které verze se má vypisovat (včetně); defaultně od počátku sledování. ?limit=500Kolik záznamů se má vypsat; defaultně 100, maximálně 1000. ?evidence=faktura-vydanaPro které evidence se mají změny vypisovat; lze uvést vícekrát, není-li uvedeno, vypisují se všechny. Ve formátu JSON vypadají změny takto: { "winstrom": { "@globalVersion": "8", "changes": [ { "@evidence": "faktura-vydana", "@in-version": "3", "@operation": "create", "@timestamp": "2019-01-01 00:00:00.0", "id": "1", "external-ids": [] }, { "@evidence": "faktura-vydana-polozka", "@in-version": "4", "@operation": "create", "@timestamp": "2019-06-07 12:34:56.7", "id": "1", "external-ids": [] }, { "@evidence": "faktura-vydana", "@in-version": "5", "@operation": "update", "@timestamp": "2019-06-07 12:34:56.7", "id": "1", "external-ids": ["code:VF1-0001/2012"] } ], "next": "6" } } Zjištění stavu zapnutí Changes API Uživatelsky lze sjistit stav zapnutí na adrese /c/{firma}/changes/control. Zde je také možné Changes API zapínat nebo vypínat. Pokud potřebujete zjistit stav programově, tak použijte GET /c/firma/changes/status.xml. V případě odpovědi <winstrom><success>true</success></winstrom> je Changes API zapnuté. Pokud je odpovědí false nebo chyba (pokud není povolené REST API) je Changes API vypnuté. Synchronizace externích systémů s ABRA Flexi Verzované změny lze snadno využít k efektivní synchronizaci externích systémů s ABRA Flexi (na rozdíl od data poslední změny). Postup je následující: Počáteční nahrání dat: Získat aktuální data včetně jejich verze (?add-global-version=true) Uložit data Zapamatovat si verzi (z atributu globalVersion) Rozdílová synchronizace: Stáhnout změny od poslední zapamatované verze (?start=<verze>) Stáhnout změněná data a uložit je, případně smazat odstraněná data Zapamatovat si verzi (z elementu next, případně z atributu globalVersion) GOTO 1 ERROR: could not obtain lock on relation "????" Pokud se vám zobrazí chyba ERROR: could not obtain lock on relation "????", nezoufejte. Kvůli výkonnosti nejsou v databázi funkce, které obsluhují Changes API vůbec přidané. V případě aktivace Changes API je do systému zaneseme. Proto je potřeba exkluzivně zamknout celou databázi. Řešením tedy je se odhlásit z ABRA Flexi - jak z webového rozhraní tak klientské aplikace. Pak už to projde. Ukázka chyby: ERROR: could not obtain lock on relation "drady" Kde: SQL statement "LOCK TABLE drady IN ACCESS EXCLUSIVE MODE NOWAIT"
Práce s uživateli ABRA Flexi XML umožňuje i práci s uživateli v systému. Kromě obvyklé struktury, kterou získáte, když si uživatele vyexportujete, je třeba doplnit ještě heslo, a to do elementů password a passwordAgain (navrženo pro použití v uživatelském rozhraní, oba elementy jsou povinné a jejich hodnoty musí být totožné). XML pro založení uživatele tak může vypadat např. takto: <winstrom version="1.0"> <uzivatel> <id>code:einstein</id> <kod>einstein</kod> <!-- přihlašovací jméno --> <jmeno>Albert</jmeno> <prijmeni>Einstein</prijmeni> <password>E=mc2</password> <!-- heslo --> <passwordAgain>E=mc2</passwordAgain> <!-- heslo znovu --> <role>code:JENCIST</role> <!-- uživatelská role --> </uzivatel> </winstrom>
Podporované formáty REST API ABRA Flexi dokáže exportovat a importovat data v různých formátech. Typ výstupního formátu může být určen příponou (.xml, .json) nebo pomocí hlavičky v HTTP požadavku (Accept / Content-Type). Formát jako přípona je nepovinný a má přednost před HTTP hlavičkou. Pokud je uvedeno Accept: */* je vrácena HTML forma. ABRA Flexi podporuje tyto formáty: Název Poznámka Přípona Content-Type Import? HTML HTML stránka pro zobrazení informací na webové stránce. .html text/html ne XML Strojově čitelná struktura ve formátu XML. .xml application/xml ano JSON Strojově čitelná struktura ve formátu JSON. .js.json text/javascriptapplication/json ano CSV Tabulkový výstup do formátu CSV. .csv.csv?encoding=iso-8859-2 text/csv ano DBF Databázový výstup ve formátu DBF (dBase). .dbf.dbf?encoding=iso-8859-2 application/dbf ano XLS Tabulkový výstup ve formátu Excel. .xls application/ms-excel ano ISDOC Formát e-fakturace - ISDOC.Parametry importu: typDokl - Typ faktury (povinný), typUcOp - Předpis zaúčtování. Oba typu identifikátor. .isdoc.isdocx?typDokl=code:FAKTURA&typUcOp=code:NÁKUP%20SLUŽBY application/x-isdocapplication/x-isdocx ano EDI Elektronická výměna dat (EDI) ve formátu INHOUSE. .edi application/x-edi-inhouse ano PDF Generování tiskového reportu. Jedná se o stejnou funkci, která je dostupná v aplikaci. Export do PDF. .pdf.pdf?report-name=vydejka application/pdf ne vCard Výstup adresáře do formátu elektronické vizitky vCard. .vcf text/vcard ne iCalendar Výstup do kalendáře ve formátu iCalendar. Lze takto exportovat události, ale také třeba splatnosti u přijatých či vydaných faktur. .ical text/calendar ne
Generování faktur ze smluv Přes REST API (i přes webové rozhraní) lze vygenerovat faktury ze smluv (buďto všech nebo jedné konkrétní). Jde o jednoduché volání přes PUT nebo POST: /c/firma/smlouva/generovani-faktur.xmlVygeneruje faktury pro všechny smlouvy /c/firma/smlouva/1/generovani-faktur.xmlVygeneruje faktury pro smlouvu s ID 1 Při volání přes REST API má odpověď (ve formátu XML) následující podobu: <winstrom version="1.0"> <operation>Generování faktur</operation> <success>ok</success> <messages> <message>Počet úspěšně vygenerovaných faktur: 1</message> </messages> <errors> <error>...</error> </errors> </winstrom> Element success může nabývat hodnot ok, partial, failed a unknown: okVygenerování faktur proběhlo v pořádku (ale nemusely být vygenerovány žádné faktury, pokud to nebylo potřeba) partialPro některé smlouvy proběhlo vygenerování faktur v pořádku, ale u jiných smluv došlo k chybě failedNebyly vygenerovány žádné faktury, u některých smluv došlo k chybě unknownNemělo by nikdy nastat Elementy message obsahují hlášení o úspěchu (nejvýše jedno), elementy error chybová hlášení (jedno pro každou smlouvu, u které došlo k chybě).
Testovací uložení (dry-run) Když pracujete s REST API a potřebujete zkontrolovat, zda jsou všechna data v pořádku, pokud uživatel změnil nějakou hodnotu, která ovlivňuje jinou (např. typ dokladu a zaúčtování) a nebo potřebujete spočítat výslednou cenu při objednávce, můžete použít režim testovacího uložení. Při uložení přidejte parameter ?dry-run=true. Výsledkem bude, že se záznam neuloží, ale jen se provedou validace. Navíc získáte v tagu <content /> výslednou reprezentaci záznamu tak, jak by vypadal, kdyby jste jej nyní uložili. Ukázka výsledného XML: <?xml version="1.0" encoding="utf-8"?> <winstrom version="1.0"> <success>true</success> <warnings> <warning for="firma">Nebyl určen příjemce a tak nebude doklad zaúčtován.</warning> <warnings> <result> <content> <!-- Doklady faktur --> <faktura-vydana> <!-- ID (celé číslo) - --> <id>-1</id> <!-- Interní číslo (řetězec) - max. délka: 20 --> <kod>00000041/09</kod> <!-- Variabilní symbol (řetězec) - --> <varSym>0000004109</varSym> <!-- Vystaveno (datum) - --> <datVyst>2009-08-12+02:00</datVyst> ... </faktura-vydana> </content> </result> </winstrom> V tomto případě došlo i k přidělení čísla dokladu. Nicméně číslo bylo hned uvolněno k dalšímu použití a tak je možné, že při skutečném uložení získá dokument jiné číslo. Je zde také ukázka validačního upozornění. Výstup je možné zpracovávat také ve formátu JSON.
Výměna SSL certifikátu V aplikačním serveru se po instalaci vygeneruje tzv. self-signed certifikát neboli certifikát podepsaný sám sebou. Na tento certifikát upozorňuje prohlížeč. Je možné, jej vyměnit za vlastní certifikát. Certifikát musí splňovat několik požadavků: Musí být ve formátu PEM V souboru musí být jak veřejná část (certifikát) tak i soukromá část (klíč). Klíč musí být ve formátu PKCS#1 (začíná BEGIN RSA PRIVATE KEY). Pokud máte klíč ve formátu PKCS#8 (začíná BEGIN PRIVATE KEY), převeďte si klíč do formátu PKCS#1 příkazem openssl rsa -in klic.pem -out klic2.pem. V souboru musí být celý řetězec certifikátů (chain). Tj. i certifikát kořenové autority. Po nahrání je potřeba restartovat aplikační server. Nahrání proběhne na adresu https://server:5434/certificate?password=abc. Certifikát musí být buď bez hesla (pak lze vynechat parametr password) a nebo musí mít heslo uvedené v parametru. V databázi je pak certifikát uložen bez hesla. Pozor: v cloudu nelze měnit certifikát (i když příkaz uspěje). Časem nasadíme SNI, ale jeho podpora je stále problematická. Ukázka příkazu pro CURL: curl -X PUT -u jmeno:heslo -k -L -T domena.eu.pem https://localhost:5434/certificate Bezpečnostní nastavení
Validace dat Při ukládání dat je prováděna validace. Chyby mohou být tří typu: chyba: záznam kvůli této chybě nejde uložit a operace byla zrušena varování: při ukládání se objevil problém, ale záznam byl uložen. informace: doplňující informace pro uživatele. Záznam byl uložen. Ukázka chyby při ukládání: <winstrom version="1.0"> <success>true</success> <result> <id>105</id> <warnings> <warning for="radekDph">Záznam nemá vyplněn řádek DPH a proto nebude doklad zaúčtován.</warning> </warnings> <infos> <info>Došlo k automatickému výběru výrobního čísla.</info> </infos> </result> <result> <id>103</id> </result> </winstrom> Pokud aplikace narazí na chybu, je zpracování okamžitě ukončeno. U varování a informací je proveden kompletní import a následně jsou vráceny všechny chybové stavy. Pokud chcete, aby i v případě varování nedošlo k uložení dat, přidejte do URL parametr: "?fail-on-warning=true". Pokud chcete zvalidovat záznam a nechcete jej při tom ukládat (tzv. dry-run), přidejte do URL parametr "?dry-run=true". Povinnost atribitů
Podporované typy proměnných Typy proměnných jsou použivány při exportu a importu do XML či JSON a při filtraci. Strojový název Název Poznámka Ukázka string Řetězec Kódování je unicode. Lze tedy použít libovolný znak. šílený koníček こちらは田中さんです integer Celé číslo Musí být bez mezer. Jde o znaménkový 4bajtový integer, ovšem rozsah může být omezený (viz přehled položek dané evidence) 12 numeric Desetinné číslo Musí být bez mezer, oddělovačem desetinných míst je tečka. Jde o 8bajtový double, ovšem rozsah může být omezený (viz přehled položek dané evidence) 12.5 date Datum Datum ve formátu YYYY-MM-DD; lze zadat i časovou zónu (YYYY-MM-DDZZZ), ale ta bude ignorována. ZZZ je označení časové zóny (Z nebo +HH:MM nebo -HH:MM). Podporované formáty vycházejí z W3C specifikace. Pro filtraci je možné použít pouze zápis bez časové zóny. 1980‑05‑06 2015‑01‑30Z 2008‑09‑01+02:00 datetime Datum + čas Datum a čas ve formátu YYYY-MM-DD'T'HH:MM:SS.SSS; lze zadat i časovou zónu (YYYY-MM-DD'T'HH:MM:SS.SSSZZZ), ale ta bude ignorována. ZZZ je označení časové zóny (Z nebo +HH:MM nebo -HH:MM). Podporované formáty vycházejí z W3C specifikace. Pro filtraci je možné použít pouze zápis bez časové zóny. 1980‑05‑06 1980‑05‑06T12:30:12 2015‑01‑30T22:55:33Z 2008‑09‑01T17:18:14+02:00 2008‑09‑01T17:18:14.075+02:00 logic Logická hodnota boolean true false select Výběr jedné z hodnot Výběr jedné z hodnot. Je reprezentován jako řetězec. typVztahu.odberDodav relation Vazba mezi daty Vstupem je záznam z jiné evidence (přehled typů identifikátorů) 123 code:CZK
QR kód dokladu QR kód dokladu ABRA Flexi umí vygenerovat QR kód dle standardu schváleným Českou Bankovní Asociací a kterou podporují mobilní klienti mnoha bank. Tento kód lze snímnout i z obrazovky pomocí mobilního zařízení. Podporujeme QR kódy přijatých dokladů (pro vlastní platbu) tak i vydaných dokladů (platba klientem). URL pro získání QR kódu: /c/<identifikátor firmy>/<evidence>/<ID záznamu>/qrcode.png?size=200 Velikost určuje rozměr obrázku od 1 do 1500 pixelů. Systém se snaží vytvořit takový okraj obrázku, aby na něm byly možné ostré přechody bílé a černé.
Odpočet záloh a ZDD Při vytváření dokladů (např. faktur) je potřeba umožnit odpočet jiným dokladem (např. zálohovou platbou). Odpočet zálohy (vystavení daňového dokladu k platbě) <winstrom version="1.0"> <faktura-vydana> <id>code:ZDD-12/2014</id> <!-- Typ faktury (objekt) - max. délka: 20 --> <typDokl>code:ZDD</typDokl> <odpocty-zaloh> <odpocet> <!-- odpočet zálohy --> <castkaMen>1600.0</castkaMen> <!-- částka v měně určená pro odpočet --> <doklad>code:ZALOHA0001/2010</doklad> <!-- identifikátor dokladu pro odpočet --> <id>ext:odpocet1</id> <!-- externí identifikátor vytvořené odpočtové položky --> </odpocet> </odpocty-zaloh> </faktura-vydana> </winstrom> Odpočet ZDD <winstrom version="1.0"> <faktura-vydana> <id>code:VF-12/2014</id> <!-- Typ faktury (objekt) - max. délka: 20 --> <typDokl>code:FAKTURA</typDokl> <odpocty-zaloh> <odpocet> <!-- odpočet zdd --> <castkaZaklMen>400.0</castkaZaklMen> <!-- částka základní sazby v měně určená pro odpočet --> <castkaSnizMen>400.0</castkaSnizMen> <!-- částka snížené sazby v měně určená pro odpočet --> <castkaSniz2Men>400.0</castkaSniz2Men> <!-- částka 2. snížené sazby v měně určená pro odpočet --> <castkaOsvMen>400.0</castkaOsvMen> <!-- částka osvobozená od DPH v měně určená pro odpočet --> <doklad>code:ZDD0001/2010</doklad> <!-- identifikátor dokladu pro odpočet --> <id>ext:odpocet1</id> <!-- externí identifikátor vytvořených odpočtových položek --> <!-- identifikátor jednotlivých položek je doplněn o posfix -ZAKL, -SNIZ, -SNIZ2, -OSV --> </odpocet> </odpocty-zaloh> </faktura-vydana> </winstrom> Při vytváření dokladů je možné využít i automatický odpočet zálohových dokladů a zálohových daňových dokladů. <winstrom version="1.0"> <faktura-vydana> <!-- Typ faktury (objekt) - max. délka: 20 --> <typDokl>code:FAKTURA</typDokl> <odpocty-zaloh> <!-- automatický odpočet zálohy a zdd, které mají automatický odpočet povolen v typu dokladu --> <automaticky-odpocet>true</automaticky-odpocet> </odpocty-zaloh> </faktura-vydana> </winstrom> Zálohové faktury a ZDD musí mít v typu dokladu zaškrtnuto zaškrtávátko Povolit automatické odpočtení při vytvoření nového dokladu. Pokud v jednom XML importujete více faktur s automatickým odpočtem, použijte mód atomic="false". V případě, že importujete fakturu s nastaveným zaokrouhlováním, vytvořte nejdříve fakturu a až následně odpočítávejte zálohové doklady. <winstrom version="1.0"> <faktura-vydana atomic="false"> <!-- Vytvoření faktury se zaokrouhlením --> <id>ext:mojeId</id> <typDokl>code:FAKTURA</typDokl> </faktura-vydana> <faktura-vydana> <id>ext:mojeId</id> <odpocty-zaloh> <!-- automatický odpočet zálohy a zdd, které mají automatický odpočet povolen v typu dokladu --> <automaticky-odpocet>true</automaticky-odpocet> </odpocty-zaloh> </faktura-vydana> </winstrom>
Uživatelské vazby Uživatelské vazby umožňují provázat libovolný objekt s jiným. U každé vazby je nutné uvést typ vazby a provázané objekty. Vazby mohou být dvou druhů: ruční - provázané v aplikaci nebo importem automatické – objekty jsou automaticky zařazovány podle konfigurace typu vazby (filtrem) Výpis objektů ve vazbě: https://demo.flexibee.eu/c/demo/faktura-vydana/1/uzivatelske-vazby Je také možné udělat, aby navázaný objekt byl přímou součástí exportu vazeb: https://demo.flexibee.eu/c/demo/faktura-vydana/1/uzivatelske-vazby.xml?detail=full&includes=/winstrom/uzivatelska-vazba/object Pro výpis je také možné využít konfiguraci relací a exportovat je jako součást objektu: https://demo.flexibee.eu/c/demo/faktura-vydana/1.xml?relations=uzivatelske-vazby Ukázka importování ruční vazby: <?xml version="1.0" encoding="UTF-8"?> <winstrom version="1.0"> <adresar> <id>109</id> <uzivatelske-vazby> <uzivatelska-vazba> <id>ext:VAZBA:TESTEXTID-CEN</id> <evidenceType>cenik</evidenceType> <object>code:SKL</object> <popis>popisek skl</popis> <poznam>poznam skl</poznam> <vazbaTyp>code:ADRCEN</vazbaTyp> </uzivatelska-vazba> </uzivatelske-vazby> </adresar> </winstrom> Mazání vazby Ukázka mazání ruční vazby: <?xml version="1.0" encoding="UTF-8"?> <winstrom version="1.0"> <uzivatelska-vazba action="delete"> <id>ext:VAZBA:TESTEXTID-CEN</id> </uzivatelska-vazba> </winstrom>
Transakční zpracování Tato stránka popisuje pokročilou variantu XML importu, která při nevhodném použití může vést k nekonsistenci dat! Ve výchozím nastavení se každý import provádí jako jedna databázová transakce – tedy buď se uloží všechno nebo nic. To je obvykle požadované chování a většinou není důvod na něm něco měnit. Může ovšem nastat situace, kdy transakční chování není nutné, pak lze atributem atomic toto chování změnit. <winstrom version="1.0" atomic="false"> <faktura-vydana> <id>code:123</id> ... <polozkyFaktury> <faktura-vydana-polozka>...</faktura-vydana-polozka> <faktura-vydana-polozka>...</faktura-vydana-polozka> <faktura-vydana-polozka>...</faktura-vydana-polozka> </polozkyFaktury> </faktura-vydana> <faktura-vydana> <id>code:456</id> ... <polozkyFaktury> <faktura-vydana-polozka>...</faktura-vydana-polozka> <faktura-vydana-polozka>...</faktura-vydana-polozka> <faktura-vydana-polozka>...</faktura-vydana-polozka> </polozkyFaktury> </faktura-vydana> </winstrom> Pokud nastavíte atribut atomic na hodnotu false, importuje se každý záznam v samostatné transakci. Tedy v příkladu výše proběhnou dvě databázové transakce, jedna pro fakturu 123, druhá pro fakturu 456. Položky jsou součástí faktury a tedy se importují ve stejné transakci, jako faktura samotná. Jaký to přináší užitek? Když importujete velká XML s mnoha záznamy, transakce trvá dlouho a mnoho informací se musí držet v paměti. Obojí má nepříznivý vliv na výkon. Pokud je ale každý záznam samostatný a nevadí, že uložení některého z nich selže (např. když import pravidelně opakujete a/nebo dokážete v případě problémů zasáhnout ručně), můžete podstatně snížit paměťovou náročnost importu. V případě opravdu velkých importů jsou paměťové nároky pro uchování ještě neuložených dat tak velké, že podstatnou část procesorového času začne zabírat garbage collector (to lze sledovat např. nástrojem jconsole, který je standardní součástí vývojového prostředí JDK). V módu atomic="false" se v takovém případě může razantně snížit i náročnost časová.
XPath Pro zjednoduššení práce z příkazové řádky či jiných systémů, je možné na výstupní XML aplikovat výraz XPath. Lze tak snadno získat jen podmnožinu výstupních dat. XPath výraz lze použít pouze v kombinaci s XML a je aplikován až na vytvořenou XML strukturu. Je tedy nejdříve aplikován filtr, stránkování a úroveň detailu a pak až je aplikován výraz XPath. Ukázky: /c/demo/adresar.xml?detail=full&xpath=//winstrom/adresar/email/text() Základy jazyka XPath...
Datum poslední změny Každý záznam v ABRA Flexi obsahuje atribut datum poslední změny (lastUpdate). Ten umožňuje detekovat, že byl záznam v ABRA Flexi modifikován. Tato hodnota je také používána u rozhraní ABRA Flexi Sync k rozpoznání změn. Tento atribut lze používat i při filtraci. Pozor: ke sledování změn je lepší použít samostatnou funkci, kterou ABRA Flexi nabízí.
Stránkování Kvůli zvýšení výkonu webových aplikací se běžně používá systém "stránkování". Seznam je rozdělen na stránky, které jsou uživateli zobrazeny a on mezi nimi může přepínat. Stránkování se řídí parametry URL: Parameter Název Ukázka limit Maximální počet záznamů na jedné stránce. Implicitně je 20. Hodnota 0 vrací všechny záznamy bez omezení. /c/firma/adresar?limit=10 start Kolik záznamů přeskočit. Není závislé na parametru limit. /c/firma/adresar?limit=10&start=4 add-row-count=true Pokud uvedete tento parameter, bude do XML/JSON exportu přidán počet záznamů v dané evidenci (zohledňuje aplikované filtry). /c/firma/adresar.xml?add-row-count=true
Kurzy na dokladech Pokud při importu dokladu v cizí měně neuvedete kurz, ABRA Flexi si jej automaticky stáhne (např. z ČNB nebo ECB). Nicméně se může stát, že se kurz bude lišit o malé částky (setiny/tisíciny) proti oficiálnímu kurzu. To je záměrné chování. Částka v cizí měně, částka v domácí měně a kurz musí být vždycky "v rovnováze" (vynásobením či vydělením dvou z nich musíte dostat to třetí). Problém je, že částky se zaokrouhlují na dvě desetinná místa, takže vzniká určitá nepřesnost. Řekněme, že mám částku 1.4 EUR a kurz 25.265. Vynásobením dostaneme 35.371 CZK a po zaokrouhlení tedy 35.37. Jenže 35.37 / 25.265 už není 1.4, ale 1.39996041955. My se zachováme tak, aby částky vždy seděly, a upravíme ("obětujeme") proto kurz, který zaokrouhlujeme až na šest desetinných míst (a umíme ho tedy uložit "přesněji"). V tomto případě ho přepočteme na 35.37 / 1.4 = 25.264286. Vzhledem k tomu, že pokaždé je nepřesnost jiná, vyjde taky vždycky trochu jiný kurz (např. při částce 5.95 EUR je částka v tuzemské měně po zaokrouhlení 150.33, a kurz tak, aby částky navzájem seděly, vyjde 25.265546). Obvykle jde o malé rozdíly, kde by zaokrouhlení částek zase všechno srovnalo, ale už jsme se setkali i s případem, kdy byl rozdíl 1 Kč (např. částka v cizí měně byla 2599.0 a kurz 0.0038), což je nepřípustné. Proto to děláme. Možná bychom mohli být chytřejší a dělat to jen, když je to opravdu nutné, ale zatím to je tak, jak to je.
Referenční příručka REST API Využívání API nad instancí v Cloudu musí být v souladu s licenčními podmínkami. Dokumentace Autentizace Způsob tvorby URL Podporované formáty Export do PDF Přístupová práva Obsluha chyb Výkonnostní optimalizace Podporované HTTP operace Validace při modifikaci záznamů Testovací uložení (dry-run) Výpis záznamů Výpis záznamů Úrovně detailu Stránkování Řazení záznamů Filtrování záznamů Sumace záznamů Přílohy Práce s firmami Založení společnosti Obnovení společnosti ze zálohy Identifikátor společnosti Podpora ABRA Flexi XML ABRA Flexi XML je technologie sloužící pro výměnu dat s ekonomickým systémem. Typy proměnných Identifikátory záznamů Režim individuálních kódů ceníkových položek Inkrementální aktualizace Povinnost atributů Vnitřní vazby při ukládání Režim pro založení/změnu Provádění akcí Datum poslední změny Výpočet Daně z přidané hodnoty (DPH) Práce s uživateli Předchozí hodnoty – způsob reakce na změnu Dávkové operace Transakční zpracování Workflow a procesy XML Schéma (XSD) Kurzy na dokladech QR kódy pro úhrady dokladů Práce se štítky Pokročilé příkazy Párování bankovních plateb Hotovostní úhrada faktur Úhrada faktury z přeplatků v pokladně a bance Úhrada faktury vzájemným zápočtem závazků Odpočet záloh Načítání bankovních výpisů Vzájemné zápočty Vazby ZDD Příkaz k úhradě Příkaz k inkasu Odesílání dokladů e-mailem Individuální ceník Generování faktur ze smluv Uživatelské dotazy Objednávka z uloženého dotazu Changes API (Sledování změn) Web Hooks Stav skladu k datu Aktualizace požadavků na výdej Analýzy nákupu / prodeje Tvorba nabídky/objednávky z poptávky/nabídky Realizace objednávky Atributy ceníku Uživatelské vazby Zamykání a odemykání záznamů Dobropisy Stavy účtů Vytvoření a zrušení účelu GDPR Import EET certifikátů Zaúčtování prodejek Přizpůsobení aplikace Uživatelské tlačítko Uživatelské mailové šablony Podpora pro konkrétní systémy Podpora pro Ruby On Rails ABRA Flexi embeddable Technologie, která umožňuje vložení ABRA Flexi serveru do cizí aplikace pomocí HTML rozhraní. Externí autorizace Autentizace kontaktu Batch API - serverová administrace Odhlašování uživatelů Automatické startování jádra Vyměna SSL certifikátu Bezpečnost
Přístupová práva Webové rozhraní automaticky zpracovává přístupová práva. V seznamu položek, v XML exportech a na webové stránce se zobrazují jen záznamy a sloupečky, ke kterým má přistupující uživatel právo. Při importech je možné modifikovat jen taková položky, ke kterým má uživatel práva. Práva mohou být omezena takto: uživatel nemůže vůbec přistupovat do dané evidence a nebo ji má jen pro čtení uživatel vidí jen některé záznamy (např. z mého střediska) a nebo jen některé záznamy může měnit uživatel vidí jen některé sloupečky (např. nevidí nákupní ceny) a jen některé sloupečky mohu editovat licence aplikace neumožňuje používat danou položku V seznamu položek uživatel vidí vždy jen položky, ke kterým má práva včetně informace o tom, zda je smí měnit. Je také možné, že obecně smí danou položku měnit, ale konkrétní řádek ne (např. je zamčený). Pokud jsou omezeny řádky, které vidí, vypadá to jako by data v aplikaci vůbec nebyly. Pokud uživatel modifikuje i položky na které nemá právo, je tento fakt ignorován a jsou změněny jen položky, které měnit smí. Pokud by chtěl modifikovat i celé záznamy a nemá na to právo, je vyvolána chyba a celá operace je zamítnuta.
Úhrada faktury vzájemným zápočtem závazků ABRA Flexi umožňuje uhradit fakturu vzájemným zápočtem závazků. Pro danou firmu se zkouší k úhradě použít všechny dostupné závazky, jejichž typ má povoleno použití pro automatizovaný vzájemný zápočet. Fakturu lze takto uhradit i pouze částečně. K tomu slouží akce uhrad-zapoctem: <winstrom version="1.0"> <faktura-vydana id="100" action="uhrad-zapoctem" /> </winstrom> Akci lze vyvolat i dávkově nad skupinou dokladů pomocí filtru: <winstrom version="1.0"> <faktura-vydana filter="not stavUhrK begins 'stavUhr.uhrazeno' and typDokl = 'code:INTERNET'" action="uhrad-preplatky" /> </winstrom>
Podporované HTTP Operace Přečtení záznamu Data lze přečíst pomocí metody GET. Je zohledňován výstupní formát. Mazání záznamu Mazat lze pouze jednotlivé záznamy a to pomocí jejich detailového URL (tj. obsahují identifikátor). Více záznamů současně lze smazat pouze použitím akcí při běžné aktualizaci (viz níže). Pokud záznam neexistuje, je vrácen kód 404. Pokud se záznam podařilo smazat, je vrácen kód 200. Vytvoření/aktualizace záznamu ABRA Flexi nerozlišuje operace POST a PUT. Význam tedy vždy závisí na cílové adrese (URL) a na obsahu, který je zaslán. Pokud ukládáme záznamy na adresu výpisu evidence, jsou záznamy buď přidány nebo aktualizovány podle toho, zda byl nalezen identifikátor. Pokud provedu operaci na detail záznamu, nemusí zpráva obsahovat již žádný identifikátor a je vzat identifikátor z URL. Záznam, který modifikuji pomocí detailového URL, musí vždy existovat. Pomocí výpisového URL mohu modifikovat současně více záznamů. Pokud mají záznamy uvedený identifikátor přidělovaný ABRA Flexi, musí existovat. Pokud obsahují jako identifikaci např. externí ID, budou záznamy, které nejsou v ABRA Flexi dostupné, vytvořeny. Poznámka: v případě metody POST se očekávají data ve formátu XML nebo JSON a nikoliv jako formulářová data (multipart/form-data). Volba formátu při vytváření záznamu Formát, v jakém jsou očekávána data a v jakém je odpověď, jsou vždy shodné a nelze je kombinovat. Vstupní formát je určen buď podle hlavičky Content-Type nebo podle přípony v URL. Identifikátor nového záznamu Identifikátor vytvořeného dokladu je předán několika způsoby (více viz podporované HTTP operace): HTTP Hlavičkou Location: https://demo.flexibee.eu:5434/c/demo/faktura-vydana/105 Součást odpovědi ve formátu ABRA Flexi XML: <winstrom version="1.0"> <success>true</success> <result> <id>105</id> </result> </winstrom>
