V posledním díle si ukážeme dva konkrétní příklady zápisu dat do ABRA Flexi přes REST API: založení ceníkové položky a založení vydané faktury s ochranou proti přepsání. Oba příklady uvádíme ve formátu XML i JSON.

🚨 Příklady nezkoušejte na ostrých účetních datech. Použijte kopii firmy, nebo si požadavek nejprve ověřte v režimu testovacího uložení doplněním parametru ?dry-run=true. Server pak požadavek zpracuje a zvaliduje, ale nic neuloží.

Než začnete

Pro sestavení požadavku potřebujete znát strojový název evidence a názvy jejích atributů. Obojí si můžete vypsat přímo z Flexi.

Seznam všech evidencí:

/c/<identifikátor firmy>/evidence-list

Atributy konkrétní evidence:

/c/<identifikátor firmy>/<evidence>/properties

Místo <evidence> uvádějte vždy strojový název, například adresar, cenik, faktura-vydana, faktura-prijata, objednavka-prijata, interni-doklad, banka, pokladna nebo faktura-vydana-polozka. Podrobnosti k oběma adresám najdete v díle o sestavování URL adresy.

Příklad 1: Založení ceníkové položky

Požadavek odešlete metodou POST na adresu výpisu evidence ceníku:

POST https://localhost:5434/c/testovaci/cenik.xml

Tělo požadavku ve formátu XML:

<?xml version="1.0" encoding="utf-8"?>
<winstrom version="1.0">
  <cenik>
    <id>ext:SHOP:123</id>
    <kod>KOD</kod>
    <nazev>POLOZKA_CENIKU</nazev>
    <mj1>code:KS</mj1>
    <typSzbDphK>typSzbDph.dphZakl</typSzbDphK>
    <typZasobyK>typZasoby.zbozi</typZasobyK>
    <cenaZakl>500</cenaZakl>
    <szbDph>21</szbDph>
  </cenik>
</winstrom>

Totéž ve formátu JSON:

{
  "winstrom": {
    "@version": "1.0",
    "cenik": [
      {
        "id": "ext:SHOP:123",
        "kod": "KOD",
        "nazev": "POLOZKA_CENIKU",
        "mj1": "code:KS",
        "typSzbDphK": "typSzbDph.dphZakl",
        "typZasobyK": "typZasoby.zbozi",
        "cenaZakl": "500",
        "szbDph": "21"
      }
    ]
  }
}

Požadavek vytvoří ceníkovou položku s:

externím identifikátorem 123 ze systému SHOP
kódem KOD
názvem POLOZKA_CENIKU
měrnou jednotkou KS
typem zásoby Zboží
základní sazbou DPH 21 %
cenou 500 Kč

ℹ️ Externí identifikátor se skládá z označení zdrojového systému a identifikátoru řádku v něm, tedy ve tvaru ext:SYSTEM:hodnota. Musí být unikátní v rámci celé evidence. Díky němu poznáte při opakovaném volání, že záznam už existuje, a nevytvoříte duplicitu. Více v článku o identifikátorech záznamů.

Příklad 2: Založení faktury bez přepsání existující

Druhý příklad zakládá vydanou fakturu, ale zároveň chrání data před nechtěným přepsáním:

POST https://localhost:5434/c/testovaci/faktura-vydana.xml

Tělo požadavku ve formátu XML:

<?xml version="1.0" encoding="utf-8"?>
<winstrom version="1.0">
  <faktura-vydana update="ignore">
    <id>ext:SHOP:456</id>
    <id>code:FAV01</id>
    <nazev>FAKTURA_01</nazev>
    <varSym>20183103</varSym>
    <stitky>VIP</stitky>
    <bankovniUcet>code:UCET01</bankovniUcet>
    <typDokl>code:FAKTURA</typDokl>
  </faktura-vydana>
</winstrom>

Totéž ve formátu JSON:

{
  "winstrom": {
    "@version": "1.0",
    "faktura-vydana": [
      {
        "@update": "ignore",
        "id": [
          "ext:SHOP:456",
          "code:FAV01"
        ],
        "nazev": "FAKTURA_01",
        "varSym": "20183103",
        "stitky": "VIP",
        "bankovniUcet": "code:UCET01",
        "typDokl": "code:FAKTURA"
      }
    ]
  }
}

Atribut update="ignore" znamená, že pokud faktura s kódem FAV01 nebo s externím identifikátorem SHOP:456 už existuje, požadavek na její změnu se ignoruje. Existující doklad tedy zůstane beze změny. Ostatní režimy popisuje článek o režimu pro založení a změnu.

⚠️ U dokladů je vždy nutné uvést typ dokladu v atributu typDokl. Bez něj Flexi neví, do jaké řady doklad zařadit, a požadavek skončí chybou.

Odpověď serveru

Na každý zápis odpoví server strukturou, ve které najdete, zda operace proběhla, kolik záznamů bylo zpracováno a jaké identifikátory dotčené záznamy dostaly.

<winstrom version="1.0">
  <success>true</success>
  <stats>
    <created>1</created>
    <updated>0</updated>
    <deleted>0</deleted>
    <skipped>0</skipped>
    <failed>0</failed>
  </stats>
  <result>
    <id>105</id>
  </result>
</winstrom>

Element success říká, zda požadavek uspěl. V stats najdete počty založených, změněných, smazaných a přeskočených záznamů. Právě podle skipped poznáte, že se uplatnil režim update="ignore". V result je pak identifikátor záznamu, se kterým Flexi pracovalo.

💡 Další hotové ukázky požadavků najdete v článku s příklady XML souborů. Praktický trénink na živých datech pak nabízí seriál API Ninja.

Další díly série

Související články

Jak začít s API Flexi 6/6 - Příklady XML a JSON