ABRA primaERP je šikovná cloudová aplikácia z rodiny produktov ABRA Software. Ide o nástroj na sledovanie času stráveného na tímových projektoch (Timetracking) a jeho následné vyfakturovanie zákazníkovi (Billing). V primaERPe možno taktiež sledovať dochádzku pomocou modulu Attendance. PrimaERP rovnako ako ABRA Flexi má prepracované API rozhranie, a preto nie je problém tieto dva systémy prepojiť.
Rozhranie API v každej aplikácii funguje v určitých smeroch odlišne. Ak už ovládate používanie API v ABRA Flexi, na odlišnosti API primaERPu si budete musieť ešte zvyknúť.
API kľúč
Najskôr je potrebné získať API kľúč, ktorý umožní API využívať. Pre jeho získanie je nutné kontaktovať podporu prostredníctvom otázky priamo v chate vnútri aplikácie alebo napísať e-mail na adresu podpora@primaerp.com. Akonáhle vám dorazí e-mail s vygenerovaným kľúčom, môžete začať s nastavovaním.
Autentifikácia a následné dotazy
API primaERPu sa od Flexi odlišuje aj postupom, ako získavať dáta. V prípade Flexi je možné využiť HTTP autentifikáciu a získať tak potrebné dáta hneď prvým dotazom. V primaERP API je nutné sa najskôr prihlásiť. Pri prihlásení sa vygeneruje token s obmedzenou platnosťou, ktorý sa potom používa pre jednotlivé dotazy do API. Akonáhle tokenu vyprší platnosť, je nutné získať nový.
Tento princíp možno použiť aj vo Flexi, hoci je užitočný skôr len pre používateľov webového rozhrania. Má však jednu nespornú výhodu. Ak je používaný správne, tzn. token sa získava až v okamžiku, keď vyprší, zrýchľuje spracovanie dotazov. Flexi totiž nemusí pre každý dotaz vytvárať nové relácie a načítavať množstvo dát do vyrovnávacej pamäte. Vytvorenie relácie a načítanie dát do cache sa tak vykoná len raz. Popis, ako využívať tento spôsob autentifikácie, je uvedený v dokumentácii Flexi API v sekcii Prihlasovanie.
Pre získanie autentifikačného tokenu je potrebné odoslať GET požiadavku na adresu
https://{tenant}.api.primaerp.com/v1/auth/login?apikey={apikey}{tenant} nahradíme názvom účtu v primaERPe
{apikey} nahradíme API kľúčom získaným od podpory primaERPu.
V hlavičke Authorization musí byť navyše meno a heslo používateľa primaERPu.
Získanie účtov z primaERP
Ak ste teda prihlásení a máte platný autentifikačný token, môžete z primaERPu začať načítavať dáta. Pre tento scenár potrebujete získať zoznam účtov, ktoré potom prenesiete do Flexi.
Zoznam účtov sa nachádza na adrese /v1/billing/bills. Rovnako ako vo Flexi je možné dáta získať v dvoch formátoch. Výber formátu je rovnaký ako vo Flexi. Dáta v XML získate doplnením prípony .xml, dáta vo formáte JSON doplnením prípony .json. Do URL musíte taktiež pridať parameter token.
Kompletná URL pre získanie JSON dát o účtoch z primaERPu je teda
https://{tenant}.api.primaerp.com/v1/billing/bills.json?token={token}Ukážka dát vo formáte JSON:
[
{
"id": "1b5127a5-b8c3-4adf-a961-0cad42f718a3",
"createdAt": "/Date(1495654409685)/",
"updatedAt": null,
"version": 0,
"docNumber": "2017/001",
"docDate": "/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": "Flexi System s.r.o.",
"code": "FLEXI",
"email": "podporaflexi@abra.eu",
"active": true,
"billsCount": null,
"projectsCount": null,
"streetAddress": "Lochotínská 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": "Tomáš",
"lastName": "Nový",
"nickName": "novotom",
"email": "tomas@flexi.eu",
"phone": null,
"position": "A02200",
"timeZone": "Europe/Berlin",
"dateFormat": "dd.MM.yyyy",
"timeFormat": "HH:mm",
"weekStart": 1,
"language": "cs_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": "Tomáš Nový"
},
"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"
}
]
Prevedenie a zápis dát do ABRA Flexi
Načítané dáta z primaERPu je potrebné transformovať do podoby, ktorú vie Flexi spracovať, a následne zapísať do príslušnej evidencie. Účty z Billingu je možné zapísať napríklad do evidencie vydaných faktúr, kde ich potom môžeme zaúčtovať.
V primaERPe sú pri účte evidované všetky potrebné údaje pre vytvorenie novej vydanej faktúry. Len typ dokladu nastavíte napevno v mostíku.
Zápis do ABRA Flexi je popísaný v článku PHP JSON zápis dát do ABRA Flexi.
Ukážkový PHP skript pre prenos účtov
function curl_get($url){ $ch = curl_init(); // create curl resource curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE); // return content as a string from curl_exec curl_setopt($ch, CURLOPT_HTTPAUTH, TRUE); // HTTP authentication curl_setopt($ch, CURLOPT_USERPWD, "emailova@adresa.cz:heslo"); // set username and password curl_setopt($ch, CURLOPT_URL, $url); // set URL curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET"); // set HTTP method $output = curl_exec($ch); $info = curl_getinfo($ch); if (curl_getinfo($ch, CURLINFO_HTTP_CODE) != 200 && curl_getinfo($ch, CURLINFO_HTTP_CODE) != 201) { printf ("Při operaci nastala chyba (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); // return content as a string from curl_exec curl_setopt($ch, CURLOPT_HTTPAUTH, TRUE); // HTTP authentication curl_setopt($ch, CURLOPT_USERPWD, "winstrom:winstrom"); // set username and password curl_setopt($ch, CURLOPT_URL, $url); // set URL curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PUT"); // set HTTP method curl_setopt($ch, CURLOPT_POSTFIELDS, $json_data); // set data $output = curl_exec($ch); // execute // Flexi return value header("Content-Type: application/json"); print ($output); // close curl resource to free up system resources 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://tenant.api.primaerp.com/v1/auth/login?apikey=abcdefgh-1234-5678-ijkl-mnopqrstuv"; $output = curl_get($url); $json = json_decode($output, true); // token for api requests $apiToken = $json['token']; echo $apiToken; // request for billing data $url = "https://tenant.api.primaerp.com/v1/billing/bills.json?token=".$apiToken; $output = curl_get($url); $billing_json = json_decode($output, true); // transform data for Flexi $faktury = array( "winstrom" => array ( "faktura-vydana" => array() ) ); foreach($billing_json as $bill){ $faktura = array(); $faktura['id'] = array(); array_push($faktura['id'], 'ext:primaerp:'.$bill['id']); array_push($faktura['id'], 'code:'.$bill['docNumber']); $faktura['typDokl'] = 'code:FAKTURA-PRIMAERP'; $faktura['kod'] = $bill['docNumber']; $faktura['bezPolozek'] = 'true'; $faktura['sumZklZakl'] = $bill['itemsPrice']; $faktura['sumCelkZakl'] = $bill['totalPrice']; $faktura['firma'] = 'code:'.$bill['client']['code']; $faktura['firma@if-not-found'] = "create"; $faktura['nazFirmy'] = $bill['client']['name']; $faktura['ulice'] = $bill['client']['streetAddress']; $faktura['psc'] = $bill['client']['zipCode']; //$faktura['stat'] = 'code:'.$bill['client']['countryCode']; $faktura['stat'] = 'code:CZ'; $faktura['dic'] = $bill['client']['vatId']; $faktura['datVyst'] = parse_date($bill['docDate'], 'Y-m-d'); $faktura['duzpPpuv'] = parse_date($bill['vatDate'], 'Y-m-d'); $faktura['datSplat'] = parse_date($bill['dueDate'], 'Y-m-d'); array_push($faktury['winstrom']["faktura-vydana"], $faktura); } // write to Flexi $url = "https://demo.flexibee.eu/c/demo/faktura-vydana.json"; $output = curl_put($url, json_encode($faktury)); ?>Ukážka 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" } ] }}Prezrite si aj ukážku vytvorenej faktúry.
Záver a zhodnotenie
V tomto príklade sa vytvárajú „bezpoložkové" faktúry. Nie je však žiadny problém začať vytvárať aj položkové. Stačí len podľa kolekcie items vytvoriť príslušné položky faktúry. Ďalším možným vylepšením celého prenosu je využitie filtrácie, vďaka ktorej možno prenášať napríklad len schválené účty alebo účty, ktoré sa zmenili od poslednej synchronizácie. Filtrácia je popísaná v dokumentácii primaERP v sekcii Filtering.
Cez API je možné priamo načítavať aj údaje z modulu Timetracking, zapisovať ich do príslušných zložiek v mzdách Flexi a zamestnancom potom podľa odpracovaných hodín počítať výplaty.
Opačným smerom z Flexi do primaERPu je možné preniesť celý adresár alebo zoznam zamestnancov, ktorí si majú evidovať čas.
Ak hľadáte pre ABRA Flexi spoľahlivý docházkový systém, primaERP je určite správnou voľbou. Navyše ponúka možnosť automatického prenosu dát z jedného systému do druhého.