Identifikátory záznamů

Záznamy ve FlexiBee je možné identifikovat několika způsoby:

Název Poznámka Ukázka
Identifikátor FlexiBee Identifikátor přidělený aplikací FlexiBee. Přiděluje FlexiBee 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 FlexiBee dokladům (atribut UUID). Nelze jej měnit. key:550e8400e29b41d4a716
PLU 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
EAN 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
VAT ID Identifikátor dle daňového čísla. V ČR odpovídá DIČ, v SR odpovídá IČ DPH. vatid:CZ28019920
Identifikátor dle IČ. 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:

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

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

Interní identifikátory

Interní identifikátor (samostatné číslo) jsou identifikátory, které přiděluje systém FlexiBee. 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ň:

<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é ve FlexiBee neexistují, budou ignorovány, takže z externího systému lze poslat do FlexiBee 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„:

<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):

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