Skills acquired:
knowledge of available formats and how to retrieve or save them
knowledge of sending required data via email
A very common task for every API Ninja is to retrieve data from the application and send it to their manager in a format of their choosing. This is often an Excel spreadsheet, a PDF document, an ISDOC file, and more. In today's training, we'll show you some agile moves to handle this with ease.
At the basic apprentice level, we'll show you how to retrieve documents and what options are available. We'll again use a standard web browser and Postman. The Warrior will learn how to upload various formats into the application instead. At the Ninja level, we'll go even further and show you how to send any output from the application via email using PHP. Warm up — let's get started!
Level: Apprentice
First, let's introduce the available formats that can be retrieved. The current list of supported formats can be found in the documentation. You can retrieve both machine-readable formats and formats intended for end users. We already showed you how to retrieve a PDF in the previous training — do you remember? Now we'll show you how to retrieve, for example, an XLS spreadsheet for Excel. We already know how to construct the correct URL, so all you need to do is choose the record type and append the format — it's that simple.
Try calling the link in your web browser. But what file will be downloaded? What columns will it have? When making a call like this without any restrictions, all possible columns of the price list will be downloaded. That is usually not what we want. The standard filtering and detail options we learned in the previous training apply here as well.
So how do we download a price list into Excel containing only the code and name? Can you figure it out, apprentice? Here's a small hint: ?detail=custom
If you want to use Postman to retrieve data, simply enter the URL in the address bar and call it using the GET method.
The application will return text that appears unreadable at first glance — Ninjas colloquially call it "spilled tea." However, once saved to a file, the system will automatically recognize it as a PDF and the download is complete. Other formats can be downloaded in the same way.
By combining knowledge from previous training sessions, we can easily retrieve, for example, the ISDOC file for an invoice with code 123 (if it exists). The ISDOC call has one required parameter: the document type. Again, you can use either a web browser or Postman.
Apprentice, now it's time to try out other formats!
Level: Warrior
At the basic level, we learned how to retrieve data and download it to a computer. However, sometimes it is necessary to do the opposite — attach a file to a document in ABRA Flexi.
Let's imagine a situation where we have an ISDOC file for a document and want to create that document in Flexi. We'll use the received invoices record. Since we are already Warriors, let's look at an example in 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"
What does the example tell us? We're already familiar with cURL; the call includes several parameters:
-H a header specifying the file type — we know we are importing an isdoc file
-u specifies the authorization credentials for Flexi.
-X specifies the HTTP method — since we are sending a file, we use the PUT method
-T the file being sent (request body), or more precisely the path to it, if you are calling cURL from a different location than where the file is stored
The API request will create a received invoice with document type FAKTURA.
Give it a try, Warrior!
Here's another agile move. We want to attach a PDF sent to us by a business partner to an existing document in ABRA Flexi. How do we do it? We'll again use the received invoices record and its attachment relation, which is referenced using the identifier prilohy. The URL for an invoice with ID = 1 looks as follows:
In the same way, you can for example attach .jpg images to price list items. That should already be a breeze for any Warrior.
Warrior, can you construct a cURL call to save a PDF or image to a price list item? Take inspiration from the first example.
A small hint! Pay attention to the Content-Type:
For images: "Content-Type: image/jpeg"
For PDF: "Content-Type: application/pdf"
We can now download files from ABRA Flexi and upload files to ABRA Flexi. All that remains is to combine all this knowledge and send files out to the world — to the responsible person via email. A handy move that every API Ninja should have up their sleeve.
Level: Ninja
For sending documents/files via email, we have several options. The Flexi REST API offers two services:
automatically send unsent issued invoices
"manually" send any selected document
The third option is to first download any document in any format and handle the sending independently, for example in PHP. Let's now look at each of these options.
Automatically send unsent issued invoices
For this task, there is a simple move that we can plug into a cURL example. We're already familiar with the cURL structure.
curl -H "Accept: application/xml" -u ninja:adminheslo -X PUT -L https://developer.flexibee.eu:5434/c/ninja/faktura-vydana/automaticky-odeslat-neodeslane
A necessary prerequisite for this call to work is that the document must have the "send" flag set. This can be set directly on the document in the desktop application, but what kind of API Ninja would we be if we couldn't handle it via the API? The request body might look like this:
<?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>
The field stavMailK can have the following values: Do not send (stavMail.neodesilat), Send (stavMail.odeslat), Sent (stavMail.odeslano)
Ninja, can you prepare an invoice for sending via the API and verify that the email was actually sent using the /automaticky-odeslat-neodeslane call? I believe you can!
Manually send any selected document
If you want to use manual sending for any selected document, at least one recipient must be specified, and the subject is also required.
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"
Who will be the email sender, Ninja? There's only one way to find out — try it.
We now also support custom email templates. If a template is available in the data, it can be retrieved at the following address:
The retrieved textSablona can then simply be used in the parameter -d, which represents the email body.
Send a downloaded output via PHP
For this script, we'll again use the previously introduced library HTTPFul.
Let's assume we know the specific ID of the invoice we want to send. We already know how to find an ID, so if we're looking for a specific invoice, we can skip that step and prepare our variables:
<?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';
?>
In order to send the email, a recipient must be specified. All other variables (parameters) are optional. Now comes the interesting part — constructing the URL for sending the email and dispatching it using HTTPFul. ABRA Flexi handles document sending via the aforementioned odeslani-dokladu.xml service. For sending, we can use either the HTTP POST or PUT method:
<?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();
?>
And that's all, Ninja — all you need to do afterwards is read the response variable. In the event of an error, it will contain accompanying error information. If the sending is successful, the response has no body — only the HTTP status code 200 OK.
For these purposes, it is useful to configure your own SMTP server in the desktop application.
This training did not cover all the formats that can be worked with, leaving room for self-study or questions. Try working with other formats as well — for example, EDI communication, which is increasingly widespread today and works with files in the IN-HOUSE format. These files can also be retrieved via the API, making it possible to automate the export and import of these electronic documents. A task made for an API Ninja! Next up: advanced actions and tricks.