Pre partnerské riešenia, ktoré potrebujú spravovať inštancie ABRA Flexi v cloude, existuje dávkové API. Odovzdá sa mu zoznam operácií nad používateľmi a firmami a jeden server ich vykoná naraz, takže je zaistená konzistencia.

⚠️ Stav tohto API je zatiaľ beta a dokument popisuje aj plánovaný stav. Všetko si pred použitím dôkladne overte na testovacom prostredí.

Autentifikácia požiadaviek voči ABRA Flexi

ABRA Flexi podporuje niekoľko spôsobov takzvanej serverovej autorizácie:

Spôsob	Kde ho možno použiť
Serverovým menom a heslom	Len na vlastnej inštalácii — v cloude použiteľné nie je.
Klientským certifikátom	Zatiaľ len v cloude — mimo cloudu použiteľné nie je.
Prihláseným administrátorom	Kdekoľvek, ale len na verzovaných cestách a s obmedzením na vlastné licenčné skupiny.

Serverové meno a heslo

Pre tento typ autorizácie je nutné upraviť /etc/flexibee/server-auth.xml a doplniť:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
<properties>
  <comment>WinStrom server configuration</comment>
  <entry key="username">winstrom-server-admin</entry>
  <entry key="password">velmi-tajne-a-hodne-dlouhe-heslo</entry>
</properties>

Po reštarte servera sa meno a heslo akceptuje.

🚨 Heslo musí byť minimálne 15 znakov dlhé a umožní prístup ku všetkým dátam na danej inštalácii. Uchovávajte ho bezpečne.

Klientským certifikátom

Bezpečnejším spôsobom je použitie certifikátu — možno sa ním autorizovať na získanie administrátorského prístupu. Na komunikáciu je nutné použiť protokol HTTPS a pripájať sa na port 7000. Na serveri je uložený iba odtlačok certifikátu (SHA1 fingerprint).

Odtlačok certifikátu získate takto:

openssl x509 -noout -in cert.pem -fingerprint

Tento odtlačok je nutné zaslať na podporu a bude nastavený do danej inštancie, resp. stromu inštancií (ich zoskupenia).

Prihláseným administrátorom

Na verzovaných cestách /v2/admin/batch a /v3/admin/batch smie dávkové API použiť aj bežne prihlásený používateľ, ktorý má práva manageAll a licenseMgmt.

ℹ️ Na rozdiel od serverovej autorizácie je takýto používateľ obmedzený na licenčné skupiny, ku ktorým má prístup — položka smerujúca do cudzej licenčnej skupiny skončí so stavom FAILED. Neverzovaná cesta /admin/batch zostáva vyhradená serverovej autorizácii.

Impersonifikácia používateľa

V niektorých prípadoch je nutné, aby sa server prihlásil a následne sa vyhlásil za jedného z používateľov. To možno vykonať doplnením hlavičky:

X-FlexiBee-Authorization: jmeno

Od tejto chvíle budú všetky zmeny vrátane práv vykonané pod týmto používateľom.

Scenáre použitia API

Celé REST API ABRA Flexi vždy pracuje nad jednou databázou s dátami firmy. Výnimkou je správa používateľov a firiem — tá je z firmy vyňatá a uložená iným spôsobom. Informácie o používateľoch sú pri bežnej inštalácii v databáze centralServer, firmy sú v jednotlivých databázach. V prípade cloudovej prevádzky sú informácie vo vysoko replikovanej databáze CouchDB.

Keby sa spracovanie robilo vo viacerých požiadavkách, mohlo by sa stať, že pri prideľovaní práv používateľa do firmy nebude obsluhujúci server vedieť, že je firma alebo používateľ už založený. Preto vzniklo toto dávkové API.

💡 Pretože požiadavka môže zlyhať — napríklad pri dočasnej nedostupnosti jednej z komponentov — je možné ju zopakovať. Potom sa vykoná všetko znova; už vykonané zmeny sa preskočia, operácie sú idempotentné.

Založenie účtu administrátora a predvolenej účtovnej firmy

So založením účtu ADMIN sa založí aj predvolená účtovná firma podľa údajov z objednávky. Firmu nie je možné založiť bez administrátorského používateľa.

