...

Panel

title	In this article

Table of Contents

The Provisioning API provides provides a mechanism for real-time integration with 3rd party systems, including softswitches, gateways, and CRM systems. The mechanism calls pre-defined handlers on the occurrence of specific events in the system.

While Core API and Management API sub-systems answer requests, Provisioning API pushes data as soon as an event occurs. For For example, you can monitor the client's balance status via this functionality. Thus, when when the client's balance is below zero, you can configure the system to send a notification to an external system to avoid any disruptions to your organization's current processes.

Handlers

A typical handler should be configured as is HTTPS or HTTP with an URL of the script, which will get HTTP POST requests about each event occurrence.

...

Panel

borderColor	#ccffcc
bgColor	#ccffcc
borderWidth	2px
borderStyle	solid

Image Modified Best practice example

There is an example based on https://hostname/handler-endpoint usage.

Open the Provisioning section and start creating a handler.

Specify the name, type, and status.
In the Event field, select Clients Create event from the drop-down list.
In the Task field, indicate HTTPS type and define the URL for the handler, for example, my-domain.org/api.
Click Apply.

Find an example of the http://handler below:

Code Block

language	py

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()

Event Payload

Supported Events

The Provisioning API supports the following list of events:

Clients
- clients.create
- clients.update
- clients.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
- email_rates_manager.rate_tables_no_match
- email_rates_manager.no_attachments
- email_rates_manager.file_processing_error
Import Manager
- importd.process_success
- importd.process_failed

Info

title	Note

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

Structure

Within 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 (check Payload Samples below)

Supported Events

Please note that some Payload Samples below contain reduced payload as they fully replicate the data structures within CoreAPI. Please refer to the respective documentation within the system interface in the Integration/CoreAPI Docs section for full format of the structure.

Event ID Payload Sample

Clients Management

clients.create

The client has been created

{
  "event": {
    "dt": "2000-01-01T00:00:00+00:00",
    "events_id": "clients.create",
    "object_id": 12
  },
  "data": {
    "id": 12,
    "name": "My name", "companies_id": 3, ...
  }
}

clients.update

The client's details have been updated

{
  "event": {
    "dt": "2000-01-01T00:00:00+00:00",
    "events_id": "clients.update",
    "object_id": 12
  },
  "data": {
    "id": 12,
    "name": "My changed name"
  }
}

clients.archive

The client has been archived

{
  "event": {
    "dt": "2000-01-01T00:00:00+00:00",
    "events_id": "clients.archive",
    "object_id": 12
  },
  "data": {}
}

clients.delete

The client has been completely deleted

Not to be confused with archived

{
  "event": {
    "dt": "2000-01-01T00:00:00+00:00",
    "events_id": "clients.delete",
    "object_id": 12
  },
  "data": {}
}

clients.balance_zero

The client's balance became <=0

{
  "event": {
    "dt": "2000-01-01T00:00:00+00:00",
    "events_id": "clients.balance_zero",
    "object_id": 12
  },
  "data": {}
}

clients.balance_notzero

The client's balance became > 0

{
  "event": {
    "dt": "2000-01-01T00:00:00+00:00",
    "events_id": "clients.balance_notzero",
    "object_id": 12
  },
  "data": {}
}

clients.custom_fields.update

The client's Custom Field has been updated

{
  "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"
  }
}

Accounts Management

clients.accounts.create

The account has been created

{
  "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",
    ...
  }
}

clients.accounts.update

The account's details have been updated

{
  "event": {
    "dt": "2000-01-01T00:00:00+00:00",
    "events_id": "clients.accounts.update",
    "object_id": 12
  },
  "data": {
    "id": 12,
    "name": "My changed account"
  }
}

clients.accounts.delete

The account has been completely deleted

{
  "event": {
    "dt": "2000-01-01T00:00:00+00:00",
    "events_id": "clients.accounts.delete",
    "object_id": 12
  },
  "data": {}
}

