Všechny sbírky
Výukové články
API Ninja
API Ninja: Trénink 6/7 - Uživatelské tlačítko a API
API Ninja: Trénink 6/7 - Uživatelské tlačítko a API

Poslední z tréninků API Ninji - implementace uživatelského tlačítka

Ota Rádl avatar
Autor: Ota Rádl
Aktualizováno před více než týdnem

Získané schopnosti:

  • znalost uživatelského tlačítka

  • implementace získaných znalostí přímo do ABRA Flexi

V předchozích trénincích jsme se naučili základy REST API, řadu obratných chvatů, jak data získat, jak data do ABRA Flexi zaslat. Vždy jsme museli použít externí nástroje, cURL nebo aplikaci Postman, nebo požadavky na získání dat kopírovat přímo do internetového prohlížeče.

V tomto závěrečném tréninku si ukážeme, jak je možné všechny tyto chvaty implementovat přímo do ABRA Flexi, zobrazit si funkci v aplikaci a dovolit tak uživateli pohodlně akci spustit jako každou jinou přímo z aplikace.

Pokud tedy ke své práci využíváte různé systémy nebo webové portály, díky uživatelským tlačítkům k nim získáte přímý přístup rovnou z ABRA Flexi. Na základní učňovské úrovni si ukážeme jeho zavedení do aplikace a jednoduchý příklad s proklikem tlačítka na externí aplikaci, například na portál MFČR. Na úrovni válečník si ukážeme implementaci tlačítka na některý z poznaných chvatů v REST API. API Ninja se seznámí s příkladem, jak napojit uživatelské tlačítko na vlastní PHP skript. Finální trénink je zde, připravte se, dáme se do toho!

Úroveň: Učeň

Nejprve k definici tlačítka. Tlačítko vychází z dokumentace jako XML Flexi, které již známe. XML můžeme do aplikace nahrát pomocí menu Nástroje > Import > Import XML, nicméně student API jistě zvládne poslat jako požadavek pomocí API a metody POST:


​https://developer.flexibee.eu/c/ninja/custom-buttom.xml

