Identifikátory záznamů

Jak identifikovat záznamy v ABRA Flexi?

Lenka Haringerová avatar
Autor: Lenka Haringerová
Aktualizováno před více než týdnem

Název

Poznámka

Ukázka

Identifikátor ABRA Flexi

Identifikátor přidělený aplikací. Přiděluje ABRA Flexi a nelze jej měnit.

123

Kód/Zkratka

Uživatelské označení. Přiděleno uživatelem a je možné jej měnit v aplikaci.

code:CZK

Key

Unikátní náhodný identifikátor, který přiděluje ABRA Flexi dokladům (atribut UUID). Nelze jej měnit.

key:550e8400e29b41d4a716

PLU je identifikační kód, který se používá při prodeji. Obvykle se jedná o 4- či 5místný číselný kód.

plu:4020

Záznam je identifikován podle kódu EAN (čárový kód). Položku ceníku je možné dohledat jak podle jejího EAN tak podle EAN jejího balení. Počet importovaných položek ceníku se v tomto případě nemění.

ean:4710937332698

Externí identifikátor

Identifikátor z externí aplikace. V aplikaci jej nelze měnit. Lze měnit z externích systémů. Skládá se z identifikátoru externího systému a identifikátoru řádku v tomto systému. Externí identifikátor musí být unikátní pro celou evidenci (např. faktura-vydana)!

ext:SHOP:123

Hybridní identifikátor

Identifikátor ve formátu ws:{UUID firmy}:{interní ID}

ws:8ee0a075-67fa-4f92-880e-a7d65ab3c6e3:66

VAT ID

Identifikátor dle daňového čísla. V ČR odpovídá DIČ, v SR odpovídá IČO DPH.

vatid:CZ28019920

IČO

Identifikátor dle IČO.

in:28019920

IBAN

Identifikátor dle kódu IBAN.

iban:CZ1201000002801992

Díky inkrementální aktualizaci je možné libovolně připojovat další externí identifikátory k již existujícím záznamům:

<?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 případě JSON je validní i zápis kombinace identifikátorů:

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

Interní identifikátory

Interní identifikátor (samostatné číslo) jsou identifikátory, které přiděluje systém ABRA Flexi. Pokud se na něj odkážete a záznam neexistuje, operace selže (na rozdíl od ostatních identifikátorů).

Pro přidělování identifikátorů je používána databázová sequence. Ta zajišťuje, že stejný identifikátor nebude nikdy přidělen dvakrát (ani když záznam smažete). Současně negarantuje číselnou návaznost (např. při rollbacku se číslo zahodí).

Vytvoření / aktualizace záznamu

Pokud použijete pro identifikaci záznamu jiný typ identifikátoru než interní identifikátor (např. kód) a odkazovaný záznam nebude existovat, tak dojde k vytvoření nového záznamu. V opačném případě se provede aktualizace existujícího záznamu.

Následující ukázka XML / JSON zajistí aktualizaci, případně vytvoření, záznamu v ceníku se zkratkou T100 (hodnota identifikátoru zde nahrazuje uvedení atributu kod):

<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"
}
]
}
}

Vícenásobné identifikátory

Záznam je možné identifikovat také použitím několika identifikátorů zároveň:

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

V takovém případě musí všechny identifikátory označovat tentýž záznam, jinak jde o chybu. Identifikátory, které v ABRA Flexi neexistují, budou ignorovány, takže z externího systému lze poslat do ABRA Flexi všechny známé identifikátory a záznam bude nalezen podle těch existujících.

Více elementů id lze použít pouze v importním XML. Na jiných místech (URL v REST API, ostatní identifikátory záznamů v importním XML, ale u elementů id lze také) je potřeba používat specializovanou syntaxi: [123][code:CZK][ext:SHOP:abc].

Pokud identifikátor obsahuje znaky [, ] nebo , je potřeba je escapovat: [, ], \. Při použití v URL je třeba nezapomenout také na správné zakódování URL jako takového.

Mazání externích identifikátorů

Provádí se atributem evidence „removeExternalIds„, kde jeho hodnota představuje prefix externích identifikátorů, které se mají odstranit.

Např. mějme objekt ceníku s ID=123 a externími identifikátory: „SHOP:abc„, „SYSTEM-1“ a „SYSTEM-2„. Pak následující příklad odstraní oba identifikátory začínající řetězcem „SYSTEM“ a přidá 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 ve formátu JSON:

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

Prefix externího identifikátoru „ext:“ se v hodnotě atributu nemusí uvádět. Prázdný řetězec znamená, že chceme odstranit všechny externí identifikátory.

Mazání externích identifikátorů z položek

Provádí se podobně jako u hlavní evidence s tím, že atribut „removeExternalIds“ je možné uvést společný pro všechny přítomné položky a nebo přímo na konkrétní položce (má přednost):

<?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>

Výše uvedený příklad odebere z položky 10 externí identifikátory začínající znakem „P“, zatímco z položky 20 externí identifikátory začínající znakem „X“. Externí identifikátory případných dalších položek na faktuře zůstanou nezměněny.

Zápis předchozího příkladu ve formátu JSON by vypadal takto:

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


Hybridní identifikátory

Jsou to identifikátory, který se chovají dle kontextu použití. Pokud hodnota {UUID firmy} odpovídá UUID firmy, do které se záznam importuje, pak se aktualizuje záznam dle hodnoty interního identifikátoru {interní ID}. Pokud se UUID neshoduje, pak funguje jako externí identifikátor.

Jinými slovy při importu záznamu zpět do firmy, kde byl záznam původně vytvořen, dojde k jeho aktualizaci na základě interního identifikátoru. V případě importu do cizí firmy se použije celý identifikátor, jako by se jednalo o externí.

Při exportu se použití hybridních identifikátorů aktivuje režimem ?mode=xml_import_export (viz parametry URL).

Dostali jste odpověď na svou otázku?