Externe API-Dokumentation

Die Integration auf Basis eines API-Schlüssels gewährt Ihnen Zugriff auf Kalender, Projekte, Kunden und Komponenten. Dadurch erhalten Sie die Flexibilität, Ihre Systeme zu integrieren und Prozesse zu automatisieren.

Inhaltsverzeichnis

1. Authentifizierung
2. Paginierung
3. Kalender-API
4. Projekte-API
5. Kunden-API
6. Komponenten-API
7. Datenkonventionen
8. Filterverhalten
9. Berechtigungsmodell
10. Fehlerbehandlung
11. Integrationsmuster
12. Stabilität & Versionierung

1. Authentifizierung

Alle Anfragen müssen im Request-Header einen API-Schlüssel enthalten.

Authorization: Api-Key <raw_api_key>

Hinweise: - API-Schlüssel werden von Unternehmensinhabern und Administratoren erstellt und verwaltet. - Jeder Schlüssel ist auf bestimmte Ressourcenberechtigungen beschränkt. - Alle Anfragen sind automatisch auf das dem API-Schlüssel zugeordnete Unternehmen beschränkt.

Authentifizierungsfehler

2. Paginierung

Listen-Endpunkte (Kalender, Projekte, Kunden) verwenden eine limit/offset-Paginierung.

Parameter

Antwortstruktur

{
  "count": 123,
  "next": null,
  "previous": null,
  "results": []
}

Wenn next null ist, haben Sie die letzte Seite erreicht.

3. Kalender-API

Stellt geplante Ereignisse wie Besprechungen, Anrufe und Installationstermine dar. Schreibgeschützt.

Endpunkte

GET https://api-production.easysolar-app.com/integrations/calendar/
GET https://api-production.easysolar-app.com/integrations/calendar/{id}/

Erforderliche Berechtigung: calendar_read

Beispielantwort

{
  "id": "7d0f4d55-3b66-4c71-a86d-2b0ef2fca6d5",
  "category": "meeting",
  "subject": "Erstbesichtigung vor Ort",
  "description": "Installationsanforderungen und Dachinspektion besprechen.",
  "client": {
    "id": "4ab8e7cb-0a27-48f1-a0f6-6d6ecf5d8c6a",
    "name": "Solar GmbH",
    "address": "Hauptstraße 10, Warschau",
    "phone": "+48123456789",
    "is_open": true
  },
  "participants": [
    {
      "first_name": "John",
      "last_name": "Smith",
      "email": "john.smith@example.com"
    }
  ],
  "start_at": "2026-06-15T09:00:00Z",
  "end_at": "2026-06-15T10:00:00Z",
  "full_day": false,
  "created_at": "2026-06-01T12:30:45Z"
}

Feldreferenz

Kategorienwerte

Verschachtelte Objekte

Kundenobjekt:

Teilnehmerobjekt:

Filter

Beispiel:

GET https://api-production.easysolar-app.com/integrations/calendar/?start_at_after=2026-01-01T00:00:00Z&category=meeting&category=call
Authorization: Api-Key <key>

4. Projekte-API

Stellt kundenbezogene Projektdatensätze dar (z. B. Photovoltaikanlagen). Schreibgeschützt.

Endpunkte

GET https://api-production.easysolar-app.com/integrations/projects/
GET https://api-production.easysolar-app.com/integrations/projects/{id}/

Erforderliche Berechtigung: projects_read

Beispielantwort

{
  "id": "d8e22cb9-1d88-4a3d-a3fd-f954d1f23d59",
  "name": "PV-Anlage - Büro Warschau",
  "address": "Aleje Jerozolimskie 120, Warschau",
  "latitude": 52.2297,
  "longitude": 21.0122,
  "client": {
    "id": "4ab8e7cb-0a27-48f1-a0f6-6d6ecf5d8c6a",
    "name": "Solar GmbH",
    "address": "Hauptstraße 10, Warschau",
    "phone": "+48123456789",
    "is_open": true
  },
  "status": {
    "name": "In Bearbeitung",
    "order": 2
  },
  "currency": {
    "code": "PLN",
    "name": "Polnischer Złoty"
  },
  "total_price": "42500.00",
  "payback_period": 8,
  "created": "2026-05-01T09:00:00Z",
  "updated": "2026-06-01T15:30:00Z"
}

