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
- firstname (string) - the customer’s first name.
- lastname (string) - the customer’s last name.
- email (string) - the customer’s email.
- address (string) - the customer’s address.
- Invoice_language (string) - the language of the customer's invoice. (en_GB - for English \ de_CH - for German \ fr_CH - for French)
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:
- _id (string): object id.
- aid (integer): customer’s id.
- can also be queried by any custom field if the flag “searchable” is on for the field.
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
- aid (integer) - the customer’s id.
- plan (string) - the subscriber’s plan name.
- firstname (string) - the subscriber’s first name.
- lastname (string) - the subscriber’s last name.
- all other custom fields (must send those marked as “mandatory”)
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
- _id (string): the object id
There is also an option to query by:
- sid (int): the subscriber id.
- type (string): the string subscriber.
- effective_date (date): the date in which the revision that was active at that time will be updated.
- push_fields (array of objects) - {"field_name":"FIELD_NAME","field_values":["VALUE1"]}.
- pull_fields (array of objects) -
- Object : {"field_name":"FIELD_NAME","field_values":["VALUE1"],"pull_by_key":"KEY"}
- Simple value: {"field_name":"FIELD_NAME","field_values":["VALUE1"]}
¶ Close and New
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:
- _id (string): object id.
- aid (integer): customer’s id.
- sid (integer): subscriber’s id.
- can also be queried by any custom field if the flag “searchable” is on for the field.
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.
- query object:
- _id - object id
- sid - the subscriber id
- aid - the subscriber's account id
- firstname - the subscriber's first name
- lastname - the subscriber's last name
- page (int) - the index of the page use for pagination (-1 for no pagination)
- size (int) - the size of the page retrieved (-1 for unlimited)
- states (string) - jsonify array of states. The state is numeric, and meaning as follow: 0 - active, 1 - future, 2 - expire. Default (if not passed) is active and future.
Example: [1,2] means only future and expired entities will be retrieved.
- Project:
- Object that mentions which field to retrieve back. For example: {“to”:1, “from”:1, “name”:1}
http://HOST/billapi/subscribers/close
Deactivate the subscriber at a specific date
Query input:
Update input:
- to (date; optional) - the expiration date. If no date supplied it will be now.
http://HOST/billapi/subscribers/reopen
Deactivate the subscriber at a specific date
Query input:
Update input:
- from (date; optional) - the expiration date. If no date supplied it will be now.
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
- _id (string): the object id
- effective_date (date): the date in which the revision that was active at that time will be updated.
There is also an option to query by:
- sid (int): the subscriber id.
- type (string): the string subscriber.
- from (date) - the date to update revisions from.
- push_fields (array of objects) - {"field_name":"FIELD_NAME","field_values":["VALUE1"]}.
- pull_fields (array of objects) -
- Object : {"field_name":"FIELD_NAME","field_values":["VALUE1"],"pull_by_key":"KEY"}
- Simple value: {"field_name":"FIELD_NAME","field_values":["VALUE1"]}
http://HOST/billapi/subscribers/permanentchange?query={"sid":"65373","type":"subscriber", "effective_date":"2017-09-18"}&update={"from":"2017-09-20", "firstname" :"Bobby"}
- When updating a subscriber's service quantity make sure to also update the “from” of the service with the revision start date.
http://HOST/billapi/subscribers/delete
http://HOST/billapi/rates/create
Create a new product
- from (date) - the start effective date.
- to (date) - the end effective date
- key (string) - product key
- description (string) - product description (used in the invoice)
- pricing_method (string) - either "tiered" or "volume"
- rates (array) - The product prices by intervals and ranges
- vatable (boolean) - Is the product taxable
http://HOST/billapi/rates/get?query={}
Method to get products
- _id (string) - object id.
- key (string) - the product name
- description (string) - the product description
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
- _id (string): the object id
There is also an option to query by:
- key (string): the product’s key.
- effective_date (date): the date in which the revision that was active at that time will be updated.
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.
- query object:
- _id - object id
- name -available on all entities except rates
- key - available only on rates entities
- other fields that relevant to each entity (see entities description or ini files)
- page (int) - the index of the page use for pagination (-1 for no pagination)
- size (int) - the size of the page retrieved (-1 for unlimited)
- states (string) - jsonify array of states. The state is numeric, and meaning as followsfollow: 0 - active, 1 - future, 2 - expire. Default (if not passed) is active and future.
Example: [1,2] means only future and expired entities will be retrieved. - Project:
- Object that mention which field to retrieve back. For example: {“to”:1, “from”:1, “name”:1}
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:
- to (date; optional) - the expired date. If no date supplied it will be now.
¶ Close and New
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
- from (date) - the start effective date.
- to (date) - the end effective date
- name (string) - plan name
- price (array) - plan price
- description (string) - plan description (used in the invoice)
- include (array) - group option includes
- upfront (boolean) - is plan paid upfront / arrears
- recurrence.periodicity (string) - "month" OR "year"
- rates (array) - overridden products price
- prorated (boolean) - is the plan pro-rated or not
- connection_type (string) - either "prepaid" OR "postpaid"
http://HOST/billapi/plans/get?query={}
Method to get plans
- _id (string) - object id.
- name (string) - the plan name
- description (string) - the plan description
http://HOST/billapi/plans/update
Update the plan entity
- _id (string): the object id
There is also an option to query by:
- name (string): the plan’s name.
- effective_date (date): the date in which the revision that was active at that time will be updated.
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).
- query object:
- _id - object id
- name -available on all entities except rates
- key - available only on rates entities
- other fields that relevant to each entity (see entities description or ini files)
- page (int) - the index of the page use for pagination (-1 for no pagination)
- size (int) - the size of the page retrieved (-1 for unlimited)
- states (string) - jsonify array of states. The state is numeric, and meaning as follow: 0 - active, 1 - future, 2 - expire. Default (if not passed) is active and future.
Example: [1,2] means only future and expired entities will be retrieved. - Project:
- Object that mention which field to retrieve back. For example: {“to”:1, “from”:1, “name”:1}
http://HOST/billapi/plans/close
Make object expired
Query input:
Update input:
- to (date; optional) - the expired date. If no date supplied it will be now.
¶ Close and New
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
- from (date) - the start effective date.
- to (date) - the end effective date
- name (string) - service name
- price (array) - service price
- description (string) - service description (used for the invoice)
- include (array) - group option includes
- recurrence (array) - {"periodicity":"month"}
http://HOST/billapi/services/get?query={}
Method to get services
- _id (string) - object id.
- name (string) - the service name
- description (string) - the service description
http://HOST/billapi/services/update
Update the service entity
- _id (string): the object id
There is also an option to query by:
- name (string): the service’s name.
- effective_date (date): the date in which the revision that was active at that time will be updated.
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).
- query object:
- _id - object id
- name -available on all entities except rates
- key - available only on rates entities
- other fields that relevant to each entity (see entities description or ini files)
- page (int) - the index of the page use for pagination (-1 for no pagination)
- size (int) - the size of the page retrieved (-1 for unlimited)
- states (string) - jsonify array of states. The state is numeric, and meaning as follow: 0 - active, 1 - future, 2 - expire. Default (if not passed) is active and future.
Example: [1,2] means only future and expired entities will be retrieved. - Project:
- Object that mention which field to retrieve back. For example: {“to”:1, “from”:1, “name”:1}
http://HOST/billapi/services/close
Make object expired
Query input:
Update input:
- to (date; optional) - the expired date. If no date supplied it will be now.
¶ Close and New
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.
http://HOST/billapi/lines/get?query={}
Method to get lines
- _id (string) - object id (optional).
- aid (integer) - the account id (optional)
- sid (integer) - the subscriber id (optional)
- type (string) - the event input processor name (optional)
- plan (string) - the subscriber's plan at the time of the usage (optional)
- _id (string) - object id.
- aid (integer) - the account id
- sid (integer) - the subscriber id
- type (string) - the event input processor name
- plan (string) - the subscriber's plan at the time of the usage
- arate_key (string) - the product key
- aprice (float) - the price before taxes
- source (string) - the source of the event
- stamp (string) - BillRun unique hash of the event
- urt (object) - the time of the event
- realtime (boolean) - Is it a real-time event
- firstname (string) - the subscriber's first name
- lastname (string) - the subscriber's last name
- connection_type (string) - the connection type of the plan (postpaid / prepaid)
- usaget (string) - the activity type of the event
- usagev (integer) - the volume used in the event
- billrun (string) - the billing cycle identifier of the event
- final_charge (float) - the price after taxes
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:
- ‘extra_params.aid’ (integer): customer’s id.
- ‘extra_params.sid’ (integer): subscriber’s id.
- ‘extra_params.row.usagev’: usage of the cdr that triggered the notification.
- start_notify_time: time that the notification was sent to 3rd party.
- notify_time: time of confirmation that the notification was received.
- event_code: the user-defined event code of the triggered event.
- event_type: balance/subscriber/customer.
- based_on:
- usage: threshold is usage based.
- monetary: threshold is monetary based.
- stamp: unique identifier of the notification record.
- creation_time: time that the notification was created at the database(some threshold was reached).
- before (integer): usage/cost before taking into account another cdr usage.
- after (integer): usage/cost after taking into account another cdr usage.
- group_total (integer): appears only if there’s condition on a group, displays the the group included usage.
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”,
”event_type”=”balance, ”before”=0, ”after”=5, “based_on”=”monetary”, stamp=”90d9b683d0f3912a41166e5aa8ac27bc”,
“start_notify_time”=1513604493, ”creation_time”=1513603493,
“extra_params”={“aid”:2, ”sid”:7, “row”:{“usagev”:60, “urt”:1513604493}}, “conditions”=[{“path”:”balance.cost”,”unit”:””,”usaget”:””,
”type”:”reached_constant_recurring”},”value”:10}]}
Method to get balances
http://HOST/billapi/balances/get?query={}
One (or combination) of the following:
- _id (string): object id.
- aid (array): customer’s id.
- sid (array): subscriber’s id.
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:
- _id (string): object id.
- sid (integer): subscriber’s id.
- aid (integer): account’s id (only in case this is shared balance)
To update a prepaid balance use one of:
- charging_plan
- charging_plan_name
- pp_includes_name
- pp_includes_external_id
- secret (card password)
Additional fields:
- value (mandatory - depends on the update parameter)
- expiration_date (optional) - date time ISO format
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:
- _id (string): object id.
- from (ISODate query)
- to (ISODate query)
- next_renew (ISODate query): the date in which the next charge should be applied
- last_renew (ISODate query): the last date in which the last charge was applied
- bucket_group: (string): the name of the bucket-group attached to the recurring-charge
- aid (array): customer’s id.
- sid (array): subscriber’s id.
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":{"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
- from (ISODate query)
- to (ISODate query)
- aid (int): customer’s id.
- sid (int): subscriber’s id.
- next_renew (ISODate): the date in which the next charge should be applied
- bucket_group: (string): the name of the bucket-group attached to the recurring-charge
- cycles (int): number of cycles that the auto-renew will occur
- Interval (string): one of: month/day
- Immediate (boolean): whether or not to run the operation instantly (or to wait for next renew cycle)
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:
- aid (int): customer’s id.
- sid (int): subscriber’s id.
- next_renew (ISODate): the date in which the next charge should be applied
- bucket_group: (string): the name of the bucket-group attached to the recurring-charge
- Interval (string): one of: month/day
- cycles_remaining (int): number of renews left
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
http://HOST/locale
- simpleArray (1 or 0) - if true return array of objects, else objects of objects while the root object key is the currency code.
- locale - return the currency name in specific locale (default: en_US)
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
- All dates in the following format: Y-m-dTH:i:sZ (e.g. 2001-09-15T21:00:00Z)
Structure:
- aid - account id [required]
- billrun_key - required billing cycle [required]
- output - requested output method. currently supporting only “invoice_meta_data” [optional (default- no output)]
- ignore_cdrs - retrieve only credit lines [optional (default- false)]
- data - in case you want to pass external data that the system will evaluate expected invoice for [optional (default- result for aid, billrun_key). Structure:
- services - array of subscribers (first should be type ‘account’)
- plan_dates- array of plan details
- from
- to
- plan (only for type ‘subscriber’)
- plan_activation (only for type ‘subscriber’)
- plan_deactivation (only for type ‘subscriber’)
- id - array with subscriber details
- aid
- sid (only for type ‘subscriber’)
- plan (only for type ‘subscriber’)
- first_name
- last_name
- type - one of [“subscriber", “account”]
- address
- Services - array of the subscriber’s services
- name
- from
- to
- service_id
- creation_time
- Passthrough - array with all subscriber data merged
- aid
- sid (only for type ‘subscriber’)
- plan (only for type ‘subscriber’)
- first_name
- last_name
- plan_activation
- services (see above structure)
- from
- to
- deactivation_date
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
- All dates in the following format: Y-m-dTH:i:sZ (e.g. 2001-09-15T21:00:00Z)
Structure:
- aid - account id [required]
- send_email - 0/1 according to your choice (default value is 1):
- 0 - no email will be sent to the account.
- 1 - email will be sent to the account.
- allow_bill - 0/1 according to your choice (default value is 1):
- 0 - the invoice could never be confirmed.
- 1 - invoice confirmation is possible at a later stage.
- step - 0/1/2 according to your choice (default value is 2):
- 0 - create only PDF file.
- 1 - create PDF file, and bill for the invoice amount.
- 2 - create PDF file, bill for the invoice amount, and try to charge.
- charge_flow - the charge flow definition
- charge_after_invoice (default) - first generating invoice and then charge the invoice.
- charge_before_invoice - invoice will be triggered only if charge successfully.
- expected (1 or 0) - if set, the invoice will be demonstrated without issuing it in the account receivable (AKA as expected invoice).
- cdrs:
- Structure:
- aid : Billrun account identifier [mandatory].
- sid : Billrun subscription identifier (in case of account level credit, use sid=0) [mandatory].
- rate : the key of the rate for the credit/debit [mandatory].
- credit_time : unix timestamp or Y-m-dTH:i:sZ (1574759597 or 2019/11/26Z9:13:00Z). Timezone is based on server if not specified. If missing, the current date + time will be the credit time.
- usagev : volume of usage. The “aprice” will be multiplied by this, to calculate the credit/debit amount [mandatory].
- type: “credit”.
- aprice : price to credit/debit (float, price sign will be -/+, respectively to credit/debit) [optional - if set it will override the original price].
- invoice_unixtime - unix timestamp (optional) - will affect the invoice billrun key (duplicates per aid are not allowed)
- uf : Custom user fields can be added to the one time invoice object. It’s possible to send a list of uf fields and their values. The uf field names need to be configured - so they will be considered in the one time invoice processing.
Examples:
- http://host/api/onetimeinvoice?cdrs=[{“aid”:3,”sid”:5,”rate”:”NATIONAL_CALL”,”credit_time”:”2019-03-01T17:17:00.000Z”,”usagev”:4,”type”:”credit”,”aprice”:5.1}]&aid=3&send_email=1&step=1&allow_bill=1
- http://host/api/onetimeinvoice?cdrs=[{"aid":1,"sid":2,"rate":"TEST","credit_time":"2022-03-01T17:17:00.000Z","usagev":4, "type":"credit","aprice":5.1}]&aid=1&send_email=1&step=1&allow_bill=1&uf={"agent":"John","message":"Hello"}
Limitations:
There are some limits imposed on the one time invoice values that need to be understood while using it:
- CDR timing (credit_time/urt) need to be within the life time of the CDR owner. for example CDR for subscriber cannot be after the subscriber cased its service.
- Invoicing time (invoice_unixtime) need to be on active accounts or within the life time of active account
- Reusing the same invoice timestamp on the same account will rewrite an existing invoice.
Create new user
http://HOST/billapi/users/create
- username (string) - the user name.
- password (string) - plain text password. This will be encrypted to database.
- roles (array) - can contain at least zero (or more) values: read, write or admin.
Method to get users
http://HOST/billapi/users/get?query={}
- _id (string): object id.
- username: the user name.
array of user objects
Notice: the hashed password will no return in the results.
Update the user entity
http://HOST/billapi/users/update
- _id (string): the object id
Update input - same as create
http://HOST/billapi/users/delete