Impac!™ API
API Endpoint
https://api-impac.maestrano.comImpac!™ is a reporting engine provided by Maestrano.
Its purpose is to fetch raw data from multiple sources (such as Connec!™), and process it into business intelligence reports.
Impac!™ can also be used to track business metrics and get alerted when these metrics reach a given threshold.
API versions
All calls must prefixed by the /api keyword, followed by the version number. Eg:
https://api-impac.maestrano.com/api/v2/boltsTwo versions are available at the moment:
-
v1stands for Impac!™’s legacy architecture. From the version 1 endpoints, you can access all the widgets and kpis that have been implemented directly in the Impac!™ API application. -
v2stands for the latest architecture where the widgets and kpis are implemented in dedicated computation engines called “bolts”. With the version 2, Impac!™ is simply proxying your requests to the relevant bolts.
Authentication
Access to Impac!™ API will be granted once you’ve provided:
-
the unique IDs of the organizations of which you are trying to access the data
-
a set of valid credentials
The organization IDs are always passed as a parameter, regardless of the method employed (POST, GET…)
This parameter is an Array: metadata[organization_ids][]
GET https://api-impac.maestrano.com/api/v2/bolts?metadata[organization_ids][]=org-fbba
-----
POST https://api-impac.maestrano.com/api/v2/bolts
{
"metadata": {
"organization_ids": ["org-fbba"]
}
}Access with developer or tenant credentials
You need to provide your Maestrano Enterprise Tenant key and token (or Maestrano developer key/token) to access Impac!™ API. You might have received this private access key directly from your Maestrano Account Manager. Use Basic Auth to give your key to the API:
+ username: "your API key"
+ password: "your API secret"Access with sso session token
When accessing the API as a logged in user, member of the organizations passed in metadata[organization_ids][], you can use the user’s SSO session token:
- via Basic Auth (recommended):
+ username: "user sso_session token"
+ no password- as a parameter:
GET https://api-impac.maestrano.com/api/v2/bolts?metadata[organization_ids][]=org-fbba&sso_session="user sso_session token"
-----
POST https://api-impac.maestrano.com/api/v2/bolts
{
"metadata": {
"organization_ids": ["org-fbba"]
},
"sso_session": "user sso_session token"
}Glossary
Bolt
External application that is dedicated to the computation of specific widgets and kpis.
All bolts respect the same data structure and have their own documentation pages.
Dashboard
A dashboard is constituted of several widgets and KPIs.
It belongs to a user and is related to one of several organizations.
KPI
Business metric that the users can attach to their dashboards and track.
It is possible to set alerts on KPIs so the user get notified when the metric reaches a given threshold.
Notification
When a data source is updated (new record, update of an existing record…), it is possible to send a Webhook notification to inform Impac! of the change.
With the v1, the update will trigger the recalculation of the KPIs. With the v2, the notification will be forwarded to the relevant bolts.
Widget
A widget is a component calculated by Impac! or a bolt, on the basis of the data associated to one or several organizations.
It can return a standard accounting report, a chart, a summary, etc.
Quick Start ¶
This example will let you fetch a widget from Maestrano Finance Bolt using the v2 API.
Get started
-
Log onto get.maestrano.com and create a new dashboard
-
Open the developer tools (F12 if you are using Chrome) and write down the following elements:
+ the "metadata['organization_ids'][]" parameter (Array)
+ the "Authorization" headerNote: The Authorization header will change everytime you log in as it is based on your user’s sso session token - see Authentication for details.
Query Finance Bolt ¶
Headers
Authorization: Basic MzkwNzUxZmU5M2ZiNTk2KjA0MzVkMDQwYjM4ODUwNDFlNzI0NTZmYg==Headers
Content-Type: application/jsonBody
{
"profit_and_loss": {
"table": {
"headers": {
"id": "profit_and_loss",
"cells": [
"Accounts",
"Profit/Loss"
]
},
"rows": {
"grouped": [
{
"headers": {
"id": "income",
"cells": [
"Income",
-28177.1
]
},
"rows": {
"single": [
{
"id": "4689c6c0-1fbd-0136-1a27-0242ac11005b",
"cells": [
"Sales",
-28177.1
]
}
]
}
},
{
"headers": {
"id": "non_operating_income",
"cells": [
"Non Operating Income",
-60.6
]
},
"rows": {
"single": [
{
"id": "46916440-1fbd-0136-1a2b-0242ac11005b",
"cells": [
"Other Revenue",
0
]
},
{
"id": "4697bd20-1fbd-0136-1a2f-0242ac11005b",
"cells": [
"Interest Income",
-60.6
]
}
]
}
},
{
"headers": {
"id": "cost_of_goods_sold",
"cells": [
"Cost Of Goods Sold",
476.6
]
},
"rows": {
"single": [
{
"id": "469f3db0-1fbd-0136-1a33-0242ac11005b",
"cells": [
"Purchases",
476.6
]
},
{
"id": "46a84040-1fbd-0136-1a37-0242ac11005b",
"cells": [
"Cost of Goods Sold",
0
]
}
]
}
},
{
"headers": {
"id": "operating_expenses",
"cells": [
"Operating Expenses",
37934.9
]
},
"rows": {
"single": [
{
"id": "46b0e6d0-1fbd-0136-1a3b-0242ac11005b",
"cells": [
"Advertising",
2560.5
]
},
{
"id": "46b85ac0-1fbd-0136-1a3f-0242ac11005b",
"cells": [
"Bank Fees",
206.9
]
},
{
"id": "46c0e220-1fbd-0136-1a43-0242ac11005b",
"cells": [
"Cleaning",
290.2
]
},
{
"id": "46c82420-1fbd-0136-1a47-0242ac11005b",
"cells": [
"Consulting & Accounting",
61.2
]
},
{
"id": "46d6afb0-1fbd-0136-1a4f-0242ac11005b",
"cells": [
"Entertainment",
173
]
},
{
"id": "46de40d0-1fbd-0136-1a53-0242ac11005b",
"cells": [
"Freight & Courier",
-5.7
]
},
{
"id": "46e5a980-1fbd-0136-1a57-0242ac11005b",
"cells": [
"General Expenses",
677.1
]
},
{
"id": "46ecf5e0-1fbd-0136-1a5b-0242ac11005b",
"cells": [
"Insurance",
0
]
},
{
"id": "46f31950-1fbd-0136-1a5f-0242ac11005b",
"cells": [
"Interest Expense",
0
]
},
{
"id": "46f9bb30-1fbd-0136-1a63-0242ac11005b",
"cells": [
"Legal expenses",
2553
]
},
{
"id": "47027a70-1fbd-0136-1a67-0242ac11005b",
"cells": [
"Light, Power, Heating",
652
]
},
{
"id": "4709c2d0-1fbd-0136-1a6b-0242ac11005b",
"cells": [
"Motor Vehicle Expenses",
548.5
]
},
{
"id": "47118d30-1fbd-0136-1a6f-0242ac11005b",
"cells": [
"Office Expenses",
889.9
]
},
{
"id": "4719a490-1fbd-0136-1a73-0242ac11005b",
"cells": [
"Printing & Stationery",
112.6
]
},
{
"id": "472199e0-1fbd-0136-1a77-0242ac11005b",
"cells": [
"Rent",
3478.4
]
},
{
"id": "472947b0-1fbd-0136-1a7b-0242ac11005b",
"cells": [
"Repairs and Maintenance",
0
]
},
{
"id": "473238e0-1fbd-0136-1a7f-0242ac11005b",
"cells": [
"Wages and Salaries",
25087.3
]
},
{
"id": "473a3010-1fbd-0136-1a83-0242ac11005b",
"cells": [
"Superannuation",
0
]
},
{
"id": "47426ca0-1fbd-0136-1a87-0242ac11005b",
"cells": [
"Commission",
0
]
},
{
"id": "474a13f0-1fbd-0136-1a8b-0242ac11005b",
"cells": [
"Subscriptions",
74.9
]
},
{
"id": "4752e2e0-1fbd-0136-1a8f-0242ac11005b",
"cells": [
"Telephone & Internet",
149.5
]
},
{
"id": "475a47f0-1fbd-0136-1a93-0242ac11005b",
"cells": [
"Travel - National",
425.7
]
},
{
"id": "47629520-1fbd-0136-1a97-0242ac11005b",
"cells": [
"Travel - International",
0
]
},
{
"id": "477a8e90-1fbd-0136-1aa3-0242ac11005b",
"cells": [
"Realised Currency Gains",
0
]
},
{
"id": "47819030-1fbd-0136-1aa7-0242ac11005b",
"cells": [
"Income Tax Expense",
0
]
}
]
}
},
{
"headers": {
"id": "non_operating_expenses",
"cells": [
"Non Operating Expenses",
0
]
},
"rows": {
"single": [
{
"id": "46cfc9e0-1fbd-0136-1a4b-0242ac11005b",
"cells": [
"Depreciation",
0
]
},
{
"id": "476a83a0-1fbd-0136-1a9b-0242ac11005b",
"cells": [
"Bank Revaluations",
0
]
},
{
"id": "4772d300-1fbd-0136-1a9f-0242ac11005b",
"cells": [
"Unrealised Currency Gains",
0
]
}
]
}
}
],
"single": [
{
"id": "gross_profit",
"cells": [
"Gross Profit",
-27761.1
]
},
{
"id": "net_profit",
"cells": [
"Net Profit",
10173.9
]
}
]
}
}
},
"settings": {},
"params": {
"provider": "maestrano",
"name": "finance",
"endpoint": "profit_and_loss",
"layouts": [
"table"
],
"metadata": {
"organization_ids": [
"org-fgu1"
],
"currency": "EUR"
}
}
}Query Finance BoltGET/api/v2/{provider}/{name}/widgets/{endpoint}?metadata[organization_ids][]={org_uid}¤cy={currency}&layouts[]={layout}
Make sure you set the Authorization header and that you pass the metadata[organization_ids][] and metadata[currency] required parameters with your request.
Note: In this example, we’ve chosen to query the report in EUR, and to render it in the table layout. For more details regarding layouts and other parameters, please refer to the v2 API documentation.
- provider
string(required) Example: maestrano- name
string(required) Example: finance- endpoint
string(required) Example: profit_and_loss- org_uid
string(required) Example: org-fbba- currency
string(required) Example: EUR- layout
string(required) Example: table
V1 - Legacy ¶
V2 - Bolts ¶
With the v2 architecture, the computation of widgets and KPIs are delegated to separate engines called “bolts”. Impac! will just proxy the requests to the relevant bolt(s).
Each bolt has its own API reference documentation:
Managing the bolts ¶
Body
{
"bolts": [
{
"id": 1,
"protocol": "https",
"provider": "maestrano",
"name": "finance",
"host": "my-bolt-application.mcube.co",
"api_path": "api/v1",
"subscribed_entities": [
"companies",
"accounts",
"journals",
"invoices"
]
}
]
}IndexGET/api/v2/bolts
Note: The following action is restricted to administrators, you need to be authenticated as a Master Tenant to get access.
This endpoint will list the registered bolts and their endpoints.
| Returned field | Description |
|---|---|
| id | ID of the Bolt as saved in Impac! database |
| protocol | Protocol in use to query the bolt (should always be https) |
| provider | Name of the entity providing the bolt |
| name | Name of the bolt - the provider + name pair is unique |
| host | URL of the bolt |
| api_path | Bolt API version / endpoint to be used |
| subscribed_entities | Everytime Impac! is notified of a change on an entity, it will forward the notification to the bolt if the entity type is listed in this array. When the array is left empty, the bolt will be notified of any change regardless of the entity type |
Body
{
"bolts": {
"protocol": "https",
"provider": "maestrano",
"name": "finance",
"host": "my-bolt-application.mcube.co",
"api_path": "api/v1",
"subscribed_entities": [
"companies",
"accounts",
"journals",
"invoices"
]
}
}Body
{
"bolts": {
"id": 1,
"protocol": "https",
"provider": "maestrano",
"name": "finance",
"host": "my-bolt-application.mcube.co",
"api_path": "api/v1",
"subscribed_entities": [
"companies",
"accounts",
"journals",
"invoices"
],
"api_key": "MY KEY",
"api_secret": "MY SECRET"
}
}CreatePOST/api/v2/bolts
Note: The following action is restricted to administrators, you need to be authenticated as a Master Tenant to get access.
This endpoint will register a new bolt on the API.
Warning: The api key and secret will be only returned once, in the response to the CREATE method. You won’t be able to retreive these credentials after the first CREATE.
| Returned field | Description |
|---|---|
| id | ID of the Bolt as saved in Impac! database |
| protocol | Protocol in use to query the bolt (should always be https) |
| provider | Name of the entity providing the bolt |
| name | Name of the bolt - the provider + name pair is unique |
| host | URL of the bolt |
| api_path | Bolt API version / endpoint to be used |
| subscribed_entities | Everytime Impac! is notified of a change on an entity, it will forward the notification to the bolt if the entity type is listed in this array. When the array is left empty, the bolt will be notified of any change regardless of the entity type |
| api_key | private key shared between Impac! API and the bolt |
| api_secret | private secret shared between Impac! API and the bolt |
Querying a bolt ¶
Body
{
"batch": {
"notifications": [
{
"channel_id": "org-abcd",
"entities": {
"journals": [
{
"id": "156d15fa546df-dsfagfa-g4gf5sdf"
}
],
"accounts": [
{
"id": "254gf54sfgdgf-fss4254-ssdfdgf4"
}
]
}
}
]
},
"metadata": {
"organization_ids": [
"org-abcd"
]
}
}Push notifications to one boltPOST/api/v2/{provider}/{name}/notifications
This endpoints allows to forward a batch of Webhook notifications to ONE GIVEN BOLT.
The notifications must be grouped by entity, under batch[:notifications].
Each entity hash can contain as many fields as necessary, and respect Connec! API v2 specifications.
Note: The system will process the batch of notifications asynchronously: The response will always be 200 (OK) and you won’t be notified if the notifications couln’t be processed properly.
Ultimately, one job will be enqueued for each notification, which will be forwarded to the bolt if it contains entities that the bolt is subscribing to, in the following format:
{
"channel_id": "org-abcd",
"entities": {
"journals": [{ "id": "156d15fa546df-dsfagfa-g4gf5sdf" }],
"accounts": [{ "id": "254gf54sfgdgf-fss4254-ssdfdgf4" }]
}
}- provider
string(required) Example: maestranoentity providing the bolt API
- name
string(required) Example: financename of the bolt provided
Body
{
"batch": {
"notifications": [
{
"channel_id": "org-abcd",
"entities": {
"journals": [
{
"id": "156d15fa546df-dsfagfa-g4gf5sdf"
}
],
"accounts": [
{
"id": "254gf54sfgdgf-fss4254-ssdfdgf4"
}
]
}
}
]
},
"metadata": {
"organization_ids": [
"org-abcd"
]
}
}Push notifications to all boltsPOST/api/v2/notifications
This endpoints allows to forward a batch of Webhook notifications to ALL THE BOLTS.
The notifications must be grouped by entity, under batch[:notifications].
Each entity hash can contain as many fields as necessary, and respect Connec! API v2 specifications.
Note: The system will process the batch of notifications asynchronously: The response will always be 200 (OK) and you won’t be notified if the notifications couln’t be processed properly.
Ultimately, one job will be enqueued for each notification, which will be forwarded to each bolt if it contains entities that the bolt is subscribing to, in the following format:
{
"channel_id": "org-abcd",
"entities": {
"journals": [{ "id": "156d15fa546df-dsfagfa-g4gf5sdf" }],
"accounts": [{ "id": "254gf54sfgdgf-fss4254-ssdfdgf4" }]
}
}KPIs endpointsGET/api/v2/{provider}/{name}/kpis
Impac! will act as a proxy to forward your request to the bolt’s KPIs endpoints. Follow the bolt API reference, and rather than accessing the bolt API directly, prefix your requests by api/v2 followed by the bolt provider and name, then kpis. Eg:
GET api/v2/maestrano/finance/kpis - lists the KPIs available on the "maestrano/finance" bolt
GET api/v2/my-own/bolt/kpis/custom_metric - queries the kpi "custom_metric" hosted on "my own bolt"- provider
string(required) Example: maestranoentity providing the bolt API
- name
string(required) Example: financename of the bolt provided
Widgets endpointsGET/api/v2/{provider}/{name}/widgets
Impac! will act as a proxy to forward your request to the bolt’s widgets endpoints. Follow the bolt API reference, and rather than accessing the bolt API directly, prefix your requests by api/v2 followed by the bolt provider and name, then widgets. Eg:
GET api/v2/maestrano/finance/widgets - lists the widgets available on the "maestrano/finance" bolt
GET api/v2/my-own/bolt/widgets/my_chart - queries the widget "my_chart" hosted on "my own bolt"All the bolt widgets respond using the same data structure, organised around generic layouts (can be “chart”, “table”, etc.).
You can then require the bolt to return a widget in one or several layouts. When no layout is passed, all the layouts supported by the widget will be returned. Eg:
GET api/v2/maestrano/finance/widgets/assets_summary?layouts[]=chart - returns the "assets summary" widget in a chart
GET api/v2/maestrano/finance/widgets/assets_summary - returns the "assets summary" widget in all the supported layoutsTo know what layouts are supported by which widgets, query the index endpoint exposed by the bolt. Eg:
GET api/v2/maestrano/finance/widgets- provider
string(required) Example: maestranoentity providing the bolt API
- name
string(required) Example: financename of the bolt provided
- layouts
array(optional) Example: [chart, table]layouts to be used when returning the widget
Generated by aglio on 30 Apr 2018