Feldreferenz

total_price wird als Dezimal-String zurückgegeben, um die Genauigkeit zu erhalten. payback_period ist null, wenn sie noch nicht berechnet wurde. latitude/longitude sind null, wenn kein Standort gesetzt ist.

Verschachtelte Objekte

Statusobjekt:

Währungsobjekt:

Filter

Beispiel:

GET https://api-production.easysolar-app.com/integrations/projects/?client=<id>&name=solar
Authorization: Api-Key <key>

5. Kunden-API

Stellt Kundenentitäten dar. Unterstützt Lese- und Schreiboperationen.

Endpunkte

GET    https://api-production.easysolar-app.com/integrations/clients/
POST   https://api-production.easysolar-app.com/integrations/clients/
GET    https://api-production.easysolar-app.com/integrations/clients/{id}/
PATCH  https://api-production.easysolar-app.com/integrations/clients/{id}/

Erforderliche Berechtigungen: clients_read (Lesen), clients_write (Schreiben)

Beispielantwort

{
  "id": "4ab8e7cb-0a27-48f1-a0f6-6d6ecf5d8c6a",
  "name": "Solar GmbH",
  "description": "Gewerbekunde mit Interesse an einer PV-Dachanlage.",
  "address": "Hauptstraße 10, Warschau",
  "latitude": 52.2297,
  "longitude": 21.0122,
  "phone": "+48123456789",
  "is_open": true,
  "created": "2026-05-01T10:15:00Z",
  "updated": "2026-06-01T08:45:30Z"
}

Feldreferenz

Kunde anlegen

POST https://api-production.easysolar-app.com/integrations/clients/

{
  "name": "Kundenname",
  "description": "Gewerbekunde",
  "address": "Adresse",
  "phone": "+48123456789",
  "latitude": 52.2297,
  "longitude": 21.0122
}

Kunde aktualisieren

PATCH https://api-production.easysolar-app.com/integrations/clients/{id}/

Fügen Sie nur die Felder ein, die Sie aktualisieren möchten:

{
  "address": "Neue Adresse 15, Warschau",
  "phone": "+48987654321"
}

Koordinatenregeln

• latitude und longitude müssen immer zusammen angegeben werden.
• Wenn nur eine Koordinate angegeben wird, führt dies zu einem Validierungsfehler.
• Wenn kein Standort gesetzt ist, werden beide Felder als null zurückgegeben.

Filter

6. Komponenten-API

Erstellt Komponenten zur Verwendung in Projekten. Nur schreibend.

Endpunkt

POST https://api-production.easysolar-app.com/integrations/components/

Erforderliche Berechtigung: components_write

Komponententypen

Es werden drei Komponententypen unterstützt: panel, inverter und other.

PV-Modul

{
  "type": "panel",
  "manufacturer_name": "Longi",
  "name": "LR5-54HPH",
  "net_unit_price": "120.00",
  "nominal_power": "430.000",
  "length": "1.7220",
  "width": "1.1340",
  "weight": "21.500",
  "efficiency": "0.2100000",
  "short_circuit_current": "13.52000",
  "open_circuit_voltage": "37.85000",
  "current_temperature_coefficient": "0.045000",
  "voltage_temperature_coefficient": "-0.280000",
  "power_temperature_coefficient": "-0.350000"
}

Wechselrichter

{
  "type": "inverter",
  "manufacturer_name": "SMA",
  "name": "Sunny Tripower 5.0",
  "net_unit_price": "900.00",
  "nominal_power": "5000.000",
  "number_of_dc_inputs": 2
}

Sonstiges

{
  "type": "other",
  "name": "Montagesystem",
  "unit": "pcs",
  "net_unit_price": "50.00"
}

Antwort

{
  "id": "uuid",
  "type": "panel | inverter | other",
  "name": "string"
}

Hinweise

• Hersteller werden automatisch angelegt, wenn sie noch nicht existieren.
• Die Eindeutigkeit der Hersteller gilt pro Unternehmen.
• Alle modulspezifischen Felder werden vor der Erstellung validiert.

7. Datenkonventionen

IDs

