Dávkové operácie

Dávkové API - správa servera

Petr Pech avatar
Written by Petr Pech
Updated over a week ago

Pre partnerské riešenia, ktoré potrebujú spravovať inštancie ABRA Flexi v cloude, sme pripravili API, ktoré to umožňuje. Jeho stav je stále beta a tento dokument opisuje plánovaný stav. Pred použitím všetko dôkladne skontrolujte.

Overovanie žiadostí voči ABRA Flexi

ABRA Flexi podporuje niekoľko metód tzv. serverovej autorizácie:

  • meno a heslo servera - po zadaní špeciálneho mena a hesla sa akceptuje autorizácia servera. Toto riešenie nie je použiteľné v cloude.

  • Klientský certifikát - umožňuje nám mať certifikát pre každého partnera alebo inštanciu, ktorá umožňuje správu. Toto riešenie zatiaľ nie je použiteľné mimo cloudu.

Názov a heslo servera

Pre tento typ autorizácie musíte upraviť súbor /etc/flexibee/server-auth.xml a pridať:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
<properties>
  <comment>Konfigurácia servera WinStrom</comment>
  <entry key="username">winstrom-server-admin</entry>
  <entry key="password">very-secret-and-worthy-long-password</entry>
</properties>

Po reštartovaní servera sa už používateľské meno a heslo neakceptuje.

Poznámka: heslo musí mať aspoň 15 znakov. Toto heslo umožní prístup ku všetkým údajom v inštalácii. Uložte ho bezpečne!

Certifikát klienta

Bezpečnejším spôsobom je použitie certifikátu. Môžete ho použiť na autorizáciu pre prístup správcu. Na komunikáciu musíte použiť protokol HTTPS a pripojiť sa na port 7000. Na serveri je uložený iba odtlačok certifikátu (odtlačok SHA1).

Odtlačok certifikátu možno získať takto:

openssl x509 -noout -in cert.pem -fingerprint

Tento odtlačok sa musí odoslať na podporu a bude nastavený na inštanciu alebo strom inštancií (zoskupenie inštancií).

Vydávanie sa za používateľa

V niektorých prípadoch je potrebné, aby sa server prihlásil a potom sa vydával za jedného z používateľov.

To sa dá dosiahnuť pridaním záhlavia:

X-FlexiBee-Authorization: meno.

Od tohto momentu sa všetky zmeny vrátane oprávnení budú vykonávať pod týmto používateľom.

Scenáre používania API

Celé rozhranie ABRA Flexi REST API pracuje vždy nad jednou databázou s údajmi o firme. Výnimkou je správa používateľov a spoločností. Tá sa zo spoločnosti odstráni a uloží iným spôsobom. Informácie o používateľovi sa nachádzajú v databáze centralServer pri bežnej inštalácii. Spoločnosti sú v jednotlivých databázach. V prípade cloudovej operácie sa informácie nachádzajú vo vysoko replikovanej databáze CouchDB.

Ak by sa spracovanie vykonávalo vo viacerých požiadavkách, je možné, že pri prideľovaní práv používateľa spoločnosti by obsluhujúci server nevedel, že spoločnosť alebo používateľ sú už vytvorené. Preto bolo vytvorené toto dávkové rozhranie API, kde sa zoznam operácií odovzdáva a vykonáva jediným serverom, aby sa zabezpečila konzistentnosť.

Keďže požiadavka môže zlyhať (napríklad keď je jedna zo zložiek dočasne nedostupná), požiadavka sa môže opakovať. Potom sa všetko opäť vykoná tak, ako bolo zadané. Ak už bola zmena vykonaná, operácia sa preskočí (operácie sú idempotentné).

Vytvorenie účtu správcu inštancie ABRA Flexi a predvolenej účtovnej spoločnosti

Pri vytvorení ADMIN účtu v ABRA Flexi sa vytvorí predvolená účtovná firma podľa údajov z objednávky (budeme mať názov firmy, IČO).

Nie je možné vytvoriť spoločnosť bez používateľa administrátora.

<?xml version="1.0"?>

Štandardné užívateľské role v systéme ABRA Flexi

  • ADMIN

  • SUPERUSER

  • MZDOVYUCETNI

  • UCETNI

  • OBCHODNÝ MANAŽÉR

  • COLLECTOR

  • SKLADNÍK

  • UŽÍVATEĽ

  • JENCIST

  • ZABLOKOVANÉ

Typ organizácie + záznamy

Podvojné účtovníctvo je štandardom pre všetky typy organizácií.

  • BUSINESS

  • ENTREPRENEURS+PU (dvojitý vstup)

  • ENTREPRENEURS+DE (daňové účtovníctvo)

  • VÝVOJ

  • NON-PROFIT

  • PODNIKATELIA (len na Slovensku)

Podporované hash funkcie na ukladanie hesiel

  • sha256 (predvolené nastavenie pre ukladanie hesiel odoslaných v obyčajnom texte)

  • sha512

  • sha1

  • md5

  • pbkdf2 (najbezpečnejšia, ale aj najpomalšia metóda - bez použitia relácie REST API je potom nepoužiteľná - je zámerne príliš pomalá).

