Je-li Changes API zapnuté, ABRA Flexi zaznamenává všechny změny provedené v databázi firmy do changelogu a umožňuje seznam změn zpětně získat.

Změny jsou vzestupně číslované, takže firma má v každém okamžiku dobře definovanou globální verzi. Čísla verzí nemusí následovat těsně po sobě — v řadě mohou být z technických důvodů mezery — vždy je však číslo verze unikátní a rostoucí. Toho lze využít k automatizované synchronizaci externích systémů s ABRA Flexi a jde také o základ pro funkci okamžitého upozorňování na změny, tedy Web Hooks.

⚠️ Licence ABRA Flexi musí mít aktivní REST API minimálně pro čtení. To mají všechny nové placené licence již standardně. Bez aktivního REST API pro čtení či zápis vrací volání 403 Forbidden.

Zapnutí a vypnutí

Nejsnáze se stav zjistí a Changes API zapne či vypne ve webovém rozhraní na adrese /c/{firma}/changes/control. Programově k tomu slouží dvě adresy, volané metodou PUT nebo POST:

PUT https://demo.flexibee.eu/c/demo/changes/enable.xml
PUT https://demo.flexibee.eu/c/demo/changes/disable.xml

Požadavek nemá tělo, proto k němu přidejte hlavičku Content-Length: 0.

🚨 Zapnutí i vypnutí Changes API mění strukturu databáze, a proto potřebuje exkluzivní zámek — viz chybu s uzamčením relace níže. Neprovádějte je tedy, když v firmě někdo pracuje.

Zjištění stavu zapnutí

Potřebujete-li stav zjistit programově, použijte:

GET https://demo.flexibee.eu/c/demo/changes/status.xml

Je-li Changes API zapnuté, odpověď obsahuje success s hodnotou true:

<?xml version="1.0" ?>
<winstrom version="1.0">
  <success>true</success>
  <message>Changelog is enabled.</message>
</winstrom>

Pokud je odpovědí false nebo chyba — což nastane, není-li povolené REST API — je Changes API vypnuté.

Získání aktuální globální verze

Do jakéhokoliv XML či JSON exportu získaného přes REST API lze doplnit aktuální globální verzi přidáním parametru ?add-global-version=true. Odpověď pak vypadá takto:

<?xml version="1.0"?>
<winstrom version="1.0" globalVersion="6">
    ...
</winstrom>

Získání záznamů o změnách

Na adrese /c/{firma}/changes.xml najdete seznam všech změn od začátku jejich sledování:

GET https://demo.flexibee.eu/c/demo/changes.xml

<?xml version="1.0"?>
<winstrom globalVersion="6">
  <faktura-vydana in-version="3" operation="create" timestamp="2019-01-01 00:00:00.0">
    <id>1</id>
  </faktura-vydana>
  <faktura-vydana-polozka in-version="4" operation="create" timestamp="2019-06-07 12:34:56.7">
    <id>1</id>
  </faktura-vydana-polozka>
  <faktura-vydana in-version="5" operation="update" timestamp="2019-06-07 12:34:56.7">
    <id>1</id>
    <id>code:VF1-0001/2012</id>
  </faktura-vydana>
  <next>6</next>
</winstrom>

Uvedeno je vždy číselné ID objektu (<id>1</id>) a kód (<id>code:KÓD</id>); pokud měl objekt v době provádění operace i nějaká externí ID, jsou uvedena i ta (<id>ext:...</id>).

V atributech každého elementu je uvedeno, v jaké verzi k operaci došlo (in-version) a o jakou operaci šlo (operation; možné hodnoty jsou create, update a delete). Vždy je přítomen atribut globalVersion. Posledním elementem ve výpisu je vždy next, který udává číslo verze, kterou by tento výpis pokračoval, případně none, pokud žádné další změny nejsou.

Výpis lze upravit následujícími parametry:

