Versions Compared

Old Version 9

changes.mady.by.user Andrii Zinchenko

Saved on

compared with

New Version Current

changes.mady.by.user Anastasiia Kovalinas

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

While Core API and Management API sub-systems answer to 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 the system to send a notification to an external system to avoid any disruptions to your organization's current processes.

...

A typical handler should be configured as is 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 the handlers, they are designed for internal usage within the system.


Panel
borderColor#ccffcc
bgColor#ccffcc
borderWidth2px
borderStylesolid

Best practice example

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

Open the Provisioning section and start creating a handler.

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

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

Code Block
languagepy
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:

  • 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
  • Import Manager
    • importd.process_success
    • importd.process_failed

Payload Structure

The "event" value contains the following data:

  • dt: the date-time of the event in the ISO8601 format;
  • events_id: the event, which happened per se;
  • object_id: the entity, to which the event happened.
Code Block
{
  "event": {
    "dt": "2000-01-01T00:00:00+00:00",
    "events_id": "clients.update",
    "object_id": 12
  },
  "data": {
    "id": 12,
    "field": "some-value" 
  }
}
Note
titleAttention

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

The clients.accounts.delete, clients.archive, clients.balance_notzero, clients.balance_zero, and clients.delete events send empty data: {} (as we send the event info, there is no need to duplicate it in data)

.


Info
titleNote

The clients.custom_fields_update event has been renamed to clients.custom_fields.update starting from JeraSoft Billing v3.23 for consistency.

Event Payload

Details

Clients

Actions:

  • create
Code Block
{
  "event": {
    "dt": "2000-01-01T00:00:00+00:00",
    "events_id": "clients.create",
    "object_id": 12
  },
  "data": {
    "id": 12,
    "name": "Customer A",
    "companies_id": 67,
    "currencies_id": 10,
    ...
  }
}
  • update
Code Block
{
  "event": {
    "dt": "2000-01-01T00:00:00+00:00",
    "events_id": "clients.update",
    "object_id": 12
  },
  "data": {
    "id": 12,         
    "name": "My changed name"
  }
}
  • delete
Code Block
{
  "event": {
    "dt": "2000-01-01T00:00:00+00:00",
    "events_id": "clients.delete",
    "object_id": 12
  },
  "data": {}
}
  • archive
Code Block
{
  "event": {
    "dt": "2000-01-01T00:00:00+00:00",
    "events_id": "clients.archive",
    "object_id": 12
  },
  "data": {}
}
  • custom fields update
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"
  }
}
  • balance became >=0
Code Block
{
  "event": {
    "dt": "2000-01-01T00:00:00+00:00",
    "events_id": "clients.balance_notzero",
    "object_id": 12
  },
  "data": {}
}
  • balance became <=0
Code Block
{
  "event": {
    "dt": "2000-01-01T00:00:00+00:00",
    "events_id": "clients.balance_zero",
    "object_id": 12
  },
  "data": {}
}

Accounts

Actions:

  • create
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",
    ...
  }
}
  • update

...

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

...

.update",
   

...

"object_id": 12
 

...

},

...

  "data": {

...

...

 

...

  

...

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

Subscriptions

Actions:

  • assign
Code Block
{
  "event": {
    "dt": "2000-01-01T00:00:00+00:00",
    "events_id": "clients.subscriptions.assign",
    "object_id": 12
  },
  "data": {
    "id": 12,
    "clients_idfield": 34,
    "packages_id": 56,
    "stop_dt": "2023-01-01T00:00:00+00:00",
    ...
  "some-value" 
  }
}
  • activate
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",
    ...
  }
}
  • deactivate
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",
    ...
  }
}
  • renew
Code Block
{
  "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,
    ...
  }
}
  • close

...

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.


Panel
borderColor#ccffcc
bgColor#ccffcc
borderWidth2px
borderStylesolid

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.