# Sites API

Mit der **Sites API** verwalten Sie Standorte vollständig per API — ohne die pvnode Web-App. Das
ist die programmatische Variante der unter [Standorte & Solarflächen](/de/v2/api/sites)
beschriebenen Konzepte.

:::note
Erfordert einen Plan mit Zugriff zur Sites-API. Ohne diesen Zugang antworten die schreibenden
Endpunkte mit **403**. Hobby-Nutzer verwalten Standorte über die
[pvnode Web-App](https://pvnode.com/sites). Ihre Freigaben siehen Sie auf der Seite über [Nutzung & Limits](https://pvnode.com/usage).
:::

## Endpunkte im Überblick

| Aktion | Endpunkt |
|---|---|
| Standort anlegen | `POST /v2/sites` |
| Alle Standorte auflisten | `GET /v2/sites` |
| Einen Standort abrufen | `GET /v2/sites/{site_id}` |
| Standort aktualisieren | `PATCH /v2/sites/{site_id}` |
| Standort löschen | `DELETE /v2/sites/{site_id}` |
| Gelöschten Standort wiederherstellen | `POST /v2/sites/{site_id}/restore` |

Die genauen Request-/Response-Schemata stehen in der [API-Referenz](/api).

## Anlegen

Pflicht sind `latitude` und `longitude`. `elevation`, `timezone` und der Geländehorizont werden
automatisch ermittelt. Ohne `strings` wird ein einzelner Standard-String angelegt.

```bash title="curl"
curl -X POST https://api.pvnode.com/v2/sites \
  -H "Authorization: Bearer IHR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Dach Süd",
    "latitude": 48.8566,
    "longitude": 2.3522,
    "strings": [{"slope": 30, "orientation": 180, "power_kw": 10}]
  }'
```

## Aktualisieren (PATCH)

Partielles Update — nur gesendete Felder ändern sich. Beachten Sie:

- **`strings` ersetzt das gesamte Array.** Jeder String hat eine stabile, vom Server vergebene `id` —
  **geben Sie sie mit zurück, um den String zu behalten** (samt seiner Daten, z. B. Messwerte);
  lassen Sie sie weg, wird der String entfernt; senden Sie einen String ohne `id`, wird ein neuer
  angelegt. Der Prognose-`strings`-Block führt diese `id` als `string_id` (plus positionsbasierten
  `string_index`); lesen Sie Standort und Prognose vom selben Zeitpunkt.
- **Eine Standortänderung** (Koordinaten) löst eine Neuermittlung von Höhe, Zeitzone und Horizont
  aus und macht den Prognose-Cache ungültig.
- Standortwechsel sind auf **1 pro 30 Tage** je Standort begrenzt (planunabhängig) → sonst **429**.

```bash title="curl"
curl -X PATCH https://api.pvnode.com/v2/sites/{site_id} \
  -H "Authorization: Bearer IHR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"config": {"modules": {"technology": "topcon"}}}'
```

## Löschen & Wiederherstellen

`DELETE` markiert den Standort als „pending deletion" (`deleted_at` gesetzt); die endgültige
Entfernung erfolgt **30 Tage später**. Innerhalb dieser Frist stellt `POST .../restore` den
Standort wieder her.

## Limits & Fehler

| Limit / Fehler          | Verhalten                                                                       |
|-------------------------|---------------------------------------------------------------------------------|
| Zugriff zur Sites-API   | Ohne Zugang → **403**.                                                          |
| Site-Limit              | Maximale Anzahl Standorte (kann `unmetered` sein) → **403** bei Überschreitung. |
| Strings pro Site        | Maximale Strings pro Standort → **422** bei Überschreitung.                     |
| Temporäre Sites         | Ohne diese Freigabe → **403**.                                                  |
| Standortwechsel-Quota   | 1 pro 30 Tage je Standort → **429**.                                            |
| Ungültige Zeitzone      | **422**.                                                                        |
| Standort nicht gefunden | **404**.                                                                        |

Die vollständige Referenz aller Felder und Fehlercodes steht in der [API-Referenz](/api).