Získané schopnosti:
znalost dostupných formátů a jak je získat nebo uložit
znalost zaslání potřebných dat na email
Velmi obvyklým úkolem každého API Ninji je získat data z aplikace a zaslat je svému šéfovi ve formátu, který si zvolí. Často to bývá Excelová tabulka, PDF dokument, ISDOC a další. V dnešním tréninku si ukážeme obratné chvaty, jak to hravě zvládnout.
Na základní učňovské úrovni si ukážeme, jak dokumenty získat, jaké všechny možnosti máme. Opět k tomu využijeme běžný internetový prohlížeč a Postman. Válečník se naučí, jak různé formáty naopak do aplikace vložit. Na úrovni Ninja půjdeme ještě dál a ukážeme si jak poslat libovolný výstup z aplikace na email pomocí PHP. Rozcvičte se a jdeme na to!
Úroveň: Učeň
Nejprve si představíme možné formáty, které lze získat. Aktuální výpis podporovaných formátů nalezneme v dokumentaci. Získat lze, jak strojově čitelné formáty, tak formáty pro běžného uživatele. Jak získat PDF jsme si ukázali již v předchozím tréninku, pamatujete? Nyní si ukážeme, jak ale získat například XLS tabulku pro Excel. Sestavit správné URL už umíme, stačí tedy zvolit evidenci a přidat formát, tak jednoduché to je.
Zkuste odkaz zavolat ve webovém prohlížeči. Co se nám, ale stáhne za soubor? Jaké bude mít sloupce? Při takovémto volání bez omezení se stáhnout všechny možné sloupce ceníku. To však většinou nechceme. Platí zde bežné možnosti filtrování a detailu, které už umíme z předchozího tréninku.
Jak tedy stáhneme ceník do Excelu, který obsahuje jen kód a název? Přijdeš na to učedníku? Malá nápověda je ?detail=custom
Pokud chcete pro získání dat použít Postman, stačí adresu zadat do adresního řádku a zavolat metodou GET.
Aplikace nám pak vrátí na první pohled nečitelný text, slangově mu Ninjové řikají rozsypaný čaj. Ten však uložíme do souboru, systém sám pozná, že se jedná o PDF a máme staženo. Stejným způsobem můžeme stahovat i další formáty.
Pokud zkombinujeme znalosti z minulých tréninků, jednoduše pak získáme například ISDOC faktury pro s kódem 123 (pokud existuje). Volání pro ISDOC má jeden povinný parametr a tím je typ dokladu. Opět můžeme použít webový prohlížeč nebo Postman.
Učedníku, nyní je čas vyzkoušet si jiné formáty!
Úroveň: Válečník
Na základní úrovni jsme se naučili, jak data získat, stáhnout do počítače. Nicméně někdy je třeba naopak soubor přiložit k dokladu do ABRA Flexi.
Představme si situaci, že máme k dispozici ISDOC soubor dokladu a chceme založit doklad ve Flexi. Využijeme evidenci faktury přijaté. Jelikož jsme již Válečník, ukážeme si pří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"
Co nám příklad říká? CURL již známé, zde je ve volání několik parametrů:
-H hlavička určující typ souboru, my víme, že importujeme isdoc
-u určuje autorizační údaje do Flexi.
-X určuje HTTP metodu, my zasíláme soubor, použijeme tedy metodu PUT
-T zasílaný soubor (tělo požadavku), respektive cesta k němu, pokud voláme cURL z jiného umístění než je soubor
Požadavek na API nám založí fakturu přijatou s typem dokladu FAKTURA.
Vyzkoušej si to válečníku!
Máme zde další obratný chvat. Chceme k již existujícímu dokladu v ABRA Flexi přiložit PDF, které nám zaslal obchodní partner. Jak na to? Využijeme opět evidenci přijaté faktury a její vazbu na přílohy, která se uvádí pomocí identifikátoru prilohy. URL k faktuře s ID = 1 vypadá následovně:
Stejným způsobem můžeme například přikládat .jpg obrázky k ceníkovým položkám. To již musí být pro každého válečníka hračka.
Dokážeš válečníku sestavit volání v cURL pro uložení PDF nebo obrázku k ceníkové položce? Inspiruj se v prvním příkladu.
Malá nápověda! Důležité je dát si pozor na Content-Type:
Pro obrázky: "Content-Type: image/jpeg"
Pro PDF: "Content-Type: application/pdf"
Nyní umíme soubory z ABRA Flexi stáhnout, umíme soubory do ABRA Flexi odeslat. Nyní už nám zbývá všechny poznatky zkombinovat a soubory odeslat do světa, odpovědné osobě na email. Šikovný chvat, který by měl mít v rukávu každý API Ninja.
Úroveň: Ninja
Pro odeslání dokladů/souborů emailem máme více možností. REST API Flexi nabízí dvě služby:
automaticky odeslat neodeslané vydané faktury
"ručně" odeslat libovolný vybraný doklad
Třetí možností je nejprve si stáhnout libovolný doklad a formát a odeslání zpracovat samostatně v například v PHP. Na jednotlivé možnosti se nyní podíváme.
Automaticky odeslat neodeslané vydané faktury
Pro tento úkol existuje jednoduchý chvat, který zapojíme například do cURL příkladu. Strukturu cURL již zná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 podmínkou, aby toto volání fungovalo je, aby doklad měl nastaven příznak odeslat. To lze nastavit přímo na dokladu v desktopové aplikaci, ale cobychom byli za API Ninju, kdybychom si neporadili přes API. Tělo požadavku může vypadat následovně:
<?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 nabývat hodnot Neodesílat (stavMail.neodesilat), Odeslat (stavMail.odeslat), Odesláno (stavMail.odeslano)
Ninjo, dokážeš fakturu připravit k odeslání pomocí API a ověřit, že email byl pomocí volání /automaticky-odeslat-neodeslane skutečně odeslán? Věřím, že ano!
Ručně odeslat libovolný vybraný doklad
Pokud chceme využít ruční odeslání libovolného dokladu musí být zadán alespoň jeden adresát, předmět je také 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"
Kdo bude odesílatel emailu, Ninjo? Nezbývá než vyzkoušet.
Nově umíme i uživatelské emailové šablony. Pokud je šablona k dispozici v datech lze jí získat na následující adrese:
https://developer.flexibee.eu:5434/c/ninja/sablona-mail/1.xml?detail=custom:textSablona
Získaný textSablona pak již stačí použít v parametru -d, který reprezentuje tělo emailu.
Odeslat stažený výstup přes PHP
Pro tento skript opět použijeme již představenou knihovnu HTTPFul.
Uvažujme, že známe konkrétní ID faktury, kterou chceme odeslat. ID již víme, jak zjistit, pokud hledáme konkrétní fakturu, tak tento krok přeskočíme a připravíme se proměnné:
<?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 bylo možné email odeslat je nutné zadat adresáta. Ostatní proměnné (parametry) jsou nepovinné. Nyní přijde to zajímavé, konstrukce URL pro odeslání emailu a odeslání pomocí HTTPFul. Odeslání dokladů ABRA Flexi zajišťuje pomocí zmíněné služby odeslani-dokladu.xml. Pro odeslání můžeme využít HTTP metody POST nebo 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še Ninjo, poté si stačí přečíst proměnnou response, v případě chyby zde najdeš doprovodné informace o chybě. V případě bezchybného odeslání odpověď nemá žádné tělo pouze HTML status kód 200 OK.
Pro tyto účely se hodí nastavit si vlastní SMTP v desktopové aplikaci.
V tréninku jsme nezmínili všechny formáty s kterými lze pracovat, aby byl prostor k samostudiu nebo pro dotazy. Vyzkoušejte si pracovat i s jinými, například v dnešní době rozvíjející se komunikace EDI, která pracuje se soubory ve formátu IN-HOUSE. I tyto soubory lze získat přes API. Lze tak automatizovat export a import těchto elektronických dokumentů. Úkol jako stvořený pro API Ninju! Nyní nás čekají pokročilé akce a triky.