primaERP API
Pro propojení primaERPu a FlexiBee je možné využít API rozhraní obou produktů. U každého z nich ale API funguje „trochu“ jinak. Pokud jsme zvyklí na FlexiBee API, tak s primaERPem budeme chvíli zápasit 🙂.
API klíč
Nejprve je potřeba získat API klíč, který nám umožní API využívat. Pro získání je bohužel nutné napsat mail na support@primaerp.com. Jeho získání jsem řešil mimo pracovní dobu a tak jsem na něj musel čekat do druhého dne. Pak mi ale dorazil mail s vygenerovaným klíčem a mohl jsem začít se zkoumáním.
Nejprve autentikace a pak teprve dotazy
Další věcí, která je jiná než u FlexiBee API, je postup, jak získávat data. U FlexiBee je možné využít HTTP autentikaci a získat tak potřebná data hned prvním requestem. V primaERP API je nutné se nejprve přihlásit. Při přihlášení se vygeneruje token s omezenou platností a ten se pak používá pro jednotlivé dotazy do API. Jakmile tokenu vyprší platnost, je nutné získat nový.
Tento princip se dá použít i ve FlexiBee, ale nemyslím si, že by ho někdo, kromě uživatelů webového rozhraní, pro své aplikace používal. Má ale jednu nespornou výhodu. Pokud je používán správně, tzn. token se získává až v okamžiku kdy vyprší, zrychluje zpracování requestů. FlexiBee totiž nemusí pro každý request vytvářet nové a nové sezení a načítat spousty dat do cache. Vytvoření sezení a načtení dat do cache se tak provede jen jednou a pak se sezení používá stále dál. Popis jak využívat tento způsob autentikace je popsán v dokumentaci FlexiBee API v sekci Přihlašování.
Pro získání autentikačního tokenu je potřeba poslat GET požadavek na adresu
https://{tenant}.api.primaerp.com/v1/auth/login?apikey={apikey}
{tenant} nahradíme názvem účtu v primaERPu
{apikey} nahradníme api klíčem, získaným od podpory primaERPu.
V hlavičce Authorization musí být ještě navíc jméno a heslo uživatele primaERPu.
Získání účtů z primaERP API
Pokud jsme tedy přihlášeni a máme platný autentikační token, můžeme z primaERPu začít číst data. Pro tento scénář potřebujeme získat seznam účtů, které pak přeneseme do FlexiBee.
Seznam účtů se nachází na adrese /v1/billing/bills . Stejně jako u FlexiBee je možné data získat ve dvou formátech. Výběr formátu je stejný jako u FlexiBee. Data v XML získáme doplněním koncovky .xml, data ve formátu JSON doplněním koncovky .json. Do URL také musíme přidat parametr token.
Kompletní URL pro získání JSON dat o účtech z primaERPu je tedy
https://{tenant}.api.primaerp.com/v1/billing/bills.json?token={token}Převedení a zápis dat do FlexiBee
Pokud máme načtena data z primaERPu, je potřeba je transformovat do podoby, kterou umí FlexiBee zpracovat a následně zapsat do patřičné evidence ve FlexiBee. Účty z billingu je možné zapsat například do evidence vydané faktury, kde je pak můžeme zaúčtovat.
V primaERPu je u účtu evidováno vše, co potřebujeme pro vytvoření nové faktury vydané. Jen typ dokladu nastavíme napevno v můstku.
Zápis do FlexiBee je popsán v článku FlexiBee API - PHP JSON zápis dat do FlexiBee, takže už ho není potřeba znovu popisovat.
Ukázkový PHP script pro přenos účtů
<?php
// primaERP nastavení
define('_PRIMAERP_USER_', 'emailova@adresa.cz'); // uživatelské jméno v primaERPu
define('_PRIMAERP_PASS_', 'heslo'); // heslo uživatele v primaERPu
define('_PRIMAERP_TENANT_', 'tenant'); // tenant primaERPu = https://{tenant}.api.primaerp.com
define('_PRIMAERP_APIKEY_', 'abcdefgh-1234-5678-ijkl-mnopqrstuv'); // API key pro komunikaci s primaERP
// FlexiBee nastavení
define('_FLEXIBEE_USER_', 'winstrom'); // uživatelské jméno ve FlexiBee
define('_FLEXIBEE_PASS_', 'winstrom'); // heslo uživatele ve FlexiBee
define('_FLEXIBEE_SERVER_', 'https://demo.flexibee.eu'); // adresa FlexiBee serveru
define('_FLEXIBEE_PORT_', '5434'); // port FlexiBee serveru
define('_FLEXIBEE_COMPANY_', 'demo'); // identifikátor firmy ve FlexiBee
function curl_get($url){
// funkce pro načtení dat z primaERP
$ch = curl_init();
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, TRUE);
curl_setopt($ch, CURLOPT_HTTPAUTH, TRUE);
curl_setopt($ch, CURLOPT_USERPWD, _PRIMAERP_USER_ . ':' . _PRIMAERP_PASS_);
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
$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){
// funkce pro zápis dat do FlexiBee
$ch = curl_init();
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, TRUE);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, FALSE);
curl_setopt($ch, CURLOPT_HTTPAUTH, TRUE);
curl_setopt($ch, CURLOPT_USERPWD, _FLEXIBEE_USER_ . ':' . _FLEXIBEE_PASS_);
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PUT");
curl_setopt($ch, CURLOPT_POSTFIELDS, $json_data);
$output = curl_exec($ch);
header("Content-Type: application/json");
print ($output);
curl_close($ch);
}
function parse_date($primaerp_date, $to_format){
// funkce převod datumu z primaERP formátu na formát FlexiBee
$timestamp = preg_replace('/[^\d]/','', $primaerp_date)/1000;
$datetime = new DateTime();
$datetime->setTimestamp($timestamp);
return $datetime->format($to_format);
}
// authentication
$url = 'https://' . _PRIMAERP_TENANT_ . '.api.primaerp.com/v1/auth/login?apikey=' . _PRIMAERP_APIKEY_;
$outputLogin = curl_get($url);
$json = json_decode($outputLogin, true);
// token for api requests
$apiToken = $json['token'];
echo $apiToken;
// request for billing data
$url = 'https://' . _PRIMAERP_TENANT_ . '.api.primaerp.com/v1/billing/bills.json?token='.$apiToken;
$outputPrimaErp = curl_get($url);
$billing_json = json_decode($outputPrimaErp, true);
// transform data for FlexiBee
$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 FlexiBee
$url = _FLEXIBEE_SERVER_ . ':' . _FLEXIBEE_PORT_ . '/c/' . _FLEXIBEE_COMPANY_ . '/faktura-vydana.json';
$outputFlexiBee = curl_put($url, json_encode($faktury));
?>
Ukázka přenosu z mého primaERP na demo.flexibee.eu
Ukázka vytvořené faktury
Závěr a zhodnocení
V tomto příkladu jsou vytvářeny „bezpoložkové“ faktury. Není ale žádný problém začít vytvářet i položkové. Stačí jen podle kolekce items vytvořit patřičné položky faktury. Dalším možným vylepšením celého přenosu je využití filtrace, abychom přenášeli například jen schválené účty nebo účty, které se změnily od poslední synchronizace. Filtrace je popsána v dokumentaci v sekci Filtering.
Přes API je možné z primaERPu načítat i přímo údaje z timetrackingu a zapisovat je do patřičných složek ve mzdách FlexiBee a zaměstnancům pak podle odpracovaných hodin vyplácet výplaty.
Z FlexiBee do primaERPu pak přichází v úvahu přenos adresáře, abychom měli komu účty vystavovat 🙂. Také seznam zaměstnanců, kteří si mají evidovat čas, je možné načítat z FlexiBee.
Největším rozdílem mezi PrimaERP API a FlexiBee API je právě autorizace. Ve FlexiBee stačí běžná HTTP autorizace, ale v primaERPu je nutné nejprve získat token a pak až teprve začít dolovat data.
Jakmile bude mít FlexiBee uživatelské transformace, bude možné celý proces zautomatizovat pomocí Integromatu. Protože pak bude FlexiBee „rozumět“ primaERP formátu dat 🙂.
Takže, jestli hledáte docházkový systém pro FlexiBee, je primaERP jistě použitelný a existuje možnost, jak automaticky přenášet data z jednoho systému do druhého.
