> For the complete documentation index, see [llms.txt](https://docs.smart-stuff.nl/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.smart-stuff.nl/dsmr-api/geavanceerd/api-overzicht.md).

# API overzicht

De DSMR-API software biedt meerdere HTTP API's waarmee de dongle lokaal kan worden uitgelezen of beheerd. Dit overzicht beschrijft de API's van de actuele v5-firmware. Oudere firmwareversies kunnen afwijken.

Gebruik in de voorbeelden het IP-adres of de hostname van uw dongle, bijvoorbeeld:

```http
http://p1-dongle-pro.local/api/v2/sm/actual
```

{% hint style="info" %}
Als Basic Auth is ingesteld, geldt deze beveiliging ook voor de API's.
{% endhint %}

## Slimme meter

| Endpoint                   | Methode | Antwoord   | Beschrijving                                                                   |
| -------------------------- | ------- | ---------- | ------------------------------------------------------------------------------ |
| `/api/v2/sm/actual`        | GET     | JSON       | Actuele slimme-meterwaarden. Alleen velden met actuele data worden opgenomen.  |
| `/api/v2/sm/info`          | GET     | JSON       | Meterinformatie zoals identificatie, P1 versie en apparatuur-ID.               |
| `/api/v2/sm/fields`        | GET     | JSON       | Alle bekende slimme-metervelden. Velden zonder waarde kunnen leeg of `-` zijn. |
| `/api/v2/sm/telegram`      | GET     | text/plain | Ruw P1 telegram zoals ontvangen van de slimme meter.                           |
| `/api/v2/sm/fields/<veld>` | GET     | JSON       | Een specifiek veld, bijvoorbeeld `/api/v2/sm/fields/power_delivered`.          |

Speciale veldnamen:

| Endpoint                          | Methode | Antwoord | Beschrijving                                                               |
| --------------------------------- | ------- | -------- | -------------------------------------------------------------------------- |
| `/api/v2/sm/fields/gas_delivered` | GET     | JSON     | Gasstand met timestamp, indien beschikbaar.                                |
| `/api/v2/sm/fields/water`         | GET     | JSON     | Waterstand, indien een watersensor of watermeter via M-Bus beschikbaar is. |

## Historie

| Endpoint              | Methode | Antwoord | Beschrijving                         |
| --------------------- | ------- | -------- | ------------------------------------ |
| `/api/v2/hist/hours`  | GET     | JSON     | Uurhistorie.                         |
| `/api/v2/hist/days`   | GET     | JSON     | Daghistorie.                         |
| `/api/v2/hist/months` | GET     | JSON     | Maandhistorie.                       |
| `/api/v2/hist/months` | POST    | JSON     | Maandstanden aanpassen of aanvullen. |

{% hint style="info" %}
Historie is alleen beschikbaar wanneer lokaal opslaan van metergegevens is ingeschakeld.
{% endhint %}

## Dashboard

| Endpoint            | Methode | Antwoord | Beschrijving                                                                                                                                           |
| ------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `/api/v2/dash/live` | GET     | JSON     | Gecombineerde actuele waarden voor het dashboard, waaronder vermogen, stroom, spanning, energie, gas, water, productie en batterij indien beschikbaar. |
| `/api/v2/dash/hist` | GET     | JSON     | Een compacte momentopname van de recente daghistorie voor het dashboard.                                                                               |

Deze endpoints zijn bedoeld om de webinterface met minder losse API-verzoeken te laten werken. Voor eigen integraties blijven de specifieke slimme-meter- en historie-endpoints meestal duidelijker.

### WebSocket

De webinterface kan actuele updates ontvangen via:

```
ws://<ip-adres-of-hostname>:81/ws
```

De berichten bevatten een `source` en een `data` object. Mogelijke bronnen zijn:

* `time`;
* `dash_live`;
* `actual`;
* `dash_hist`.

De WebSocket gebruikt dezelfde Basic Auth gebruikersnaam en hetzelfde wachtwoord als de webinterface. Er kunnen maximaal drie clients tegelijk verbonden zijn.

## Apparaat

| Endpoint               | Methode  | Antwoord | Beschrijving                                                                  |
| ---------------------- | -------- | -------- | ----------------------------------------------------------------------------- |
| `/api/v2/dev/info`     | GET      | JSON     | Systeeminformatie van de dongle, zoals firmware, geheugen, netwerk en uptime. |
| `/api/v2/dev/time`     | GET      | JSON     | Datum en tijd zoals bekend bij de dongle.                                     |
| `/api/v2/dev/settings` | GET      | JSON     | Instellingen die via de webinterface zichtbaar of beheerbaar zijn.            |
| `/api/v2/dev/settings` | POST/PUT | JSON     | Een instelling wijzigen.                                                      |
| `/api/v2/stats`        | GET      | JSON     | Interne statistieken en statusinformatie.                                     |
| `/api/listfiles`       | GET      | JSON     | Bestanden op de dongle, zoals settings, log en historiebestanden.             |

Voor het wijzigen van een instelling wordt een JSON body gebruikt:

```json
{
  "name": "mqtt_interval",
  "value": 10
}
```

De beschikbare instellingen zijn afhankelijk van het type dongle en de ingeschakelde functies.

## Productie en batterij

| Endpoint       | Methode | Antwoord | Beschrijving                                          |
| -------------- | ------- | -------- | ----------------------------------------------------- |
| `/api/v2/gen`  | GET     | JSON     | Productiegegevens van gekoppelde omvormers.           |
| `/api/v2/accu` | GET     | JSON     | Batterijstatus, indien ondersteund en geconfigureerd. |

Wanneer er geen productie- of batterijgegevens beschikbaar zijn, geeft de API een JSON antwoord met `active:false`.

## Modbus

| Endpoint                 | Methode | Antwoord | Beschrijving                                                         |
| ------------------------ | ------- | -------- | -------------------------------------------------------------------- |
| `/api/v2/modbus/monitor` | GET     | JSON     | Laatste Modbus TCP/RTU requests, wanneer de monitor is ingeschakeld. |
| `/api/v2/modbus/monitor` | POST    | JSON     | Modbus monitor leegmaken.                                            |

De Modbus monitor is bedoeld voor diagnose: u ziet welke registers door een client worden uitgevraagd en of dat goed gaat.

## HomeWizard-compatible API

| Endpoint           | Methode | Antwoord   | Beschrijving                                               |
| ------------------ | ------- | ---------- | ---------------------------------------------------------- |
| `/api`             | GET     | JSON       | Root/info endpoint voor HomeWizard-compatible integraties. |
| `/api/v1/data`     | GET     | JSON       | HomeWizard-compatible P1 data.                             |
| `/api/v1/telegram` | GET     | text/plain | Ruw telegram via het v1 endpoint.                          |

Deze endpoints maken het mogelijk om de dongle via integraties te gebruiken die de HomeWizard P1 Meter API verwachten.

## EnergyID

| Endpoint        | Methode | Antwoord | Beschrijving                                          |
| --------------- | ------- | -------- | ----------------------------------------------------- |
| `/eid/getclaim` | GET     | JSON     | Claim/activatie voor EnergyID koppeling.              |
| `/eid/planner`  | GET     | JSON     | EnergyID stroomplannerinformatie, indien beschikbaar. |

## Praktische tips

* Gebruik `/api/v2/sm/actual` voor actuele meetwaarden in eigen scripts.
* Gebruik `/api/v2/hist/days` of `/api/v2/hist/months` voor rapportage over langere perioden.
* Gebruik MQTT wanneer u automatisch elke paar seconden data wilt ontvangen zonder polling.
* Gebruik `/api/v1/data` of de HomeWizard koppeling in Home Assistant als u zo weinig mogelijk zelf wilt configureren.