`?start=123`	Od které verze se má vypisovat (včetně); defaultně od počátku sledování.
`?limit=500`	Kolik záznamů se má vypsat; defaultně 100, maximálně 1000.
`?evidence=faktura-vydana`	Pro které evidence se mají změny vypisovat; lze uvést vícekrát, není-li uvedeno, vypisují se všechny.

⚠️ Vyšší limit než 1000 se tiše sníží na 1000 a neznámý název evidence v parametru ?evidence= se tiše ignoruje — výpis pak vrátí změny všech evidencí. Názvy si proto ověřte v tabulkách níže.

Ve formátu JSON vypadají změny takto:

{
    "winstrom": {
        "@globalVersion": "8",
        "changes": [
            {
                "@evidence": "faktura-vydana",
                "@in-version": "3",
                "@operation": "create",
                "@timestamp": "2019-01-01 00:00:00.0",
                "id": "1",
                "external-ids": []
            },
            {
                "@evidence": "faktura-vydana-polozka",
                "@in-version": "4",
                "@operation": "create",
                "@timestamp": "2019-06-07 12:34:56.7",
                "id": "1",
                "external-ids": []
            },
            {
                "@evidence": "faktura-vydana",
                "@in-version": "5",
                "@operation": "update",
                "@timestamp": "2019-06-07 12:34:56.7",
                "id": "1",
                "external-ids": [
                    "code:VF1-0001\/2012"
                ]
            }
        ],
        "next": "6"
    }
}

Synchronizace externích systémů s ABRA Flexi

Verzované změny lze snadno využít k efektivní synchronizaci externích systémů s ABRA Flexi — na rozdíl od data poslední změny. Postup je následující.

Počáteční nahrání dat

Získat aktuální data včetně jejich verze (?add-global-version=true).
Uložit data.
Zapamatovat si verzi z atributu globalVersion.

Rozdílová synchronizace

Stáhnout změny od poslední zapamatované verze (?start=).
Stáhnout změněná data a uložit je, případně smazat odstraněná data.
Zapamatovat si verzi z elementu next, případně z atributu globalVersion.
Opakovat od kroku 1.

Chyba „could not obtain lock on relation"

Zobrazí-li se vám při zapínání nebo vypínání Changes API chyba ERROR: could not obtain lock on relation "????", nezoufejte. Kvůli výkonnosti nejsou funkce, které Changes API obsluhují, v databázi vůbec přidané — zaneseme je do systému teprve při jeho aktivaci, a proto je potřeba exkluzivně zamknout celou databázi.

Řešením je odhlásit se z ABRA Flexi, a to jak z webového rozhraní, tak z klientské aplikace. Pak už operace projde.

Ukázka chyby:

ERROR: could not obtain lock on relation "drady"
Kde: SQL statement "LOCK TABLE drady IN ACCESS EXCLUSIVE MODE NOWAIT"

Endpointy logované v Changes API

Adresář a kontakty

Agenda	Endpoint
Adresář	`adresar`
Bankovní účet (adresář)	`adresar-bankovni-ucet`
Kontakt	`kontakt`
Místo určení	`misto-urceni`
PSČ	`psc`
Skupina firem	`skupina-firem`
Peněžní ústav	`penezni-ustav`
Stát	`stat`
Typ aktivity	`typ-aktivity`
Typ nákladu	`typ-nakladu`

Ceník a zboží

Agenda	Endpoint
Atribut	`atribut`
Cenová úroveň	`cenova-uroven`
Ceník	`cenik`
Dodavatel	`dodavatel`
Kusovník	`kusovnik`
Měrná jednotka	`merna-jednotka`
Odběratel	`odberatel`
Podobné zboží	`podobne-zbozi`
Poplatek	`poplatek`
Příslušenství	`prislustenstvi`
Sady a komplety	`sady-a-komplety`
Ceníková skupina	`cenikova-skupina`
Skupina zboží	`skupina-zbozi`
Typ atributu	`typ-atributu`
Skupina atributů	`skupina-atributu`
Stav ceníku	`stav-ceniku`

Doklady — faktury a pohledávky

