Universal API

en | ru

In cooperation with the developers of a number of billing systems, a universal API structure has been created, which enables convenient and standardised access to information from various billing systems.

Current version: 1.5 dated 06.10.2017 (see change history)

At the moment this API is supported by billings:

• uBilling v.0.7.2+ (API version 1.2) v.0.8.0+ (API version 1.4) (https://wiki.ubilling.net.ua/doku.php?id=usersideapi)
• MikBill v.2.8.16+ (API version 1.2) v.2.12.7+ (API version 1.4) (https://wiki.mikbill.pro/billing/configuration/api/userside)
• Carbon Billing v.5.15.06+ (API version 1.2) (https://docs.carbonsoft.ru/display/CarbonBilling/UserSide)
• ABillS (with Userside module) (http://abills.net.ua/wiki/doku.php/abills:docs:modules:userside:ru)
• also in the ERP "UserSide" itself the output of the requirements of this API is supported

The usm_billing module is used for the interaction.

IMPORTANT: Universal API is a very handy tool to work with self-written billing systems or those billing systems that we do not support at the moment. The administrator/programmer just needs to provide the data output in the required format from their billing and it will be enough for our (free) interaction module usm_billing to process it as standard.

Introductions

1. All communication is based on API queries

2. Working encoding is UTF-8

3. Response data format - JSON

4. API key is used as identification

5. Additionally, it's recommended to configure and check the IP address of the host from which requests come or limit access by vlan

6. Unsupported methods (or methods without necessary parameters) should be answered with HTTP-400 status via header. The text of the 400 response can be expanded to describe the nature of the error.

7. Text fields which have empty value - it is recommended not to return them at all (to save traffic).

8. Data is used in format:

Date - "YYYY-MM-DD hh:nn:ss" - e.g. "2012-12-28 13:59:59"
IP address - long-format inet_aton() - for example 3232235521 for "192.168.0.1"
MAC addresses - 12 lowercase unseparated characters - for example "0012b3a78912" for "00:12:B3:A7:89:12"

Supported methods

Receiving data:

GET requests are used to retrieve data. Only information that exists/is used is retrieved

get_api_information - Used version of API

get_city_district_list - Addresses. Districts in populated areas

get_city_list - Addresses. Populated areas.

get_connect_list - Connecting objects (users/equipment) to each other

get_device_list - Equipment. Device list.

get_device_model - Equipment. Device models

get_device_type - Equipment. Device types

get_house_list - Addresses. Houses

get_services_list - Services/Additional Services]]

get_street_list - Addresses. Streets

get_supported_change_user_data_list - Supported methods for changing user data via the API

get_supported_change_user_state - Supported statuses for user exchange status via API

get_supported_change_user_tariff - Supported tariff plans to change a user's tariff via API

get_supported_method_list - Supported_method_list|get_supported_method_list]].

get_system_information - System information

get_tariff_list - Fee plans. Standard Fees

get_user_additional_data_type_list - Optional field types by user

get_user_group_list - User Groups]]

get_user_history - User history by subscriber

get_user_list - Users/clients

get_user_messages - User messages]]

get_user_state_list - User status types (status configurator)]]

get_user_tags - User_tags]]

Changing data:

POST or GET requests are used. Only information that exists/is used is given

change_user_data - Changing user data

Possible operations in billing (from under UserSide)

This functionality is supported natively in uBilling starting from v.0.8.0 and in MikBill starting from v.2.12.7, or can be organised for your own self-written billing as per the above mentioned universal API

Users

• viewing the history of payments by user
• Changing the user's name/name
• Changing the user's balance

The following steps are required to use this functionality:

• In the /userside3/main/config/config.php file, add a block

$billingSynergy[99] = [
   'url' => 'http://mydomain.com/ubilling/?module=remoteapi&key=my_key&action=userside',
   'is_allow_change' => 1
];

Where:
99 - billing number ( Settings - Billings)
url - URL to the billing
my_key - billing api key
is_allow_change - flag - allows to change data from under UserSide in billing. If not enabled, only data reading is performed

• if filled in correctly, the " Settings - Billings - desired billing" page will show the results of the direct polling of the billing

History of changes

v. 1.1
17.10.2015
Added methods:
 get_supported_method_list
 get_api_information
 get_system_information
Removed element in get_house_list method
 city_id' => Identifier of the settlement
Added elements to get_house_list method
 'street2_id' => Secondary street identifier '(for corner houses)'
 'number2' => Number on secondary street (numeric. If available)
 'block2' => Block/Building/Building on secondary street (text. If present)

v. 1.2
25.10.2015
Added element to the get_user_list method
 'login' => User account name

v. 1.3
12.10.2016
Added methods:
 get_user_tags
 get_services_list
Added element to get_tariff_list method
 'service_type' => Type of tariff
Added element to get_house_list method
 'floor' => Number of storeys
 'entrance' => Number of entrances
 'coordinates' => Coordinates of house polygon points '(array)'
Added elements to the get_user_list method
 'tag' => User tags (textual)'
 'mark' => User tags (boolean)
 'service' => User service
 'password' => User password

v. 1.4
03.01.2017
Added option to get_user_list method to sample only a specific user
Added methods:
 get_user_messages
 get_user_history
 get_supported_change_user_data_list
 change_user_data
 get_supported_change_user_state
 get_supported_change_user_tariff

v. 1.5
06.10.2017
Added methods:
 get_device_type
 get_device_model
 get_device_list
 get_connect_list

v. 1.5.1
in progress
Improved method
 get_user_history
 - Added variable "customer_id" to the output
 - as input parameter can be given sample dates "date_start", "date_finish"
 - the type of actions "type" for which the selection is to be obtained can be given as an input parameter