WinStrom 10 a REST API

Dnešní ekonomické softwary již neřeší jen samotné účetnictví, ale také mnoho dalších navazujících úkolů. Samotné účetnictví je tak již jen zlomkem celkové funkčnosti. A co neřeší ekonomický systém, to řeší navazující systémy (jako např. CRM, výrobní, plánovací systémy, …). A právě s nimi chceme WinStrom 10 co nejlépe integrovat.

Dnes je samozřejmostí import a export dat, nicméně je to řešením jen části problému. Import a export se obvykle provádí ručně. Některé ekonomické systémy umožňují i jeho strojové zpracování. Nicméně pokud něco naimportujete do účetního systému, je těžké již s daty dále pracovat. Příkladem může být vytvoření objednávky a tvorba navazující výdejky ze skladu a faktury. U většiny systémů se informace o této vazbě se ztratí. Znemožňuje to pak následné analýzy a statistiky v účetnictví.

Z těchto důvodů je nutné neprovádět jen import a export, ale přímo manipulovat s daty v ekonomickém systému.

Proto jednou z funkcí, které chceme přidat je i REST API. Jedná se o jednoduchý protokol postavený na HTTP, pomocí kterého mohou mezi sebou snadno komunikovat různé systémy. Dnes snad neexistuje programovací jazyk nebo platforma, která by tento protokol nepodporoval.

Tento článek je tedy určen pro vývojáře a ukazuje, jak by takové rozhraní mohlo vypadat. Berte jej, prosím, hlavně jako návrh rozhraní a představení možností.

Účetnictví obsahuje mnoho evidencí. Vše si budeme ukazovat na faktuře (vydané) a v jazyce PHP. Když máme fakturu založenou, můžeme se na ní podívat pomocí jednoduchého HTTP požadavek.

  // požádej o vydanou fakturu číslo 1000 ve formátu JSON
  $faktura = http_get("https://winstrom:5434/api/faktura-vydana/1000.json");
  $faktura = json_decode($faktura); // Načtení z JSON formátu do paměťových struktur PHP
  print($faktura["faktura"]["cena"]); // vytištění ceny faktury

Místo JSON je také možné použít XML pro získání stejné struktury v XML. Samozřejmě je možné stejnou informaci získat i velmi snadno pomocí JavaScriptu v HTML stránce. Výhodou zjištění údajů pomocí JavaScriptu je, že není nutné výrazně upravovat existující systém (např. CRM), abyste zjistili, zda nemá odběratel fakturu po splatnosti. Je také možné použít autorizaci do WinStromu z uživatelovo prohlížeče. Je tedy možné použít tzv. MashUp systém, který se dnes používá u internetových aplikací např. od Google.

Co by tedy takové rozhraní mělo umět?

Dotazování

Snadný způsob, který vám umožní pracovat s více fakturami – stránkování, hledání dle podmínek (po splatnosti, odběratel, …). Rádi bychom implementovali všechny možnosti, které dnes nabízí filtrace v aplikaci.

S tím souvisí i agregační funkce – někdy chcete vědět jen počet faktur nebo výslednou částku. Budete tedy moci snadno postavit dotaz, který zjistí kolik vám odběratel dluží, nebo za jakou částku odebral za poslední rok a čtvrtletí.

Externí ID

Účetnictví je potřeba napojovat na různé systémy. Každý takový systém má identifikaci záznamů. A s touto identifikaci by uměl WinStrom pracovat – při zakládání záznamu si prostě přidáte i externí ID. To pak budete moci použít při čtení dat z WinStromu. Příkladem může být: ext:SHOP:100 – určuje objednávku 100 ze systému  názvem SHOP. Ke každému záznamu bude možné uvést více identifikátorů. Takto můžete vytvořit číslo zákazníka navázané na různé systémy.

Externí ID je samozřejmě nepovinné. Součástí odpovědí při založení záznamu bude i ID, které přidělí WinStrom. Výhodou externího ID je, že si nemusíte pamatovat mapování mezi ID externího systému a WinStromem – to za vás bude řešit WinStrom.

Různé formáty dat

Už jsem zmiňoval, že by aplikace měla umožnit pracovat s daty v různých formátech – WinStrom XML, WinStrom JSON, ale např. i standardizované XML pro faktury.

Omezení výstupu

U faktury může být evidováno velké množství informací. Jejich načtení při každém čtení faktury by zpomalovalo systém. Proto některé informace budou zasílány až na požádání.

Takovými daty jsou přiložené soubory, vazby na jiné doklady (objednávka, výdejka ze skladu a odpovídající faktura), položky faktury (někdy chcete jen součet), apod.

Chtěli bychom umožnit také evidenci vlastních údajů ke každému záznamu. Tyto údaje mohou být buď základní a editovatelné ve WinStromu a nebo složitější (složené) a přístupné jen pro externí systémy.

Export do PDF

Jedním z formátů do kterého budete moci exportovat je i PDF. Budete tak moci snadno vytvořit fakturu a následně k ní získat i PDF formu a třeba ji uživateli zaslat automaticky e-mailem.

Typy dokladů

