Záznamy v ABRA Flexi je možné identifikovať niekoľkými spôsobmi:
Názov | Poznámka | Ukážka |
Identifikátor ABRA Flexi | Identifikátor pridelený aplikáciou. Prideľuje ABRA Flexi a nie je možné ho meniť. |
|
Kód/Skratka | Používateľské označenie. Pridelené používateľom a je možné ho meniť v aplikácii. |
|
Key | Unikátny náhodný identifikátor, ktorý prideľuje ABRA Flexi dokladom (atribút UUID). Nie je možné ho meniť. |
|
PLU je identifikačný kód, ktorý sa používa pri predaji. Zvyčajne ide o 4- či 5-miestny číselný kód. |
| |
Záznam je identifikovaný podľa kódu EAN (čiarový kód). Položku cenníka je možné dohľadať tak podľa jej EAN, ako aj podľa EAN jej balenia. Počet importovaných položiek cenníka sa v tomto prípade nemení. |
| |
Externý identifikátor | Identifikátor z externej aplikácie. V aplikácii ho nie je možné meniť. Je možné ho meniť z externých systémov. Skladá sa z identifikátora externého systému a identifikátora riadku v tomto systéme. Externý identifikátor musí byť unikátny pre celú evidenciu (napr. |
|
Hybridný identifikátor | Identifikátor vo formáte |
|
VAT ID | Identifikátor podľa daňového čísla. V ČR zodpovedá DIČ, v SR zodpovedá IČ DPH. |
|
IČO | Identifikátor podľa IČO. |
|
IBAN | Identifikátor podľa kódu IBAN. |
|
ℹ️ Pri čítaní cez REST API sa neinterný identifikátor najprv preloží: server odpovie 301 a v hlavičke Location pošle URL s číselným ID. Váš HTTP klient teda musí vedieť nasledovať presmerovanie. Ak záznam neexistuje, vráti 404.
Vďaka inkrementálnej aktualizácii je možné ľubovoľne pripájať ďalšie externé identifikátory k už existujúcim záznamom:
<?xml version="1.0"?>
<winstrom version="1.0">
<cenik id="123">
<id>ext:SHOP:abc</id>
<id>ext:SYSTEM3:xyz</id>
</cenik>
</winstrom>
Tento zápis je ekvivalentný s týmto:
<?xml version="1.0"?>
<winstrom version="1.0">
<cenik>
<id>123</id>
<id>ext:SHOP:abc</id>
<id>ext:SYSTEM3:xyz</id>
</cenik>
</winstrom>
V prípade JSON je validný aj zápis kombinácie identifikátorov:
"cenik": "[code:NIKON][123][ext:SHOP:abc]"
Interné identifikátory
Interný identifikátor (samostatné číslo) sú identifikátory, ktoré prideľuje systém ABRA Flexi. Ak sa naň odkážete a záznam neexistuje, operácia zlyhá (na rozdiel od ostatných identifikátorov).
Na prideľovanie identifikátorov je používaná databázová sequence. Tá zabezpečuje, že rovnaký identifikátor nebude nikdy pridelený dvakrát (ani keď záznam vymažete). Zároveň negarantuje číselnú nadväznosť (napr. pri rollbacku sa číslo zahodí).
Vytvorenie / aktualizácia záznamu
Ak použijete na identifikáciu záznamu iný typ identifikátora ako interný identifikátor (napr. kód) a odkazovaný záznam nebude existovať, tak dôjde k vytvoreniu nového záznamu. V opačnom prípade sa vykoná aktualizácia existujúceho záznamu.
Nasledujúca ukážka XML / JSON zabezpečí aktualizáciu, prípadne vytvorenie, záznamu v cenníku so skratkou T100 (hodnota identifikátora tu nahrádza uvedenie atribútu kod):
<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"
}]
}
}
Viacnásobné identifikátory
Záznam je možné identifikovať aj použitím niekoľkých identifikátorov zároveň:
<?xml version="1.0"?>
<winstrom version="1.0">
<cenik>
<id>123</id>
<id>code:KRABICE</id>
</cenik>
</winstrom>
V takom prípade musia všetky identifikátory označovať ten istý záznam, inak ide o chybu. Identifikátory, ktoré v ABRA Flexi neexistujú, budú ignorované, takže z externého systému je možné poslať do ABRA Flexi všetky známe identifikátory a záznam bude nájdený podľa tých existujúcich.
Viac elementov id je možné použiť iba v importnom XML. Na iných miestach (URL v REST API, ostatné identifikátory záznamov v importnom XML, ale pri elementoch id je to tiež možné) je potrebné používať špecializovanú syntax:
[123][code:CZK][ext:SHOP:abc]
⚠️ Ak identifikátor obsahuje znaky [, ] alebo \, je potrebné ich escapovať ako \[, \] a \\. Pri použití v URL je potrebné nezabudnúť aj na správne zakódovanie URL ako takého.
ℹ️ Správanie hranatej syntaxe v URL: ak všetky identifikátory smerujú na ten istý záznam, server presmeruje na jeho číselné ID; ak si odporujú, odpovie 400; neexistujúci identifikátor v kombinácii s existujúcim sa ignoruje.
Externé identifikátory
Mazanie externých identifikátorov
Vykonáva sa atribútom evidencie removeExternalIds, kde jeho hodnota predstavuje prefix externých identifikátorov, ktoré sa majú odstrániť.
Napr. majme objekt cenníka s ID=123 a externými identifikátormi SHOP:abc, SYSTEM-1 a SYSTEM-2. Potom nasledujúci príklad odstráni oba identifikátory začínajúce reťazcom SYSTEM a pridá nový identifikátor SHOP:123:
<?xml version="1.0"?>
<winstrom version="1.0">
<cenik removeExternalIds="ext:SYSTEM">
<id>123</id>
<id>ext:SHOP:123</id>
</cenik>
</winstrom>
Ekvivalentný zápis vo formáte JSON:
{
"winstrom": {
"@version": "1.0",
"cenik": [{
"id": [ "123", "ext:SHOP:123" ],
"@removeExternalIds": "ext:SYSTEM"
}]
}
}Prefix externého identifikátora ext: sa v hodnote atribútu nemusí uvádzať. Prázdny reťazec znamená, že chceme odstrániť všetky externé identifikátory.
Mazanie externých identifikátorov z položiek
Vykonáva sa podobne ako pri hlavnej evidencii s tým, že atribút removeExternalIds je možné uviesť spoločný pre všetky prítomné položky alebo priamo na konkrétnej položke (má prednosť):
<?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>
Vyššie uvedený príklad odoberie z položky 10 externé identifikátory začínajúce znakom P, zatiaľ čo z položky 20 externé identifikátory začínajúce znakom X. Externé identifikátory prípadných ďalších položiek na faktúre zostanú nezmenené.
Zápis predchádzajúceho príkladu vo formáte JSON by vyzeral takto:
{
"winstrom": {
"@version": "1.0",
"faktura-vydana": [{
"id": "123",
"polozkyFaktury": [
{ "id": "10" },
{ "id": "20", "@removeExternalIds": "ext:X" }
],
"polozkyFaktury@removeExternalIds": "ext:P"
}]
}
}
Hybridné identifikátory
Sú to identifikátory, ktoré sa správajú podľa kontextu použitia. Ak hodnota {UUID firmy} zodpovedá UUID firmy, do ktorej sa záznam importuje, potom sa aktualizuje záznam podľa hodnoty interného identifikátora {interní ID}. Ak sa UUID nezhoduje, potom funguje ako externý identifikátor.
Inými slovami, pri importe záznamu späť do firmy, kde bol záznam pôvodne vytvorený, dôjde k jeho aktualizácii na základe interného identifikátora. V prípade importu do cudzej firmy sa použije celý identifikátor, akoby išlo o externý.
Pri exporte sa použitie hybridných identifikátorov aktivuje režimom ?mode=xml_import_export (pozri parametre URL).