# 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.raised` by [webhook](https://api.maci.energy/docs/webhooks.md#alarm-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](https://api.maci.energy/docs/alarms.md#acknowledge-alarm), so it stops going on to the next people on the list. [Close it](https://api.maci.energy/docs/alarms.md#close-alarm) 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](https://api.maci.energy/docs/units.md) 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](https://api.maci.energy/docs/f-gas-log.md#get-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](https://api.maci.energy/docs/service.md#create-service-entry) and [F-gas entries](https://api.maci.energy/docs/f-gas-log.md#create-f-gas-entry) 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](https://api.maci.energy/docs/invoicing.md) by webhook, book it in your accounting system and [mark it exported](https://api.maci.energy/docs/invoicing.md#mark-invoice-drafts-exported). Keep the catalogue in step with [your price list](https://api.maci.energy/docs/invoicing.md#put-price-list-items).
- **Report to your clients.** Fetch a period's alarms with [GET /alarms](https://api.maci.energy/docs/alarms.md#list-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](https://api.maci.energy/docs/photos.md#create-photo) and use [what was read](https://api.maci.energy/docs/photos.md#get-photo-reading) 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.

```javascript
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.

```bash
curl -X POST https://api.maci.energy/v1/alarms/7e3b1c90-2f4a-4d8e-9b61-5a0c3d7f2e18/acknowledge \
  -H "Authorization: Bearer $MACI_API_KEY"
```

```javascript
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();
```

```python
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()
```

```php
$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.

```bash
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."
  }'
```

```javascript
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();
```

```python
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()
```

```php
$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);
```

## Start building

- [Quickstart](https://api.maci.energy/docs/quickstart.md): Make a key and your first call in a few minutes.
- [Webhooks](https://api.maci.energy/docs/webhooks.md): Set up the address, check the signature, answer and retries.
- [Alarms](https://api.maci.energy/docs/alarms.md): List, read, take and close alarms.
- [Authentication](https://api.maci.energy/docs/authentication.md): Keys, scopes and the sandbox.