WinStrom podporuje typy dokladů – šablony dokladu. Vytvoříte si typ dokladu (základní jsou již předpřipravené), nastavíte všechny potřebné položky (zaúčtování, středisko, zakázka, …) a při zakládání dokladu jej zvolíte a vše se předvyplní. Šablona umožňuje nastavit téměř všechny části dokladu (kromě ceny a položek) a je možné podle ní i filtrovat. Výhodou pak je, že s WinStromem mohou pracovat i lidé, kteří nejsou účetní. Mají připravené případy použití (zálohová faktura, zahraniční faktura, …), které pak mohou snadno použít.

A přesně této funkce bychom chtěli využít i u našeho rozhraní. Z externí aplikace provedete vytvoření faktury za „poskytování internetu“ a všechny položky se správně doplní. Když pak později dojde k zákonné změně, účetní prostě jen přenastaví šablonu a systém dál správně pracuje. Podle typu dokladu lze i filtrovat a můžete tak i později snadno provádět dávkové změny nad těmito daty. Samozřejmě hodnoty z šablony jsou jen výchozí a je možné je u každého dokladu explicitně uvést.

Ukázka

Ukažme si, jak by taková práce se systémem mohla vypadat:

// vytvoření PHP objektů, které popisují fakturu
$faktura = array("faktura" => array( // Struktura obsahuje kořenový prvek <faktura />
               "type" => "FAKTURA_VYDANA",  // typ dokladu (Šablona)
               "externId" => "ext:SHOP:1000", // ID přidělené externím systémem
               "customer" => "ext:SHOP:273", // ID zákazníka u externího systému
               "nazev" => "Faktura za služby", 
               "cena" => "2000" )); // cena faktury 
  
// převedení na formát JSON pro snažší komunikaci se serverem.
// je také možné použít XML
$data = json_decode($faktura);

/* založení faktury, vrací FALSE při chybě */
if (http_put_data  ( "https://winstrom:5434/api/faktura.json", $data) === FALSE) {
   die("Chyba při zakládání faktury");
}

/* přečtení faktury ve formátu PDF (tisk) */
$pdf = http_get("https://winstrom:5434/api/faktura/ext:SHOP:1000/pdf/ZAKLADNI/");
/* zobrazíme jej uživateli v prohlížeči */
header("Content-Type: application/pdf");
print($pdf);

Všimněte si množství položek je nutné, které je nutné uvést. Vše ostatní je převzato z typu dokladu (šablony).

Součástí Vašeho CRM by mohl být takovýto JavaScriptový kód (ukázka používá AJAX a JavaScriptovou knihovnu JQuery):

<script type="text/javascript">
$(document).ready(function(){ // po zobrazení stránky proveď ...
    $.getJSON("/api/faktura.json$count?po_splatnosti=true&customerId=ext:SHOP:273",
        function(data){ // po dokončení AJAXového požadavku je zavolána tato funkce.
          // pokud nic nedluží, zapiš do DIV s ID  'info' text OK nebo DLUŽÍ
          if (data == 0) {
              $('#info').replaceWith("OK");
          } else { 
              $('#info').replaceWith("DLUŽÍ");
          }
        });
  });
</script>

Výhodou této ukázky je, že stačí jen upravit statický HTML kód a nemusíte tak zasahovat do vašeho CRM systému.

Webové aplikace postavené na WinStromu

Jak vidíte, pracovat s WinStromem je velmi snadné. Chtěli bychom proto podporovat tvorbu aplikací, které budou jako backend používat právě WinStrom.

Bude dokonce možné napsat aplikaci, která bude používat jen WinStrom a nebude mít vlastní databázi. Aplikace prostě umožní modifikaci dat přímo ve WinStromu. Chtěli bychom vytvořit jednoduchý ukázkový objednávkový systém, který umožní registraci uživatele, vytvoření objednávky a zobrazení jejího stavu realizace. Budete moci tuto aplikaci vzít a vytvořit nad ní jednoduchý internetový obchod. Tuto ukázkovou aplikaci chceme uvolnit jako OpenSource.

Stejným způsobem upravíme i naši webovou aplikaci pro objednávky WinStromu.

Bezpečnost

Přístup k rozhraní bude samozřejmě autorizovaný jménem a heslem uživatele a bude možné omezit jej přístupovými právy (např. jen pro čtení). Bude také možné omezit jeho funkčnost jen na některé IP adresy a případně jej i zcela vypnout.

Co zbývá k řešení

Existují samozřejmě další věci, které by bylo dobré implementovat, nicméně je nemáme v krátkodobém plánu. Příkladem je možnost napojení vašeho systému na WinStrom tak, že při nějaké události (např. zaplacení faktury), budete o této události informováni.

Kdy to bude?

Aktuálně sbíráme požadavky od zákazníků a implementujeme prototypy. Nicméně zde navržené rozhraní by mělo být součástí produktu již za tři měsíce. Verze WinStromu 10.4, která vyjde v únoru již v tomto směru udělá velký krok.

Pokud vás tyto novinky zaujaly nebo máte nějaké připomínky či nápady, neváhejte nám napsat.