REST API ABRA Flexi pracuje se dvěma základními typy požadavků: čtením dat a jejich zápisem. V tomto díle si projdeme, jak se která operace chová, jak se záznamy mažou a stornují a jak poznáte identifikátor nově vytvořeného záznamu.
Čtení záznamů
Data se čtou metodou GET. Server přitom zohlední výstupní formát, který uvedete jako příponu adresy nebo v hlavičce Accept.
GET https://demo.flexibee.eu/c/demo/faktura-vydana.xml
Rozsah vrácených dat můžete omezit filtrem, stránkováním nebo úrovní detailu, jak popisuje díl o sestavování URL adresy.
Vytvoření a aktualizace záznamu
ABRA Flexi nerozlišuje mezi metodami POST a PUT. Význam požadavku vždy závisí na cílové adrese a na obsahu, který pošlete.
Pokud ukládáte na adresu výpisu evidence, budou záznamy přidány nebo aktualizovány podle toho, zda se podařilo najít identifikátor.
Pokud ukládáte na adresu konkrétního záznamu, nemusí tělo požadavku identifikátor obsahovat. Převezme se z adresy. Takový záznam ale musí existovat.
Přes adresu výpisu lze upravit více záznamů najednou. Záznamy s interním identifikátorem přiděleným Flexi musí existovat; záznamy identifikované například externím ID budou v případě potřeby založeny.
⚠️ Metoda POST očekává data ve formátu XML nebo JSON, nikoliv jako formulářová data (multipart/form-data). Odeslání formulářových dat je častou příčinou chyby 400.
Chování při zápisu lze řídit i podle toho, zda záznam už existuje. Slouží k tomu atributy create a update s hodnotami ok, ignore a fail. Díky nim můžete například zajistit, že se existující záznam nepřepíše. Podrobnosti popisuje článek o režimu pro založení a změnu.
Mazání a storno záznamů
Pro odstranění záznamu použijte akci action="delete" přímo v těle importního požadavku. Stejným způsobem lze doklad stornovat pomocí action="storno".
<?xml version="1.0" encoding="utf-8"?>
<winstrom version="1.0">
<faktura-vydana action="delete">
<id>123</id>
</faktura-vydana>
</winstrom>
Při provádění akcí se záznamy jinak nemění, nemá tedy smysl uvádět jiné elementy než
id.Záznamy musí již existovat. Nelze například rovnou vytvořit smazanou fakturu.
Storno lze použít pouze pro doklady.
V jednom požadavku takto zpracujete i více záznamů najednou.
Akce lze vyvolat i na položkách dokladu, a to prostřednictvím kolekce položek na odpovídajícím dokladu. Kompletní popis najdete v článku o provádění akcí.
🚨 Mazání a storno jsou zásahy do účetních dat. Než akci spustíte na ostrých datech, vyzkoušejte si ji na kopii firmy nebo si požadavek ověřte v režimu testovacího uložení ?dry-run=true.
Formát vstupu a výstupu
Formát, ve kterém data posíláte, a formát odpovědi jsou vždy shodné a nelze je kombinovat. Vstupní formát určíte hlavičkou Content-Type nebo příponou v adrese.
Content-Type: application/xml
https://demo.flexibee.eu/c/demo/faktura-vydana.xml
Přehled všech podporovaných formátů najdete v následujícím díle.
Identifikátor nového záznamu
Po úspěšném vytvoření záznamu vám server jeho identifikátor vrátí dvěma způsoby. Jednak v HTTP hlavičce Location:
Location: https://demo.flexibee.eu:5434/c/demo/faktura-vydana/105
A také přímo v těle odpovědi:
<winstrom version="1.0">
<success>true</success>
<result>
<id>105</id>
</result>
</winstrom>
💡 Vrácený identifikátor si v integraci uložte. Při dalších voláních se pak můžete na záznam odkázat přímo, aniž byste ho museli dohledávat. Více o možnostech identifikace popisuje článek o identifikátorech záznamů.
Úplnou referenční dokumentaci k operacím najdete v článku podporované HTTP operace.
Další díly série
Čtení, zápis a mazání záznamů (tento článek)