Ukážka programu na výpočet odtlačku hesla pre ABRA Flexi.

import org.apache.commons.codec.binary.Hex; public static final String SHA256 = "sha256"; public static final String SEPARATOR = ":"; protected static String encryptPasswordSHA256(String plain, String salt) { String toDigest = salt + SEPARATOR + plain; try { MessageDigest md = MessageDigest.getInstance("SHA-256"); byte[] result = md.digest(toDigest.getBytes("utf-8")); return SHA256 + SEPARATOR + salt + SEPARATOR + new String(Hex.encodeHex(result)); } catch (UnsupportedEncodingException e) { throw new RuntimeException(e); } catch (GeneralSecurityException e) { throw new RuntimeException(e); } } } } public static String getRandomSalt() { byte[] b = new byte[10]; new Random().nextBytes(b); return new String(Hex.encodeHex(b)).substring(10); } String plain = "moje heslo"; String result = encryptPasswordSHA256(plain, getRandomSalt());

Vytvorenie ďalších "bežných" používateľov

Týchto používateľov vytvorí správca nájomcu z portálu správcu ako nových používateľov. Pri zmene profilu na portáli administrátora sa bude volať aj hromadne pre viacerých používateľov.

<?xml version="1.0"?>

Heslo je možné uložiť aj bez preklopenia, ale dôrazne sa to neodporúča!

Zmena hesla existujúceho používateľa

<?xml version="1.0"?>

Odstránenie existujúceho používateľa

Odstránenie používateľa z portálu administrátora = uvoľnenie licencie. Pri zmene profilu sa zavolá aj hromadne pre viacerých používateľov.

<?xml version="1.0"?>

Poznámka: ak bol používateľ vymazaný a neskôr som nastavil create-update, mal by byť obnovený.

Obnovenie používateľa

<?xml version="1.0"?>

Poznámka: pri vytváraní a aktualizácii používateľa sa najprv pokúsi recyklovať záznamy s príznakom "deleted". Všetky nastavenia prístupu a rolí sa zachovajú.

Blokovanie existujúceho používateľa

Zablokovanie používateľa na portáli správcu = nemôže sa prihlásiť.

<?xml version="1.0"?>

Odblokovanie používateľa

<?xml version="1.0"?>
<flexibee-batch id="abc-123456">
  <user action="create-update">
    <username>anna.mlada</username>
    <blocked>false</blocked>
  </user>
</flexibee-batch>

Pridanie úlohy ADMIN existujúcemu používateľovi

Pridajte atómovú rolu "Správca ERP" na portál administrátora. Môže sa tiež hromadne vyvolať pre viacerých používateľov pri zmene profilu na portáli správcu.

<?xml version="1.0"?>
<flexibee-batch id="abc-1234567">
  <user action="create-update">
    <username>anna.mlada</username>
    <defaultRole>ADMIN</defaultRole>
  </user>
  <access role="ADMIN"/>
</flexibee-batch>

Odstránenie úlohy ADMIN existujúcemu používateľovi

Odstráňte atómovú rolu "Správca ERP" na portáli správcu. Môže sa tiež hromadne vyvolať pre viacerých používateľov pri zmene profilu na portáli správcu.

<?xml version="1.0"?>
<flexibee-batch id="abc-12345678">
  <user action="create-update">
    <username>anna.mlada</username>
    <defaultRole>UZIVATEL</defaultRole>
  </user>
  <access role="UZIVATEL"/>
</flexibee-batch>

Zmena mena, priezviska existujúceho používateľa

<?xml version="1.0"?>

Skryť / zobraziť spoločnosť (odpojiť)

<?xml version="1.0"?>
<flexibee-batch id="abc-123">
  <company action="create-update">
    <id>digital_media_s_r_o_</id>
    <show>false</show>
    <!-- true to show -->
  </company>
</flexibee-batch>

Odstránenie spoločnosti

<?xml version="1.0"?>
<flexibee-batch id="abc-123">
  <company action="delete">
    <id>digital_media_s_r_o_</id>
  </company>
</flexibee-batch>

Používanie rozhrania API

Platí pre prvú zverejnenú testovaciu verziu s funkčným vytvorením používateľa v centrálnej databáze.

Zavolajte na

Žiadosť musí byť autorizovaná.

XML s požiadavkou je možné odoslať pomocou curl nasledovne:

curl -3 'https://server:7000/admin/batch' -T batch.xml -E cert.pem

Žiadosť o vzorku

batch.xml

<?xml version="1.0"?>

Odpoveď

V prípade úspechu (HTTP 200) sa odošle XML v tomto formáte:

<?xml version="1.0"?>

Výpočet typu subjektu

  • UŽÍVATEĽ

  • SPOLOČNOSŤ

  • ACCESS_LIST

Zoznam typov akcií

  • CREATE_UPDATE

  • DELETE

Zoznam stavových kódov

  • VYTVORENÉ

  • AKTUALIZOVANÉ

  • ZRUŠENÉ

  • FAILED (popis dôvodu chyby bude v prvku <message>)

  • SKIPPED (možno pridať do prvku <message>)

Did this answer your question?