Skills gained:
overview of options for calling web services
command line orientation
creating your own PHP script
authentication
Several approaches and applications can be used for training and testing the ABRA Flexi API. We will walk you through the basic options for honing your skills all the way to API Ninja level. We have also set up a dedicated testing environment for you at:
Here you can easily test your own API tricks.
The simplest possible approach — though only useful for reading data — is your web browser. You enter a request in the browser's address bar, log in to Flexi in the standard way, and retrieve exactly the data you need. We will look at examples later at the Apprentice level, which anyone can handle. For more advanced testing, including the ability to send (write) data to ABRA Flexi, we recommend using the Postman application.
If you feel like a Warrior and don't want to install Postman, you can train using the system command line and the cURL tool. cURL is an extension that lets you add additional commands to the command line (CMD, Terminal). If you are still at the Apprentice level, you may already be feeling a bit overwhelmed by what you're reading — but don't worry, we will cover everything step by step.
A true API Ninja, with a basic knowledge of PHP, can take advantage of the HTTPFul library. HTTPFul is a PHP library developed for simple and elegant communication with APIs of various applications. Using this library together with PHP, you can create your own smart scripts, triggerable for example by a custom button. More on that later in a dedicated training session.
Now let's take a look at the individual training environments by level.
Level: Apprentice
For apprentices, we recommend two powerful allies on the API battlefield. A web browser will help us read data from Flexi. And the even more powerful companion, Postman, will assist us with even the most complex moves when it comes to writing and editing data in Flexi.
Using a web browser
There is no simpler way to retrieve a specific record or set of records from ABRA Flexi without launching the Flexi application and spending time clicking and filtering to find what you need. Just use any web browser you're comfortable with. How about downloading overdue invoices to PDF or Excel with a single click? Give it a try.
Open the following addresses in your web browser:
A curious apprentice will notice that percent-encoded characters — such as %3C — sometimes appear in the browser's address bar. This is because URLs must be encoded for the browser, which does not allow special characters or spaces in an address. We will cover this in more detail in the URL construction training.
The first address returns a PDF report of all overdue invoices. The second link downloads an Excel spreadsheet with the codes of all invoices that are overdue as of today. These simple tricks let you get an overview of the data you need. The link can be customized for your own license and saved as a browser bookmark. Simple, right, apprentice? There are plenty of useful examples to be found — I'm sure you can think of more.
Unfortunately, a web browser cannot handle every trick.
A web browser is not a fully-featured testing environment. It is only useful when you want to quickly read specific data from Flexi. If you want to modify invoices — for example, change a reminder date — you also need to send a request body using the POST method. That's where the Postman application comes in.
Postman application
Postman is the reliable companion of every API Apprentice. It offers a simple graphical interface and helps you perform even the most complex API tricks and moves. Let's take a look at how to work with it. Postman is available as a free download at GetPostman, or it can be added as a Google Chrome extension — however, we recommend the full desktop application.
After a successful installation, take some time to familiarize yourself with the application's interface. For any operation, user authentication is required first. You do this on the Auth tab, where you enter your login credentials.
For our API training, Basic Auth will be sufficient — this is standard HTTP authentication. In apprentice terms: it's the same kind of login as accessing the Flexi web interface directly. Other types of authentication are also available, but those are beyond the scope of the Apprentice level.
Now let's focus on the most important areas of the Postman interface. Pay attention to the numbered areas — the descriptions are provided below. Every Apprentice using Postman must know these few points, even during a midnight API practice drill.
Train hard, fight easy!
1) HTTP operation selector
Postman supports a wide range of operations, but for working with Flexi we currently only need the basic HTTP methods — GET, POST, PUT, DELETE
2) URL input field — the address Postman will work with
you already know this address from the web browser section, for example https://developer.flexibee.eu/c/ninja/faktura-vydana/(datSplat%3Cnow()).xml
3) Format selector for data being sent to the URL
this area only applies when you are sending data
NOTE — the URL file extension must match the format of the data being sent
4) Request format selector (raw by default)
this area is related to area 3 and is also relevant when sending data
5) Response area
Flexi communicates back when the API is called — this area displays the response from Flexi, either the requested data, or the status of the request (success or error) when data was sent to ABRA Flexi
6) Request body
this is where you write the content of your request when sending data to Flexi, for example in XML/JSON format
An example speaks for itself — let's try our first move in Postman. On the Auth tab, enter your login credentials (Where do I find them?). Select the HTTP operation POST and set the URL to https://developer.flexibee.eu:5434/c/ninja/faktura-vydana.xml.
Now enter the raw request body in XML (application/xml) format with the following content:
<?xml version="1.0" encoding="utf-8"?>
<winstrom version="1.0">
<faktura-vydana>
<typDokl>code:FAKTURA</typDokl>
<firma>code:FLEXI</firma>
<popis>Ninja faktura z CURL</popis>
<sumZklZakl>1000.0</sumZklZakl>
<bezPolozek>true</bezPolozek>
</faktura-vydana>
</winstrom>
All that's left is to click Send! Success: true? Yes, apprentice — you've just created an invoice in Flexi using the API. Postman saves all commands to history, so you can always come back to them.
Postman can do much more, of course — go explore, apprentice.
Level: Warrior
A warrior will certainly appreciate an option that requires no graphical application installation — working entirely from the command line to both retrieve and send data to ABRA Flexi.
cURL
cURL is a command that makes it easy to download data from any address, as well as send data to a specified address. cURL is available for your system at https://curl.haxx.se/. In the Download section you will find an extensive list of versions — choose the one appropriate for your operating system.
The website also provides installation instructions depending on your system. On Linux, it is sufficient to install cURL via the command line using your distribution's package manager. On Windows, you will likely need to set the PATH system variable. macOS includes cURL out of the box and you can start using it right away.
Tighten your belt, warrior — let's get to it!
Once you have cURL ready, let's dive into the command line — "cmd" on Windows, "terminal" on Linux and Mac. The basic command looks like this:
curl -u jmeno:heslo -L -o soubor.pdf
-u specifies the authentication credentials for Flexi.
-L follows redirects. If the URL structure changes in the future, this flag ensures the script will continue to work.
-o ensures that the returned data will be written to a file called "file.pdf".
-f specifies that if a server-side error occurs, nothing should be written to the output — the command should exit immediately instead.
-k if you are using your own installation with an auto-generated certificate, this flag allows you to ignore an untrusted certificate authority.
-T the file to be sent (request body)
More information about command syntax is available by running "curl --help".
Proper training calls for trying out some moves. For example, you can retrieve all unpaid invoices to a PDF file using the following command:
curl -u login:heslo -k -L -f "https://developer.flexibee.eu:5434/c/ninja/faktura-vydana/(stavUhrK%20!=%20%27stavUhr.uhrazeno%27).pdf" -o neuhrazene-faktury.pdf
Of course, you need to replace login:password with your actual credentials, which you can obtain via the form at the end of the first API Ninja article in the series. The PDF file neuhrazene-faktury.pdf will be saved to the directory where you are currently located in the command line.
Can you save the file somewhere else, warrior?
Reading data is very straightforward — and so is writing data to Flexi. Let's consider creating an invoice. To create an invoice, we first need an XML file containing the data. Create a file called faktura.xml with the following content:
<?xml version="1.0" encoding="utf-8"?>
<winstrom version="1.0">
<faktura-vydana>
<typDokl>code:FAKTURA</typDokl>
<firma>code:FLEXI</firma>
<popis>Ninja faktura z CURL</popis>
<sumZklZakl>1000.0</sumZklZakl>
<bezPolozek>true</bezPolozek>
</faktura-vydana>
</winstrom>
Then all that remains is to call the cURL command from the directory in the command line where the created file is saved. Flexi's response will be returned directly to the command line.
curl -u login:heslo -k -L https://developer.flexibee.eu:5434/c/ninja/faktura-vydana.xml -T faktura.xml
Feeling like you're ready for more, warrior? Not afraid to step into the world of PHP? Try the Ninja level and join the elite API Ninja tier right from your very first training.
Level: Ninja
A Ninja warrior needs no one else. They build their own tools and training ground. HTTPFul can serve that purpose perfectly.
HTTPFul
HTTPFul is a PHP library that makes it easy to communicate via the HTTP protocol in a PHP environment. The library's creator provides instructions on their website on how to install the library. Of course, you need to have a working PHP environment on your computer.
For our training purposes, installation option number 1 will be the most suitable. Simply include the downloaded file in your script:
<?php
//Cesta ke staženému souboru include('./httpful.phar');
...
?>
You can then continue with your script, which contains an HTTPFul call to the Flexi API and outputs the result to the screen:
<?php
$flexiLogin = 'ninja';
$flexiHeslo = 1234;
$uri = 'https://developer.flexibee.eu/c/ninja/faktura-vydana/(datSplat%3Cnow()).xml?limit=0;
$response = \Httpful\Request::get($uri)
->expectsXML()
->authenticateWith($flexiLogin, $flexiHeslo)
->send();
echo $response->body->winstrom->{'faktura-vydana'};
...
?>
This is the simplest way to retrieve the XML of all overdue invoices. If we want to send data to Flexi using HTTPFul, we first prepare the data in XML/JSON format. For PHP, JSON is the most convenient format, as it can be easily created from a PHP array.
And once again we call HTTPFul to help, this time using the POST method:
<?php
$idFaktury = 1;
$faktura['winstrom']['faktura-vydana']['id'] = $idFaktury; $faktura['winstrom']['faktura-vydana']['varSym'] = '123456789';
$json = json_encode($faktura);
$uri = 'https://developer.flexibee.eu/c/ninja/faktura-vydana.json';
$response = \Httpful\Request::post($uri)
->sendsJson()
->authenticateWith($flexiLogin, $flexiHeslo)
->send();
...
?>
With this script, we have changed the variable symbol of a selected invoice. We have covered the basics of using the library as a tool for accessing the Flexi API. A true API Ninja will enrich these scripts with a basic knowledge of PHP — adding parameters, processing results, and more. But we'll leave that to your creativity.
Take time to get thoroughly familiar with your chosen testing environment. In the next training session, we will cover the theory of URL structure and construction.