# Énergie VE — API and webhooks for a company's own tools

A company creates its keys and its webhook addresses in **EV energy → Rules → Your own tools**.
A key or a webhook secret is shown once, when it is made.

## API (read only)

Base: `/api/v1/energy-api` · header `Authorization: Bearer dcen_…` · 120 calls a minute per key.
A key reads its own company's data and nothing else. No recharge ever carries a position.

| Call | Parameters | Returns |
| --- | --- | --- |
| `GET /sessions` | `from`, `to` (dates), `vehicle_id`, `driver_id`, `place_class` (`home`, `site`, `public`, `unknown`), `page` | Recharges, newest first, 100 a page |
| `GET /balances` | `period` (`YYYY-MM`, required) | The energy balance of each vehicle for the month |
| `GET /anomalies` | `status` (`open`, `accepted`, `corrected`, `rejected`, `resolved`), `page` | Anomalies, newest first |
| `GET /statements` | `period`, `page` | Validated statements |
| `GET /statements/{id}` | | One statement with its lines |

Lists answer `{ "status": true, "data": [...], "meta": { "page", "last_page", "per_page", "total" } }`.
An unknown or revoked key answers 401.

Not offered through a key: declaring, confirming, validating, exporting. Those stay with a
signed-in person, so every decision keeps an author.

## Webhooks

An HTTPS address receives a `POST` for each event it asked for:

```json
{ "event": "energy.statement.validated", "occurred_at": "2026-10-07T16:51:08+00:00",
  "data": { "statement_id": 12, "number": "…", "driver_id": 58012, "period": "2026-09", "kwh_total": 104.76, "amount_total": 17.54, "hash": "…" } }
```

Events: `energy.session.created`, `energy.anomaly.created`, `energy.statement.proposed`,
`energy.statement.validated`, `energy.payroll_export.ready`. They carry identifiers and
figures, never a name nor an address: read the rest through the API.

Each request carries:

- `X-Dadycar-Signature: t=<unix time>,v1=<hex>` where `<hex>` is the HMAC-SHA256 of
  `"<unix time>.<raw body>"` with the address's secret. Check it, and refuse a time too far from now.
- `X-Dadycar-Delivery: <id>`: the same event sent again keeps its id, so it can be ignored the second time.

Answer with any 2xx status within 10 seconds. Anything else is tried again after 1 minute,
5 minutes, 30 minutes, 2 hours and 12 hours, six tries in all; after that the sending waits
and can be sent again by hand from the screen. The payroll connection of sprint 6 signs the same way.

## AI connector (release 3)

The same read-only questions can be asked in plain language, in Dadycar's own chat and through
the AI connector, under the signed-in user's rights (`view_energy`) and limited to the sites
that user may see. Four tools:

| Tool | Answers |
| --- | --- |
| `get_ev_energy_costs` | Home-charging cost of a month by site, vehicle, driver or department, with the numbers and fingerprints of the sealed statements the validated amounts rest on |
| `list_ev_energy_statements` | The closing of a month, driver by driver |
| `list_ev_energy_anomalies` | What the controls found, and what was decided |
| `list_ev_energy_balances` | The energy balance of each vehicle for a month |

Nothing can be validated, decided or exported through them.
