# Énergie VE — API for DadycarGo

What the mobile app needs to build the Energy section: six screens, eleven endpoints.
Everything is under `/api/v1/mobile-app/energy`, with the app's usual bearer token.
Answers use the house envelope `{ status, message, data }`; a refused action answers
`422` with a translated `message`, an unknown object `404`. A company whose plan does not
include the module answers `402` like any other closed module.

Codes are returned, never wording: the app translates `status`, `place`, `source`,
`status_reason`, `pricing_status` itself.

## Screens and their calls

| Screen | Call |
| --- | --- |
| Energy home | `GET /overview` |
| Set-up, step 1: home and equipment | `GET /profile`, `POST /profile` |
| Set-up, step 2: electricity contract | `GET /contract`, `POST /contract` |
| My recharges of the month | `GET /sessions?month=YYYY-MM` |
| A recharge to confirm | `POST /sessions/{id}/confirm` |
| Declare a recharge | `POST /sessions/declarations` |
| My statements | `GET /statements`, `GET /statements/{YYYY-MM}`, `GET /statements/{YYYY-MM}/file` |
| Contest a recharge | `POST /sessions/{id}/contest` |

## Energy home — `GET /overview`

The first call of an invited driver marks his invitation as opened, so the manager sees
it was followed: nothing to pass. (The link of the invitation e-mail leads to a web page
that sends the driver to the app; `?invitation=` is still accepted and ignored.)

```json
{
  "onboarding": {
    "invited": true,
    "home_declared": false,
    "privacy_mode": null,
    "equipment_declared": false,
    "contract_declared": false,
    "contract_complete": false,
    "complete": false
  },
  "has_vehicle_in_scope": true,
  "expected_proof_level": 3,
  "source_status": "ok",
  "next_statement_on": "2026-11-01",
  "month": {
    "period": "2026-10",
    "sessions": 5,
    "kwh_home": 113.37,
    "amount_estimated": 18.84,
    "to_confirm": 1,
    "in_review": 2,
    "unpriced": 0
  },
  "statement_to_check": {
    "period": "2026-09",
    "amount_total": 17.54,
    "lines_count": 4,
    "contest_until": "2026-10-06T21:59:59+00:00"
  }
}
```

- `onboarding.complete` false: show the set-up steps first.
- `amount_estimated` is an estimate until the month is validated; say so.
- `expected_proof_level` 1 to 5 (1 = the driver declares his recharges, 3 = measured by
  the vehicle). `source_status`: `ok`, `to_fix`, `none`.
- `statement_to_check` is null when nothing waits for the driver's check.

## Set-up

### `POST /profile`

| Field | Rule |
| --- | --- |
| `privacy_mode` | `address` or `confirm`. With `confirm` the driver gives no address and confirms his home recharges himself. |
| `home_address`, `home_latitude`, `home_longitude` | The address is required with `address`. The position comes with a new address; a profile saved again at the same address keeps the position it had (422 `home_position_required` otherwise). Never shown to a manager. |
| `equipment` | Required: `socket`, `reinforced_socket` or `wallbox`. |
| `charger_brand`, `charger_is_mid` | Optional. |
| `paid_by_mileage_allowance` | Optional boolean, for a personal vehicle paid by the mileage scale. |
| `effective_from` | Optional date. A move is a new profile from that date; recharges of before keep the address of before. |

### `POST /contract` (multipart when an invoice is attached)

| Field | Rule |
| --- | --- |
| `option` | Required: `base`, `hphc` or `tempo`. |
| `supplier`, `power_kva` (3 to 36) | Optional. The power matters for the regulated single price. |
| `offpeak_ranges` | Required with `hphc`: up to three `["22:00", "06:00"]` pairs. |
| `prices` | Per kWh, tax included, by band: `base`; or `hp`, `hc`; or `blue_hp`, `blue_hc`, `white_hp`, `white_hc`, `red_hp`, `red_hc`. |
| `effective_from` | Optional date: a new contract only prices the recharges from that day on. |
| `invoice` | Optional file (jpg, png, webp, pdf, 10 MB). |

`GET /contract` returns the contract in force with `has_all_prices`, `has_invoice` and
`review_on` (the date the driver is asked to confirm it again).

## Recharges

### `GET /sessions?month=YYYY-MM`

