Získané schopnosti:
znalosť dostupných formátov a ako ich získať alebo uložiť
znalosť odoslania potrebných dát na email
Veľmi obvyklou úlohou každého API Ninju je získať dáta z aplikácie a odoslať ich svojmu šéfovi vo formáte, ktorý si zvolí. Často to býva Excelová tabuľka, PDF dokument, ISDOC a ďalšie. V dnešnom tréningu si ukážeme obratné chvaty, ako to hravo zvládnuť.
Na základnej učňovskej úrovni si ukážeme, ako dokumenty získať, aké všetky možnosti máme. Opäť k tomu využijeme bežný internetový prehliadač a Postman. Bojovník sa naučí, ako naopak rôzne formáty vložiť do aplikácie. Na úrovni Ninja pôjdeme ešte ďalej a ukážeme si, ako poslať ľubovoľný výstup z aplikácie na email pomocou PHP. Rozcvičte sa a poďme na to!
Úroveň: Učeň
Najprv si predstavíme možné formáty, ktoré je možné získať. Aktuálny výpis podporovaných formátov nájdeme v dokumentácii. Získať možno tak strojovo čitateľné formáty, ako aj formáty pre bežného používateľa. Ako získať PDF sme si ukázali už v predchádzajúcom tréningu, pamätáte? Teraz si ukážeme, ako získať napríklad XLS tabuľku pre Excel. Zostaviť správne URL už vieme, stačí teda zvoliť evidenciu a pridať formát, tak jednoduché to je.
Skúste odkaz zavolať vo webovom prehliadači. Čo sa nám ale stiahne za súbor? Aké bude mať stĺpce? Pri takomto volaní bez obmedzenia sa stiahnu všetky možné stĺpce cenníka. To však väčšinou nechceme. Platia tu bežné možnosti filtrovania a detailu, ktoré už poznáme z predchádzajúceho tréningu.
Ako teda stiahneme cenník do Excelu, ktorý obsahuje len kód a názov? Prídeš na to, učedník? Malá nápoveda je ?detail=custom
Ak chcete na získanie dát použiť Postman, stačí adresu zadať do adresného riadku a zavolať metódou GET.
Aplikácia nám potom vráti na prvý pohľad nečitateľný text, slangovo mu Ninjovia hovoria rozsypaný čaj. Ten však uložíme do súboru, systém sám spozná, že ide o PDF a máme stiahnuté. Rovnakým spôsobom môžeme sťahovať aj ďalšie formáty.
Ak skombinujeme znalosti z minulých tréningov, jednoducho potom získame napríklad ISDOC faktúry s kódom 123 (pokiaľ existuje). Volanie pre ISDOC má jeden povinný parameter, a tým je typ dokladu. Opäť môžeme použiť webový prehliadač alebo Postman.
Učedník, teraz je čas vyskúšať si iné formáty!
Úroveň: Bojovník
Na základnej úrovni sme sa naučili, ako dáta získať, stiahnuť do počítača. Niekedy je však potrebné naopak súbor priložiť k dokladu do ABRA Flexi.
Predstavme si situáciu, že máme k dispozícii ISDOC súbor dokladu a chceme založiť doklad vo Flexi. Využijeme evidenciu faktúry prijatej. Keďže sme už Bojovník, ukážeme si príklad v cURL:
curl -H "Content-Type: application/x-isdoc" -u ninja:adminheslo -X PUT https://developer.flexibee.eu:5434/c/ninja/faktura-prijata?typDokl=code:FAKTURA" -T "/cesta/soubor.isdoc"
Čo nám príklad hovorí? CURL už poznáme, tu je vo volaní niekoľko parametrov:
-H hlavička určujúca typ súboru, my vieme, že importujeme isdoc
-u určuje autorizačné údaje do Flexi.
-X určuje HTTP metódu, my zasielame súbor, použijeme teda metódu PUT
-T zasielaný súbor (telo požiadavky), respektíve cesta k nemu, pokiaľ voláme cURL z iného umiestnenia, než je súbor
Požiadavka na API nám založí faktúru prijatú s typom dokladu FAKTURA.
Vyskúšaj si to, bojovník!
Máme tu ďalší obratný chvat. Chceme k už existujúcemu dokladu v ABRA Flexi priložiť PDF, ktoré nám zaslal obchodný partner. Ako na to? Využijeme opäť evidenciu prijatej faktúry a jej väzbu na prílohy, ktorá sa uvádza pomocou identifikátora prilohy. URL k faktúre s ID = 1 vyzerá nasledovne:
Rovnakým spôsobom môžeme napríklad prikladať .jpg obrázky k cenníkovým položkám. To už musí byť pre každého bojovníka hračka.
Dokážeš, bojovník, zostaviť volanie v cURL na uloženie PDF alebo obrázka k cenníkovej položke? Inšpiruj sa v prvom príklade.
Malá nápoveda! Dôležité je dať si pozor na Content-Type:
Pre obrázky: "Content-Type: image/jpeg"
Pre PDF: "Content-Type: application/pdf"
Teraz vieme súbory z ABRA Flexi stiahnuť, vieme súbory do ABRA Flexi odoslať. Teraz nám už zostáva všetky poznatky skombinovať a súbory odoslať do sveta, zodpovednej osobe na email. Šikovný chvat, ktorý by mal mať v rukáve každý API Ninja.
Úroveň: Ninja
Na odoslanie dokladov/súborov emailom máme viac možností. REST API Flexi ponúka dve služby:
automaticky odoslať neodoslané vydané faktúry
„ručne“ odoslať ľubovoľný vybraný doklad
Treťou možnosťou je najprv si stiahnuť ľubovoľný doklad a formát a odoslanie spracovať samostatne, napríklad v PHP. Na jednotlivé možnosti sa teraz pozrieme.
Automaticky odoslať neodoslané vydané faktúry
Pre túto úlohu existuje jednoduchý chvat, ktorý zapojíme napríklad do príkladu cURL. Štruktúru cURL už poznáme.
curl -H "Accept: application/xml" -u ninja:adminheslo -X PUT -L https://developer.flexibee.eu:5434/c/ninja/faktura-vydana/automaticky-odeslat-neodeslane
Nutnou podmienkou, aby toto volanie fungovalo, je, aby doklad mal nastavený príznak odoslať. To možno nastaviť priamo na doklade v desktopovej aplikácii, ale to by sme neboli API Ninja, keby sme si neporadili cez API. Telo požiadavky môže vyzerať nasledovne:
<?xml version='1.0' encoding='utf-8'?>
<winstrom version="1.0">
<faktura-vydana>
<id>code:VF0001-2021</id>
<stavMailK>stavMail.odeslat</stavMailK>
<kontaktEmail>ninja@firma.cz</kontaktEmail>
</faktura-vydana>
</winstrom>
Pole stavMailK môže nadobúdať hodnoty Neodosielať (stavMail.neodesilat), Odoslať (stavMail.odeslat), Odoslané (stavMail.odeslano)
Ninja, dokážeš pripraviť faktúru na odoslanie pomocou API a overiť, že email bol pomocou volania /automaticky-odeslat-neodeslane skutočne odoslaný? Verím, že áno!
Ručne odoslať ľubovoľný vybraný doklad
Ak chceme využiť ručné odoslanie ľubovoľného dokladu, musí byť zadaný aspoň jeden adresát, predmet je tiež povinný.
curl -k -L -u ninja:adminheslo -X PUT -d 'Dobrý den, zasíláme Vám objednávku. S pozdravem ...' "https://developer.flexibee.eu:5434/c/ninja/objednavka-prijata/1/odeslani-dokladu.xml?to=ninja@firma.cz&subject=Doklad%20ABC"
Kto bude odosielateľ emailu, Ninja? Nezostáva než to vyskúšať.
Novo vieme aj používateľské emailové šablóny. Ak je šablóna k dispozícii v dátach, možno ju získať na nasledujúcej adrese:
https://developer.flexibee.eu:5434/c/ninja/sablona-mail/1.xml?detail=custom:textSablona
Získaný textSablona potom už stačí použiť v parametri -d, ktorý reprezentuje telo emailu.
Odoslať stiahnutý výstup cez PHP
Pre tento skript opäť použijeme už predstavenú knižnicu HTTPFul.
Uvažujme, že poznáme konkrétne ID faktúry, ktorú chceme odoslať. Ako zistiť ID, už vieme, pokiaľ hľadáme konkrétnu faktúru, tak tento krok preskočíme a pripravíme si premenné:
<?php
//Cesta ke staženému souboru knihovny HTTPFul
include('./httpful.phar');
// login do Flexi
$flexiLogin = 'ninja';
$flexiHeslo = 1234;
// zjistíme ID faktury
$idFAV = 123;
// pro odeslání musíme určit adresáta,
// dále je možné zadat kopii a předmět emailu
$adresat = 'ninja@flexi.eu';
$kopie = 'valecnik@flexi.eu';
$predmetEmailu = 'Doklad od Ninji';
?>
Aby bolo možné email odoslať, je nutné zadať adresáta. Ostatné premenné (parametre) sú nepovinné. Teraz príde to zaujímavé, konštrukcia URL na odoslanie emailu a odoslanie pomocou HTTPFul. Odoslanie dokladov ABRA Flexi zabezpečuje pomocou spomínanej služby odeslani-dokladu.xml. Na odoslanie môžeme využiť HTTP metódy POST alebo PUT:
<?php
// URL pro odeslání se skládá z uvedených proměnných
// a volání odeslani-dokladu.xml
$uri = 'https://developer.flexibee.eu/c/ninja/faktura-vydana/'
.$idFAV.'/odeslani-dokladu.xml?to='.$adresat
.'&cc='.$kopie
.'&subject='.$predmetEmailu;
$response = \Httpful\Request::post($uri)
->expectsXML()
->authenticateWith($flexiLogin, $flexiHeslo)
->send();
?>
A to je všetko, Ninja, potom už stačí prečítať premennú response, v prípade chyby tu nájdeš sprievodné informácie o chybe. V prípade bezchybného odoslania odpoveď nemá žiadne telo, iba HTML status kód 200 OK.
Na tieto účely sa hodí nastaviť si vlastný SMTP v desktopovej aplikácii.
V tréningu sme nespomenuli všetky formáty, s ktorými možno pracovať, aby bol priestor na samoštúdium alebo na otázky. Vyskúšajte si pracovať aj s inými, napríklad v dnešnej dobe rozvíjajúcou sa komunikáciou EDI, ktorá pracuje so súbormi vo formáte IN-HOUSE. Aj tieto súbory možno získať cez API. Možno tak automatizovať export a import týchto elektronických dokumentov. Úloha ako stvorená pre API Ninju! Teraz nás čakajú pokročilé akcie a triky.