# 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 %}

## 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.smart-stuff.nl/dsmr-api/geavanceerd/api-overzicht.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.