`{ month, kwh_home, to_confirm, sessions: [...] }`. Each session carries `id`, `vehicle`,
`started_at`, `ended_at`, `duration_minutes`, `place`, `kwh_grid`, `is_estimated`,
`amount`, `pricing_status`, `price_breakdown`, `proof_level`, `status`, `status_reason`.
No position is ever returned: none is stored.

`status`: `in_progress`, `to_confirm`, `proposed`, `in_review`, `validated`, `rejected`,
`excluded`, `control`.

### `POST /sessions/{id}/confirm`

`{ "at_home": true | false }`, on a session whose status is `to_confirm`.

### `POST /sessions/declarations` (multipart)

`vehicle_id`, `started_at`, `ended_at`, `kwh` (up to 200), `at_home`, optional `note`,
and `document` (required: a photo of the meter or of the charger's display). A declared
recharge always waits for a manager.

### `POST /sessions/{id}/contest`

`{ "reason": "…" }` (3 to 500 characters), on a `proposed` session, once per session.
The session goes back to a manager; the driver is notified of the decision.

## Statements

- `GET /statements` → `{ proposed: [...], validated: [...] }`. A validated statement
  carries `number`, totals, `sealed_at` and its SHA-256 `hash`.
- `GET /statements/{YYYY-MM}` → the month line by line. `status` is `proposed` (each line
  has `can_contest`) or `validated` (sealed, read-only).
- `GET /statements/{YYYY-MM}/file` → the validated statement as a PDF; `404` while the
  month is not validated.

## Notifications the app receives

Sent through the platform's notification engine, with a `screen` in the payload:

| Type | When | `screen` |
| --- | --- | --- |
| `energy_invitation` | The driver is invited, then reminded on day 3 and day 7 | `energy_onboarding` |
| `energy_statement_proposed` | His month is ready to check | `energy_statement` (+ `period`) |
| `energy_contest_window_closing` | 48 hours before the end of the check period | `energy_statement` (+ `period`) |
| `energy_contest_decided` | A manager decided on his contest | `energy_session` (+ `session_id`) |
| `energy_session_to_confirm` | A recharge ended where the place could not be told: was it at home? | `energy_session` (+ `session_id`) |
| `energy_contract_to_update` | Once a year, at the review date of his electricity contract | `energy_contract` |

The day statements are offered and the length of the check period are set by each
company (defaults: the 1st, 5 days): always read `contest_until` and
`next_statement_on` from the API, never compute them in the app.

## My charge point (release 2)

### `GET /charge-point`

```json
{
  "charge_point": { "id": 41, "brand": "Zaptec", "model": "Go", "is_mid": true, "linked": false, "provider": null, "last_sync_at": null, "sync_error": false },
  "project": { "id": 3, "stage": "quote", "stage_since": "2026-10-07T14:02:11+00:00", "stages": ["request", "quote", "approval", "installation", "commissioned"] },
  "providers": ["zaptec"]
}
```

`charge_point` and `project` are `null` when the driver has none. `providers` lists the
makers a charge point can be linked to right now; when it is empty, hide the link screen.

### `POST /charge-point/link`

`{ "provider": "zaptec", "charger_ref": "<the charger's id, a UUID>", "serial_number": "<printed on the charge point, e.g. ZAP000123>", "consent": true }`

Before calling it, the driver gives the Dadycar account access to his installation in
the Zaptec portal: explain that step on the screen. Nothing of his own Zaptec
credentials is ever asked. `serial_number` is required: seeing a charge point is not
owning it, so the driver also types the serial number on its label, which has to be the
one the maker knows (and the one the company registered, when it did). Case, spaces and
dashes do not count. Errors (422, message ready to show): the charge point is not
shared with us yet, the serial number does not match, it is already linked, linking is
unavailable.

Once linked, his recharges on that charge point come by themselves with the strongest
proof (N5 when the meter is certified, N4 otherwise) and replace the vehicle's estimate.

### `DELETE /charge-point/link`

The driver takes his consent back: nothing more is read.

### `POST /charge-point/request`

`{ "housing": "house" | "condo" | "rental", "note": "optional, 500 characters" }` — asks
for a charge point at home. One request at a time (422 otherwise). The steps then show
in `project`.

## Linky consent (release 2)

### `GET /linky`

```json
{ "available": true, "consent": { "consented_at": "2026-10-09T07:00:00+00:00", "expires_at": "2029-10-09T07:00:00+00:00", "last_read_at": null, "reading_failed": false } }
```

`consent` is `null` when the driver gave none. When `available` is false, hide the screen.

### `POST /linky/consent`

Returns `{ "url": "…" }`: open it in the phone's browser. The driver consents on Enedis's
own pages, as the holder of the electricity contract. Enedis then sends him to our
server, which records the consent and redirects to the app with `?linky=ok`, or
`?linky=<reason>` when it could not be recorded. The link is good for 30 minutes.
The meter is only kept once Enedis confirms a consent for it (`linky_meter_not_consented`
otherwise) and while no other driver holds it (`linky_meter_taken`).

What to say on the screen: the meter confirms his recharges, it never measures them;
only the home's total consumption is read, during his recharges and per month; he can
take his consent back at any time; it lasts three years at most.

### `DELETE /linky/consent`

Takes the consent back. Nothing more is read.

## Reading an invoice (release 2)

### `POST /contract/read` (multipart, field `invoice`: PDF or photo, 10 MB)

Proposes the contract's fields from an electricity invoice. Nothing is saved: show the
fields for the driver to check, then call `POST /contract` as before (with the same file
as `invoice`).

```json
{
  "fields": { "supplier": "EDF", "option": "hphc", "power_kva": 9, "offpeak_ranges": [["22:30", "06:30"]], "prices": { "hp": 0.2146, "hc": 0.1696 }, "subscription_monthly": 16.7 },
  "found": ["supplier", "option", "power_kva", "prices", "subscription_monthly"],
  "missing": []
}
```

A field in `missing` was not on the invoice, or did not look right: leave it empty for
the driver to fill. 422 with a message ready to show when the invoice cannot be read.

`POST /contract` now also takes `subscription_monthly` (€ incl. tax per month, optional),
returned by `GET /contract`.

## Bank account for transfers (release 2)

Only useful when the driver's company pays by bank transfer instead of through payroll.

- `GET /bank-account` → `{ "bank_account": { "iban": "FR14 •••• 2606", "bic": null, "holder": "Ana Test" } }`, or `null`.
  The IBAN always comes back masked.
- `POST /bank-account` with `{ "iban", "holder", "bic" (optional) }`. 422 with a message when the IBAN or the BIC is not valid.
- `DELETE /bank-account` removes it.

What to say on the screen: the account is stored encrypted, used only in the transfer file
the company's payroll prepares, and removed when the driver leaves the company.

## Advice notifications (release 2)

| Type | When | `screen` |
| --- | --- | --- |
| `energy_tempo_red_day` | The evening before a Tempo red day, to drivers on the Tempo tariff | `energy_advice` |
| `energy_offpeak_advice` | Once a month is validated, to a driver who charged more than 40 % in peak hours | `energy_advice` (+ `period`) |
| `energy_linky_consent_expiring` | Thirty days before the Linky consent runs out | `energy_linky` |

`POST /profile` also takes `has_solar` (boolean): the driver says he produces solar electricity
at home. His company may then apply a rule of its own to his recharges; `GET /profile` returns it.

`POST /profile` also takes `home_region` (`flanders`, `brussels` or `wallonia`), returned by
`GET /profile`. `GET /overview` returns `home_regions`: the list to choose from, empty when the
company's country does not price by region. Ask for it only when that list is not empty: the
official price of the kWh depends on the region of the home. Until the driver gives it, his home
recharges have no amount (`pricing_status` = `no_region`).

## Off-peak charging on a linked charge point (release 3)

`GET /charge-point` now also returns, inside `charge_point`: `offpeak_scheduling`,
`held_back_now`, `charge_now_until` (an instant, or `null`) and `scheduling_failed`.

- `POST /charge-point/schedule` with `{ "enabled": true, "consent": true }` — the driver lets the
  platform hold his charge point back during the peak hours of his contract; it is released
  when off-peak hours begin. `{ "enabled": false }` stops it and releases the charge point at once.
  422 with a message when the charge point is not linked, or the contract has no off-peak hours.
- `POST /charge-point/charge-now` — the charge point is released now and left alone for twelve hours.

What to say on the screen: the vehicle may wait until off-peak hours to charge; "Charge now"
is always one tap away; turning the option off takes effect at once.
