In this final part, we'll show two concrete examples of writing data to ABRA Flexi via the REST API: creating a price list item and creating an issued invoice with overwrite protection. Both examples are provided in XML and JSON format.

🚨 Do not try these examples on live accounting data. Use a copy of the company, or first verify the request in test-save mode by adding the ?dry-run=true parameter. The server will then process and validate the request, but won't save anything.

Before You Start

To build a request, you need to know the machine name of the record type and the names of its attributes. You can list both directly from Flexi.

List of all record types:

/c/<identifikátor firmy>/evidence-list

Attributes of a specific record type:

/c/<identifikátor firmy>/<evidence>/properties

Instead of <evidence>, always use the machine name, for example adresar, cenik, faktura-vydana, faktura-prijata, objednavka-prijata, interni-doklad, banka, pokladna, or faktura-vydana-polozka. You'll find details on both addresses in the part about building the URL address.

Example 1: Creating a Price List Item

Send the request using the POST method to the address for listing the price list record type:

POST https://localhost:5434/c/testovaci/cenik.xml

Request body in XML format:

<?xml version="1.0" encoding="utf-8"?>
<winstrom version="1.0">
  <cenik>
    <id>ext:SHOP:123</id>
    <kod>KOD</kod>
    <nazev>POLOZKA_CENIKU</nazev>
    <mj1>code:KS</mj1>
    <typSzbDphK>typSzbDph.dphZakl</typSzbDphK>
    <typZasobyK>typZasoby.zbozi</typZasobyK>
    <cenaZakl>500</cenaZakl>
    <szbDph>21</szbDph>
  </cenik>
</winstrom>

The same in JSON format:

{
  "winstrom": {
    "@version": "1.0",
    "cenik": [
      {
        "id": "ext:SHOP:123",
        "kod": "KOD",
        "nazev": "POLOZKA_CENIKU",
        "mj1": "code:KS",
        "typSzbDphK": "typSzbDph.dphZakl",
        "typZasobyK": "typZasoby.zbozi",
        "cenaZakl": "500",
        "szbDph": "21"
      }
    ]
  }
}

The request creates a price list item with:

an external identifier 123 from the SHOP system
code KOD
name POLOZKA_CENIKU
unit of measure PCS
stock type Goods
standard VAT rate of 21%
price of CZK 500

ℹ️ The external identifier consists of the source system designation and the row identifier within it, in the format ext:SYSTEM:hodnota. It must be unique within the entire record type. Thanks to it, on repeated calls you can tell that the record already exists and avoid creating a duplicate. Read more in the article on record identifiers.

Example 2: Creating an Invoice Without Overwriting an Existing One

The second example creates an issued invoice, while also protecting the data from unwanted overwriting:

POST https://localhost:5434/c/testovaci/faktura-vydana.xml

Request body in XML format:

<?xml version="1.0" encoding="utf-8"?>
<winstrom version="1.0">
  <faktura-vydana update="ignore">
    <id>ext:SHOP:456</id>
    <id>code:FAV01</id>
    <nazev>FAKTURA_01</nazev>
    <varSym>20183103</varSym>
    <stitky>VIP</stitky>
    <bankovniUcet>code:UCET01</bankovniUcet>
    <typDokl>code:FAKTURA</typDokl>
  </faktura-vydana>
</winstrom>

The same in JSON format:

{
  "winstrom": {
    "@version": "1.0",
    "faktura-vydana": [
      {
        "@update": "ignore",
        "id": [
          "ext:SHOP:456",
          "code:FAV01"
        ],
        "nazev": "FAKTURA_01",
        "varSym": "20183103",
        "stitky": "VIP",
        "bankovniUcet": "code:UCET01",
        "typDokl": "code:FAKTURA"
      }
    ]
  }
}

The update="ignore" attribute means that if an invoice with the code FAV01 or with the external identifier SHOP:456 already exists, the request to change it is ignored. The existing document therefore remains unchanged. Other modes are described in the article on create-and-update mode.

⚠️ For documents, you must always specify the document type in the typDokl attribute. Without it, Flexi doesn't know which series to assign the document to, and the request will fail with an error.

Server Response

For every write operation, the server responds with a structure showing whether the operation was successful, how many records were processed, and what identifiers the affected records received.

<winstrom version="1.0">
  <success>true</success>
  <stats>
    <created>1</created>
    <updated>0</updated>
    <deleted>0</deleted>
    <skipped>0</skipped>
    <failed>0</failed>
  </stats>
  <result>
    <id>105</id>
  </result>
</winstrom>

The success element indicates whether the request succeeded. In stats, you'll find the counts of created, updated, deleted, and skipped records. It's from skipped that you can tell the update="ignore" mode was applied. result then contains the identifier of the record that Flexi worked with.

💡 You'll find more ready-made request examples in the article with XML file examples. For hands-on practice with live data, check out the API Ninja series.

Other Parts in This Series

How to Get Started with the Flexi API 6/6 - XML and JSON Examples