Pro partnerská řešení, která potřebují spravovat instance ABRA Flexi v cloudu, existuje dávkové API. Předá se mu seznam operací nad uživateli a firmami a jeden server je vykoná najednou, takže je zajištěná konzistence.

⚠️ Stav tohoto API je zatím beta a dokument popisuje i plánovaný stav. Vše si před použitím důkladně ověřte na testovacím prostředí.

Autentifikace požadavků vůči ABRA Flexi

ABRA Flexi podporuje několik způsobů takzvané serverové autorizace:

Způsob	Kde jej lze použít
Serverovým jménem a heslem	Jen na vlastní instalaci — v cloudu použitelné není.
Klientským certifikátem	Zatím jen v cloudu — mimo cloud použitelné není.
Přihlášeným administrátorem	Kdekoli, ale jen na verzovaných cestách a s omezením na vlastní licenční skupiny.

Serverové jméno a heslo

Pro tento typ autorizace je nutné upravit /etc/flexibee/server-auth.xml a doplnit:

<?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 restartu serveru se jméno a heslo akceptuje.

🚨 Heslo musí být minimálně 15 znaků dlouhé a umožní přístup ke všem datům na dané instalaci. Ukládejte jej bezpečně.

Klientským certifikátem

Bezpečnějším způsobem je použití certifikátu — lze se jím autorizovat pro získání administrátorského přístupu. Pro komunikaci je nutné použít protokol HTTPS a připojovat se na port 7000. Na serveru je uložen pouze otisk certifikátu (SHA1 fingerprint).

Otisk certifikátu získáte takto:

openssl x509 -noout -in cert.pem -fingerprint

Tento otisk je nutné zaslat na podporu a bude nastaven do dané instance, resp. stromu instancí (jejich seskupení).

Přihlášeným administrátorem

Na verzovaných cestách /v2/admin/batch a /v3/admin/batch smí dávkové API použít i běžně přihlášený uživatel, který má práva manageAll a licenseMgmt.

ℹ️ Na rozdíl od serverové autorizace je takový uživatel omezen na licenční skupiny, ke kterým má přístup — položka mířící do cizí licenční skupiny skončí se stavem FAILED. Neverzovaná cesta /admin/batch zůstává vyhrazená serverové autorizaci.

Impersonifikace uživatele

V některých případech je nutné, aby se server přihlásil a následně se prohlásil za jednoho z uživatelů. To lze provést doplněním hlavičky:

X-FlexiBee-Authorization: jmeno

Od té chvíle budou všechny změny včetně práv provedeny pod tímto uživatelem.

Scénáře použití API

Celé REST API ABRA Flexi vždy pracuje nad jednou databází s daty firmy. Výjimkou je správa uživatelů a firem — ta je z firmy vyjmutá a uložená jiným způsobem. Informace o uživatelích jsou u běžné instalace v databázi centralServer, firmy jsou v jednotlivých databázích. V případě cloudového provozu jsou informace ve vysoce replikované databázi CouchDB.

Kdyby se zpracování dělalo ve více požadavcích, mohlo by se stát, že při přidělování práv uživatele do firmy nebude obsluhující server vědět, že je firma nebo uživatel už založený. Proto vzniklo toto dávkové API.

💡 Protože požadavek může selhat — například při dočasné nedostupnosti jedné z komponent — je možné jej zopakovat. Pak se provede vše znovu; už provedené změny se přeskočí, operace jsou idempotentní.

Založení účtu administrátora a výchozí účetní firmy

Se založením účtu ADMIN se založí i výchozí účetní firma podle údajů z objednávky. Firmu není možné založit bez administrátorského uživatele.

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

Standardní uživatelské role

ADMIN
SUPERUZIVATEL
MZDOVYUCETNI
UCETNI
OBCHODNIK
SKLADNIK
SKLADNIKSPOKLADNOU
UZIVATEL
JENCIST
ZABLOKOVAN

Typ organizace a evidence

Podvojné účetnictví je výchozí pro všechny typy organizací.

Hodnota `type`	Význam
`PODNIKATELE`	Podnikatelé.
`PODNIKATELE+PU`	Podnikatelé s podvojným účetnictvím.
`PODNIKATELE+DE`	Podnikatelé s daňovou evidencí.
`ROZPOCTOVE`	Rozpočtové organizace.
`NEZISKOVE`	Neziskové organizace.
`PODNIKATELIA`	Pouze pro Slovensko.

Podporované hash funkce pro ukládání hesel

Funkce	Poznámka
`sha256`	Výchozí pro ukládání hesel poslaných v otevřené podobě.
`sha512`	—
`sha1`	—
`md5`	—
`pbkdf2`	Nejbezpečnější, ale také nejpomalejší metoda — je záměrně pomalá, takže bez použití session je u REST API nepoužitelná.

Otisk hesla se počítá z řetězce salt + ":" + heslo a zapisuje se jako hexadecimální řetězec malými písmeny. Ukázka 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žení dalších „běžných" uživatelů

Tyto uživatele zakládá správce tenanta z Admin portálu. Voláno může být i hromadně pro více uživatelů při změně 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 lze uložit i bez salt, ale důrazně to nedoporučujeme.

Změna hesla existujícího uživatele

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

Smazání existujícího uživatele

Smazání uživatele z Admin portálu znamená uvolnění licence. Voláno může být i hromadně pro více uživatelů při změně profilu.

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

Byl-li uživatel smazán a později jej znovu založíte akcí create-update, měl by se obnovit.

Obnovení uživatele

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

ℹ️ Při create-update uživatele se nejprve zkouší recyklovat záznamy s příznakem „vymazáno". Veškeré nastavení přístupů a rolí zůstane zachováno.

Blokace existujícího uživatele

Zablokovaný uživatel se nemůže přihlásit.

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

Odblokování uživatele

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

Přidání role ADMIN existujícímu uživateli

Odpovídá přidání atomické role „ERP administrátor" na Admin portálu. Voláno může být i hromadně pro více uživatelů.

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

Odebrání role ADMIN existujícímu uživateli

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

Změna jména a příjmení existujícího uživatele

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

Skrytí a zobrazení firmy (odpojení)

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

Totéž lze udělat i mimo dávkové API — viz odpojení a připojení firmy.

Smazání firmy

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

Použití API

Následující popis platí pro první zveřejněnou testovací verzi s funkčním zakládáním uživatelů v centrální databázi.

Volání

Dávka se odesílá metodou PUT na adresu https://server:7000/admin/batch a požadavek musí být autorizován jedním ze způsobů popsaných výše. Tělem požadavku je XML dávky:

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

<obsah souboru batch.xml>

Při autorizaci klientským certifikátem se certifikát přiloží k TLS spojení; při serverové autorizaci se posílá serverové jméno a heslo v hlavičce Authorization.

Ukázkový požadavek

Obsah souboru 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>

Odpověď

Při úspěchu (200) je odesláno XML v tomto formátu — každá položka dávky má vlastní entry se stavem:

<?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 u celé dávky neznamená, že prošly všechny položky. Výsledek vždy čtěte z jednotlivých entry — mohou nést i SKIPPED nebo FAILED.

Související

Související články

Batch API