Name | Note | Example |
ABRA Flexi Identifier | An identifier assigned by the application. Assigned by ABRA Flexi and cannot be changed. |
|
Code/Abbreviation | A user-defined label. Assigned by the user and can be changed within the application. |
|
Key | A unique random identifier assigned by ABRA Flexi to records (UUID attribute). Cannot be changed. |
|
PLU is an identification code used at the point of sale. It is typically a 4- or 5-digit numeric code. |
| |
A record is identified by its EAN code (barcode). A price list item can be looked up either by its own EAN or by the EAN of its packaging. The number of imported price list items does not change in this case. |
| |
External Identifier | An identifier from an external application. It cannot be changed within the application but can be changed from external systems. It consists of the external system identifier and the row identifier in that system. The external identifier must be unique across the entire record set (e.g. |
|
Hybrid Identifier | An identifier in the format | ws:8ee0a075-67fa-4f92-880e-a7d65ab3c6e3:66 |
VAT ID | An identifier based on the tax number. In the Czech Republic this corresponds to DIČ; in Slovakia it corresponds to IČO DPH. |
|
Company Registration Number (IČO) | An identifier based on the company registration number (IČO). |
|
IBAN | An identifier based on the IBAN code. |
|
Thanks to incremental updates, you can freely attach additional external identifiers to 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 the following:
<?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 valid:
"cenik": "[code:NIKON][123][ext:SHOP:abc]"
Internal Identifiers
An internal identifier (a standalone number) is an identifier assigned by the ABRA Flexi system. If you reference one and the record does not exist, the operation will fail (unlike other identifier types).
Identifier assignment uses a database sequence. This ensures that the same identifier is never assigned twice (even if the record is deleted). It does not, however, guarantee numerical continuity (for example, a number is discarded upon 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 does not exist, a price list record with the abbreviation T100 (the identifier value here replaces the need to specify the kod attribute):
<winstrom version="1.0">
<cenik>
<id>code:T100</id>
<nazev>Téčko 100 mm</name>
</cenik>
</winstrom>
{
"winstrom": {
"@version": "1.0",
"cenik": [
{
"id": "code:T100",
"name": "Téčko 100 mm"
}
]
}
}Multiple Identifiers
A record can also be identified by using several identifiers at the same time:
<?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 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 those that do exist.
Multiple id elements can only be used in import XML. In other places (URLs in the REST API, other record identifiers in import XML, though id elements also support this) you must use the specialized syntax: [123][code:CZK][ext:SHOP:abc].
If an identifier contains the characters [, ], or , they must be escaped: [, ], \. When used in a URL, remember to also apply proper URL encoding.
Deleting External Identifiers
This is done using the record attribute "removeExternalIds", where its value represents the prefix of the external identifiers to be removed.
For example, consider a price list object with ID=123 and the external identifiers: "SHOP:abc", "SYSTEM-1", and "SYSTEM-2". The following example removes both identifiers starting with the string "SYSTEM" and adds 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 included in the attribute value. An empty string means that all external identifiers should be removed.
Deleting External Identifiers from Line Items
This is done similarly to the main record, with the difference that the "removeExternalIds" attribute can be specified as a shared value for all present line items and/or directly on a specific line 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 line item 10, while removing external identifiers starting with the character "X" from line item 20. External identifiers of any other line 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 {UUID firmy} value matches the UUID of the company into which the record is being imported, the record is updated based on the internal identifier value {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 full identifier is used as if it were an external one.
During export, the use of hybrid identifiers is activated by the ?mode=xml_import_export mode (see URL parameters).