API-Referenz

Übersicht

Das SolarLog-System bietet drei separate API-Services:

Backend API (Port 3000): Hauptanwendung, Datenbank-Zugriff
Scanner API (Port 3001): Netzwerk-Scanner für Geräte-Erkennung
Frontend API (Port 3002): React-Anwendung (UI)

Backend API (Port 3000)

Base URL: http://localhost:3000

Inverter Management

GET /api/inverters

Listet alle Wechselrichter auf.

Response:

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Garage Wechselrichter",
      "manufacturer": "SMA",
      "model": "Sunny Boy 5.0",
      "ip_address": "192.168.1.100",
      "port": 502,
      "location": "Garage Dach",
      "enabled": 1,
      "created_at": "2025-01-15T10:30:00.000Z",
      "updated_at": "2025-01-15T10:30:00.000Z",
      "last_successful_poll": null
    }
  ]
}

GET /api/inverters/:id

Ruft einen spezifischen Wechselrichter ab.

Parameter: - id (number): Wechselrichter-ID

Response:

href="#__codelineno-1-1">{ "success": true, "data": { "id": 1, "name": "Garage Wechselrichter", "manufacturer": "SMA", "model": "Sunny Boy 5.0", "ip_address": "192.168.1.100", "port": 502, "location": "Garage Dach", "notes": "Installation 2024", "username": "user", "password": "********", "protocol": "modbus_tcp", "modbus_unit_id": 1, "poll_interval": 300, "enabled": 1, "created_at": "2025-01-15T10:30:00.000Z", "updated_at": "2025-01-15T10:30:00.000Z", "last_successful_poll": null } }

POST /api/inverters

Erstellt einen neuen Wechselrichter.

Request Body:

{
  "name": "Neuer Wechselrichter",
  "manufacturer": "KOSTAL",
  "model": "PIKO 10",
  "ip_address": "192.168.1.101",
  "port": 502,
  "location": "Carport",
  "notes": "Test-Wechselrichter",
  "username": "",
  "password": "",
  "protocol": "modbus_tcp",
  "modbus_unit_id": 1,
  "poll_interval": 300,
  "enabled": 1
}

Response:

{
  "success": true,
  "data": {
    "id": 2,
    "name": "Neuer Wechselrichter",
    // ... alle Felder
  }
}

PUT /api/inverters/:id

Aktualisiert einen Wechselrichter.

Parameter: - id (number): Wechselrichter-ID

Request Body:

{
  "name": "Aktualisierter Name",
  "enabled": 0
}

Response:

{
  "success": true,
  "message": "Inverter updated",
  "data": {
    "id": 1,
    "name": "Aktualisierter Name",
    // ... alle Felder
  }
}

DELETE /api/inverters/:id

Löscht einen Wechselrichter.

Parameter: - id (number): Wechselrichter-ID

Response:

{
  "success": true,
  "message": "Inverter deleted"
}

GET /api/inverters/:id/data

Ruft Produktionsdaten eines Wechselrichters ab.

Parameter: - id (number): Wechselrichter-ID - start (string, optional): Start-Datum (ISO 8601) - end (string, optional): End-Datum (ISO 8601) - limit (number, optional): Maximale Anzahl Ergebnisse

Response:

{
  "success": true,
  "data": [
    {
      "id": 1,
      "inverter_id": 1,
      "timestamp": "2025-01-15T12:00:00.000Z",
      "current_power": 4500,
      "daily_energy": 15.5,
      "total_energy": 12500,
      "voltage": 230,
      "current": 19.5,
      "frequency": 50,
      "temperature": 45,
      "status": "online"
    }
  ]
}

GET /api/inverters/:id/errors

Ruft Fehlerprotokoll eines Wechselrichters ab.

Parameter: - id (number): Wechselrichter-ID - resolved (boolean, optional): Nur gelöste/ungelöste Fehler

Response:

{
  "success": true,
  "data": [
    {
      "id": 1,
      "inverter_id": 1,
      "timestamp": "2025-01-15T08:00:00.000Z",
      "error_type": "connection",
      "error_message": "Connection timeout",
      "error_details": "{\"timeout\": 5000}",
      "resolved": 0
    }
  ]
}

