<>

PHP AbraFlexi

PHP7.1+ Based Library for easy interaction with Czech accounting system AbraFlexi.

CZ: PHP Knihovna pro snadnou práci s českým ekonomickým systémem AbraFlexi

Poděkování

Vznik této knihovny by nebyl možný bez laskavé podpory společnosti Spoje.Net, která hradila vývoj řešení pro propojení LMS / AbraFlexi a importu skladu. :+1:

Dále chci poděkovat technické podpoře společnosti ABRA Flexi s.r.o. za jejich svatou trpělivost při reakcích na mé ne vždy bystré otázky a bugreporty.

Parsování výsledků pro účely GDPR logování bylo dopracováno za laskavé podpory <PureHTML>

Instalace

    composer require spojenet/flexibee

pokud váš výsledný composer.json bude vypadat zhruba takto:

{
    "name": "vendor/projectname",
    "description": "Test",
    "type": "project",
    "require": {
        "spojenet/flexibee": "*"
    },
    "license": "MIT",
    "authors": [
        {
            "name": "Vítězslav Dvořák",
            "email": "info@vitexsoftware.cz"
        }
    ],
    "minimum-stability": "stable"
}

spustí se příkazem composer install instalace:

Konfigurace

Konfigurace se provádí nastavením následujících konstant:

   /*
    * URL AbraFlexi API
    */
    define('ABRAFLEXI_URL', 'https://abraflexi-dev.spoje.net:5434');
   /*
    * Uživatel AbraFlexi API
    */
    define('ABRAFLEXI_LOGIN', 'apiuser');
   /*
    * Heslo AbraFlexi API
    */
    define('ABRAFLEXI_PASSWORD', 'apipass');
   /*
    * Společnost v AbraFlexi
    */
    define('ABRAFLEXI_COMPANY', 'test_s_r_o_');
   /*
    * Nebo pokud nechceme používat jméno a heslo 
    */
    define('ABRAFLEXI_AUTHSESSID', '6QuifebMits'); //Volitelné
   /*
    * Pomalý server, velká databáze a přes modem k tomu
    */
    define('ABRAFLEXI_TIMEOUT', 60); //Volitelné
   /*
    * Pomalý server, velká databáze a přes modem k tomu
    */
    define('ABRAFLEXI_EXCEPTIONS', true); //Vracet PHP vyjímku v případě že AbraFlexi vrátí chybu

Pokud nejsou konstanty nastaveny, pouší se třídy také o konfiguraci ze stejnojmených proměnných prostředí. např getenv('ABRAFLEXI_URL')

Taktéž je možné přihlašovací údaje zadávat při vytváření instance třídy.

    $invoicer = new \AbraFlexi\FakturaVydana(null,[
                'company' => 'Firma_s_r_o_',
                'url' => 'https://abraflexi.firma.cz/',
                'user' => 'rest',
                'password' => '-dj3x21xaA_'
            ]);

Tento způsob nastavení má vyšší prioritu než výše uvedené definovaní konstant.

    $order = new \AbraFlexi\ObjednavkaPrijata('code:OBP0034/2019',['companyUrl'=> $_GET['companyUrl'], 'authSessionId'=>$_GET['authSessionId'] ])

Takto se ke abraflexi a konrétní objednávce může připojit aplikace vyvolaná uživatelským tlačítkem předávajícím hodnoty companyUrl a authSessionId

Jak to celé funguje ?

Ústřední komponentou celé knihovny je Třída RO, která je schopna pomocí PHP rozšíření curl komunikovat s REST Api AbraFlexi.

Z ní jsou pak odvozeny třídy pro jednotlivé evidence, obsahující metody pro často používané operace, například "Zaplať" v případě přijatých faktur.

Nová odvozená třída vzniká tak, že jméno třídy je název evidence avšak bez pomlček. Ty jsou ve jméně nahrazeny velkým písmenem.

    function evidenceToClass($evidence)
    {
        return str_replace(' ', '', ucwords(str_replace('-', ' ', $evidence)));
    }

