V poslednom diele si ukážeme dva konkrétne príklady zápisu dát do ABRA Flexi cez REST API: založenie cenníkovej položky a založenie vydanej faktúry s ochranou proti prepísaniu. Oba príklady uvádzame vo formáte XML aj JSON.

🚨 Príklady neskúšajte na ostrých účtovných dátach. Použite kópiu firmy, alebo si požiadavku najprv overte v režime testovacieho uloženia doplnením parametra ?dry-run=true. Server potom požiadavku spracuje a zvaliduje, ale nič neuloží.

Skôr než začnete

Na zostavenie požiadavky potrebujete poznať strojový názov evidencie a názvy jej atribútov. Oboje si môžete vypísať priamo z Flexi.

Zoznam všetkých evidencií:

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

Atribúty konkrétnej evidencie:

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

Namiesto <evidence> uvádzajte vždy strojový názov, napríklad adresar, cenik, faktura-vydana, faktura-prijata, objednavka-prijata, interni-doklad, banka, pokladna alebo faktura-vydana-polozka. Podrobnosti k obom adresám nájdete v diele o zostavovaní URL adresy.

Príklad 1: Založenie cenníkovej položky

Požiadavku odošlite metódou POST na adresu výpisu evidencie cenníka:

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

Telo požiadavky vo formáte 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>

To isté vo formáte 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žiadavka vytvorí cenníkovú položku s:

externým identifikátorom 123 zo systému SHOP
kódom KOD
názvom POLOZKA_CENIKU
mernou jednotkou KS
typom zásoby Tovar
základnou sadzbou DPH 21 %
cenou 500 Kč

ℹ️ Externý identifikátor sa skladá z označenia zdrojového systému a identifikátora riadku v ňom, teda v tvare ext:SYSTEM:hodnota. Musí byť unikátny v rámci celej evidencie. Vďaka nemu pri opakovanom volaní zistíte, že záznam už existuje, a nevytvoríte duplicitu. Viac v článku o identifikátoroch záznamov.

Príklad 2: Založenie faktúry bez prepísania existujúcej

Druhý príklad zakladá vydanú faktúru, ale zároveň chráni dáta pred nechceným prepísaním:

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

Telo požiadavky vo formáte 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>

To isté vo formáte 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"
      }
    ]
  }
}

Atribút update="ignore" znamená, že ak faktúra s kódom FAV01 alebo s externým identifikátorom SHOP:456 už existuje, požiadavka na jej zmenu sa ignoruje. Existujúci doklad teda zostane bez zmeny. Ostatné režimy popisuje článok o režime pre založenie a zmenu.

⚠️ Pri dokladoch je vždy nutné uviesť typ dokladu v atribúte typDokl. Bez neho Flexi nevie, do akej rady doklad zaradiť, a požiadavka skončí chybou.

Odpoveď servera

Na každý zápis odpovie server štruktúrou, v ktorej nájdete, či operácia prebehla, koľko záznamov bolo spracovaných a aké identifikátory dotknuté záznamy dostali.

<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 hovorí, či požiadavka uspela. V stats nájdete počty založených, zmenených, zmazaných a preskočených záznamov. Práve podľa skipped zistíte, že sa uplatnil režim update="ignore". V result je potom identifikátor záznamu, s ktorým Flexi pracovalo.

💡 Ďalšie hotové ukážky požiadaviek nájdete v článku s príkladmi XML súborov. Praktický tréning na živých dátach ponúka seriál API Ninja.

Ďalšie diely série

Sorodni članki

Ako začať s API Flexi 6/6 - Príklady XML a JSON