Skills gained:

We have the test environment ready from the first training session and can now start building the URL address where we will find the resources we need. URL stands for "Uniform Resource Locator" — a standardized address pointing to a specific resource. It means an unambiguous address for a requested resource; in other words, a given URL precisely specifies where a particular source of information is located.

We already showed a few examples in the previous training session. Now we will break down the URL in a bit more detail — the kind of detail a Ninja apprentice should know by heart at midnight. A Flexi URL always follows a fixed structure:

{server}/c/{identifikátor firmy}/{kód evidence}/{identifikátor záznamu}.{formát výstupu}

Let's now describe each part of the URL address:

{server} - this is the server on which the called Flexi instance is hosted. The server can be referenced by IP address or domain name. Examples speak for themselves:

1. Cloud server address:

2. Own server address:

3. Local installation address (the PC itself acts as the server):

{company identifier} - uniquely identifies a given billed company within the instance. How do we find it? The company identifier can always be found in the browser's address bar after accessing the company. For our training sessions, the company identifier is - ninja

{register code} - this is the unique identifier for the register you intend to work with. For example, issued invoices have the code faktura-vydana. An important reference listing all available registers can be found here: https://developer.flexibee.eu/c/ninja/evidence-list. We are interested in the machine name, which is the register code.

{record identifier} - here we get down to identifying a specific record within the register; the identifier can be found in the application in the ID column. This is the unique number of the record in the given register. No two records in a register can share the same ID.

{output format} - specifies the format in which data will be retrieved (XML, JSON, and others). If not specified, entering the URL in a standard web browser will redirect you to the HTML web interface of Flexi.

The URL address can of course be extended further

{server}/c/{identifikátor firmy}/{kód evidence}/({filtry}).{formát výstupu}?{parametry}

{filters} - allow us to filter data and retrieve it based on conditions other than the record ID. For example, the filter (varSym ='201800123') retrieves a record based on its variable symbol. We will cover this in more detail in the filtering training session.

{parameters} - parameters allow us to further sort, order, or perform other actions on the data. One of the most basic parameters is detail, which determines how much information about a given record we want to retrieve. We will cover this in more detail in the training session.

Enough theory — let's get to the training!

At the Apprentice level, we will practice building several simple addresses to retrieve useful data. There are additional options within the URL address structure. Let's explore some of them now.

A simple and useful URL can be an address that provides summations within a register. This is done using the $sum variable. For example, calling the address https://developer.flexibee.eu/c/ninja/faktura-prijata/$sum returns a summary of totals in the received invoices register.

We now know what each part of the address means. Try making your own API call, apprentice.

At the Apprentice level, we will also look at a simple filter. We will try filtering using one of the available fields on an invoice. A sharp-eyed apprentice will have noticed in the previous theory section that filtering via the "varSym" field was mentioned. Where do we find additional fields? That's what "/properties" is for. At the address https://developer.flexibee.eu/c/ninja/cenik/properties, you can find all available fields in a given register.

Final task for the apprentice: Filter all customer orders from the current year.

A small hint: Dates must be entered in the format YYYY-MM-DD, or you can use the magic function now() for today's date.

As an API Warrior, we need to go even deeper into the capabilities of the Flexi API. Let's explore some more special addresses.

The first is the address https://developer.flexibee.eu/c/ninja/skladovy-pohyb/reports.xml. At this address, you can retrieve a list of all available print reports for the given register. So how do you download, for example, a delivery note via the API? This is done using the "report-name" parameter, to which you pass the "reportId" from the previous address.

An example will reveal everything — a Warrior can easily handle this on their own.

Some registers have related registers linked to them. An example is the Price List, which has additional registers associated with it. The easiest way to find linked registers is via the address https://developer.flexibee.eu/c/ninja/cenik/relations.xml. To apply this in practice, use the relation URL in the parameter "?relations={relation URL, second relation URL, ...}".

A Warrior can surely already imagine the use cases — for example, how to display the stock cards associated with a price list item?

One question remains: what if I want to display information from a register that is not directly linked as a whole, but is only referenced by one of the fields? Let's look again at the address https://developer.flexibee.eu/c/ninja/faktura-vydana/properties — specifically the fields of variable type "relation". To retrieve information about a related record when calling the main register, use the parameter ?includes={path to record, additional record path, ...}.

Let's walk through an example for better understanding. We want to retrieve additional details about the customer associated with each invoice. We will use the following address:

https://developer.flexibee.eu/c/ninja/faktura-vydana.xml?includes=faktura-vydana/firma

Try out more examples — the final level of this training awaits.

An API Ninja is capable of managing data and monitoring the operation of Flexi through the API. They can peer into the darkest corners of the Flexi environment. Several addresses serve this purpose. They differ from other addresses in that they do not reference a specific company /c/{company identifier} but rather the entire instance.

The first of these is the address https://developer.flexibee.eu/status.xml, where you can retrieve information about licensing, version, and other service details about the operating system and database.

For the curious explorers out there — these values cannot be overwritten via an API request at will :-)

If you are a Flexi administrator and want to see which users are currently logged in, you can find them at https://developer.flexibee.eu/status/session.xml. A full list of all users with access to companies can be found at https://developer.flexibee.eu/a.xml

The last address we will cover in this training session is the list of companies. This list contains not only the required company ID but also information about the company's status: https://developer.flexibee.eu/c.xml

We have walked through the structure and construction of a URL address, including simple examples. We are now ready for the full training on URL parameters and filtering, where we will focus more on practical examples and less on dry theory.