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
HTTP PUT na URL = http://server:7000/admin/batch
Ž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>)