POST /api/inverters/:id/test

Testet die Verbindung zu einem Wechselrichter.

Parameter: - id (number): Wechselrichter-ID

Response:

{
  "success": true,
  "message": "Connection test successful",
  "data": {
    "latency": 50,
    "status": "online"
  }
}

Scan Management

GET /api/scan/results

Listet alle Scan-Ergebnisse auf.

Parameter: - added (boolean, optional): Nur hinzugefügte/nicht hinzugefügte Geräte

Response:

{
  "success": true,
  "data": [
    {
      "id": 1,
      "ip_address": "192.168.1.50",
      "manufacturer": "SMA",
      "model": "Web Interface",
      "ports": "[80,502]",
      "device_info": null,
      "protocol": "http",
      "scan_date": "2025-01-15T10:00:00.000Z",
      "added_to_inverters": 0
    }
  ]
}

POST /api/scan/add-inverter

Wandelt ein Scan-Ergebnis in einen Wechselrichter um.

Request Body:

{
  "scan_result_id": 1,
  "name": "Neuer Wechselrichter",
  "location": "Dach",
  "notes": "Aus Scan hinzugefügt"
}

Response:

{
  "success": true,
  "message": "Inverter added from scan result",
  "data": {
    "id": 3,
    "name": "Neuer Wechselrichter",
    // ... alle Felder
  }
}

Legacy Endpoints (für Abwärtskompatibilität)

GET /api/v1/now

Aktuelle Leistung (simuliert).

Response:

{
  "current_power": 3500,
  "timestamp": "2025-01-15T12:30:00.000Z"
}

GET /api/v1/day

Tagesproduktion (simuliert).

Response:

{
  "daily_energy": 25.5,
  "date": "2025-01-15"
}

Scanner API (Port 3001)

Base URL: http://localhost:3001

GET /

API-Übersicht.

Response:

{
  "status": "online",
  "version": "1.0.0",
  "endpoints": {
    "scan": "/scan",
    "scanStatus": "/scan/status",
    "deviceInfo": "/device/:ip"
  }
}

POST /scan

Startet einen neuen Netzwerk-Scan.

Response:

{
  "success": true,
  "message": "Scan started",
  "lastScan": "2025-01-15T10:00:00.000Z"
}

Status Code: - 200: Scan gestartet - 409: Scan läuft bereits

GET /scan

Gibt den aktuellen Scan-Status zurück.

Response:

{
  "success": true,
  "scanning": false,
  "lastScan": "2025-01-15T10:00:00.000Z",
  "devices": [
    {
      "ip": "192.168.1.50",
      "manufacturer": "SMA",
      "type": "Web Interface",
      "ports": [80, 502]
    }
  ]
}

GET /device/:ip

Ruft detaillierte Informationen zu einem Gerät ab.

Parameter: - ip (string): IP-Adresse

Response:

{
  "success": true,
  "device": {
    "ip": "192.168.1.50",
    "manufacturer": "SMA",
    "type": "Web Interface",
    "ports": [80, 502]
  },
  "source": "cached"
}

Fehlerbehandlung

Alle APIs verwenden einheitliche Fehlerformate:

Error Response:

{
  "success": false,
  "error": "Error message here",
  "details": {
    // Zusätzliche Details (optional)
  }
}

HTTP Status Codes: - 200: Erfolg - 400: Ungültige Anfrage - 404: Nicht gefunden - 409: Konflikt (z.B. Scan läuft bereits) - 500: Serverfehler

Rate Limiting

Derzeit keine Rate-Limits implementiert. Für Produktionsumgebungen sollte dies hinzugefügt werden.

Authentifizierung

Derzeit keine Authentifizierung implementiert. Für Produktionsumgebungen sollte JWT oder ähnliches verwendet werden.

CORS

CORS ist aktiviert für: - http://localhost:3000 - http://localhost:3001 - http://localhost:3002

Erlaubte Methoden: GET, POST, PUT, DELETE

WebSocket Support

Aktuell nicht implementiert. Für Echtzeit-Updates könnte Socket.io hinzugefügt werden.