Tzn. Pokud chceme odvodit novou třídu pro evidenci "Měrné jednotky" bude vypadat takto:

    <?php
    /**
     * @link https://demo.abraflexi.eu/c/demo/merna-jednotka/properties Vlastnosti evidence
     */
    class MernaJednotka extends /AbraFlexi/RW
    {
        /**
         * Evidence užitá objektem.
         *
         * @var string
         */
        public $evidence = 'merna-jednotka';
    }

A poté je již snadné si vypsat měrné jednotky na 2 řádky:

    $jednotky = new MernaJednotka();
    print_r( $jednotky->getAllFromAbraFlexi() );

Pokud chceme aby nově vytvořená třída uměla do abraflexi i zapisovat, je třeba jí odvodit od předka AbraFlexiRW.

Více příkladů použití je možné najít v samostatném projektu

Struktura Evidencí, Akcí a vztahů

V některých případech je dobré znát jaké můžeme provádět akce, či jáká je struktura evidence. Tyto informace je možno získat voláním https://demo.abraflexi.eu/c/demo//properties.json respektive https://demo.abraflexi.eu/c/demo//actions.json avšak jedná se o relativně časově náročné operace. Jelikož se struktura evidencí a Akce či vztahy mezi evidencemi AbraFlexi často nemění AbraFlexi disponuje mechanizmem který umožní pracovat s těmito údaji bez nutnosti dotazovat se na ně serveru.

Struktura je uložena ve třídě Structure (Actions,Relations) která obsahuje staticky definované pole obsahující informace které by jinak bylo nutné získat z AbraFlexi.

Položku v seznamu evidencí https://demo.abraflexi.eu/c/demo/evidence-list je pak možné kdykoliv snadno ukázat:

    echo \AbraFlexi\Structure::$evidence['faktura-vydana'];

Sturktury jednotlivých evidencí jsou pak uloženy ve statických proměnných. Jejich jméno se řídí stejnými pravidly jako jsou pro vytváření jména nové třídy jen s tím rozdílem, že první písmeno je malé. Tzn.:

    lcfirst(\AbraFlexi\RO::evidenceToClassName($evidence))

V případě potřeby je možné tyto třídy pak možné vygenerovat s aktuálním obsahem následujícím příkazem:

cd tools/ 
./update_all.sh

Operace trvá několik minut. Zobrazit průběh můžeme takto:

tail -f /var/log/syslog | grep  AbraFlexitest

Ladicí režim

Pokud v objektech AbraFlexi nastavíte $this->debug na true, budou se před odesláním dat do AbraFlexi provedeny dodatečné testy. Kontrolují se tyto možné chyby:

• Existuje vkládané políčko definované pro evidenci ?
• Je vkládané políčko Pouze pro čtení ?
• Pokud je vkládané políčko vazbou, je i polem ?

V ladícím režimu se také ukládají do složky /tmp všechny požadavky na abraflexi a jejich odpovědi

Knihovna obsahuje mechanizmus pro odesílání zaznamenaných chyb při běhu AbraFlexi vývojářům:

Pokud AbraFlexi vrátí Internal Server Error 500, je odeslán vývojářům email obsahující chybovou zprávu.

V případě že je použito AbraFlexi běžící na stejném serveru a je možné číst chybové logy je z nich vypreparován patřičný fragment a i ten je přidán do těla mailu.

Email obsahuje také dodatečné informace o licenci a povolených modulech.

Jako přílohy jsou také připojeny soubory obsahující tělo dotazu na server, tělo jeho odpovědi a soubor obsahující informace o curl.

Během života objektu se chyby evidují a odesílá se pouze první každého druhu.

Aktualizace na verzi 2.0

Oproti 1.x se změnilo následující:

• Zmizely Třídy FlexiBeeRO a FlexiBeeRW (nově RO a RW)
• Data z AbraFlexi jsou typovaná (už ne jenom strig)
• Všechno FlexiBee bylo přejmenováno na AbraFlexi
• Při chybě ze serveru se vyhodí Exeption (předtím se pouze zalogovalo)
• Požadavky nespecifikují počet výsledků, (je třeba explicitně požadovat limit 0 pro všechny výsledky požadavku na api)
• již se nepužívá starý zápis polí array()

