The new bill api is more REST convenient and simple to use. It’s implemented from version 5.3.
The general structure is http://{HOST}/billapi/<entity>/<method>?query={<input>}&update={<input>}{&<more flags>}
Date format should be ISO 8601 Format: YYYY-MM-DDThh:mm:ss{+XX:XX}
When querying with effective date the chosen revision will be the one that was active at the time of the date transferred in effective_date field.
Create a new customer, "aid" (customer/account id) will be generated automatically.
http://HOST/billapi/accounts/create
http://HOST/billapi/accounts/create?update={"firstname":"account2","lastname":"account2","email":"test@abcde.com","address":"test_address_1"}
{
"status":1,
"details":true,
"entity":
{"_id": {"$id":"5910791210bc9655652f31a3"},
"aid":27,
"firstname":"account2",
"lastname":"account2",
"email":"test@abcde.com",
"address":"test_address_1",
"type":"account",
"creation_time":{"sec":1494251794,"usec":393000},
"from":{"sec":1494251794,"usec":393000},
"to":{"sec":6196229794,"usec":0}
}
}
Method to get customers
http://HOST/billapi/accounts/get?query={}
One (or combination) of the following:
array of customer objects
http://HOST/billapi/accounts/get?query={"aid":27}
{
"status":1,
"next_page":false,
"details":[{
"_id":{"$id":"5910791210bc9655652f31a3"},
"aid":27,
"firstname":"account2",
"lastname":"account2",
"email":"test@abcde.com",
"address":"test_address_1",
"type":"account",
"creation_time":{"sec":1494251794,"usec":393000},
"from":"2017-05-08T16:56:34+0300",
"to":"2166-05-08T16:56:34+0200",
"invoice_language":"en_GB”,
"revision_info":{
"status":"active",
"early_expiration":false,
"updatable":true,
"closeandnewable":true,
"movable":true,
"removable":true,
"movable_from":true,
"movable_to":true
}
}]
}
http://HOST/billapi/accounts/delete
http://HOST/billapi/accounts/delete?query={"_id":"62d542d18d5ed567061f8d13"}
The object id can be archived by: http://HOST/billapi/accounts/get?query={} and search for the account to be deleted.
{"status": 1,"details": true,"entity": null}
Create new subscriber, sid will be generated automatically.
http://HOST/billapi/subscribers/create
http://HOST/billapi/subscribers/create?update={"aid":27,"plan":"pp_plan_1","firstname":"test_2","lastname":"test_2","MSISDN":"972547778881"}
{"status":1,"details":true,"entity":{"_id":{"$id":"5910795c10bc9648f906e5b5"},"aid":27,"sid":28,"plan":"pp_plan_1","firstname":"test_2","lastname":"test_2","MSISDN":"972547778881","type":"subscriber","plan_activation":{"sec":1494251868,"usec":393000},"creation_time":{"sec":1494251868,"usec":393000},"services":null,"from":{"sec":1494251868,"usec":393000},"to":{"sec":6196229868,"usec":0}}}
http://HOST/billapi/subscribers/update
Update the subscriber entity
There is also an option to query by:
Method to close the current entity and open a new one with follow-up change (used for tracking changes and in-advance update in the future).
http://HOST/billapi/subscribers/closeandnew
Input same as update method. The from field will be used as the close date for the updated revision.
Method to get subscribers
http://HOST/billapi/subscribers/get?query={}
One (or combination) of the following:
array of subscriber objects
http://HOST/billapi/subscribers/get?query={"sid":28}
{"status":1,"next_page":false,"details":[{"_id":{"$id":"5910795c10bc9648f906e5b5"},"aid":27,"sid":28,"plan":"pp_plan_1","firstname":"test_2","lastname":"test_2","MSISDN":"972547778881","type":"subscriber","plan_activation":{"sec":1494251868,"usec":393000},"creation_time":{"sec":1494251868,"usec":393000},"services":null,"from":"2017-05-08T16:57:48+0300","to":"2166-05-08T16:57:48+0200","revision_info":{"status":"active","early_expiration":false,"updatable":true,"closeandnewable":true,"movable":true,"removable":true,"movable_from":true,"movable_to":true}}]}
http://HOST/billapi/subscribers/uniqueget?query={}
Retrieve list of objects without duplication of history/future changes. The uniqueness is by the subscriber sid.
http://HOST/billapi/subscribers/close
Deactivate the subscriber at a specific date
Query input:
Update input:
http://HOST/billapi/subscribers/reopen
Deactivate the subscriber at a specific date
Query input:
Update input:
http://HOST/billapi/subscribers/reopen?query={"_id":"63a1c2875284ac91f50baf74"}&update={"from":"2022-12-19T22:00:00.000Z"}
Updates all revisions of subscriber according to the “from” parameter that is passed.
If from date is between some revision dates permanent change acts like "close and new" on the first half of the revision (between revision from date and the passed from date) and like update on the second half of the revision (between the passed from date and revision to date).
* Note: you can also specify the time of the “from” and "to", for example: from":"2018-10-15T22:15:00Z".
http://HOST/billapi/subscribers/permanentchange
There is also an option to query by:
http://HOST/billapi/subscribers/delete
http://HOST/billapi/rates/create
Create a new product
http://HOST/billapi/rates/get?query={}
Method to get products
http://HOST/billapi/rates/get?query={"key":"MOB_AAA"}
{"status": 1,"next_page": false,"details": [{"_id": {"$id": "605b45871ddad6161ae10e2c"},"from": "2019-12-31T23:00:00+0000", … }
http://HOST/billapi/rates/update
Update the product entity
There is also an option to query by:
http://HOST/billapi/rates/delete
http://HOST/billapi/rates/uniqueget?query={}
Retrieve list of objects without duplication of history/future changes. The uniqueness if by the product key.
http://HOST/billapi/rates/uniqueget?query={"status":"1"}
{"status": 1,"next_page": false,"details": [{"_id": {"$id": "605b45871ddad6161ae10e2a"},"from": "2017-12-31T23:00:00+0000", … }
http://HOST/billapi/rates/close
Make object expired
Query input:
Update input:
Method to close the current entity and open a new one with follow-up change (use for track changes and in-advance update in the future).
http://HOST/billapi/rates/closeandnew
Input same as update method. The from field will be used as the close date.
http://HOST/billapi/plans/create
Create a new plan
http://HOST/billapi/plans/get?query={}
Method to get plans
http://HOST/billapi/plans/update
Update the plan entity
There is also an option to query by:
http://HOST/billapi/plans/delete
http://HOST/billapi/plans/uniqueget?query={}
Retrieve list of objects without duplication of history/future changes. The uniqueness is by the name of the objects (or key in rates/products).
http://HOST/billapi/plans/close
Make object expired
Query input:
Update input:
Method to close the current entity and open a new one with follow-up change (use for track changes and in-advance update in the future).
http://HOST/billapi/plans/closeandnew
Input same as update method. The from field will be used as the close date.
http://HOST/billapi/services/create
Create new service
http://HOST/billapi/services/get?query={}
Method to get services
http://HOST/billapi/services/update
Update the service entity
There is also an option to query by:
http://HOST/billapi/services/delete
http://HOST/billapi/services/uniqueget?query={}
Retrieve list of objects without duplication of history/future changes. The uniqueness if by the name of the objects (or key in rates/products).
http://HOST/billapi/services/close
Make object expired
Query input:
Update input:
Method to close the current entity and open a new one with follow-up change (use for track changes and in-advance update in the future).
http://HOST/billapi/services/closeandnew
Input same as update method. The from field will be used as the close date.
Discount create:
http://HOST/billapi/discounts/create
Conditional charge create:
http://HOST/billapi/charges/create
Create new discount/conditional charge:
Field: All subscriber/account/services fields.
Operators:
Value: (string/int/date) - depending on the condition field chosen.
Subject Use example (discounts):
http://HOST/billapi/discounts/create?update={"description":"sub","key":"DISCNT","proration":"inherited","priority":"","params":{"min_subscribers":"","max_subscribers":""},"from":"2019-10-10","type":"monetary","subject":{"plan":{"MOBILE_MAX":{"value":150}}}}
Subject Use example (Conditional Charges):
Operator Use Example:
This current discount example will only be approved if the account’s payment gateway is “EASY_PAY”:
"conditions":[{"account":{"fields" : [{ "field" : "payment_gateway", "op" : "eq","value" : "EASY_PAY"}] }}]
Notice: every database field of services,account,subscriber can/may be used as a query condition,while using logically suitable operators.
Subject structure example:
"subject" : {"plan" : {"PACKAGE2" : {"value" : "30"}}}
Database condition structure example:
“params”:{
“conditions”:[{
"account" : {
"fields" : [{
"field" : "account_num",
"op" : "in",
"value" : [123]
}]
},
“subscriber”:[{
“fields”:[{“field”:”plan”.
“op”:”eq”
“value”:”PLAN_KEY”}],
“service”:{
“any”[{
fields:[{“field”:”name”.
“op”:”in”
“value”:”SERIVCE_KEY}]
}]
}
}]
}]
}The “params” is an object which contains a nested condition array. In the condition array first object, we allow 3 condition filters “account condition”, “subscriber condition” and “service condition”. Each have different values which are used as filters for the condition query. From each of those, there’s no limit on the amount of filters & conditions. Notice: the “service” condition is placed in the subscriber object (even when a subscriber’s condition is empty).
Examples:
Assuming we want to grant “old subscribers” a 20% off discount for “LOCAL CALLS“ service. old subscribers will be categorized by an activation date older than 1/10/2018:
Method to get discounts
http://HOST/billapi/discounts/get
http://HOST/billapi/discounts/get?query={"key":"DISCOUNT_KEY"}
Update the user entity
http://HOST/billapi/discounts/update
Update input - can update the params
http://HOST/billapi/lines/get?query={}
Method to get lines
Deletes only manual charges (type="credit").
If the relevant charge is still being calculated (in the queue) or is from a closed billing cycle, an error will be received and the charge won't be deleted.
http://HOST/billapi/lines/delete
Method to get events
http://HOST/billapi/events/get?query={}
One (or combination) of the following:
array of events objects
http://HOST/billapi/events/get?query={"sid":28, ”event_type”:”balance” }
{"status":1,"next_page":false,"details":[{“event_code”=”TOTAL_COST”,
“start_notify_time”=1513604493, ”creation_time”=1513603493,
”type”:”reached_constant_recurring”},”value”:10}]}
Method to get balances
http://HOST/billapi/balances/get?query={}
One (or combination) of the following:
array of balances objects
http://HOST/billapi/balances/get?query={"sid":{"$in":[110]}}
{"status":1,"next_page":false,"details":[{"_id":{"$id":"59070f7510bc96262f59573c"},"balance_id":"balance_1","aid":100,"sid":110,"from":"2016-10-15T21:11:43+0300","to":"2116-10-15T20:11:43+0200","balance":{"totals":{"call":{"usagev":0}}},"tx":[],"revision_info":{"status":"active","early_expiration":false,"updatable":false,"closeandnewable":false,"movable":false,"removable":false,"movable_from":true,"movable_to":true}}]}
Method to create/update balances (wallets)
http://HOST/billapi/balances/update
One (or combination) of the following:
To update a prepaid balance use one of:
Additional fields:
Success response (status=1) on success, error message on failure
http://HOST/billapi/balances/update?query={"sid":5,"pp_includes_external_id":1}&update={"value":-50}
{"status":1,"details":true,"entity":null}
Method to get auto-renews (Recurring Charges)
http://HOST/billapi/autorenew/get?query={}
One (or combination) of the following:
array of auto renew (recurring-charges) objects
http://HOST/billapi/autorenew/get?query={"sid":25,"next_renew":{"$gt":"2017-09-20T00:00:00"}}
{"status":1,"next_page":false,"details":[{"_id":{"$id":"59ec623110bc962fab3a2c02"},"from":"2017-10-22T00:00:00+0000","sid":101,"aid":100,"bucket_group":"BUCKET1","cycles":12,"interval":"month","next_renew":"2017-11-22T00:00:00+0000","cycles_remaining":12,"to":"2166-10-22T09:17:37+0000","creation_time":{"sec":1508630400,"usec":0},"revision_info":[
{
"id": "0000010670591",
"rejection": {
"code": "wrong_branch"
}
},
{
"id": "0000010670866",
"rejection": {
"code": "wrong_branch"
}
},
{
"id": "0000010668718",
"rejection": {
"code": "wrong_branch"
}
},
{
"id": "0000010668150",
"rejection": {
"code": "wrong_branch"
}
},
{
"id": "0000010670501",
"rejection": {
"code": "wrong_branch"
}
},
{
"id": "0000010671320",
"rejection": {
"code": "wrong_branch"
}
}
]{"status":"active","is_last":true,"early_expiration":false,"updatable":true,"closeandnewable":true,"movable":true,"removable":true,"movable_from":true,"movable_to":true}}]}
Method to delete an auto-renew (Recurring Charge)
http://HOST/billapi/autorenew/delete
The deleted object, and success code
http://HOST/billapi/autorenew/delete?query={“_id”:”59ec66b410bc961eb94f59f4”}
{"status":1,"details":true,"entity":{"_id":{"$id":"59ec623110bc962fab3a2c02"},"from":{"sec":1508630400,"usec":0},"sid":101,"aid":100,"bucket_group":"BUCKET1","cycles":12,"interval":"month","next_renew":{"sec":1511308800,"usec":0},"cycles_remaining":12,"to":{"sec":6210639412,"usec":0},"creation_time":{"sec":1508630400,"usec":0}}}
Method to create a new auto-renew (Recurring Charge)
http://HOST/billapi/autorenew/create
auto renew (recurring-charge) object, and success code
http://HOST/billapi/autorenew/create?update={"aid":"100","sid":"101","bucket_group":"BUCKET1","cycles":"10","next_renew":"2017-11-03T22:00:00.000Z","interval":"month","from":"2017-10-22"}
{"status":1,"details":null,"entity":{"_id":{"$id":"59ec6f9b10bc962fa2680d32"},"from":{"sec":1508630400,"usec":0},"sid":101,"aid":100,"bucket_group":"BUCKET1","cycles":10,"interval":"month","next_renew":{"sec":1509746400,"usec":0},"cycles_remaining":10,"to":{"sec":6210641691,"usec":0},"creation_time":{"sec":1508630400,"usec":0}}}
Method to update an auto-renew (Recurring Charge)
http://HOST/billapi/autorenew/update
One (or combination) of the following:
Updated auto renew (recurring-charge) object, and success code
http://HOST/billapi/autorenew/update?query={“_id”:”59ec6f9b10bc962fa2680d32”}&update={"cycles_remaining”:2,"interval":"month"}
{"status":1,"next_page":false,"details":[{"_id":{"$id":"59b7e4d3ac23e57c2d8b5877"},"sid":90,"aid":74,"bucket_group":"DATA_2_USD_1_MONTH","cycles":0,"interval":"month","next_renew":"2017-09-29T20:00:00-0400","cycles_remaining":2}]}
http://HOST/billapi/prepaidgroups/uniqueget?query={}
Retrieve list of objects without duplication of history/future changes. The uniqueness is by the name of the objects (or key in rates/products).
Example result:
{"status":1,"next_page":false,"details":[{"_id":{"$id":"5949159fad23e58f038b4896"},"from":"2017-05-31T23:00:00+0200","name":"HOME_PLAN_10GB_30_DAYS","code":"HOME_PLAN_10GB_30_DAYS","description":"Home plan 10GB 30 days","include":[{"usagev":"10737418240","period":{"unit":"days","duration":"30"},"pp_includes_name":"Data_bucket","pp_includes_external_id":112}],"operation":"set","charging_value":1499,"to":"2117-06-20T22:00:00+0100","revision_info":{"status":"active","is_last":true,"early_expiration":false,"updatable":false,"closeandnewable":false,"movable":false,"removable":false,"movable_from":false,"movable_to":true}}
API to get all currencies supported
List of currencies properties.
Description: returns JSON of the expected invoice for the required [aid + billrun_key] or based on the input data given.
HTTP method: GET
Outgoing request:
Format: URL params
Structure:
Example:
http://host/api/generateexpected?aid=555&output=invoice_meta_data&billrun_key=201910&data={"services":[{"plan_dates":{"0":{"from":"2001-09-15T21:00:00Z","to":"2168-09-16T09:36:07Z"}},"id":{"aid":2,"first_name":"test","last_name":"account","type":"account"},"passthrough":{"aid":555,"first_name":"test","last_name":"account","invoice_shipping_method":"email","invoice_detailed":0,"from":"2001-09-15T21:00:00Z","to":"2168-09-16T09:36:07Z"}},{"plan_dates":{"0":{"plan":"TEST_PLAN","from":"2001-09-15T21:00:00Z","to":"2168-09-16T09:36:07Z","plan_activation":"2001-09-15T21:00:00Z","plan_deactivation":"2168-09-16T09:36:07Z"}},"id":{"aid":555,"sid":556,"plan":"TEST_PLAN","first_name":"test_sub","last_name":"test_subb","type":"subscriber","services":{"0":{"name":"TEST_SERVICE","from":"2001-09-15T21:00:00Z","to":"2168-09-16T09:36:07Z","service_id":"1645011450845550","creation_time":"2001-09-15T21:00:00Z"}}},"passthrough":{"sid":556,"aid":555,"first_name":"test_sub","last_name":"test_subb","plan":"TEST_PLAN","plan_activation":"2001-09-15T21:00:00Z","services":{"0":{"name":"TEST_SERVICE","from":"2001-09-15T21:00:00Z","to":"2168-09-16T09:36:07Z","service_id":"1111111111111111","creation_time":"2001-09-15T21:00:00Z"}},"from":"2001-09-15T21:00:00Z","to":"2168-09-16T09:36:07Z","deactivation_date":"2168-09-16T09:36:07Z"}}]}
Description: generates pdf file of the immediate invoice that was created, according to the cdr information, and the aid.
HTTP method: GET / POST.
Outgoing request:
Format: URL params
Structure:
Examples:
Limitations:
There are some limits imposed on the one time invoice values that need to be understood while using it:
Create new user
http://HOST/billapi/users/create
Method to get users
http://HOST/billapi/users/get?query={}
array of user objects
Notice: the hashed password will no return in the results.
Update the user entity
http://HOST/billapi/users/update
Update input - same as create
http://HOST/billapi/users/delete