api: Added History to Billing API Functions (#8209)

* Add Previous Period options to Bill API functions

* Add Bill History API Functions

doc/API/Bills.md

@@ -5,12 +5,14 @@ source: API/Bills.md
 Retrieve the list of bills currently in the system.
 
 Route: `/api/v0/bills`
+       `/api/v0/bills?period=previous`
 
 Input:
 
 Example:
 ```curl
 curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/bills
+curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/bills?period=previous
 ```
 
 Output:
@@ -64,12 +66,16 @@ Output:
 Retrieve a specific bill
 
 Route: `/api/v0/bills/:id`
+       `/api/v0/bills/:id?period=previous`
        `/api/v0/bills?ref=:ref`
+       `/api/v0/bills?ref=:ref&period=previous`
        `/api/v0/bills?custid=:custid`
+       `/api/v0/bills?custid=:custid&period=previous`
 
   - id is the specific bill id
   - ref is the billing reference
   - custid is the customer reference
+  - period=previous indicates you would like the data for the last complete period rather than the current period
 
 Input:
 
@@ -125,3 +131,49 @@ Output:
  ]
 }
 ```
+
+### `get_bill_history`
+
+Retrieve the history of specific bill
+
+Route: `/api/v0/bills/:id/history`
+
+Input:
+
+Example:
+```curl
+curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/bills/1/history
+```
+
+Output:
+```json
+{
+ "status": "ok",
+ "bill_history": [
+    {
+        "bill_hist_id": "1",
+        "bill_id": "1",
+        "updated": "2018-02-06 17:01:01",
+        "bill_datefrom": "2018-02-01 00:00:00",
+        "bill_dateto": "2018-02-28 23:59:59",
+        "bill_type": "CDR",
+        "bill_allowed": "100000000",
+        "bill_used": "229963765",
+        "bill_overuse": "129963765",
+        "bill_percent": "229.96",
+        "rate_95th_in": "229963765",
+        "rate_95th_out": "1891344",
+        "rate_95th": "229963765",
+        "dir_95th": "in",
+        "rate_average": "136527101",
+        "rate_average_in": "135123359",
+        "rate_average_out": "1403743",
+        "traf_in": "3235123452544",
+        "traf_out": "33608406566",
+        "traf_total": "3268731859110",
+        "pdf": null
+    }
+ ],
+ "count": 1,
+}
+```

html/api_v0.php

@@ -113,6 +113,7 @@ $app->group(
                     function () use ($app) {
                         $app->get('/:bill_id', 'authToken', 'list_bills')->name('get_bill');
                         // api/v0/bills/$bill_id
+                        $app->get('/:bill_id/history', 'authToken', 'get_bill_history')->name('get_bill_history');
                     }
                 );
                 $app->get('/bills', 'authToken', 'list_bills')->name('list_bills');

html/includes/api_functions.inc.php

@@ -86,6 +86,13 @@ function api_error($statusCode, $message)
     $app->stop();
 } // end api_error()
 
+function check_bill_permission($bill_id)
+{
+    if (!bill_permitted($bill_id)) {
+        api_error(403, 'Insufficient permissions to access this bill');
+    }
+}
+
 function check_device_permission($device_id)
 {
     if (!device_permitted($device_id)) {
@@ -1248,6 +1255,7 @@ function list_bills()
     $bill_id = mres($router['bill_id']);
     $bill_ref = mres($_GET['ref']);
     $bill_custid = mres($_GET['custid']);
+    $period = $_GET['period'];
     $param = array();
 
     if (!empty($bill_custid)) {
@@ -1266,8 +1274,21 @@ function list_bills()
         $sql    .= ' AND `bill_id` IN (SELECT `bill_id` FROM `bill_perms` WHERE `user_id` = ?)';
         $param[] = $_SESSION['user_id'];
     }
+    
+    if ($period === 'previous') {
+        $select = "SELECT bills.bill_name, bills.bill_notes, bill_history.*, bill_history.traf_total as total_data, bill_history.traf_in as total_data_in, bill_history.traf_out as total_data_out ";
+        $query = 'FROM `bills`
+            INNER JOIN (SELECT bill_id, MAX(bill_hist_id) AS bill_hist_id FROM bill_history WHERE bill_dateto < NOW() AND bill_dateto > subdate(NOW(), 40) GROUP BY bill_id) qLastBills ON bills.bill_id = qLastBills.bill_id
+            INNER JOIN bill_history ON qLastBills.bill_hist_id = bill_history.bill_hist_id
+    ';
+    } else {
+        $select = "SELECT bills.*,
+            IF(bills.bill_type = 'CDR', bill_cdr, bill_quota) AS bill_allowed
+        ";
+        $query = "FROM `bills`\n";
+    }
 
-    foreach (dbFetchRows("SELECT * FROM `bills` WHERE $sql ORDER BY `bill_name`", $param) as $bill) {
+    foreach (dbFetchRows("$select $query WHERE $sql ORDER BY `bill_name`", $param) as $bill) {
         $rate_data    = $bill;
         $allowed = '';
         $used = '';
@@ -1299,6 +1320,25 @@ function list_bills()
     api_success($bills, 'bills');
 }
 
+function get_bill_history()
+{
+    global $config;
+    $app = \Slim\Slim::getInstance();
+    $router = $app->router()->getCurrentRoute()->getParams();
+    $bill_id = mres($router['bill_id']);
+    
+    if (!is_admin() && !is_read()) {
+        check_bill_permission($bill_id);
+    }
+    
+    $result = [];
+    foreach (dbFetchRows('SELECT * FROM `bill_history` WHERE `bill_id` = ? ORDER BY `bill_datefrom` DESC LIMIT 24', array($bill_id)) as $history) {
+        $result[] = $history;
+    }
+    
+    api_success($result, 'bill_history');
+}
+
 function update_device()
 {
     check_is_admin();