Agenda	Endpoint
Faktura přijatá	`faktura-prijata`
Faktura přijatá — položka	`faktura-prijata-polozka`
Faktura vydaná	`faktura-vydana`
Faktura vydaná — položka	`faktura-vydana-polozka`
Prodejka *	`prodejka`
Prodejka — položka *	`prodejka-polozka` (viz `faktura-vydana-polozka`)
Pohledávka	`pohledavka`
Pohledávka — položka	`pohledavka-polozka`
Závazek	`zavazek`
Závazek — položka	`zavazek-polozka`
Typ faktury přijaté	`typ-faktury-prijate`
Typ faktury vydané	`typ-faktury-vydane`
Typ prodejky *	`typ-prodejky`
Typ pohledávky	`typ-pohledavky`
Typ závazku	`typ-zavazku`

Doklady — banka, pokladna, interní doklady

Agenda	Endpoint
Banka *	`banka`
Banka — položka	`banka-polozka`
Vzájemný zápočet *	`vzajemny-zapocet`
Typ banky *	`typ-banka`
Typ vzájemných zápočtů *	`typ-vzajemnych-zapoctu`
Pokladní pohyb	`pokladni-pohyb`
Pokladní pohyb — položka	`pokladni-pohyb-polozka`
Typ pokladního pohybu	`typ-pokladni-pohyb`
Interní doklad	`interni-doklad`
Interní doklad — položka	`interni-doklad-polozka`
Typ interního dokladu	`typ-interniho-dokladu`

Doklady — obchodní

Agenda	Endpoint
Nabídka přijatá	`nabidka-prijata`
Nabídka přijatá — položka	`nabidka-prijata-polozka`
Nabídka vydaná	`nabidka-vydana`
Nabídka vydaná — položka	`nabidka-vydana-polozka`
Objednávka přijatá	`objednavka-prijata`
Objednávka přijatá — položka	`objednavka-prijata-polozka`
Objednávka vydaná	`objednavka-vydana`
Objednávka vydaná — položka	`objednavka-vydana-polozka`
Poptávka přijatá	`poptavka-prijata`
Poptávka přijatá — položka	`poptavka-prijata-polozka`
Poptávka vydaná	`poptavka-vydana`
Poptávka vydaná — položka	`poptavka-vydana-polozka`
Typ nabídky přijaté	`typ-nabidky-prijate`
Typ nabídky vydané	`typ-nabidky-vydane`
Typ objednávky přijaté	`typ-objednavky-prijate`
Typ objednávky vydané	`typ-objednavky-vydane`
Typ poptávky přijaté	`typ-poptavky-prijate`
Typ poptávky vydané	`typ-poptavky-vydane`
Stav obchodního dokladu	`stav-obchodniho-dokladu`
Forma dopravy	`forma-dopravy`
Forma úhrady	`forma-uhrady`
Platba prodejky	`prodejka-platba`
Forma úhrady — zaúčtování	`forma-uhrady-zauctovani`

Doklady — sklad

Agenda	Endpoint
Skladový pohyb	`skladovy-pohyb`
Skladový pohyb — položka	`skladovy-pohyb-polozka`
Typ skladového pohybu	`typ-skladovy-pohyb`
Skladová karta	`skladova-karta`
Inventura	`inventura`
Inventura — položka	`inventura-polozka`
Rezervace	`rezervace`
Mapování skladu	`mapovani-skladu`
Umístění ve skladu — místnost *	`umisteni-ve-skladu-mistnost`
Umístění ve skladu — regál *	`umisteni-ve-skladu-regal`
Umístění ve skladu — police *	`umisteni-ve-skladu-police`
Výrobní číslo	`vyrobni-cislo`

Doklady — smlouvy

Agenda	Endpoint
Smlouva *	`smlouva`
Dodavatelská smlouva *	`dodavatelska-smlouva`
Smlouva — položka	`smlouva-polozka`
Typ smlouvy *	`typ-smlouvy`
Dodavatelský typ smlouvy *	`dodavatelsky-typ-smlouvy`
Stav smlouvy	`stav-smlouvy`