Subscriptions Management

clients.subscriptions.assign

The subscription has been assigned

{
  "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",
    ...
  }
}

clients.subscriptions.activate

The subscription has been activated

{
  "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",
    ...
  }
}

clients.subscriptions.deactivate

The subscription has been deactivated

{
  "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",
    ...
  }
}

clients.subscriptions.renew

The subscription has been renewed

{
  "event": {
    "dt": "2000-01-01T00:00:00+00:00",
    "events_id": "clients.subscriptions.renew",
    "object_id": 12
  },
  "data": {
    "id": 12,
    "clients_id": 34,
    "packages_id": 56,
    "stop_dt": "2023-01-01T00:00:00+00:00",
    "renew_count": 1,
    ...
  }
}

clients.subscriptions.close

The subscription has been closed

{
  "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",
    ...
  }
}

Email Rates Manager

email_rates_manager.import

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

{
"data":
{
"mailbox":
{
"login": "[email protected]",
"host": "imap.gmail.com"
},
"message":
{
"from": "Sender <[email protected]>",
"id": "77798",
"subject": "Subject of the message"
},
"queue":
{
<IMPORT_QUEUE> (see importd.process_success method for extra details)
}
},
"event":
{
"dt": "2022-01-24T15:44:47.216756+00:00",
"events_id": "email_rates_manager.import",
"object_id": "77798"
}
}

email_rates_manager.rate_tables_no_match

No Rate Tables match received email

{
"data":
{
"credentials":
{
"login": "[email protected]",
"host": "imap.gmail.com"
},
"message":
{
"from": "Sender <[email protected]>",
"id": "77798",
"subject": "Subject of the message"
}
},
"event":
{
"dt": "2022-01-24T15:44:47.216756+00:00",
"events_id": "email_rates_manager.rate_tables_no_match",
"object_id": "77798"
}
}

email_rates_manager.no_attachments

No attachments have been identified

{
"data":
{
"credentials":
{
"login": "[email protected]",
"host": "imap.gmail.com"
},
"message":
{
"from": "Sender <[email protected]>",
"id": "77798",
"subject": "Subject of the message"
},
"rate_tables":
[
{
"id": 74,
"name": "Rate Table A"
},
{
"id": 7,
"name": "Rate TAble B"
}
]
},
"event":
{
"dt": "2022-01-24T15:44:47.216756+00:00",
"events_id": "email_rates_manager.no_attachments",
"object_id": "77798"
}
}

email_rates_manager.file_processing_error

The file processing error

{
"data":
{
"error":
{
"code": "incorrect-file-ext",

      "message": "Can't process file: /opt/jerasoft/vcs-data/files/xJv/xJv5aMoqMKoNK1s2hwlJ8ik4bF3aiMVi (test_import_9999.zip). File is not a zip file"

},
"credentials":
{
"login": "[email protected]",
"host": "imap.gmail.com"
},
"message":
{
"from": "Sender <[email protected]>",
"id": "77798",
"subject": "Subject of the message"
},
"rate_tables":
[
{
"id": 74,
"name": "Rate Table A"
},
{
"id": 7,
"name": "Rate TAble B"
}
]
},
"event":
{
"dt": "2022-01-24T15:44:47.216756+00:00",
"events_id": "email_rates_manager.no_attachments",
"object_id": "77798"
}
}

Import Manager

importd.process_success

The import attempt was successful

