ABRA primaERP is a handy cloud application from the ABRA Software product family. It is a tool for tracking time spent on team projects (Timetracking) and subsequently invoicing the customer (Billing). primaERP also allows you to track attendance using the Attendance module. Just like ABRA Flexi, primaERP has a sophisticated API interface, so integrating the two systems is straightforward.
The API interface works somewhat differently in each application. If you are already familiar with using the API in ABRA Flexi, you will need to get used to the differences in the primaERP API.
API Key
First, you need to obtain an API key that will allow you to use the API. To get one, contact support via the in-app chat or send an email to podpora@primaerp.com. Once you receive an email with your generated key, you can begin the setup.
Authentication and Subsequent Requests
The primaERP API also differs from Flexi in the way data is retrieved. With Flexi, you can use HTTP authentication and obtain the required data in a single request. With the primaERP API, you must log in first. Upon login, a token with a limited validity period is generated, which is then used for individual API requests. Once the token expires, a new one must be obtained.
This approach can also be used in Flexi, although it is primarily useful for web interface users. However, it has one clear advantage. When used correctly — meaning the token is only retrieved after it has expired — it speeds up request processing. Flexi does not need to create a new session and load large amounts of data into the buffer for every request. Session creation and cache loading are therefore performed only once. A description of how to use this authentication method is provided in the Flexi API documentation under the Login section.
To obtain an authentication token, you need to send a GET request to the following address:
https://{tenant}.api.primaerp.com/v1/auth/login?apikey={apikey}Replace {tenant} with the name of your primaERP account.
Replace {apikey} with the API key obtained from primaERP support.
The Authorization header must also include the primaERP username and password.
Retrieving Bills from primaERP
Once you are logged in and have a valid authentication token, you can start loading data from primaERP. For this scenario, you need to retrieve a list of bills, which you will then transfer to Flexi.
The list of bills is available at /v1/billing/bills. As with Flexi, data can be retrieved in two formats. The format is selected in the same way as in Flexi. Append the .xml extension to get XML data, or the .json extension to get JSON data. You must also add a token parameter to the URL.
The complete URL for retrieving JSON bill data from primaERP is therefore:
https://{tenant}.api.primaerp.com/v1/billing/bills.json?token={token}Sample data in JSON format:
[
{
"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"
}
]
Transforming and Writing Data to ABRA Flexi
The data loaded from primaERP must be transformed into a format that Flexi can process and then written to the appropriate register. Bills from Billing can be written, for example, to the issued invoices register, where they can subsequently be posted.
In primaERP, a bill contains all the information needed to create a new issued invoice. Only the document type needs to be set as a fixed value in the bridge.
Writing data to ABRA Flexi is described in the article PHP JSON — Writing Data to ABRA Flexi.
Sample PHP Script for Transferring Bills
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)); ?>Sample transfer from primaERP to 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" } ] }}Also take a look at the sample generated invoice.
Conclusion and Summary
In this example, "line-item-free" invoices are created. However, there is no obstacle to creating invoices with line items as well — simply use the items collection to generate the appropriate invoice lines. Another possible improvement to the transfer process is the use of filtering, which allows you to transfer only approved bills or bills that have changed since the last synchronization, for example. Filtering is described in the primaERP documentation under the Filtering section.
Via the API, you can also directly retrieve data from the Timetracking module, write it to the appropriate payroll categories in Flexi, and calculate employee pay based on hours worked.
In the opposite direction — from Flexi to primaERP — you can transfer an entire address book or a list of employees who need to track their time.
If you are looking for a reliable attendance system to use alongside ABRA Flexi, primaERP is certainly the right choice. It also offers the ability to automatically transfer data between the two systems.