Docs for all releases
Page History
...
Panel | ||
---|---|---|
| ||
|
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 | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
Best practice example There is an example based on https://hostname/handler-endpoint usage. Open the Provisioning section and start creating a handler.
Find an example of the http://handler below:
|
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 | ||
---|---|---|
| ||
The |
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 | |||||||||||
The client has been created |
| ||||||||||
The client's details have been updated |
| ||||||||||
The client has been archived |
| ||||||||||
The client has been completely deleted Not to be confused with archived |
| ||||||||||
The client's balance became <=0 |
| ||||||||||
The client's balance became > 0 |
| ||||||||||
The client's Custom Field has been updated |
| ||||||||||
Accounts Management | |||||||||||
The account has been created |
| ||||||||||
The account's details have been updated |
| ||||||||||
The account has been completely deleted |
| ||||||||||
Subscriptions Management | |||||||||||
The subscription has been assigned |
| ||||||||||
The subscription has been activated |
| ||||||||||
The subscription has been deactivated |
| ||||||||||
The subscription has been renewed |
| ||||||||||
The subscription has been closed |
| ||||||||||
Email Rates Manager | |||||||||||
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" } } | ||||||||||
No Rate Tables match received email |
| ||||||||||
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" } } | ||||||||||
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 | |||||||||||
The import attempt was successful |
"main": {
"queue": {
| ||||||||||
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 | |||||||||||
The Transaction of Type Charge has been created |
| ||||||||||
The Transaction of Type Charge has been removed |
| ||||||||||
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 | |||||||||||
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" } } | ||||||||||
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" } } | ||||||||||
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
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 | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
Tip
|