<?xml version="1.0"?>
<flexibee-batch id="abc-1">
  <user action="create-update">
    <username>admin</username>
    <password hash="sha256" salt="123">f86vs6vds66</password>
    <email>admin@firma.cz</email>
    <givenName>Roman</givenName>
    <familyName>Skamene</familyName>
    <ssoIdentifier>admin@firma.cz</ssoIdentifier>
    <defaultRole>ADMIN</defaultRole>
    <permissions>
      <manageAll>true</manageAll>
      <createCompany>false</createCompany>
      <deleteCompany>false</deleteCompany>
      <createUser>false</createUser>
      <changePassword>false</changePassword>
      <grantPermission>false</grantPermission>
      <licenseManagement>false</licenseManagement>
    </permissions>
  </user>
  <company action="create-update">
    <id>digitalni_media_s_r_o_</id>
    <name>Digitalní media s.r.o.</name>
    <country>CZ</country>
    <regNo>966664322</regNo><!-- IČO -->
    <type>PODNIKATELE</type>
    <adminUser role="ADMIN">admin</adminUser>
  </company>
</flexibee-batch>

Štandardné používateľské role

ADMIN
SUPERUZIVATEL
MZDOVYUCETNI
UCETNI
OBCHODNIK
SKLADNIK
SKLADNIKSPOKLADNOU
UZIVATEL
JENCIST
ZABLOKOVAN

Typ organizácie a evidencia

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

Hodnota `type`	Význam
`PODNIKATELE`	Podnikatelia.
`PODNIKATELE+PU`	Podnikatelia s podvojným účtovníctvom.
`PODNIKATELE+DE`	Podnikatelia s daňovou evidenciou.
`ROZPOCTOVE`	Rozpočtové organizácie.
`NEZISKOVE`	Neziskové organizácie.
`PODNIKATELIA`	Iba pre Slovensko.

Podporované hashovacie funkcie pre ukladanie hesiel

Funkcia	Poznámka
`sha256`	Predvolená pre ukladanie hesiel poslaných v otvorenej podobe.
`sha512`	—
`sha1`	—
`md5`	—
`pbkdf2`	Najbezpečnejšia, ale aj najpomalšia metóda — je zámerne pomalá, takže bez použitia session je pri REST API nepoužiteľná.

Odtlačok hesla sa počíta z reťazca salt + ":" + heslo a zapisuje sa ako hexadecimálny reťazec malými písmenami. Ukážka výpočtu:

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());

Založenie ďalších „bežných" používateľov

Týchto používateľov zakladá správca tenanta z Admin portálu. Volané môže byť aj hromadne pre viacerých používateľov pri zmene profilu.

<?xml version="1.0"?>
<flexibee-batch id="abc-12">
  <user action="create-update">
    <username>anna.mlada</username>
    <password hash="sha256" salt="123">f86vs6vds66</password>
    <email>anna.mlada@firma.cz</email>
    <givenName>Anna</givenName>
    <familyName>Mladá</familyName>
    <defaultRole>UZIVATEL</defaultRole>
    <permissions>
      <manageAll>true</manageAll>
    </permissions>
  </user>
</flexibee-batch>

🚨 Heslo možno uložiť aj bez salt, ale dôrazne to neodporúčame.

Zmena hesla existujúceho používateľa

<?xml version="1.0"?>
<flexibee-batch id="abc-123">
  <user action="create-update">
    <username>anna.mlada</username>
    <password hash="sha256" salt="123">f86vs6vds66</password>
  </user>
</flexibee-batch>

Zmazanie existujúceho používateľa

Zmazanie používateľa z Admin portálu znamená uvoľnenie licencie. Volané môže byť aj hromadne pre viacerých používateľov pri zmene profilu.

<?xml version="1.0"?>
<flexibee-batch id="abc-12345">
  <user action="delete">
    <username>anna.mlada</username>
  </user>
</flexibee-batch>

Ak bol používateľ zmazaný a neskôr ho znovu založíte akciou create-update, mal by sa obnoviť.

Obnovenie používateľa

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

ℹ️ Pri create-update používateľa sa najprv skúša recyklovať záznamy s príznakom „vymazané". Všetko nastavenie prístupov a rolí zostane zachované.

Blokovanie existujúceho používateľa

Zablokovaný používateľ sa nemôže prihlásiť.

<?xml version="1.0"?>
<flexibee-batch id="abc-123456">
  <user action="create-update">
    <username>anna.mlada</username>
    <blocked message="Blocked from external system">true</blocked>
  </user>