Výchozí Nativní typy se projevují tak že ze serveru ve chlívečku obsahující datum obdržíte php objekt DateTime. ve sloupečku 'id' integer a pod. Toto chování je možné vypnout pomocí parametru konstruktoru ['nativeTypes' = false]

    new \AbraFlexi\FakturaVydaná( 'code:VF2-12345', ['nativeTypes'=>false,'debug'=>true,'ignore404'=>false] );

Viz.: constructor RO

Je možno zadat některé z těchto parametrů:

 * user,password,authSessionId - autentifikace
 * company,url,evidence - vynucení parametrů přístupu
 * prefix - pro url začínající jinak než  '/c/' pro  company
 * defaultUrlParams - pole vlastností pak automaticky přidávané
 * debug - pro zapnutí ladícího režimu
 * detail - pro specifikaci požadované [úrovně detailů](https://www.flexibee.eu/api/dokumentace/ref/detail-levels/). 
 * offline - nevykonávají se žádné síťové operace ( nepřiřipojit se při instancování objektu ) 
 * filter - viz [Filtrování](https://www.flexibee.eu/api/dokumentace/ref/filters}
 * ignore404 - v případě že nevím zdali požadovaný záznam existuje nastavte na true aby to nevyhodilo chybu
 * nativeTypes - pokud chci všecho ze serveru vracet jako stringy 
 * timeout - trpělivost než se vyhodí chyba síťové komunikace (předáváno do cURL)
 * companyUrl - načte si z řetězce všechny náležitosti k připojení (heslo pro API atd..)
 * ver - vynucení verze api (pokud chcete volat funkce určené pro nové webové rozhraní)
 * throwException - vyhodit vyjímku při každé vhodné příležitosti

Autoloading dat

Pokud se konstruktoru objektu předá ID typu int nebo kódem (code:..) záznamu zavolá tento funkci loadFromAbraFlexi(id) Poté je možné k načteným hodnotám se dostat za použití metod $this->getData() a RO::getDataValue('nazev')

Datové typy

Jelikož API vrací vše víceméně jako řetězec, knihovna provádí automatické konverze datových typů:

| Strojový název | Název | Poznámka | Ukázka | PHP Typ | | -------------- | :-------------- | ----------- | :----------: | :------- | | string | Řetězec | Kódování je unicode. Lze tedy použít libovolný znak. | šílený koníček こちらは田中さんです | string | | integer | Celé číslo | Musí být bez mezer. Jde o znaménkový 4bajtový integer, ovšem rozsah může být omezený (viz přehled položek dané evidence) | 12 | integer | | numeric | Desetinné číslo | Musí být bez mezer, oddělovačem desetinných míst je tečka. Jde o 8bajtový double, ovšem rozsah může být omezený (viz přehled položek dané evidence) | 12.5 | float | | date | Datum | Datum ve formátu YYYY-MM-DD; lze zadat i časovou zónu (YYYY-MM-DDZZZ), ale ta bude ignorována. ZZZ je označení časové zóny (Z nebo +HH:MM nebo -HH:MM). | 1980‑05‑06 2015‑01‑30Z 2008‑09‑01+02:00 | \Date() | | datetime | Datum + čas | Datum a čas ve formátu YYYY-MM-DD'T'HH:MM:SS.SSS; lze zadat i časovou zónu (YYYY-MM-DD'T'HH:MM:SS.SSSZZZ), ale ta bude ignorována. | 1980‑05‑06 1980‑05‑06T12:30:12 2015‑01‑30T22:55:33Z 2008‑09‑01T17:18:14+02:00 2008‑09‑01T17:18:14.075+02:00 | \DateTime() | | logic | Logická hod. | boolean | true false | boolean | | select | Výběr jedné z hodnot | Výběr jedné z hodnot. Je reprezentován jako řetězec. | typVztahu.odberDodav | string | | relation | Vazba mezi daty | Vstupem je záznam z jiné evidence (přehled typů identifikátorů) | 123 code:CZK ext:DB:232 | \AbraFlexi\Relation |

Testování

PHPUnit testy se nachází ve složce testing. Pokud chcete testovat proti jinému serveru než je oficální http://demo.abraflexi.eu/ , je třeba změnit nastavení v souboru bootstrap.php.

Obsah proměnné $testServer určuje která z předvolených nastavení budou použita. A samozřejmě si můžete nadefinovat i vlastní. Jako příklad je zde uveden testovací server spoje.net.

Pro testování vytvořte prosím nejprve testovací firmu TESTING s.r.o. a nastavte přístupové údaje uživatele s oprávněním používat REST API. (Což je uživatel administrátora zadaný při instalaci AbraFlexi.)

Upozornění: testování proti firmě s množstvím faktur a připojenou bankou může trvat nějakou dobu, jelikož se testuje i zavolání automatického párování dokladů.

Pokud se ve vašem projektu rozhodnete podědit AbraFlexi a k těmto třídám napíšete testy také poděděné z AbraFlexi např:

class HookRecieverTest extends \Test\AbraFlexi\ChangesTest

Přidejte do vašeho composer.json i cesty k původním testům:

    "autoload-dev": {
        "psr-4": {
            "Test\\": "vendor/spojenet/php-abraflexi/test/src/AbraFlexi/test/",
            "Test\\Ease\\": "vendor/vitexsoftware/ease-core/tests/src/Ease",
            "Test\\AbraFlexi\\": "vendor/spojenet/php-abraflexi/test/src/AbraFlexi/",
         }
    }

Ukázka

Ve složce Examples jsou tyto ukázky použití:

| Soubor | Popis | | ------------------------------------------------------------- | --------------------------------------| | AttachmentSaveToFile.php | uložení přílohy do souboru | AttachmentUpload.php | nahrání přílohy | AuthSessionIdUsage.php | Ukázka autentizace AuthSessionId | AuthentizeContact.php | autentizace kontaktu | BatchOperation.php | Použití filtru při dávkových operacích | CreateLabel.php | práce se štítky | DryRun.php | Testovací uložení (dry-run) | DownloadInvoicePDF.php | stažení PDF faktury | Error404.php | práce s neexistujícími záznamy | FindOverdueInvoices.php | najdi faktury po splatnosti | GetRecordWithRelation.php | Získání záznamu včetně dat z podevidence | GetBankAccountForCompany.php | Získání bankovního účtu k firmě z adresáře | InvoiceLockUnlock.php | Zamykání a odemykání záznamu | InvoiceCopy.php | vytvoření daňového dokladu ze zálohy | LoginLogout | přihlášení uživatele a jeho odhlášení | NajdiDanovyDokladKzalohovemu.php | dohledání dokladu | Naskladnění.php | Naskladní produkt se sériovými čísly | NewInvoice.php | Nová faktura se splatností vypsaná jako json | ObjectChaining.php | Řetězení objektů pro více operací v jenom pořadavku | ObjectCooperation.php | Sdílení data a parametrů připojení mezi objekty | PerformingActions.php | Jak vykonávat akce nad dokladem akce. např. storno | ReadAddressColumns.php | vrať konkrétní sloupečky | sendInvoiceByMail.php | odeslání faktury mailem | SendReminders.php | odeslání upomínek | SetContactAuth.php | nastavení autentizace | TestConnection.php | kontrola spojení

Příklady použití:

• Flexplorer Vývojářský nástoj a editor záznamů
• FlexiProXY Modifikátor webového rozhraní AbraFlexi
• Upomínač Odesílač upomínek
• Matcher Párovač fakur
• Redmine2AbraFlexi Generuje faktury z odpracovaného času v Redmine
• FlexiPeeHP-Bricks Příklady a často požívaní třídy při práci s AbraFlexi
• AbraFlexi Tools Nástroje pro skriptování AbraFlexi z příkazové řádky

Reference:

• Import dat z FAPI do AbraFlexi - blahasoft.cz
• Import dat z iDokladu do AbraFlexi - blahasoft.cz

AbraFlexi knihovny pro další jazky:

• Flexipy (Python) Dokumentace
• Flexibee.rb (Ruby)
• UniMapper Flexibee extension (PHP)
• Flexibee client (PHP)
• flexibee-client (PHP)
• flexibee-client (PHP)
• Flexibee (Java)

Statistiky práce na projektu WakaTime Statistiky práce na projektu před přejmenováním (cca 250h)