Desc: get the account current balance with breakdown and lines details
Status: deprecated call since version 5.0
Path: http://<host>/api/balance
HTTP Method: GET
Input:
- account_id - The account ID to get the balance for.
- subscribers - List of subscribers. 0 - retrieve details for all subscribers; x,y,z - (separated by commas) retrieve detailed lines for subscriber x,y,z. If not supplied - none. The subscribers arg doesn't affect the account total.
For example:
http://172.29.202.110/api/balance?aid=138192
http://172.29.202.110/api/balance?aid=138192&subscribers=0
http://172.29.202.110/api/balance?aid=138192&subscribers=453885,141074
Output format: XML
Notes:
- this call will store the details in a cache for X hours.
Error output:
- format : JSON
- all errors will have the “status” field === 0.
- all errors will have the “desc” field contain the error description.
- Possible errors :
- “aid field is not numeric” : when the provided input contain an aid value that is not numeric.
Desc: fetch alerts based on customer data usage
Status: deprecated call since version 5.0
Path: http://<host>/api/datausage
HTTP Method: GET
Input:
- plan [Mandatory]
- data_usage (Megabytes) [Mandatory]
- from_account_id [Mandatory]
- to_account_id [Mandatory]
- billrun [Mandatory]
e.g.: http://<host>/api/datausage?plan=LARGE&data_usage=3&from_account_id=1&to_account_id=10000&billrun=201312
Output format : JSON
Output structure:
- status - 1 on success, 0 on failure.
- desc - success when status 1, error description when status 0.
- subscribers_count - number of subscribers found.
- output - JSON - {"aid":{"ACCOUNT_ID_XXXX_NUM":{"subs":{"SUB_ID_XXXX_NUM":"data usage(Megabytes)","SUB_ID_YYYY_NUM":"data usage(Megabytes)"}}
Error output:
- all errors will have the “status” field === 0.
- all errors will have the “desc” field contain the error description.
- Possible errors :
- “Missing required parameter: X” : When a required field wasn’t passed as input.
Desc: get the customer’s activity (calls & sms)
Status: deprecated call since version 5.0
Path: http://<host>/api/activity
HTTP Method: POST
Input:
- sid: subscriber id
- include_incoming: incoming calls flag (1 to include, 0 exclude)
- include_outgoing: outgoing calls flag (1 to include, 0 exclude)
- include_sms: including sms flag (1 to include, 0 exclude)
- from_date: start date, can be timestamp or datetime format (PHP date: Y-m-d [H:i:s])
- to_date: end date, can be timestamp or datetime format (PHP date: Y-m-d [H:i:s])
Output Format: JSON
Output structure:
- status: 1 on success, 0 on failure
- desc: description of the api call
- details: on success only, array of lines; each line contain:
- date => event date time full format (PHP date: Y-m-d H:i:s)
- called_number => the called number (to)
- calling_number => the calling number (from)
- usagev => usage volume (duration in seconds on call and incoming call, 1 on sms)
- usaget => type of usage (call, incoming_call or sms)
- input: the input the api get (array)
Notes:
- You must specify one of the flags (include_incoming, include_outgoing or include_sms) to get results.
- All datetime fields are under local timezone
- There is a limit of 100,000 rows for results per API call, so if you need more than that need to do some pagination on the 3rd party side.
Error output:
- all errors will have the “status” field === 0.
- all errors will have the “desc” field contain the error description.
- Possible errors :
- “Subscriber not exists” : Subscriber couldn’t be found in the billing system.
Example:
http://host/api/activity?aid=12345&include_incoming=1&include_sms=0&from_date=2014-01-01&to_date=2015-01-01
Desc: Perform a JSON query on popular BillRun collections
Status: deprecated call since version 5.0
Path: http://host/api/find
HTTP Method: POST
input:
- collection - the collection on which the query should be performed (string)
- query - the query to perform on the collection (JSON string)
- page - pagination page number (int, default to 0)
- size - pagination page size (int, defaults to 1000 and is configurable)
- sort - a list of field and their sort order. Use 1 for ascending and -1 for descending. This is the same format as the input for MongoDB's sort command (JSON string).
Output format: JSON
Output structure:
- status: 1 for success, 0 for failure (int)
- desc: textual description of the result (string)
- input: the input for the api (JSON string)
- details - an object representing the resulted documents. Each key in the document is an alphanumeric string representing the MongoDB object id of the document.
Desc: Updates / creates a plan or rate after validating the input
Status: deprecated call since version 5.0
Path: http://host/admin/save
HTTP Method: POST
input:
- id - alphanumeric string representing the MongoDB object id of the original rate / plan
- coll - the desired entity (either 'rates' or 'plans', string)
- type - type of the action to perform. Either one of:
- 'close_and_new' - saves the new entity and closes the original one.
- 'duplicate' - uses the data of one entity in the new one with possibly new data to merge.
- 'update' - updates an existing entity.
- 'new' - insert a new entity (for rates - this is a new key. For plans - a new name).
Output format: JSON
Output structure:
- status: 1 for success, 0 for failure (int)
- input: the input the api get (array)
Desc: retrieve billing rates
Status: deprecated call since version 5.0
Path: http://host/api/rates
HTTP Method: GET
input:
- query - associative array represents MongoDB query (see examples)
- strip - array list of colu mn names to appear in the output without full info of rates
Output structure (array of rates) :
- key: the slug
- rates: array of each usage type (key of the array), as follow:
- unit
- category
- access
- rate as follow - array of duration and their price
- duration: int
- interval: int
- charge: float
- plans - the plan that this rate related to
- input: the input the api get (array)
Examples:
Desc: retrieve billing plans
Status: deprecated call since version 5.0
Path: http://host/api/plans
HTTP Method: GET
input:
- query - associative array represents MongoDB query (see examples)
- strip - array list of column names to appear in the output without full info of plans
Output format: JSON
Output structure ( array of plans) :
- details: JSON array of objects containing plans document (מפרט יישום Pelephone Prepaid)
Examples:
Deprecated since version 5. Please used lines delete.
Desc: removes billing lines by stamp. Remove only credit and active billrun lines.
Warning: This API is disabled by default
Path : http://host/api/remove
Method : GET
input :
Output format : JSON
Output :
- status: number of documents removed on success, false on failure
- desc: description
- input: the input sent to the api get (array)
Notes:
- This is not activated by default.
Pay attention!
- Return status === 0 *is not* the same when return status === false. On the first case means the remove runs successfully, but documents not exists in db, so number of documents is 0 (zero). On the second case means some failure occurred.
Error output:
- all errors will have the “status” field === 0.
- all errors will have the “desc” field contain the error description.
- Possible errors :
- “failed - invalid stamps input” : There was an invalid stamp in the the stamp field input.
- “remove failed‘ : the remove was failed for some of the requested stamps.
Desc: retrieves invoicing metadata for an account from billruns starting at a specific billrun date.
Status: deprecated call since version 5.0
Path: http://host/api/querybillrun
HTTP Method: GET
Input:
- aid - account id or list of account ids (separated by comma). Max: 1000
- billrun - effective billrun (format: YYYYmm), can be string or array of billrun keys
Output format: JSON
Output structure:
- status :
- 1 = successful, all subscriber balances were reset successfully
- 0 = failed, there was an error see the desc field for more information.
- desc = description of the results
- input = the input objects that were received.
- details = array of invoicing metadata
Error output:
- all errors will have the “status” field === 0.
- all errors will have the “desc” field contain the error description.
- Possible errors :
- “Require to supply aid or sid” : Invalid or missing sid and aid input fields.
- “Maximum of sid is <X>” : to many SIDs were asked in a single request.
- “Maximum of aid is <X>” : to many AIDs were asked in a single request.
Desc: API to recreate an accounts’ invoices for the last billrun
Path: http://host/api/recreateinvoices
HTTP Method: POST
Notes:
- Apache user should have write permission to files/invoices folder.
- Apache timeout is effect this call, please send in bulk in case you need more than 500.
- Flat / occ (credits) lines created during the first run should be removed before calling this method.
Input:
- account_id - list of account ids (separated by comma)
Output format: JSON
Output structure:
- status :
- 1 = successful
- 0 = failed
- desc = description of the results
- input = the raw input
- successfulAccounts = array of account ids (integers) whose billrun was recreated.
Desc: retrieve values for deleting a subscriber.
Pay attention - the subscriber is never delete but close (“to” field will be set to “now”)
Status: deprecated call since version 5.5
Path: http://host/api/subscribers
HTTP Method: POST
Input:
- method: delete
- query: JSON Object stringify which contain the filter of the delete. At least SID must be passed to the API.
- sid (integer): subscriber Id
- imsi (string): array of available imsi (International Mobile Subscriber Identity) for a subscriber
- msisdn (string): Mobile Station International Subscriber Directory Number
- keep_balances (boolean): define if to close all open balances of the subscriber after update. Default: false
Output format: JSON
Output structure:
- status: one of the following integer values
- desc: textual description of the status
- input: the raw input
Examples:
http://host/api/subscribers?method=delete&query={"sid":12345, "imsi":"4000123412341234"}
Desc: retrieve values for updating a subscriber
Status: deprecated call since version 5.5
Path: http://host/api/subscribers
HTTP Method: POST
Input:
- method: update
- query: JSON Object stringify which contain the filter of the update. At least SID must be passed to the API.
- sid (integer): subscriber Id
- imsi (string): array of available imsi (International Mobile Subscriber Identity) for a subscriber
- msisdn (string): Mobile Station International Subscriber Directory Number
- update: JSON Object stringify which contain the values to update
- imsi (string): array of available imsi (International Mobile Subscriber Identity) for a subscriber
- msisdn (string): Mobile Station International Subscriber Directory Number - uniquely identifying a subscription in a GSM or a UMTS
- aid (integer): account Id
- sid (integer): subscriber Id
- plan (string): subscriber’s market plan
- language (string): subscriber’s default interface language (e.g. for sms notifications)
- service_provider (string): subscriber’s service provider
- service: array of JSON Objects containing the following fields:
- track_history (boolean): define if to track the change applied of the subscriber or not. Default true.
- keep_balances (boolean): define if to close all open balances including auto renew services of the subscriber after update or to move the balance to new sid (if updated). Default: true. Must pass sid or aid if you want to keep balances when move to new subscriber or account.
- keep_lines (boolean): define in to keep subscriber’s lines. Default: true
Output format: JSON
Output structure:
- status: one of the following integer values
- desc: textual description of the status
- input : the raw input
- details: JSON object containing subscriber document after update
- details: JSON object containing subscriber document before update
Example:
{"status":1,"desc":"Success updating subscriber","details":[{"_id":{"$id":"55ade77600a655be6ac50e84"},"from":{"sec":1325376000,"usec":0},"to":{"sec":4604659161,"usec":0},"imsi":"425030024380232","msisdn":"0503040419","aid":12345,"sid":77777,"plan":"LARGE","service_provider":"PELEPHONE","charging_type":"prepaid"},{"_id":{"$id":"55ade77600a655be6ac50e84"},"from":{"sec":1325376000,"usec":0},"to":{"sec":4604659313,"usec":0},"imsi":"425030024380232","msisdn":"0503040419","aid":12345,"sid":77777,"plan":"LARGE","service_provider":"PELEPHONE","charging_type":"prepaid"}],"input":{"method":"update","query":"{\"aid\":12345,\"sid\":77777}","update":"{\"msisdn\":\"0503040419\"}"}}
Notes:
Updating a subscriber closes the current subscriber (changes ‘to’ field) and creates a new document.
Desc: retrieve subscriber’s history. If no “from” and “to” will be transferred, the current open line will be retrieved
Status: deprecated call since version 5.5
Path: http://host/api/subscribers
HTTP Method: POST
Input:
- method: query
- query: JSON Object stringify of the subscriber to look for (one or more):
- sid (integer): subscriber Id
- imsi (string): of the subscriber
- msisdn (string): Mobile Station International Subscriber Directory Number - uniquely identifying a subscription in a GSM or a UMTS
- from (string; optional): start effective date (ISO)
- to (string; optional): end effective date (ISO)
Output format: JSON
Output structure:
- status: one of the following integer values
- desc: textual description of the API response
- input: the raw input
- details: Array of JSON objects containing the following fields:
- from: creation date
- to: cancellation date or empty date for current line
- imsi: array of available imsi (International Mobile Subscriber Identity) for a subscriber
- msisdn: Mobile Station International Subscriber Directory Number - uniquely identifying a subscription in a GSM or a UMTS
- aid: account Id
- sid: subscriber Id (will be the same as msisdn)
- plan: subscriber’s market plan
- language: subscriber’s default interface language (e.g. for sms notifications)
- service_provider: subscriber’s service provider
Desc: retrieve subscriber’s auto renew services (such periodic charges)
Status: deprecated call since version 5.5
Path: http://host/api/subscribersautorenew
HTTP Method: POST
Input:
- method: query
- query: JSON Object stringify of the subscriber to look for (one or more):
- sid (integer): subscriber Id
- from (string; optional): start effective date (ISO), put * (asterisk for ignore this filter)
- to (string; optional): end effective date (ISO), put * (asterisk for ignore this filter)
Output format: JSON
Output structure:
- status: one of the following integer values
- desc: textual description of the API response
- input: the raw input
- details: Array of JSON objects containing the following fields (example):
- "_id" : ObjectId("55ade77600a655be6ac50e84"),
- "from" : 2012-03-06T02:00:00+0200,
- "to" : 2016-03-06T02:00:00+0200,
- "last_renew_date" : 2014-03-06T02:00:00+0200,
- "creation_time" : 2012-03-06T02:00:00+0200,
- "interval" : "day" / "week" / "month",
- "aid" : 12345,
- "sid" : 77777,
- "charging_plan_name" : "PPC36M1G",
- "charging_plan_external_id" : "139",
- "done" : 0 (intervals used),
- "operation" : "inc" / "set"
Desc: set subscriber’s auto renew services (such periodic charges). The recurring manage by the billing engine
Status: deprecated call since version 5.5
Path: http://host/api/subscribersautorenew
HTTP Method: POST
Input:
- method: update
- query: JSON Object stringify of the subscriber to look for (by this upsert will be done so you can update with the same API):
- sid (integer): subscriber Id
- charging_plan: the charging plan for to charge on each recur
- from (string): start effective date (ISO)
- upsert:
- to (string; mandatory): end effective date (ISO)
- interval (string: optional): "day" / "week" / "month" (default: “month”)
- operation (string: optional): "inc" / "set" (default: “inc”)
Output format: JSON
Output structure:
- status: one of the following integer values
- desc: textual description of the API response
- input: the raw input
- details: Array of JSON objects containing the following fields (example):
- "_id" : ObjectId("55ade77600a655be6ac50e84"),
- "from" : 2012-03-06T02:00:00+0200,
- "to" : 2016-03-06T02:00:00+0200,
- "last_renew_date" : 2014-03-06T02:00:00+0200,
- "creation_time" : 2012-03-06T02:00:00+0200,
- "interval" : "day" / "week" / "month",
- "aid" : 12345,
- "sid" : 77777,
- "charging_plan_name" : "PPC36M1G",
- "charging_plan_external_id" : "139",
- "done" : 0 (intervals used),
- "operation" : "inc" / "set"
Desc: Update the auto renew services by delta with an array of expected values.
Status: deprecated call since version 5.5
Path: http://host/api/subscribersautorenew
HTTP Method: POST
Input:
- method: bydelta
- sid(integer): subscriber ID
- expected: JSON Object stringify array of the expected records for the subscriber (one or more):
- "charging_plan" (string): The plan to charge by on each recurring period.
- "to" (string): end effective date (ISO)
- "from" (string; optional): start effective date (ISO)
- "Interval" (string: optional): "day" / "week" / "month" (default: “month”)
- "Operation" (string: optional): "inc" / "set" (default: “inc”)
Output format: JSON
Output structure:
- status: one of the following integer values
- desc: textual description of the API response
- input: the raw input
- details: Array of JSON objects containing the array of expected results, representing the state of the data base.
Desc: retrieve subscriber’s balances. If no “from” and “to” will be transferred, the current open documents will be retrieved.
Status: deprecated call since version 5.5
Path: http://host/api/balances
HTTP Method: POST
Input:
- method: query
- sid (integer): subscriber Id
- from (string): start effective date (ISO)
- to (string): end effective date (ISO)
- pp_includes_name: Prepaid includes (wallet) name
- pp_includes_external_id: Prepaid includes (wallet) external_id
- aggregate (1 or 0): flag indicate if to aggregate results by pp includes (default: 1, means on).
- sort - sort field/s - list of values separated by “,”Can be one of the following values: 'from', 'to', 'pp_includes_external_id', 'pp_includes_name', 'priority' (default: pp_includes_external_id)
- sortOrder - 1 (ascending; default) or -1 (descending)
- completeAvailableBalances -
- 1 (default) - Show all balances for all prepaid includes. If balance is not stored in database and/or not fetched, it will generated it in the output with zero value.
- 0 - Show only existing balances that met the query.
Output format: JSON
Output structure:
- status: one of the following integer values
- desc: textual description of the API response
- input: the raw input
- details: JSON array of objects containing balances document
Example:
http://billrun/api/balances?method=query&sid=528668668&from=2016-08-01%2000:00:00&to=2019-11-01%2000:00:00&sort=pp_includes_external_id&sortOrder=1
Desc: create or update (AKA upsert in MongoDB world) balance for subscriber. Means if balance (document) is not exists it will be created.
The search is by either charging_plan_name or charging_plan_external_id or pp_includes_name or pp_includes_external_id when pp_includes represents the account (wallet) name and the charging_plan represents the charging plan.
Status: deprecated call since version 5.5
Path: http://host/api/balances
HTTP Method: POST
Input:
- method: update
- sid (integer): subscriber Id
- query: JSON Object stringify which contains one of the following filters
- _id or id: MongoDB internal id (directly on balances)
- charging_plan_name or charging_plan: Charging plan name
- charging_plan_external_id: External id of charging plan
- pp_includes_name: Prepaid includes (wallet) name
- pp_includes_external_id: Prepaid includes (wallet) external_id
- recurring: Recurring charging plan
- secret: Prepaid credit card - secret code
- upsert: JSON Object stringify which contain the values to insert/update
- value: credit value for duration / data / sms / amount
from: date for first charge of recurring account. (move to separate API)to: date for last charge of recurring account. (move to separate API)- expiration_date: end date of the credit
- operation: “inc” / “set” (default: “inc”). “inc” for increment, “set” for override
additional_information: any additional information
- additional: JSON Object stringify which contain the additional values that will be added to the charging line
Output format: JSON
Output structure:
- status: one of the following integer values
- desc: textual description of the status
- input : the raw input
- details: JSON array of objects containing balances document
Example:
http://billrun/api/balances?method=update&sid=528668668&query={"charging_plan_name":"145"}&upsert={"a":1}
Desc: retrieve values for creating one or array of new cards. All input fields are required.
Path: http://host/api/cards
HTTP Method: POST
Input:
- method: create
- cards: array of JSON Objects stringify containing all the following properties:
- secret: unique code (secret) for a card - 12 digits
- batch_number: issuing batch number. without leading ‘0’
- serial_number: issuing batch’s serial code. without leading ‘0’
- charging_plan_name: connection to charging plan
- service_provider: connection to service provider
- to: card expiration date
- status: card status (default: “Idle”)
- creation_time: card production time
- additional_information: any additional information
Output format: JSON
Output structure:
- status :
- desc: textual description of the status
- details: JSON object containing created document card[s] without the secret code
Notes:
- Card validity check (existance/secret code etc.) will be performed during this phase.
- One-way encryption will be performed on the secret code before insert to DB.
- [{"secret":"123456789011","batch_number":1231,"serial_number":12345671,"charging_plan_external_id":"5678","service_provider":"pelephone","to":"2015-08-31T13:00:00%2B03:00","status":"cancelled","creation_time":"2015-08-31T13:00:00%2B03:00","additional_information":""},{"secret":"123456789012","batch_number":1232,"serial_number":12345672,"charging_plan_external_id":"5678","service_provider":"pelephone","to":"2015-08-31T13:00:00%2B03:00","status":"cancelled","creation_time":"2015-08-31T13:00:00%2B03:00","additional_information":""}]
Desc: retrieve one or range of serial codes in a specific batch with the requested status for update (default creation status: “Idle”)
Path: http://host/api/cards
HTTP Method: POST
Input:
- method: update
- query: JSON Object stringify which contains the following filters
- status: card status (optional)
- batch_number: issuing batch number. without leading ‘0’ (required)
- serial_number: issuing batch serial code. without leading ‘0’ (required)
- secret: unique code (secret) for a card - 12 digits (optional)
- update: JSON Object stringify which contain the values to update
- status: card status
- batch_number: issuing batch number. without leading ‘0’
- serial_number: issuing batch serial code. without leading ‘0’
- charging_plan_name: connection to charging plan (like charging_plan_external_id)
- service_provider: connection to service provider
- to: card expiration date
Output format: JSON
Output structure:
- status: one of the following integer values
- desc: textual description of the API response
- details: return the number of documents updated
Notes:
- If required to filter range from 1000 to 2000 of serial_number you should use the next JSON:
{“serial_number”:{'$gte':1000, '$lte':2000}}
- {"status":"Idle","batch_number":1234,"serial_number":12345678}&update={"status":"active"}
- {"status":"cancelled","batch_number":{'$gte':1111,'$lte':9999},"serial_number":{'$gte':11111111,'$lte':99999999}}&update={"status":"active"}
Desc: retrieve one or range of serial codes in a specific batch with the requested status and/or secret (code)
Mandatory Fields: batch_number, serial_number
Path: http://host/api/cards
HTTP Method: POST
Input:
- method: query
- query: JSON Object stringify which contains one of the following filters
- status: card status
- batch_number: issuing batch number. without leading ‘0’
- serial_number: issuing batch serial code. without leading ‘0’
- secret: unique code (secret) for a card - 12 digits
- size: limit the query results. Default: 10,000.
- page: pagination of results. Default: 0 (first page)
Output format: JSON
Output structure:
- status: one of the following integer values
- desc: textual description of the API response
- details: JSON array of objects containing cards document without the secret code
Notes:
- If required to filter range from 1000 to 2000 of serial_number you should use the next JSON:
{“serial_number”:{'$gte':1000, '$lte':2000}}
- {"status":"cancelled","batch_number":1234,"serial_number":12345678}
- {"status":"cancelled","batch_number":{'$gte':1111,'$lte':9999},"serial_number":{'$gte':11111111,'$lte':99999999}}
Desc: delete one or range of cards by each of the query fields. batch_number is required
Mandatory Fields: batch_number
Path: http://host/api/cards
HTTP Method: POST
Input:
- method: delete
- query: JSON Object stringify which contains one of the following filters
- status: card status
- batch_number: issuing batch number. without leading ‘0’ (required)
- serial_number: issuing batch serial code. without leading ‘0’
- secret: unique code (secret) for a card - 12 digits
Output format: JSON
Output structure:
- status: one of the following integer values
- desc: textual description of the API response
- details: return the number of documents deleted
Notes:
- Must use the batch_number and can use the other fields
- Example: {"batch_number":1239}
Desc: save statistics to the database
Mandatory Fields: statistics
Path: http://host/api/statistics
HTTP Method: POST
Input:
- method: create
- statistics: JSON Object stringify containing the statistics information to save
Output format: JSON
Output structure:
- status: one of the following integer values
- desc: textual description of the API response
- input: the JSON that was saved
Desc: get statistics from database by date
Mandatory Fields:
Path: http://host/api/statistics
HTTP Method: POST
Input:
- method: query
- from: Date formatted as YYYY-MM-DD (optional)
- to: Date formatted as YYYY-MM-DD (optional)
Output format: JSON
Output structure:
- status: one of the following integer values
- desc: textual description of the API response
Notes:
- If no date given, returns all statistics in the DB
- If the to field is not queried, returns all statistics from ‘from’ query onwards
- Same for ‘from’ - queries all statistics from the first until ‘to’