{
"data":
{

"main": {

Expand

title	<IMPORT_CONFIG>

  "agreements_tolerance": null,
  "az_codes": [],
  "az_date": null,
  "az_interval_type": "days",
  "az_interval_value": null,
  "az_mode": null,
  "billing_increment_check": false,
  "billing_increment_format": [
    "grace_volume",
    "pay_interval",
    "min_volume"
  ],
  "code_deck_mode": null,
  "code_decks_id": 1,
  "codes_import_key": "import-rates-62",
  "current_date": "2022-07-14T13:11:49.064229+00:00",
  "datetime_format": "mdy",
  "error_mode": "skip_rows",
  "rate_deviation_tolerance": null,
  "rate_table": {
    "agreements_id": null,
    "c_dt": "2018-02-28T09:12:28.758533+00:00",
    "code_decks_id": 1,
    "companies_id": 3,
    "credentials_id": null,
    "currencies_id": 26,
    "export_templates_id": null,
    "id": 64,
    "import_templates_id": null,
    "last_export_dt": "2020-01-07T18:33:47.912665+00:00",
    "lastedit_dt": "2022-07-14T13:11:25.964915+00:00",
    "mail_auto_import": false,
    "mail_import_template_id": null,
    "name": "0parent",
    "notes": "",
    "parent_rate_tables_id": null,
    "rates_generation_auto": false,
    "rates_generators_id": null,
    "remote_settings": {
      "email_sender": null,
      "email_subject": null
    },
    "src_code_decks_id": null,
    "tags": [
      "@"
    ],
    "with_taxes": false
  },
  "rate_tables_logs": {
    "c_dt": "2022-07-14T13:11:49+00:00",
    "closed": 0,
    "closed_by_az": 0,
    "decreased": 0,
    "future_changes": 0,
    "id": 86,
    "import_queue_id": 62,
    "increased": 0,
    "new": 0,
    "overlaid": 0,
    "rates_generators_queue_details_id": null,
    "total": 0,
    "unchanged": 0
  },
  "sheets": [
    {
      "code_rules": [
        {
          "code": "*",
          "code_name": null,
          "effective_from": null,
          "effective_from_interval_type": "days",
          "effective_from_interval_value": null,
          "end_date": null,
          "end_date_interval_type": "days",
          "end_date_interval_value": null,
          "grace_volume": 0,
          "min_volume": 1,
          "notes": null,
          "num_length_max": null,
          "num_length_min": null,
          "pay_interval": 1,
          "pay_setup": 0,
          "policy": "regular",
          "services_id": 1,
          "status": "active",
          "tag": "@",
          "time_profiles_id": 1
        }
      ],
      "columns": [
        "code",
        "code_name",
        "value",
        "effective_from"
      ],
      "file_meta": {
        "count": 10313,
        "id": 0,
        "name": "rates-1_RT_for_services-2222-05-13_073122.csv",
        "path": "/opt/jerasoft/vcs-data/files/CRk/CRkCwQS6oGWC0BeDXfFE0yMJ7TNicq6f"
      },
      "skip_rows_bottom": 0,
      "skip_rows_top": 1,
      "type": "rates"
    }
  ],
  "skip_dash": false,
  "split_src_code_name": false,
  "src_code_decks_id": null,
  "total_changes_threshold": null,
  "unchanged_mode": "skip_rows",
  "warning_mode": "save_rows"

},

"queue": {

Expand

title	<IMPORT_QUEUE>

            "dt": "2022-07-14T13:11:46.567390+00:00",
            "files_id": "CRkCwQS6oGWC0BeDXfFE0yMJ7TNicq6f",
            "files_meta":
            [
                {
                    "count": 10313,
                    "id": 0,
                    "name": "rates-1_RT_for_services-2222-05-13_073122.csv",
                    "path": "/opt/jerasoft/vcs-data/files/CRk/CRkCwQS6oGWC0BeDXfFE0yMJ7TNicq6f"
                }
            ],
            "id": 62,
            "messages":
            [],
            "object": "rate_tables",
            "object_id": 64,
            "settings":
            {
                "agreements_tolerance": null,
                "az_codes":
                [],
                "az_date": null,
                "az_interval_type": "days",
                "az_interval_value": null,
                "az_mode": null,
                "billing_increment_check": false,
                "billing_increment_format":
                [
                    "grace_volume",
                    "pay_interval",
                    "min_volume"
                ],
                "code_deck_mode": null,
                "code_decks_id": 1,
                "codes_import_key": "import-rates-62",
                "current_date": "2022-07-14T13:11:49.064229+00:00",
                "datetime_format": "mdy",
                "error_mode": "skip_rows",
                "rate_deviation_tolerance": null,
                "rate_table":
                {
                    "agreements_id": null,
                    "c_dt": "2018-02-28T09:12:28.758533+00:00",
                    "code_decks_id": 1,
                    "companies_id": 3,
                    "credentials_id": null,
                    "currencies_id": 26,
                    "export_templates_id": null,
                    "id": 64,
                    "import_templates_id": null,
                    "last_export_dt": "2020-01-07T18:33:47.912665+00:00",
                    "lastedit_dt": "2022-07-14T13:11:25.964915+00:00",
                    "mail_auto_import": false,
                    "mail_import_template_id": null,
                    "name": "0parent",
                    "notes": "",
                    "parent_rate_tables_id": null,
                    "rates_generation_auto": false,
                    "rates_generators_id": null,
                    "remote_settings":
                    {
                        "email_sender": null,
                        "email_subject": null
                    },
                    "src_code_decks_id": null,
                    "tags":
                    [
                        "@"
                    ],
                    "with_taxes": false
                },
                "rate_tables_logs":
                {
                    "c_dt": "2022-07-14T13:11:49+00:00",
                    "closed": 0,
                    "closed_by_az": 0,
                    "decreased": 0,
                    "future_changes": 0,
                    "id": 86,
                    "import_queue_id": 62,
                    "increased": 0,
                    "new": 0,
                    "overlaid": 0,
                    "rates_generators_queue_details_id": null,
                    "total": 0,
                    "unchanged": 0
                },
                "sheets":
                [
                    {
                        "code_rules":
                        [
                            {
                                "code": "*",
                                "code_name": null,
                                "effective_from": null,
                                "effective_from_interval_type": "days",
                                "effective_from_interval_value": null,
                                "end_date": null,
                                "end_date_interval_type": "days",
                                "end_date_interval_value": null,
                                "grace_volume": 0,
                                "min_volume": 1,
                                "notes": null,
                                "num_length_max": null,
                                "num_length_min": null,
                                "pay_interval": 1,
                                "pay_setup": 0,
                                "policy": "regular",
                                "services_id": 1,
                                "status": "active",
                                "tag": "@",
                                "time_profiles_id": 1
                            }
                        ],
                        "columns":
                        [
                            "code",
                            "code_name",
                            "value",
                            "effective_from"
                        ],
                        "file_meta":
                        {
                            "count": 10313,
                            "id": 0,
                            "name": "rates-1_RT_for_services-2222-05-13_073122.csv",
                            "path": "/opt/jerasoft/vcs-data/files/CRk/CRkCwQS6oGWC0BeDXfFE0yMJ7TNicq6f"
                        },
                        "skip_rows_bottom": 0,
                        "skip_rows_top": 1,
                        "type": "rates"
                    }
                ],
                "skip_dash": false,
                "split_src_code_name": false,
                "src_code_decks_id": null,
                "total_changes_threshold": null,
                "unchanged_mode": "skip_rows",
                "warning_mode": "save_rows"
            },
            "stats":
            {
                "closed_by_az": 0,
                "decreased": 2,
                "duplicates": 10307,
                "errors": 5,
                "increased": 3,
                "overlaid": 10312,
                "processed": 10312,
                "stashed_by_az": 0,
                "successful": 10312
            },
            "status": "enqueued",
            "users_id": 6

}

},

"event":
{
"dt": "2022-07-14T13:12:02.918034+00:00",
"events_id": "importd.process_success",
"object_id": "62"
}
}

