ABRA primaERP je praktická cloudová aplikácia z rodiny produktov ABRA Software. Je to nástroj na sledovanie času stráveného na tímových projektoch (Sledovanie času) a jeho následnú fakturáciu zákazníkovi (Fakturácia). Dochádzku môžete sledovať aj v systéme primaERP pomocou modulu Dochádzka. PrimaERP, rovnako ako ABRA Flexi, má prepracované rozhranie API, a preto nie je problém tieto dva systémy prepojiť.
Aplikácie API v každej aplikácii fungujú v určitých ohľadoch odlišne. Ak už ovládate používanie API v systéme ABRA Flexi, budete si musieť zvyknúť na rozdiely v API v systéme primaERP.
Kľúč API
Najprv je potrebné získať kľúč API, ktorý umožní používanie rozhrania API. Ak ho chcete získať, musíte kontaktovať podporu a požiadať oň priamo v chate v aplikácii alebo napísať e-mail na adresu podpora@primaerp.com. Po prijatí e-mailu s vygenerovaným kľúčom môžete začať s nastavovaním.
Overenie a následné otázky
PrimaERP API sa od Flexi líši aj spôsobom získavania údajov. Pomocou systému Flexi je možné použiť overenie HTTP na získanie potrebných údajov pomocou prvého dotazu. V rozhraní primaERP API sa musíte najprv prihlásiť. Pri prihlásení sa vygeneruje token s obmedzenou platnosťou, ktorý sa potom používa na jednotlivé dotazy na API. Po uplynutí platnosti tokenu je potrebné získať nový.
Tento princíp sa dá použiť aj v systéme Flexi, hoci je užitočnejší len pre používateľov webového rozhrania. Má však jednu nespornú výhodu. Ak sa token používa správne, t. j. načíta sa až po uplynutí jeho platnosti, zrýchľuje sa tým spracovanie dotazov. Flexi totiž nemusí pre každý dotaz vytvárať nové relácie a načítavať množstvo údajov do vyrovnávacej pamäte. Vytvorenie relácie a načítanie údajov do vyrovnávacej pamäte sa teda vykoná len raz. Popis používania tejto metódy overovania je opísaný v dokumentácii k rozhraniu Flexi API v časti Záznamy.
Aby ste získali overovací token, musíte odoslať požiadavku GET na túto adresu
https://{tenant}.api.primaerp.com/v1/auth/login?apikey={apikey}nahradiť {tenant} názvom účtu v systéme primaERP
nahraďte {apikey} kľúčom API získaným od podpory primaERP
Okrem toho musí hlavička Authorization obsahovať meno a heslo používateľa primaERP.
Získanie účtov z programu primaERP
Pokiaľ ste prihlásení a máte platný overovací token, môžete začať načítavať údaje z programu primaERP. Pre tento scenár je potrebné získať zoznam účtov, ktoré potom prenesiete do systému Flexi.
Súpis účtov sa nachádza na adrese /v1/billing/bills. Podobne ako v prípade systému Flexi možno údaje získať v dvoch formátoch. Výber formátu je rovnaký ako v prípade Flexi. Údaje XML získate pridaním prípony .xml, údaje JSON pridaním prípony .json. Do adresy URL musíte pridať aj parameter token.
Takže
úplná adresa URL na získanie údajov o účte vo formáte JSON zo systému primaERP je
https://{tenant}.api.primaerp.com/v1/billing/bills.json?token={token}Vzorka údajov vo formáte JSON:
"/Date(1495576800000)/", "vatDate":"/Date(1495576800000)/", "dueDate":"/Date(1496786400000)/", "lastPaymentDate": null, "description": "Flexi System s.r.o. - 2017-05", "notes": null, "vatText": null, "header": null, "footer": null, "itemsPrice": 21300.0, "totalPrice": 25773.0, "client": {"id": "c46d9eca-585b-4d2a-ba2c-1c93da0ea08c", "createdAt":"/Date(1495654059779)/", "updatedAt":"/Date(1495732307124)/", "version": 4, "externalSystem": null, "externalResourceId": null, "externalBrowsableUrl": null, "externalSyncedAt": null, "externalSynced": null, "name".r.o..", "code": "FLEXI", "email": "podporaflexi@abra.eu", "active": true, "billsCount": null, "projectsCount": null, "streetAddress": "Lochotínska 18", "additionalAddressInfo": null, "zipCode": "30100", "city": "Plzeň", "state": "Plzeňský kraj", "countryCode": "CZE", "phone": "371 124 321", "vatId": "CZ28019920", "website": "www."flexibee.eu", "displayName": "Flexi System s.r.o." }, "contactPerson": null, "approved": false, "items": [ { "id": "636da95d-e19a-48cf-83e3-698a89a4108b", "createdAt":"/Date(1495654409685)/", "updatedAt": null, "version": 0, "attributes": "JSON{\"duration\":63900000\"}", "itemGroup": "trbi", "docIndex": null, "quantity": 17.75, "price": 21300.0, "unitPrice": 0.0, "unit": null, "displayName": "#null"} ], "author": {"id": "9e3c6b13-dc81-4630-9a21-3b9ab4023e60", "createdAt": "/Date(1495653967694)/", "updatedAt":"/Date(1495818089532)/", "version": 5, "firstName": "Kája", "lastName": "z Norska", "nickName": "z Norska, K.", "email": "kbel@flexi.eu", "phone": null, "position": "A02200", "timeZone": "Europe/Berlin", "dateFormat": "dd.MM.yyyy", "timeFormat": "HH:mm", "weekStart": 1, "language": "sk_CZ", "password": null, "secretKey": null, "confirmed": true, "confirmedEmail": true, "active": true, "birthdayRemind": null, "workingTimeStart": null, "workingTimeEnd": null, "created":"/Date(1495653967694)/", "admin": false, "projectManager": false, "displayName": "from Norska Kája" }, "groupAttributes": "JSON[[\"\"],null]", "draft": false, "vatMode": "DECLARE_VAT", "vats": [ {"id": "d0a1fbe9-ee92-495d-940b-b89accd586e2", "createdAt":"/Date(1495654409685)/", "updatedAt": null, "version": 0, "vatRate": 21.0, "vatPrice": 4473.0, "displayName": "21.0" } ], "displayName": "2017/001" } ]
Prenos a zápis údajov do ABRA Flexi
Dáta načítané z programu primaERP je potrebné transformovať do podoby, ktorú dokáže Flexi spracovať, a potom zapísať do príslušných záznamov. Účty z fakturácie môžete zadať napríklad do záznamu faktúry, kde ich potom môžete zaúčtovať.
V systéme primaERP je pre daný účet zaznamenané všetko, čo je potrebné na vytvorenie novej vystavenej faktúry. V mostíku je pevne stanovený len typ dokumentu.
Zápis do ABRA Flexi je popísaný v článku Vkladanie údajov JSON do ABRA Flexi pomocou PHP.
Ukážka skriptu PHP na prenos účtu
funkcia curl_get($url){ $ch = curl_init(); // vytvorenie curl zdroja curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE); // vrátenie obsahu ako reťazca z curl_exec curl_setopt($ch, CURLOPT_HTTPAUTH, TRUE); // HTTP autentifikácia curl_setopt($ch, CURLOPT_USERPWD, "emailova@adresa.cz:heslo"); // nastavenie používateľského mena a hesla curl_setopt($ch, CURLOPT_URL, $url); // nastavenie URL curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET"); // nastavenie HTTP metódy $output = curl_exec($ch); $info = curl_getinfo($ch); if (curl_getinfo($ch, CURLINFO_HTTP_CODE) != 200 & curl_getinfo($ch, CURLINFO_HTTP_CODE) != 201) { printf ("Počas operácie došlo k chybe (HTTP %d): %sn", curl_getinfo($ch, CURLINFO_HTTP_CODE), $output); } curl_close($ch); return $output; } function curl_put($url, $json_data){ $ch = curl_init(); // create curl resource curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE); // vrátiť obsah ako reťazec z curl_exec curl_setopt($ch, CURLOPT_HTTPAUTH, TRUE); // HTTP autentifikácia curl_setopt($ch, CURLOPT_USERPWD, "winstrom:winstrom"); // nastavte používateľské meno a heslo curl_setopt($ch, CURLOPT_URL, $url); // nastavte URL curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PUT"); // nastavte HTTP metódu curl_setopt($ch, CURLOPT_POSTFIELDS, $json_data); // nastavte dáta $output = curl_exec($ch); // vykonajte // Flexi návratová hodnota header("Content-Type: application/json"); print($output); // zatvorte zdroj curl, aby ste uvoľnili systémové zdroje curl_close($ch); } function parse_date($primaerp_date, $to_format){ $timestamp = preg_replace('/[^\d]/','', $primaerp_date)/1000; $datetime = new DateTime(); $datetime->setTimestamp($timestamp); return $datetime->format($to_format); } // authentication $url = "https://nájomca.api.primaerp.com/v1/auth/login?apikey=abcdefgh-1234-5678-ijkl-mnopqrstuv"; $output = curl_get($url); $json = json_decode($output, true); // token pre api požiadavky $apiToken = $json['token']; echo $apiToken; // žiadosť o fakturačné údaje $url = "https://tenant.api.primaerp.com/v1/billing/bills.json?token=".$apiToken; $output = curl_get($url); $billing_json = json_decode($output, true); // transformácia údajov pre Flexi $invoices = array("winstrom" => array("invoice-issued" => array() ) ); foreach($billing_json as $bill){ $invoice = array(); $invoice['id'] = array(); array_push($invoice['id'], 'ext:primaerp:'.$bill['id']); array_push($invoice['id'], 'code:'.$bill['docNumber']); $invoice['typeDoc'] = 'code:INVOICE-PRIMAERP"; $invoice['code'] = $bill['docNumber']; $invoice['noPost'] = 'true'; $invoice['sumZklZakl'] = $bill['itemsPrice']; $invoice['sumCelkZakl'] = $bill['totalPrice']; $invoice['company'] = 'code:'.$bill['client']['code']; $invoice['firm@if-not-found'] = 'create'; $invoice['nazFirmy'] = $bill['client']['name']; $invoice['street'] = $bill['client']['streetAddress']; $invoice['psc'] = $bill['client']['zipCode']; //$invoice['stat'] = 'code:'.$bill['client']['countryCode']; $invoice['stat'] = 'code:CZ"; $invoice['dic'] = $bill['client']['vatId']; $invoice['datVyst'] = parse_date($bill['docDate'], 'Y-m-d'); $invoice['duzpPpuv'] = parse_date($bill['vatDate'], 'Y-m-d'); $invoice['datSplat'] = parse_date($bill['dueDate'], 'Y-m-d'); array_push($invoice['winstrom']['invoice-issued'], $invoice); } // zápis do Flexi $url = "https://demo.flexibee.eu/c/demo/invoice-issued.json"; $output = curl_put($url, json_encode($invoice)); ?>Príklad prenosu z primaERP na demo.flexibee.eu:
{
"winstrom": {
"@version": "1.0",
"success": "true",
"stats": {
"created": "0",
"updated": "1",
"deleted": "0",
"skipped": "0",
"failed": "0"
},
"results": [
{
"id": "3468",
"request-id": "ext:primaerp:1b5127a5-b8c3-4adf-a961-0cad42f718a3",
"ref": "\/c\/demo\/faktura-vydana\/3468.json"
}
]
}
}Pozrite si tiež vytvorenú faktúru.
Zatvorenie a ocenenie
V tomto príklade sú vytvorené faktúry "bez položiek". Nie je však problém začať vytvárať aj položkové. Stačí vytvoriť príslušné položky faktúry podľa kolekcie položiek. Ďalším možným vylepšením celého prenosu je použitie filtrovania, aby sa napríklad mohli prenášať len schválené účty alebo účty, ktoré sa zmenili od poslednej synchronizácie. Filtrovanie je popísané v dokumentácii primaERP v časti Filtrovanie.
Prostredníctvom rozhrania API je tiež možné priamo načítať údaje z modulu Timetracking, zapísať ich do príslušných priečinkov vo Flexi payroll a následne vypočítať mzdy zamestnancov podľa odpracovaných hodín.
V opačnom smere je možné preniesť celý adresár alebo zoznam zamestnancov, ktorí majú evidovať čas z Flexi do primaERP.
Ak hľadáte spoľahlivý systém na evidenciu pracovného času a dochádzky pre ABRA Flexi, primaERP je určite tou správnou voľbou. Okrem toho ponúka možnosť automatického prenosu údajov z jedného systému do druhého.