Alle Ressourcenkennungen sind UUID-Strings, stabil und unternehmensweit eindeutig:

"id": "550e8400-e29b-41d4-a716-446655440000"

Zeitstempel

Alle Datums-/Zeitfelder werden im ISO-8601-Format und stets in UTC zurückgegeben:

"created": "2026-06-09T12:34:56Z"

Geokoordinaten

Koordinaten gelten für Kunden und Projekte. Sie werden als geografischer Punkt gespeichert und als separate Felder zurückgegeben:

"latitude": 52.2297,
"longitude": 21.0122

Umgang mit null-Werten

Nicht gesetzte Felder werden als null zurückgegeben — sie werden niemals aus der Antwort weggelassen.

8. Filterverhalten

Allgemeine Regeln

• Alle Filter sind optional, sofern nicht anders angegeben.
• Mehrere Filter werden mit AND-Logik kombiniert.
• Mehrfachauswahl-Filterwerte (z. B. category) verwenden intern ODER-Logik.
• Ungültige Filterwerte liefern je nach Feldtyp leere Ergebnisse oder einen Validierungsfehler.

Datumsbereichsfilter

In allen Endpunkten verfügbar:

Textsuchfilter

Teilweise Übereinstimmung ohne Beachtung der Groß-/Kleinschreibung für name und phone:

?name=solar

Treffer: "Solar GmbH", "Mein Solarprojekt", usw.

9. Berechtigungsmodell

Die Berechtigungen für API-Schlüssel werden je Ressource separat konfiguriert:

10. Fehlerbehandlung

Fehlerformat

Allgemeiner Fehler:

{
  "detail": "Fehlermeldung"
}

Validierungsfehler auf Feldebene:

{
  "field_name": ["Fehlermeldung"]
}

Fehlerreferenz

Integrations-Checkliste

Wenn Fehler auftreten, überprüfen Sie:

1. Der API-Schlüssel verfügt über die richtigen Ressourcenberechtigungen.
2. Das Unternehmenskonto ist aktiv.
3. Alle Filterwerte (IDs usw.) gehören zum selben Unternehmenskontext.

11. Integrationsmuster

Synchronisationsstrategie

Empfohlene Vorgehensweise für die Datensynchronisierung:

1. Rufen Sie den Listen-Endpunkt ab (mit Paginierung).
2. Speichern Sie die id als externe Referenz.
3. Verwenden Sie das Feld updated für inkrementelle Synchronisierungen.

Umgang mit Pagination

Blättern Sie durch die Seiten, indem Sie den offset erhöhen, bis next null ist:

GET https://api-production.easysolar-app.com/integrations/clients/?limit=100&offset=0
GET https://api-production.easysolar-app.com/integrations/clients/?limit=100&offset=100

Inkrementelle Synchronisierung

Verwenden Sie Datumsfilter, um nur Datensätze abzurufen, die sich seit Ihrer letzten Synchronisierung geändert haben:

GET https://api-production.easysolar-app.com/integrations/projects/?updated_after=2026-01-01T00:00:00Z

Best Practices beim Filtern

• Verwenden Sie bei Synchronisierungen mit hohem Datenvolumen bevorzugt ID-basierte Filter (client, status) statt Textsuchen.
• Kombinieren Sie mehrere Filter, um die Ergebnismenge zu reduzieren.
• Vermeiden Sie breit angelegte Textsuchen in großen Datensätzen.

12. Stabilität & Versionierung

Stabile Zusagen

Folgendes ändert sich nicht ohne eine versionierte Migration:

• Endpunkt-URLs
• Feldnamen
• UUID-Format
• Paginierungsstruktur
• Authentifizierungsschema

Kann sich ändern (nicht brechend)

• Optionale Filter (neue Filter können hinzugefügt werden)
• Antwortanreicherung (neue Felder können hinzugefügt werden)

Versionierungsrichtlinie

In der URL ist derzeit keine explizite Version sichtbar. Inkompatible Änderungen führen zu einem neuen Endpunkt-Namespace:

https://api-production.easysolar-app.com/integrations/v2/...

Ergänzende Änderungen gelten als nicht brechend und können ohne Versionssprung bereitgestellt werden.

Ende der Dokumentation