This documentation relates to an earlier version of JeraSoft VCS.
View User Guide 3.26 or visit our current documentation home page.

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 7 Next »

In this article

The Provisioning API 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 JeraSoft Billing Core API and Management API 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 that the billing will send to an external system a notification to avoid any disruptions to your organization's current processes.

Handlers

A typical handler is HTTPS or HTTP (called via POST requests). Local server scripts (called locally on the server) are extremely rare cases used mainly by the JeraSoft team.

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:

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.create
  • clients.update
  • clients.delete
  • clients.archive
  • clients.custom_fields.update
  • clients.balance_notzero
  • clients.balance_zero
  • clients.accounts.create
  • clients.accounts.update
  • clients.accounts.delete
  • clients.subscriptions.assign
  • clients.subscriptions.activate
  • clients.subscriptions.deactivate
  • clients.subscriptions.renew
  • clients.subscriptions.close

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.
{
  "event": {
    "dt": "2000-01-01T00:00:00+00:00",
    "events_id": "clients.update",
    "object_id": 12
  },
  "data": {
    "id": 12,
    "field": "some-value" 
  }
}

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

Note

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

Payload Details

Clients

Actions:

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

Accounts

Actions:

  • create
{
  "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
{
  "event": {
    "dt": "2000-01-01T00:00:00+00:00",
    "events_id": "clients.accounts.update",
    "object_id": 12
  },
  "data": {
    "id": 12,
    "name": "My changed account"
  }
}
  • delete
{
  "event": {
    "dt": "2000-01-01T00:00:00+00:00",
    "events_id": "clients.accounts.delete",
    "object_id": 12
  },
  "data": {}
}

Subscriptions

Actions:

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


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. 
  • No labels