...
The Provisioning API provides a provides a mechanism for real-time integration with 3rd with 3rd party systems, including softswitches, gateways, and CRM systems. The The mechanism calls pre-defined handlers on an the occurrence of specific events in the system. The handlers are allowed to modify data, allow or forbid the action or simply process given event.
While Prior to that, JeraSoft Billing Core API and Management API provide utilities needed to receive requests from external systems. Now, you can configure the JeraSoft Billing platform to send requests to your 3rd party system.
sub-systems answer requests, Provisioning API pushes data as soon as an event occurs. For example, you can monitor the client's balance status via this functionality. Thus, when the client's balance is below zero, you can configure that the billing will system to send a notification to an external system a notification to avoid any disruptions to your organization's current processes.
Panel |
---|
borderColor | #ccffcc |
---|
bgColor | #ccffcc |
---|
borderWidth | 2px |
---|
borderStyle | solid |
---|
|
Image Removed Tip The full list of Provisioning API parameters matches with CoreAPI and they are available upon individual request of your current clients. |
Handlers
...
Handlers
A typical handler should be configured as either HTTPS or HTTP with an URL of the script, which will get HTTP POST requests about each event occurrence.
Please avoid using the Script type of handlers, they are designed for internal usage within the system.
...
Panel |
---|
borderColor | #ccffcc |
---|
bgColor | #ccffcc |
---|
borderWidth | 2px |
---|
borderStyle | solid |
---|
|
Image Modified Best practice example Here There is an example based on http https://hostname/handler-endpoint usage. 1. Open the Provisioning section and start creating a handler. - Specify the name, type, and status.
- In the Event field, select
the - Clients Create event from the drop-down list.
- In the Task field, indicate
http:// - HTTPS type and
determine the port and method- define the URL for the handler, for example,
120.0.0.1:5000- my-domain.org/api.
- Click Apply.
Find an example of the http://handler below: Code Block |
---|
| from flask import Flask, request
import json
app = Flask(__name__)
@app.route("/api", methods=['GET', 'POST'])
def api():
data = json.loads(request.data)
return json.dumps(data)
if __name__ == "__main__":
app.run() |
|
Supported Events
The Provisioning API supports the following list of events:
TitleAction | Structure | | Code Block |
{
"event": {
"dt": "2000-01-01T00:00:00+00:00",
"events_id": "",
"object_id": 12
},
"data": {
"id": 12,
"name": "Customer A",
"companies_id": 67,
"currencies_id": 10,
...
}
} | Code Block |
{
"event": {
"dt": "2000-01-01T00:00:00+00:00",
"events_id": "",
"object_id": 12
},
"data": {
"id": 12,
"name": "My changed name"
}
} | Code Block |
{
"event": {
"dt": "2000-01-01T00:00:00+00:00",
"events_id": "delete",
"object_id": 12
},
"data": {}
}- archive
- clients.delete
- clients.balance_zero
- clients.balance_notzero
- clients.custom_fields.update
- Accounts
- clients.accounts.create
- clients.accounts.update
- clients.accounts.delete
- Subscriptions
- clients.subscriptions.assign
- clients.subscriptions.activate
- clients.subscriptions.deactivate
- clients.subscriptions.renew
- clients.subscriptions.close
- Email Rates Manager
- email_rates_manager.import
- Import Manager
- importd.process_success
- importd.process_failed
Note |
---|
|
Please note that the email_rates_manager.import event means the following logic: the import file has been prepared for further processing by the task specified in the Provisioning API handler settings, and the import process was stopped. |
Info |
---|
|
The clients.custom_fields_update event has been renamed to clients.custom_fields.update starting from JeraSoft Billing v3.23 for consistency. |
Event Payload
Structure
During notification, the handler will be called with a JSON-formatted data payload. The payload has the following structure:
event
dt
- the date-time of the event in the ISO8601 format;events_id
- ID of the event occurred (helpful, when multiple events are handled by the same handler);object_id
- the entity, to which the event happened;
data
- data related to the specific event.
Example
Code Block |
---|
{
"event": {
"dt": "2000-01-01T00:00:00+00:00",
"events_id": "clients.archive",
"object_id": 12
},
"data": {}
} |
| Code Block |
---|
{
"event": {
"dt": "2000-01-01T00:00:00+00:00",
"events_id": "clients.custom_fields.update",
"object_id": 12
},
"data": {
"id": 12,
"custom-field-name": "custom-field-value"
}
} |
| Code Block |
---|
{
"event": {
"dt": "2000-01-01T00:00:00+00:00",
"events_id": "clients.balance_notzero",
"object_id": 12
},
"data": {}
} |
| Code Block |
---|
{
"event": {
"dt": "2000-01-01T00:00:00+00:00",
"events_id": "clients.balance_zero",
"object_id": 12
},
"data": {}
} |
Accounts | | Code Block |
---|
{
"event": {
"dt": "2000-01-01T00:00:00+00:00",
"events_id": "clients.accounts.create",
"object_id": 12
},
"data": {
"id": 12,
"clients_id": 7,
"name": "My account",
"auth_type": "name",
...
}
} |
| Code Block |
---|
{
"event": {
"dt": "2000-01-01T00:00:00+00:00",
"events_id": "clients.accounts.update",
"object_id": 12
},
"data": {
"id": 12,
"name": "My changed account"
}
} |
| Code Block |
---|
{
"event": {
"dt": "2000-01-01T00:00:00+00:00",
"events_id": "clients.accounts.delete",
"object_id": 12
},
"data": {}
} |
Clients Packages | | Code Block |
---|
{
"event": {
"dt": "2000-01-01T00:00:00+00:00",
"events_id": "clients.subscriptions.assign",
"object_id": 12
},
"data": {
"id": 12,
"clients_id": 34,
"packages_id": 56,
"stop_dt": "2023-01-01T00:00:00+00:00",
...
}
} |
| Code Block |
---|
{
"event": {
"dt": "2000-01-01T00:00:00+00:00",
"events_id": "clients.subscriptions.activate",
"object_id": 12
},
"data": {
"id": 12,
"clients_id": 34,
"packages_id": 56,
"stop_dt": "2023-01-01T00:00:00+00:00",
"condition": "activated",
...
}
} |
| Code Block |
---|
{
"event": {
"dt": "2000-01-01T00:00:00+00:00",
"events_id": "clients.subscriptions.deactivate",
"object_id": 12
},
"data": {
"id": 12,
"clients_id": 34,
"packages_id": 56,
"stop_dt": "2023-01-01T00:00:00+00:00",
"condition": "deactivated",
...
}
} |
| Code Block |
{
"event": {
"dt": "2000-01-01T00:00:00+00:00",
|
subscriptions.renew clients_id34,
"packages_id": 56,
"stop_dt": "2023-01-01T00:00:00+00:00",
"renew_count": 1,
...
| Data
The data provided within the notification depends on the specific type of event.
Events that represent basic status changes will not contain any additional data as the ID of the related entity is provided within the "event" key. Examples of such events are: clients.accounts.delete
, clients.archive
, clients.balance_notzero
, clients.balance_zero, etc.
For the rest of the events, the structure will match the respective CoreAPI method's structure. Please check the respective documentation within the system interface in the Integration/CoreAPI Docs section.
Code Block |
{
"event": {
"dt": "2000-01-01T00:00:00+00:00",
"events_id": "clients.subscriptions.close",
"object_id": 12
},
"data": {
"id": 12,
"clients_id": 34,
"packages_id": 56,
"stop_dt": "2000-01-01T00:00:00+00:00",
...
}
}
Panel |
---|
borderColor | #ccffcc |
---|
bgColor | #ccffcc |
---|
borderWidth | 2px |
---|
borderStyle | solid |
---|
|
Tip - For more information about configuring and monitoring the hooks for Provisioning API, visit our respective article User Guide > System > Provisioning API.
- If you need to process some of the actions that are not listed here, contact our support for a feature request.
|