importd.process_failed

The import attempt has failed

{
"data":
{
"main": <IMPORT_CONFIG>
"queue": <IMPORT_QUEUE>
},
"event":
{
"dt": "2022-07-14T13:12:02.918034+00:00",
"events_id": "importd.process_failed",
"object_id": "62"
}
}

Charges

accounting.charges.create

The Transaction of Type Charge has been created

{
"data": {
"id": 2220,
"c_dt": "2022-07-06 00:00:00+0000",
"tags": [],
"type": "charge",
"notes": "t",
"taxes": null,
"amount": 10,
...
},
"event": {
"dt": "2022-07-22T11:41:09.253251+00:00",
"events_id": "accounting.charges.create",
"object_id": "2220"
}
}

accounting.charges.delete

The Transaction of Type Charge has been removed

{
"data": [],
"event": {
"dt": "2022-07-22T11:41:44.650430+00:00",
"events_id": "accounting.charges.delete",
"object_id": "2220"
}
}

accounting.charges.update

The Transaction of Type Charge has been edited

{

  "data":
  {

"id": 2220,
"c_dt": "2022-07-06 00:00:00+0000",
"tags": [],
"type": "charge",
"notes": "t_1",
"taxes": null,
"amount": 10,
...
},

  "event":
  {

"dt": "2022-07-22T11:41:27.298884+00:00",
"events_id": "accounting.charges.update",
"object_id": "2220"
}
}

