REST API ABRA Flexi pracuje s dvoma základnými typmi požiadaviek: čítaním dát a ich zápisom. V tomto diele si prejdeme, ako sa ktorá operácia správa, ako sa záznamy mažú a stornujú a ako spoznáte identifikátor novo vytvoreného záznamu.
Čítanie záznamov
Dáta sa čítajú metódou GET. Server pritom zohľadní výstupný formát, ktorý uvediete ako príponu adresy alebo v hlavičke Accept.
GET https://demo.flexibee.eu/c/demo/faktura-vydana.xml
Rozsah vrátených dát môžete obmedziť filtrom, stránkovaním alebo úrovňou detailu, ako popisuje diel o zostavovaní URL adresy.
Vytvorenie a aktualizácia záznamu
ABRA Flexi nerozlišuje medzi metódami POST a PUT. Význam požiadavky vždy závisí od cieľovej adresy a od obsahu, ktorý pošlete.
Ak ukladáte na adresu výpisu evidencie, budú záznamy pridané alebo aktualizované podľa toho, či sa podarilo nájsť identifikátor.
Ak ukladáte na adresu konkrétneho záznamu, telo požiadavky nemusí identifikátor obsahovať. Prevezme sa z adresy. Takýto záznam ale musí existovať.
Cez adresu výpisu je možné upraviť viacero záznamov naraz. Záznamy s interným identifikátorom prideleným Flexi musia existovať; záznamy identifikované napríklad externým ID budú v prípade potreby založené.
⚠️ Metóda POST očakáva dáta vo formáte XML alebo JSON, nie ako formulárové dáta (multipart/form-data). Odoslanie formulárových dát je častou príčinou chyby 400.
Správanie pri zápise je možné riadiť aj podľa toho, či záznam už existuje. Slúžia na to atribúty create a update s hodnotami ok, ignore a fail. Vďaka nim môžete napríklad zaistiť, že sa existujúci záznam neprepíše. Podrobnosti popisuje článok o režime pre založenie a zmenu.
Mazanie a storno záznamov
Na odstránenie záznamu použite akciu action="delete" priamo v tele importnej požiadavky. Rovnakým spôsobom je možné doklad stornovať pomocou action="storno".
<?xml version="1.0" encoding="utf-8"?>
<winstrom version="1.0">
<faktura-vydana action="delete">
<id>123</id>
</faktura-vydana>
</winstrom>
Pri vykonávaní akcií sa záznamy inak nemenia, nemá teda zmysel uvádzať iné elementy než
id.Záznamy musia už existovať. Nie je napríklad možné rovno vytvoriť vymazanú faktúru.
Storno je možné použiť iba pre doklady.
V jednej požiadavke takto spracujete aj viacero záznamov naraz.
Akciu je možné vyvolať aj na položkách dokladu, a to prostredníctvom kolekcie položiek na zodpovedajúcom doklade. Kompletný popis nájdete v článku o vykonávaní akcií.
🚨 Mazanie a storno sú zásahy do účtovných dát. Skôr než akciu spustíte na ostrých dátach, vyskúšajte si ju na kópii firmy alebo si požiadavku overte v režime testovacieho uloženia ?dry-run=true.
Formát vstupu a výstupu
Formát, v ktorom dáta posielate, a formát odpovede sú vždy zhodné a nie je možné ich kombinovať. Vstupný formát určíte hlavičkou Content-Type alebo príponou v adrese.
Content-Type: application/xml
https://demo.flexibee.eu/c/demo/faktura-vydana.xml
Prehľad všetkých podporovaných formátov nájdete v nasledujúcom diele.
Identifikátor nového záznamu
Po úspešnom vytvorení záznamu vám server jeho identifikátor vráti dvoma spôsobmi. Jednak v HTTP hlavičke Location:
Location: https://demo.flexibee.eu:5434/c/demo/faktura-vydana/105
A tiež priamo v tele odpovede:
<winstrom version="1.0">
<success>true</success>
<result>
<id>105</id>
</result>
</winstrom>
💡 Vrátený identifikátor si v integrácii uložte. Pri ďalších volaniach sa potom môžete na záznam odkázať priamo, bez toho aby ste ho museli dohľadávať. Viac o možnostiach identifikácie popisuje článok o identifikátoroch záznamov.
Úplnú referenčnú dokumentáciu k operáciám nájdete v článku podporované HTTP operácie.
Ďalšie diely série
Čítanie, zápis a mazanie záznamov (tento článok)