Docs for all releases
Page History
...
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.
Handlers
A typical handler is should be configured as either HTTPS or HTTP (called via POST requests). Local server scriptswith 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 (called locally on the server) are extremely rare cases used mainly by the JeraSoft team.
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:
|
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
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"
}
} |
- Email Rates Manager
- email_rates_manager.import
- Import Manager
- importd.process_success
- importd.process_failed
Note | ||
---|---|---|
| ||
Please note that 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 | ||
---|---|---|
| ||
The |
Event Payload
DetailsClients
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 | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
Tip
|