source: API/Bills.md path: blob/master/doc/ ### `list_bills` 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: ```json { "status": "ok", "message": "", "count": 1, "bills": [ { "bill_id": "1", "bill_name": "Router bills", "bill_type": "cdr", "bill_cdr": "10000000", "bill_day": "1", "bill_quota": "0", "rate_95th_in": "0", "rate_95th_out": "0", "rate_95th": "0", "dir_95th": "in", "total_data": "0", "total_data_in": "0", "total_data_out": "0", "rate_average_in": "0", "rate_average_out": "0", "rate_average": "0", "bill_last_calc": "2015-07-02 17:01:26", "bill_custid": "Router", "bill_ref": "Router", "bill_notes": "Bill me", "bill_autoadded": "0", "ports_total": "0", "allowed": "10Mbps", "used": "0bps", "percent": 0, "overuse": "-", "ports": [ { "device_id": "168", "port_id": "35146", "ifName": "eth0" } ] } ] } ``` ### `get_bill` 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: Example: ```curl curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/bills/1 curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/bills?ref=:customerref curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/bills?custid=:custid ``` Output: ```json { "status": "ok", "message": "", "count": 1, "bills": [ { "bill_id": "1", "bill_name": "Router bills", "bill_type": "cdr", "bill_cdr": "10000000", "bill_day": "1", "bill_quota": "0", "rate_95th_in": "0", "rate_95th_out": "0", "rate_95th": "0", "dir_95th": "in", "total_data": "0", "total_data_in": "0", "total_data_out": "0", "rate_average_in": "0", "rate_average_out": "0", "rate_average": "0", "bill_last_calc": "2015-07-02 17:01:26", "bill_custid": "Router", "bill_ref": "Router", "bill_notes": "Bill me", "bill_autoadded": "0", "ports_total": "0", "allowed": "10Mbps", "used": "0bps", "percent": 0, "overuse": "-", "ports": [ { "device_id": "168", "port_id": "35146", "ifName": "eth0" } ] } ] } ``` ### `get_bill_graph` Retrieve a graph image associated with a bill. NB: The graphs returned from this will always be png as they do not come from rrdtool, even if you have SVG set. Route: `/api/v0/bills/:id/graphs/:graph_type Example: ```curl curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/bills/1/graphs/bits curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/bills/1/graphs/bits?from=1517443200 curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/bills/1/graphs/bits?from=1517443200&to=1517788800 curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/bills/1/graphs/monthly ``` Output: Graph Image ### `get_bill_graphdata` Retrieve the data used to draw a graph so it can be rendered in an external system Route: `/api/v0/bills/:id/graphdata/:graph_type` Input: The `reducefactor` parameter is used to reduce the number of data points. Billing data has 5 minute granularity, so requesting a graph for a long time period will result in many data points. If not supplied, it will be automatically calculated. A reducefactor of 1 means return all items, 2 means half of the items etc. Example: ```curl curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/bills/1/graphdata/bits curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/bills/1/graphdata/bits?from=1517443200 curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/bills/1/graphdata/bits?from=1517443200&to=1517788800 curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/bills/1/graphdata/bits?from=1517443200&to=1517788800&reducefactor=5 ``` Output: { "status": "ok", "graph_data": { "from": "1517443200", "to": 1518196161, "last": "1518195901", "in_data": [ 103190525.20999999, 104949255.81 ], "out_data": [ 1102059.1299999999, 1079216.46 ], "tot_data": [ 104292584.33999999, 106028472.27 ], "ticks": [ "1517750401", "1517756101" ], "rate_95th": "251880417", "rate_average": "146575554", "bill_type": "cdr", "max_in": 9888289942, "max_out": 75848756, "ave_in": 18029660.242105871, "ave_out": 196447.38060137472, "last_in": 3790227.9500000002, "last_out": 122731.63333333333 } } ### `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, } ``` ### `get_bill_history_graph` Retrieve a graph of a previous period of a bill NB: The graphs returned from this will always be png as they do not come from rrdtool, even if you have SVG set. Route: `/api/v0/bills/:id/history/:bill_hist_id/graphs/:graph_type` Input: Example: ```curl curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/bills/1/history/1/graphs/bits curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/bills/1/history/1/graphs/hour curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/bills/1/history/1/graphs/day ``` Output: (image) ### `get_bill_history_graphdata` Retrieve the data for a graph of a previous period of a bill, to be rendered in an external system Route: `/api/v0/bills/:id/history/:bill_hist_id/graphdata/:graph_type` Input: Example: ```curl curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/bills/1/history/1/graphdata/bits curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/bills/1/history/1/graphdata/hour curl -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/bills/1/history/1/graphdata/day ``` Output: ### `delete_bill` Delete a specific bill and all dependent data Route: `/api/v0/bills/:id` - id is the specific bill id Input: Example: ```curl curl -X DELETE -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/bills/1 ``` Output: ```json { "status": "ok", "message": "Bill has been removed" } ``` ### `create_edit_bill` Creates a new bill or updates an existing one Route: `/api/v0/bills` Method: `POST` - If you send an existing bill_id the call replaces all values it receives. For example if you send 2 ports it will delete the existing ports and add the the 2 new ports. So to add ports you have to get the current ports first and add them to your update call. Input: Example (create): ```curl curl -X POST -d '{"ports":[ 1021 ],"bill_name":"NEWBILL","bill_day":"1","bill_type":"quota","bill_quota":"2000000000000","bill_custid":"1337","bill_ref":"reference1","bill_notes":"mynote"}' -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/bills ``` Example (set): ```curl curl -X POST -d '{"bill_id":"32","ports":[ 1021 ],"bill_name":"NEWNAME","bill_quota":"1000000000000"}' -H 'X-Auth-Token: YOURAPITOKENHERE' https://librenms.org/api/v0/bills ``` Output: ```json { "status": "ok", "bill_id": 32 } ```