Guides
What you can build
Maci Intelligence watches each refrigeration system and warns before it breaks down. The API and the webhooks take what it finds, and the data around each unit, into the systems your people already work in.
Ideas
Act on the alarms where you work, keep your own records in step with Maci, or both:
- Turn an alarm into a work order. Receive
alarm.raisedby webhook and open a ticket in your service or CAFM system, with the unit, the site and the readings the rule saw. - Take and close alarms from your own system. When someone takes the job, acknowledge the alarm, so it stops going on to the next people on the list. Close it as real or false when the visit is done; what was found helps tune the alarm rules.
- Keep your asset register in step. Read units, sites and components with refrigerant, charge and CO2 equivalent into your CAFM or ERP, and send changes back. A replaced component keeps its history.
- Plan leak checks across all your sites. Read each unit's F-gas status: the interval, the last check and when the next one is due, and put the deadlines in your planning.
- Write service history from your own tools. Add service notes and F-gas entries when your technicians work in another app, so each unit's history in Maci stays whole.
- Invoice from approved service reports. Get each approved invoice basis by webhook, book it in your accounting system and mark it exported. Keep the catalogue in step with your price list.
- Report to your clients. Fetch a period's alarms with GET /alarms for an SLA report: when each alarm came, who took it, how fast, and whether it was real.
- Register units from a photo. Send a photo of the nameplate and use what was read to fill in the manufacturer, model and refrigerant.
The readings behind an alarm stay in Maci. The API gives each alarm with the values the rule saw, and everything about the units around it.
Who builds what
| Who | What they usually build |
|---|---|
| Facility management and owners of many sites | Alarms into the CAFM system as work orders, the asset register in step, leak check deadlines in the plan, and an alarm report for each client. |
| Refrigeration companies on watch | The alarms of the units where the owner has chosen you as the watch, straight to your on-call tool; service notes and F-gas entries from your field service app; invoice bases to your accounting system. |
| Software companies and integrators | The same for your customers. Each customer makes a key for your integration with only the scopes it needs, and can delete it at any time. |
An example: from alarm to work order
1. Open a work order when an alarm is raised. Set the address for alarms in the app, check the signature, answer at once, and open the work order. openWorkOrder and signatureIsValid stand for your own code.
Webhook receiver
import express from 'express';
const app = express();
// The raw body, so the signature can be checked before anything else (see Webhooks).
app.post('/maci/alarms', express.raw({ type: 'application/json' }), async (req, res) => {
if (!signatureIsValid(req.body, req.get('X-Maci-Signature'))) return res.sendStatus(401);
res.sendStatus(200); // Answer at once, then do the work.
const { event, data: alarm } = JSON.parse(req.body);
if (event === 'alarm.raised') {
await openWorkOrder({
title: `${alarm.name}: ${alarm.unit} (${alarm.unit_public_id})`,
site: alarm.site,
priority: alarm.severity === 'HIGH' ? 'urgent' : 'normal',
details: alarm.values,
maciAlarmId: alarm.id,
});
}
});2. Take the alarm when a person takes the job. Acknowledge it from your system when a technician accepts the work order, so Maci stops passing it on. Do not acknowledge it as soon as the work order is made: then nobody else is told, even if nobody has seen it.
Take the alarm
curl -X POST https://api.maci.energy/v1/alarms/7e3b1c90-2f4a-4d8e-9b61-5a0c3d7f2e18/acknowledge \
-H "Authorization: Bearer $MACI_API_KEY"const response = await fetch('https://api.maci.energy/v1/alarms/7e3b1c90-2f4a-4d8e-9b61-5a0c3d7f2e18/acknowledge', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.MACI_API_KEY}`,
},
});
const data = await response.json();import os
import requests
response = requests.post(
"https://api.maci.energy/v1/alarms/7e3b1c90-2f4a-4d8e-9b61-5a0c3d7f2e18/acknowledge",
headers={"Authorization": f"Bearer {os.environ['MACI_API_KEY']}"},
)
data = response.json()$client = new \GuzzleHttp\Client();
$response = $client->request('POST', 'https://api.maci.energy/v1/alarms/7e3b1c90-2f4a-4d8e-9b61-5a0c3d7f2e18/acknowledge', [
'headers' => [
'Authorization' => 'Bearer '.getenv('MACI_API_KEY'),
],
]);
$data = json_decode($response->getBody(), true);3. Close it when the visit is done, as real or false, with what was found.
Close the alarm
curl -X POST https://api.maci.energy/v1/alarms/7e3b1c90-2f4a-4d8e-9b61-5a0c3d7f2e18/close \
-H "Authorization: Bearer $MACI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"result": "real",
"note": "Door left open after a delivery."
}'const response = await fetch('https://api.maci.energy/v1/alarms/7e3b1c90-2f4a-4d8e-9b61-5a0c3d7f2e18/close', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.MACI_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"result": "real",
"note": "Door left open after a delivery."
}),
});
const data = await response.json();import os
import requests
response = requests.post(
"https://api.maci.energy/v1/alarms/7e3b1c90-2f4a-4d8e-9b61-5a0c3d7f2e18/close",
headers={"Authorization": f"Bearer {os.environ['MACI_API_KEY']}"},
json={
"result": "real",
"note": "Door left open after a delivery."
},
)
data = response.json()$client = new \GuzzleHttp\Client();
$response = $client->request('POST', 'https://api.maci.energy/v1/alarms/7e3b1c90-2f4a-4d8e-9b61-5a0c3d7f2e18/close', [
'headers' => [
'Authorization' => 'Bearer '.getenv('MACI_API_KEY'),
],
'json' => [
'result' => 'real',
'note' => 'Door left open after a delivery.',
],
]);
$data = json_decode($response->getBody(), true);