Příkazy k úhradě a číselníky plateb

Agenda	Endpoint
Příkaz k úhradě	`prikaz-k-uhrade`
Bankovní účet	`bankovni-ucet`
Pokladna	`pokladna`
Sklad	`sklad`
Číslo balíku	`cislo-baliku`
Konstantní symbol	`konst-symbol`
Formát elektronického bankovnictví	`format-elektronickeho-bankovnictvi`

Účetnictví

Agenda	Endpoint
Účetní osnova	`ucetni-osnova`
Účet	`ucet`
Účetní období	`ucetni-obdobi`
Obrat	`obrat`
Řádek přiznání DPH	`radek-priznani-dph`
Sazba DPH	`sazba-dph`
Členění DPH	`cleneni-dph`
Přenesení DPH	`preneseni-dph`
Činnost	`cinnost`
Středisko	`stredisko`
Zakázka	`zakazka`
Typ zakázky	`typ-zakazky`
Stav zakázky	`stav-zakazky`
Hodnocení zakázky	`hodnoceni-zakazky`
Předpis zaúčtování	`predpis-zauctovani`
Typ organizace	`typ-organizace`

Kurzy

Agenda	Endpoint
Kurz (obecný) *	`kurz`
Kurz pro cenotvorbu *	`kurz-pro-cenotvorbu`
Intrastat — kurz *	`intrastat-kurz`
Měna	`mena`

Intrastat

Agenda	Endpoint
Intrastat — dodací podmínky	`intrastat-dodaci-podminky`
Intrastat — druh dopravy	`intrastat-druh-dopravy`
Intrastat — měrná jednotka	`intrastat-merna-jednotka`
Intrastat — kraj určení	`intrastat-kraj-urceni`
Intrastat — kód nomenklatury	`intrastat-kod-nomenklatury`
Intrastat — obchodní transakce	`intrastat-obchodni-transakce`
Intrastat — zvláštní pohyb	`intrastat-zvlastni-pohyb`

Řady dokladů

Agenda	Endpoint
Řada	`rada`
Řada — banka	`rada-banka`
Řada — faktury přijaté	`rada-faktury-prijate`
Řada — faktury vydané	`rada-faktury-vydane`
Řada — interního dokladu	`rada-interniho-dokladu`
Řada — nabídky přijaté	`rada-nabidky-prijate`
Řada — nabídky vydané	`rada-nabidky-vydane`
Řada — objednávky přijaté	`rada-objednavky-prijate`
Řada — objednávky vydané	`rada-objednavky-vydane`
Řada — pohledávky	`rada-pohledavky`
Řada — pokladního pohybu	`rada-pokladni-pohyb`
Řada — poptávky přijaté	`rada-poptavky-prijate`
Řada — poptávky vydané	`rada-poptavky-vydane`
Řada — skladového pohybu	`rada-skladovy-pohyb`
Řada — závazků	`rada-zavazku`
Roční řada	`rocni-rada`

Nastavení a systém

Agenda	Endpoint
Nastavení	`nastaveni`
Parametr	`parametr`
Příloha	`priloha`
Report	`report`
Role	`role`
Text	`text`
Uživatel	`uzivatel`
Zástupost	`zastupnost`
Žurnál	`zurnal`
Filtr	`filtr`
Uživatelský dotaz	`uzivatelsky-dotaz`
Uživatelský dotaz — parametr	`uzivatelsky-dotaz-parametr`
Uživatelský dotaz — vlastnost	`uzivatelsky-dotaz-vlastnost`
Uživatelská vazba	`uzivatelska-vazba`
Typ uživatelské vazby	`typ-uzivatelske-vazby`
Právo viditelnosti	`pravo-viditelnosti`
Certifikační autorita	`certifikacni-autorita`
Skupina štítků	`skupina-stitku`
Štítek	`stitek`
Strom (kořen)	`strom-koren`
Strom	`strom`
Strom — ceník	`strom-cenik`
Vazba	`vazba`

Související články