<?xml version="1.0"?>
<winstrom version="1.0">
  <custom-button>
    <id>code:MFCR-ARES</id>
    <url><![CDATA[
https://wwwinfo.mfcr.cz/cgi-bin/ares/darv_res.cgi?ico=${object.ic}&jazyk=cz&xml=1]]>
    </url>
    <title>Kontrola IČ</title>
    <description>Validace IČ z faktury vydané na ARES</description>
    <evidence>faktura-vydana</evidence>
    <location>detail</location>
    <browser>desktop</browser>
  </custom-button>
</winstrom>

Výborně! Po importu definice tlačítka je nutný restart aplikace a máme první tlačítko připraveno.

Evidence uživatelských tlačítek se jmenuje custom-buttom, nyní si popíšeme strukturu těla požadavku:

  • ID již známe, identifikátor, při vytváření uživatelského tlačítka musí být prvek uveden s kódem (zkratkou).

  • URL, je stežejní, 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 (jako náš příklad https://wwwinfo.mfcr.cz/)

    • 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é.

    • Důležitou součástí jsou hodnoty z aplikace předávané v proměnné. V našem příkladu využíváme IČ z faktury vydané. Proměnné jsou vyhodnoceny FreeMarkerem při běhu aplikace a zajistí předání hodnot z aplikace. Řetězec object je v názvu proměnných povinný, pomocí něj je odkazováno na aktuální záznam vybrané evidence.

Kde jsme zjistili podobu URL na MFČR?

URL https://wwwinfo.mfcr.cz/cgi-bin/ares/darv_res.cgi?ico=63469588&jazyk=cz&xml=1 jsme získali přímo z internetového prohlížeče . Stačí na webu MFČR vyhledat libovolné IČ, poté přistoupit do ARES a již se nám adresa zobrazí v adresním řádku prohlížeče.

Z adresy je patrné, že stránka MFČR předává vybrané IČ jako parametr v adrese, stačí tedy nahradit naším ${object.ic} z aplikace a máme hotovo. Zpět k dalším polím definice:

  • title a description popisují tlačítko, zobrazí se i uživateli v aplikaci, title je název, description je popis při najetí myší na tlačítko

  • evidence je také velmi důležitý údaj, uvádí, kde bude tlačítko použito a zobrazeno, obsahem je tedy kód evidence dle evidence listu.

  • location, nám říká zda bude tlačítko zobrazeno v editačním okně záznamu - detail, nebo bude zobrazeno v přehledu záznamů evidence - list

  • browser obsahuje informaci, zda se po stisku tlačítka URL otevře v interním browseru ABRA Flexi - automatic, nebo v externím prohlížeči ve PC - desktop

    • aktuálně se plánuje tvorba nového interní prohlížeč, doporučujeme tedy vždy použít volbu desktop

Dobře - object je faktura-vydana a kde jsme zjistili, že můžeme použít IČ, účedníku?

Bystrý učedník si všiml, že jsme použili proměnnou ${object.ic} a jistě tuší i další možnosti. Jak bylo uvedeno, pomocí řetězce object máme přístup ke všem polím evidence, ale to nemůže být vše, že? Existují ještě další proměnné, které lze při volání použít:

  • objectIds – seznam ID vybraných záznamů oddělených čárkou. Znamená to, že pokud v aplikaci zaklikáte záznamy zaškrtávacími okýnky, budou předána všechna ID. Důležité upozornění, proměnné object a objectIds se vzájemně vylučují!

  • user – lze předat i Jméno a příjmení aktuálně přihlášeného uživatele

  • url – můžeme si předat i URL, odkud bylo tlačítko stisknuto, tedy například pro nás https://developer.flexibee.eu/c/ninja/faktura-vydana/{ID faktury}.

  • companyUrl – adresa API rozhraní firmy, ve které je tlačítko umístěno, tedy pro nás https://developer.flexibee.eu/c/ninja.

  • evidence – jméno evidence, na které je tlačítko umístěno (faktura-vydana).

  • authSessionId – autentizační token k aktuálnímu sezení uživatele. Po dobu platnosti sezení lze využít k autentizace dotazů. S autentizačním tokenem jsme se seznámili ve 3. tréninku v Ninja úrovni.

  • customerNo – číslo zákazníka odpovídající licenci.

  • licenseId – identifikátor licence.

Učedníku, nyní víš jak použít uživatelské tlačítko. Jistě vymyslíš další příklady použití, například zavolat chvaty z předchozích tréninků nebo tvé vlastní externí weby? Hurá do toho, možností je neomezeně!

Úroveň: Válečník

Na učňovské úrovni jsme se naučili definici tlačítka, jeho zavedení do aplikace a příklad jak zavolat externí web. Nyní si ukážeme, jak nadefinovat některou ze složitějších služeb REST API pomocí uživatelského tlačítka. Obecně bez vlastního skriptu můžeme používat pouze služby a výstupy, které se posílají metodou GET, jelikož tlačítkem nevyvoláme POST požadavek. Jaké další tlačítko do aplikace přidat bez programování skriptu, když už služby a tlačítka v aplikaci jsou?

Nejprve si ukážeme jak na jedno kliknutí získat PDF faktury. Tlačítko si umístíme do evidence vydané faktury na přehled záznamů:

<?xml version="1.0"?>
 <winstrom version="1.0">
  <custom-button>
    <id>code:FAV-PDF</id>
    <url><![CDATA[${url}.pdf?report-name=NINJAFAV&report-sign=true]]>
    </url>
    <title>PDF</title>
    <description>Stáhnout PDF faktury<description>
    <evidence>faktura-vydana</evidence>
    <location>list</location>
    <browser>desktop</browser>
  </custom-button>
</winstrom>

Když si projdeme definici, všimneme si, že v poli <url> jsme použili přímo proměnnou ${url}. Tento chvat nám umožní importovat do jakéhokoliv ABRA Flexi a vždy přebere správnou adresu, odkud doklad stáhnout. Dále jsme zapsaly kód uživatelské tiskové sestavy NINJAFAV (musí existovat) a chceme tiskopis podepsaný certifikátem (musí existovat). Na jedno kliknutí tak můžeme zobrazovat PDF faktur v prohlížeči.

Pojďme na hned na další šikovné tlačítko. Přímo z aplikace si můžeme zobrazit aktuálně pracující přihlášené uživatele. Definice tlačítka vypadá následovně:

<?xml version="1.0"?>
  <winstrom version="1.0">
    <custom-button>
      <id>code:SESSIONS</id>
      <url>
      <![CDATA[https://developer.flexibee.eu/status/session]]>
      </url>
      <title>Přihlášení uživatelé</title>
      <description>Seznam přihlášených uživatelů </description>
      <evidence>uzivatel</evidence>
      <location>list</location>
      <browser>desktop</browser>
    </custom-button>
</winstrom>

Informace o přihlášených uživatelých se nechází na stránce /status/session. Tlačítko můžeme opět přidat na libovolné místo, nyní volíme evidenci uzivatel - Osoby a uživatelé.

Válečníku, přijdeš na to, proč jsme v url nepoužili proměnnou companyUrl? Nápověda: lze vidět z URL vs. obsah proměnné.

Poslední šikovné tlačítko kombinuje naše znalosti filtrace dat a možnosti tlačítka. Uvažujme, že denně potřebujeme exportovat do XML faktury, které mají datum splatnosti dnes a nejsou uhrazené. Využijeme tedy filtraci, detail a tlačítko:

<?xml version="1.0"?>
  <winstrom version="1.0">
    <custom-button>
      <id>code:NEUHRAZENEFAV</id>
      <url>
        <![CDATA[${companyUrl}${evidence}
           /(datSplat=now()%20and%20stavUhrK<>'stavUhr.uhrazeno').xml?    
           detail=custom:kod,sumCelkem,varSym&limit=0]]>
     </url>
     <title>FAV bez uhrady</title>
     <description>
       Faktury vydané se splatnostní dnes a bez úhrady
     </description>
     <evidence>faktura-vydana</evidence>
     <location>list</location>
     <browser>desktop</browser>
  </custom-button>
</winstrom>

Zápis definice tlačítka už je nám známý. Zajímavá je v tomto příkladu URL. Pro ukázku používáme proměnné companyUrl i evidence. Tlačítko je tedy možné použít i v jiných evidencích a firmách. Dále již zápis také známe, filtrace dokladů s datem splatnosti dnes a stav úhrady není uhrazeno. Poslední parametry říkají vlastní detail XML a nesmíme zapomenout nastavit limit=0, abychom získaly v XML všechny faktury.

Válečníku, nyní znáš spoustu možností, jak uživatelům aplikaci vylepšit!

Úroveň: Ninja

Na úrovni Ninja si ukážeme jak využít uživatelské tlačítko pro naše skripty. Příklad můžeme vidět například zde. Jedná se o rozesílač uživatelských dotazů napsaný v PHP a vyvolaný uživatelským tlačítkem. Uvedeme si ale vlastní příklad, co říkáš Ninjo?

Uvažujme příklad, že chceme faktury se splatností dnes a stále neuhrazené zaslat šéfovi k prověření. Definici tlačítka již známe pro naše účely bude element URL vypadat trošku odlišně:

<?xml version="1.0"?>
<winstrom version="1.0">
  <custom-button>
    <id>code:NEUHRAZENEFAV</id>
    <url><![CDATA[https://ninja.webserver.cz/PHP/neuhrazene-faktury.php]]></url>
    <title>Report neuhrazených FAV</title>
    <description>Odešle na email šéfovy neuhrazené faktury</description>
    <evidence>faktura-vydana</evidence>
    <location>list</location>
    <browser>desktop</browser>
  </custom-button>
</winstrom>

Všimni si Ninjo, URL element obsahuje cestu k PHP skriptu, pro jednoduchost ani nepředáváme, žádné informace z Flexi. Vše zařídí skript. Jdeme na to!

Skript je v našem příkladu velmi jednoduchý, cílem tréninku není naučit se PHP, ale pochopit sílu, jak moc chvat každého API Ninji je uživatelské tlačítko.

<?php
include('./httpful.phar');

$flexiLogin = 'ninja'; 
$flexiHeslo = 1234; 
$uri = 'https://developer.flexibee.eu/c/ninja/faktura-vydana/(datSplat=now()%20and%20stavUhrK<>"stavUhr.uhrazeno").csv?detail=custom:kod,sumCelkem,varSym,nazFirmy&limit=0';

$response = \Httpful\Request::get($uri) 
->expectsXML() 
->authenticateWith($flexiLogin, $flexiHeslo)
->send();

//případné další zpracování odpovědi z Flexi

// příprava zprávy
$to = 'velkysef@ninja.cz';
$subject = 'Nezaplacené faktury';$message = 'Dobrý den, šéfe, zasílám report neplatičů:\n' . $response->body;

//odeslání emailu
mail($to, $subject, $message);
?>

Kliknutím na tlačítko v aplikaci můžeme kdykoliv šéfovi odeslat přehled neuhrazených faktur. Nebo taky cokoliv jiného. Již znáš všechny možnosti Ninjo, tvoje síla je v API neomezená. Můžeš se vrhnout na závěrečný souboj a získat certifikát!

Dostali jste odpověď na svou otázku?