</flexibee-batch>

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 role ADMIN existujúcemu používateľovi

Zodpovedá pridaniu atomickej role „ERP administrátor" na Admin portáli. Volané môže byť aj hromadne pre viacerých používateľov.

<?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>

Odobratie role ADMIN existujúcemu používateľovi

<?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 a priezviska existujúceho používateľa

<?xml version="1.0"?>
<flexibee-batch id="abc-123456789">
  <user action="create-update">
    <username>anna.mlada</username>
    <givenName>Anička</givenName>
    <familyName>Starší</familyName>
  </user>
</flexibee-batch>

Skrytie a zobrazenie firmy (odpojenie)

<?xml version="1.0"?>
<flexibee-batch id="abc-123">
  <company action="create-update">
    <id>digitalni_media_s_r_o_</id>
    <show>false</show><!-- true pro zobrazení -->
  </company>
</flexibee-batch>

To isté možno urobiť aj mimo dávkového API — pozri odpojenie a pripojenie firmy.

Zmazanie firmy

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

Použitie API

Nasledujúci popis platí pre prvú zverejnenú testovaciu verziu s funkčným zakladaním používateľov v centrálnej databáze.

Volanie

Dávka sa odosiela metódou PUT na adresu https://server:7000/admin/batch a požiadavka musí byť autorizovaná jedným zo spôsobov popísaných vyššie. Telom požiadavky je XML dávky:

PUT https://server:7000/admin/batch
Content-Type: application/xml

<obsah souboru batch.xml>

Pri autorizácii klientskym certifikátom sa certifikát priloží k TLS spojeniu; pri serverovej autorizácii sa posiela serverové meno a heslo v hlavičke Authorization.

Ukážkový požiadavok

Obsah súboru batch.xml:

<?xml version="1.0"?>
<flexibee-batch id="abc-123"><!-- ID by mělo unikátně označovat dávku -->
  <user>
    <username>anna.mlada</username>
    <password hash="sha256" salt="xyz987">af123bd35</password>
    <email>anna.mlada@firma.cz</email>
    <givenName>Anna</givenName>
    <familyName>Mladá</familyName>
    <permissions>
      <manageAll>true</manageAll>
      <createCompany>true</createCompany>
      <deleteCompany>true</deleteCompany>
      <createUser>false</createUser>
      <changePassword>false</changePassword>
      <grantPermission>true</grantPermission>
      <licenseManagement>false</licenseManagement>
    </permissions>
    <defaultRole>UZIVATEL</defaultRole>
  </user>
  <company action="create-update"><!-- create-update je výchozí akce -->
    <id>moje_firma_s_r_o_</id>
    <name>Moje Firma s.r.o.</name>
    <country>CZ</country><!-- aktuálně podporované jsou CZ a SK -->
    <regNo>123</regNo><!-- IČO -->
    <vatId>CZ123</vatId><!-- DIČ -->
    <type>PODNIKATELE</type>
    <adminUser>anna.mlada</adminUser>
  </company>
  <company action="delete">
    <id>demo_a_s_</id>
  </company>
  <access role="ADMIN">anna_mlada_s_r_o_</access>
  <access role="UZIVATEL">moje_firma_s_r_o_</access>
  <access>demo_a_s_</access>
</flexibee-batch>

Odpoveď

Pri úspechu (200) je odoslané XML v tomto formáte — každá položka dávky má vlastný entry so stavom:

<?xml version="1.0" encoding="UTF-8"?>
<flexibee-batch-result id="abc-12345678">
  <entry>
    <id>moje_firma_s_r_o_</id>
    <entity>COMPANY</entity>
    <action>DELETE</action>
    <result>
      <status>SKIPPED</status>
      <message>Not implemented yet.</message>
    </result>
  </entry>
  <entry>
    <id>anna.mlada@firma.cz</id>
    <entity>USER</entity>
    <action>CREATE_UPDATE</action>
    <result>
      <status>CREATED</status>
    </result>
  </entry>
</flexibee-batch-result>

⚠️ Stav 200 pri celej dávke neznamená, že prešli všetky položky. Výsledok vždy čítajte z jednotlivých entry — môžu niesť aj SKIPPED alebo FAILED.

Súvisiace

Sorodni članki

Batch API