Payments

accounting.payments.create

The Transaction of Type Payment has been created

{

 "data":
  {

"id": 2223,
"c_dt": "2022-07-14 00:00:00+0000",
"tags": [],
"type": "payment",
"notes": "test",
"taxes": null,
"amount": 1,
"status": "approved",
...
},

 "event":
  {

"dt": "2022-07-22T11:49:41.212852+00:00",
"events_id": "accounting.payments.create",
"object_id": "2223"
}
}

accounting.payments.delete

The Transaction of Type Payment has been removed

{
"data": [],

  "event":
  {

"dt": "2022-07-22T11:49:53.178009+00:00",
"events_id": "accounting.payments.delete",
"object_id": "2223"
}
}

accounting.payments.update

The Transaction of Type Payment has been edited

{

  "data":
  {

"id": 2223,
"c_dt": "2022-07-14 00:00:00+0000",
"tags": [],
"type": "payment",
"notes": "test",
"taxes": null,
"amount": 10,
...
},

  "event":
  {

"dt": "2022-07-22T11:49:45.263719+00:00",
"events_id": "accounting.payments.update",
"object_id": "2223"

Code Block
{ "event": { "dt": "2000-01-01T00:00:00+00:00", "events_id": "clients.update", "object_id": 12 }, "data": { "id": 12, "field": "some-value" } }

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.

Supported Events

Event IDPayload Sample

clients.update

Client details have been updated

{
  "event": {
    "dt": "2000-01-01T00:00:00+00:00",
    "events_id": "clients.update",
    "object_id": 12
  },
  "data": {
    "id": 12,
    "name": "My changed name"
  }
}

clients.delete

Client has been completely deleted

Not to be confused with archived

{
  "event": {
    "dt": "2000-01-01T00:00:00+00:00",
    "events_id": "clients.delete",
    "object_id": 12
  },
  "data": {

}
}

Panel

borderColor	#ccffcc
bgColor	#ccffcc
borderWidth	2px
borderStyle	solid

Image Modified 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.

Versions Compared

Old Version 3

New Version Current

Key

Handlers

Event Payload

Supported Events

Event Payload

Structure

Example

Structure

Supported Events

Clients Management

Accounts Management

Subscriptions Management

Email Rates Manager

Import Manager

Charges

Payments

Data

Supported Events

Page History

Versions Compared

Old Version 3

New Version Current

Key

Handlers

Event Payload

Supported Events

Event Payload

Structure

Example

Structure

Supported Events

Clients Management

Accounts Management

Subscriptions Management

Email Rates Manager

Import Manager

Charges

Payments

Data

Supported Events