Records in ABRA Flexi can be identified in several ways:

Name	Note	Example
ABRA Flexi identifier	An identifier assigned by the application. Assigned by ABRA Flexi and cannot be changed.	`123`
Code/Abbreviation	A user-defined label. Assigned by the user and can be changed within the application.	`code:CZK`
Key	A unique random identifier that ABRA Flexi assigns to documents (the UUID attribute). It cannot be changed.	`key:550e8400e29b41d4a716`
PLU	PLU is an identification code used at the point of sale. It is usually a 4- or 5-digit numeric code.	`plu:4020`
EAN	The record is identified by its EAN (barcode). A price list item can be looked up either by its own EAN or by the EAN of its packaging. In this case, the number of imported price list items does not change.	`ean:4710937332698`
External identifier	An identifier from an external application. It cannot be changed within the application, but it can be changed from external systems. It consists of the external system's identifier and the identifier of the row in that system. The external identifier must be unique across the entire record collection (e.g. `faktura-vydana`)!	`ext:SHOP:123`
Hybrid identifier	An identifier in the format `ws:{UUID firmy}:{interní ID}` (see below).	`ws:8ee0a075-67fa-4f92-880e-a7d65ab3c6e3:66`
VAT ID	An identifier based on the tax ID number. In the Czech Republic this corresponds to the DIČ, and in Slovakia to the IČO DPH.	`vatid:CZ28019920`
Company ID (IČO)	An identifier based on the company ID number (IČO).	`in:28019920`
IBAN	An identifier based on the IBAN code.	`iban:CZ1201000002801992`

ℹ️ When reading via the REST API, a non-internal identifier is first resolved: the server responds with 301 and sends the URL with the numeric ID in the Location header. Your HTTP client therefore needs to be able to follow redirects. If the record does not exist, it returns 404.

Thanks to incremental updates, you can freely attach additional external identifiers to already existing records:

<?xml version="1.0"?>
<winstrom version="1.0">
  <cenik id="123">
    <id>ext:SHOP:abc</id>
    <id>ext:SYSTEM3:xyz</id>
  </cenik>
</winstrom>

This notation is equivalent to:

<?xml version="1.0"?>
<winstrom version="1.0">
  <cenik>
    <id>123</id>
    <id>ext:SHOP:abc</id>
    <id>ext:SYSTEM3:xyz</id>
  </cenik>
</winstrom>

In JSON, a combination of identifiers is also a valid notation:

"cenik": "[code:NIKON][123][ext:SHOP:abc]"

Internal identifiers

Internal identifiers (standalone numbers) are identifiers assigned by the ABRA Flexi system. If you reference one and the record does not exist, the operation will fail (unlike with other identifier types).

Identifier assignment uses a database sequence. This ensures that the same identifier will never be assigned twice (even if you delete the record). At the same time, it does not guarantee numerical continuity (e.g., the number is discarded on a rollback).

Creating / updating a record

If you use an identifier type other than the internal identifier (e.g., a code) to identify a record, and the referenced record does not exist, a new record will be created. Otherwise, the existing record will be updated.

The following XML / JSON example will update, or create if it doesn't exist, a price list record with the abbreviation T100 (the identifier value here replaces the use of the kod attribute):

<winstrom version="1.0">
  <cenik>
    <id>code:T100</id>
    <nazev>Téčko 100 mm</nazev>
  </cenik>
</winstrom>

{
  "winstrom": {
    "@version": "1.0",
    "cenik": [{
      "id": "code:T100",
      "nazev": "Téčko 100 mm"
    }]
  }
}

Multiple identifiers

A record can also be identified by using several identifiers at once:

<?xml version="1.0"?>
<winstrom version="1.0">
  <cenik>
    <id>123</id>
    <id>code:KRABICE</id>
  </cenik>
</winstrom>

In such a case, all identifiers must refer to the same record; otherwise it is treated as an error. Identifiers that do not exist in ABRA Flexi will be ignored, so an external system can send all known identifiers to ABRA Flexi, and the record will be found based on the ones that exist.

Multiple id elements can only be used in import XML. Elsewhere (URLs in the REST API, other record identifiers in import XML, though it is also possible with id elements), a specialized syntax is required:

[123][code:CZK][ext:SHOP:abc]

⚠️ If an identifier contains the characters [, ], or \, they need to be escaped as \[, \], and \\. When used in a URL, don't forget to also apply proper URL encoding.

ℹ️ Behavior of the bracket syntax in URLs: if all identifiers point to the same record, the server redirects to its numeric ID; if they conflict, it responds with 400; a non-existent identifier combined with an existing one is ignored.

External identifiers

Deleting external identifiers

This is done using the record collection attribute removeExternalIds, whose value represents the prefix of the external identifiers to be removed.

For example, let's have a price list object with ID=123 and the external identifiers SHOP:abc, SYSTEM-1, and SYSTEM-2. The following example will remove both identifiers starting with the string SYSTEM and add a new identifier, SHOP:123:

<?xml version="1.0"?>
<winstrom version="1.0">
  <cenik removeExternalIds="ext:SYSTEM">
    <id>123</id>
    <id>ext:SHOP:123</id>
  </cenik>
</winstrom>

The equivalent notation in JSON format:

{
  "winstrom": {
    "@version": "1.0",
    "cenik": [{
      "id": [ "123", "ext:SHOP:123" ],
      "@removeExternalIds": "ext:SYSTEM"
    }]
  }
}

The external identifier prefix ext: does not need to be specified in the attribute value. An empty string means that all external identifiers should be removed.

Deleting external identifiers from items

This is done similarly to the main record collection, except that the removeExternalIds attribute can be specified either as common for all present items, or directly on a specific item (which takes precedence):

<?xml version="1.0"?>
<winstrom version="1.0">
  <faktura-vydana>
    <id>123</id>
    <polozkyFaktury removeExternalIds="ext:P">
      <faktura-vydana-polozka>
        <id>10</id>
      </faktura-vydana-polozka>
      <faktura-vydana-polozka removeExternalIds="ext:X">
        <id>20</id>
      </faktura-vydana-polozka>
    </polozkyFaktury>
  </faktura-vydana>
</winstrom>

The example above removes external identifiers starting with the character P from item 10, while removing external identifiers starting with the character X from item 20. The external identifiers of any other items on the invoice remain unchanged.

The previous example written in JSON format would look like this:

{
  "winstrom": {
    "@version": "1.0",
    "faktura-vydana": [{
      "id": "123",
      "polozkyFaktury": [
        { "id": "10" },
        { "id": "20", "@removeExternalIds": "ext:X" }
      ],
      "polozkyFaktury@removeExternalIds": "ext:P"
    }]
  }
}

Hybrid identifiers

These are identifiers that behave according to the context in which they are used. If the value of {UUID firmy} matches the UUID of the company into which the record is being imported, the record is updated based on the value of the internal identifier {interní ID}. If the UUID does not match, it functions as an external identifier.

In other words, when importing a record back into the company where it was originally created, it will be updated based on the internal identifier. When importing into a different company, the entire identifier is used, as if it were an external identifier.

On export, the use of hybrid identifiers is activated by the ?mode=xml_import_export mode (see URL parameters).

Record Identifiers