# Energie Schnee - Anleitung für Agenten und Chatbots Diese Seite rechnet Photovoltaikanlagen. Über die Schnittstelle bekommst du zu einer Adresse alle Dachflächen des Anwesens mit Modulmenge, Leistung, Ausrichtung, Neigung und Verschattung. - Basisadresse: `https://energie.schnee.co.at/api/v1` - Ausführliche Doku: - Maschinenlesbar: - Format: JSON, UTF-8 - Abgedeckt: Österreich, Deutschland, Schweiz. Die Schnittstelle rechnet nicht nur, sie **legt ein Projekt an**. Je Adresse und Konto gibt es genau eines. Ein zweites wird mit 409 abgewiesen, und das ist kein Fehler, sondern die Regel. *This file is German. The API returns German texts but stable English-style error codes in snake_case. Field names are ASCII without umlauts.* ## Rate nichts, ruf es ab Alles hier ist ohne Zugang abrufbar. Wenn du unsicher bist, hol dir die Wahrheit, statt sie zu erfinden: ```bash curl -s https://energie.schnee.co.at/AGENT.md # diese Anleitung curl -s https://energie.schnee.co.at/api/v1/lastprofile # gültige Lastprofile curl -s https://energie.schnee.co.at/api/v1/openapi.json # alle Endpunkte samt Feldnamen ``` Wenn dein Werkzeug an einer dieser Adressen scheitert, etwa mit 403 aus deiner eigenen Umgebung, nimm das andere Werkzeug. Dieselbe Anleitung steht als gewöhnliche Webseite unter , und die kommt auch durch, wenn eine Sandbox keine Dateien laden darf. Gib nicht auf, bevor du beide Wege probiert hast. Erfinde keine Feldnamen, keine Parameter und keine Adressen. Was du brauchst, steht in diesen drei Abrufen. Es gibt daneben Endpunkte, die du nicht verwenden kannst, weil sie eine angemeldete Sitzung im Browser verlangen und keinen Schlüssel: `/api/v1/schluessel` samt Widerruf, `/api/v1/nutzung` und `/api/v1/meine-projekte`. Sie stehen deshalb auch nicht in `openapi.json`. ## Schritt 0: Zugang Ohne Schlüssel geht nur Lesen. So kommt dein Benutzer an einen: 1. **Konto anlegen.** Der Testzugang für die Schnittstelle liegt unter . Er schaltet von den Modulen der Anwendung allein die Schnittstelle frei und erlaubt **eine Adresse**, also ein Projekt. Gezählt wird jedes Projekt des Kontos, auch eines, das der Benutzer in der Anwendung selbst anlegt. Das Konto entsteht sofort, sobald der Benutzer die Bestätigungsmail angeklickt hat, und **läuft nach dreißig Tagen ab**. Du kannst das nicht für ihn erledigen, sag es ihm. Wer die ganze Anwendung testen will, nimmt auf der Startseite den Knopf **Kostenlos testen**, dort schaltet der Betreiber von Hand frei. 2. **Anmelden** unter . 3. **Modul Schnittstelle öffnen**: . Dort auf **Schlüssel anlegen**, einen Namen vergeben. Der Schlüssel erscheint **genau einmal** und beginnt mit `es_`. Er lässt sich danach nicht wieder anzeigen, nur widerrufen. 4. Der Benutzer gibt dir diesen Schlüssel. Sag ihm dazu, dass er ihn nach dem Gespräch im selben Modul widerrufen soll, wenn der Chatverlauf irgendwo gespeichert wird. Erst wenn du einen Schlüssel hast, geht es weiter. Behaupte nie, du hättest etwas gerechnet, wenn kein Schlüssel vorlag. ## Was du vom Benutzer brauchst Vier Angaben: 1. einen **Projektnamen**, unter dem das Projekt angelegt wird 2. die **Adresse** mit Straße, Hausnummer, Postleitzahl und Ort 3. den **Jahresverbrauch** in Kilowattstunden 4. das **Standardlastprofil** aus der Tabelle unten, im Zweifel `H0` Frage nach dem, was fehlt. Rate nichts, besonders keinen Verbrauch. ## Der kurze Weg, wenn du nur Adressen abrufen kannst Viele Chatbots können ausschließlich eine Adresse aufrufen: kein POST, keine eigene Kopfzeile. Dafür gibt es einen einzigen Aufruf, der alles erledigt. ``` https://energie.schnee.co.at/api/v1/analyse?schluessel=es_...&name=Testprojekt&adresse=Mösl%205,%204841%20Ungenach&jahresverbrauch_kwh=6000&lastprofil=H0 ``` Beim ersten Aufruf legt er das Projekt an und startet die Analyse, Antwort 202 mit `zustand: läuft`. Ruf **dieselbe Adresse** nach der Zahl von Sekunden aus dem Feld `erneut_in_s` noch einmal auf, dann steht das Ergebnis darin, mit `zustand: fertig`. Es wird kein zweites Projekt angelegt, egal wie oft du aufrufst. Auf diesem Weg zählt **jede** Abfrage gegen die Ratengrenze von 40 Aufrufen je Stunde, auch das Nachfragen. Frage deshalb nicht schneller als alle zehn Sekunden. Dieser Weg ist die **Notlösung** für Werkzeuge, die nicht anders können. Der Schlüssel steht dabei in der Adresse und damit im Zugriffsprotokoll jedes Rechners dazwischen. Prüfe zuerst, ob du eine Kopfzeile setzen kannst, viele Werkzeuge können mehr als sie zunächst annehmen. Wenn ja, nimm den regulären Weg darunter. ## Der reguläre Weg Der Lauf dauert zehn bis neunzig Sekunden, deshalb zwei Schritte. **Schritt 1: anlegen** ```bash curl -X POST https://energie.schnee.co.at/api/v1/projekte \ -H "X-API-Key: es_..." -H "Content-Type: application/json" \ -d '{"name":"Haus Muster","adresse":"Musterweg 1, 4840 Vöcklabruck", "jahresverbrauch_kwh":4500,"lastprofil":"H0"}' ``` Antwort 202 mit `projekt_id` und `analyse_url`. Die Kopfzeile `Content-Type: application/json` ist Pflicht, sonst kommt 415. **Schritt 2: abholen** `GET` auf die `analyse_url` aus Schritt 1, bis `zustand` auf `fertig` steht. Solange kommt 202 mit `schritt`, `fertig`, `gesamt` und `wartet`. ```bash curl -s https://energie.schnee.co.at/api/v1/projekte/42/dachanalyse \ -H "X-API-Key: es_..." ``` **Wie lange du zwischen zwei Abfragen wartest, steht in der Antwort**, im Feld `erneut_in_s` und in der Kopfzeile `Retry-After`. Halte dich daran. **`wartet: true` heißt: die Rechnung hat noch gar nicht begonnen.** Es rechnen gerade zwei andere Analysen, deine ist vorgemerkt. Jede Abfrage ist zugleich der Versuch, den frei gewordenen Platz zu bekommen. Diese Wartezeit zählt **nicht** gegen die Frist im nächsten Absatz. **Höre 150 Sekunden nach dem Beginn der Rechnung auf zu fragen**, also ab dem ersten Mal, dass `wartet` auf `false` steht. Ein normaler Lauf braucht zehn bis neunzig Sekunden. Dauert es länger, hängt er. Dann stößt du ihn genau einmal neu an und wartest wieder bis 150 Sekunden. Kommt danach immer noch nichts, sag dem Benutzer, dass die Analyse nicht durchläuft, und nenne ihm die Projektkennung. Frage nicht endlos weiter. Sag dem Benutzer beim Warten einmal, dass es bis zu anderthalb Minuten dauert. Er hält das für einen Hänger, wenn du schweigst. Die fertige Antwort enthält `flaechen[]`, `zusammenfassung`, `wirtschaftlichkeit`, `medien` und `quellen`. **Wenn der Lauf scheitert:** Ein zweites Projekt an derselben Adresse geht nicht, das Projekt steht ja schon. Stoße den Lauf stattdessen erneut an, mit **POST auf dieselbe `analyse_url`**, die du zum Abholen verwendest: ```bash curl -X POST https://energie.schnee.co.at/api/v1/projekte/42/dachanalyse \ -H "X-API-Key: es_..." ``` **Alle eigenen Projekte** liefert `GET /api/v1/projekte`, jeweils mit `analyse_url` und dem Link in die Wirtschaftlichkeitsrechnung. Die Liste ist seitenweise, die nächste Seite steht im Feld `weiter` oder ist `null`. ## Bilder und 3D-Modell Zahlen allein überzeugen niemanden. Zu jedem gerechneten Projekt gibt es Bilder, und der Weg dorthin steht in der Antwort selbst: `medien.uebersicht_url` sagt, was vorliegt, und je Fläche steht `bild_url` daneben. ```bash curl -s https://energie.schnee.co.at/api/v1/projekte/42/medien -H "X-API-Key: es_..." ``` - **Belegungsbild je Fläche**: `/api/v1/projekte/42/bilder/flaeche/3`. Das Luftbild der Fläche mit dem eingezeichneten Modulraster, dazu Nordpfeil und Maßstab. Gezeichnet ist, was geometrisch daraufpasst, also `module_moeglich`, nicht die kleinere Auslegung `module_empfohlen`. Die Nummer ist dieselbe wie das Feld `id` der Fläche in der Dachanalyse. - **Übersichtsbild**: `/api/v1/projekte/42/bilder/uebersicht`, alle belegten Flächen in einem Bild. - Beide kommen als **SVG**. Kann dein Werkzeug kein SVG anzeigen, hänge `?format=png` an. Die Bildbreite steuert `?breite=` zwischen 200 und 2000 Pixeln. - **Orthofoto**: `/api/v1/projekte/42/orthofoto`, das gespeicherte Luftbild des Anwesens. - **3D-Modell**: `/api/v1/projekte/42/modell`, eine GLB-Datei zum Herunterladen. **Orthofoto und 3D-Modell entstehen erst, wenn das Projekt in der Anwendung geöffnet und gespeichert wurde.** Zu einem Projekt, das nur über die Schnittstelle gerechnet wurde, gibt es keines, und die Abfrage antwortet mit 404 und dem Grund. Erfinde dann keine Erklärung, sondern sag dem Benutzer, dass er das Projekt einmal in der Anwendung öffnen muss. **Belegungsbilder gibt es zu jeder gerechneten Fläche mit Modulen**, aber nicht in jeder Lage: Ohne gespeicherte Dachanalyse kommt 404 `analyse_fehlt`, ohne eine einzige belegte Fläche 404 `keine_belegten_flaechen`. Beides sagt dir, was zu tun ist. Rechne nicht auf Verdacht neu. Für Bilder gilt eine eigene Ratengrenze von 120 Abrufen je Stunde und Konto. ## Was du dem Benutzer sagst - Die **empfohlene Anlage** steht in `zusammenfassung.auslegung_kwp` und `zusammenfassung.auslegung_module`. Sie folgt dem gesendeten Jahresverbrauch. - Das **Dachpotenzial insgesamt** steht in `zusammenfassung.leistung_moeglich_kwp`. Das ist, was geometrisch daraufpasst, nicht was sinnvoll ist. Dasselbe Feld gibt es auch je Fläche, achte auf den Pfad. - **Welche Flächen** sinnvoll sind, erkennst du an `flaechen[].empfohlen`. - **Gib immer den Link aus** `wirtschaftlichkeit.url`. Dort rechnet der Benutzer seine Wirtschaftlichkeit fertig, mit Speicher, Auto und Tarifen. Der Link verlangt die Anmeldung des Mandanten, dem der Schlüssel gehört. - Verschattung: `flaechen[].verschattung.verlust_mittel_pct` ist der mittlere Verlust über fünf Messpunkte, Einzelwerte stehen in `flaechen[].verschattung.messpunkte`. **Das ganze Feld `verschattung` kann `null` sein**, wenn keine Messpunkte vorliegen. Erfinde dann keine Zahl, sag, dass keine Verschattungsdaten vorliegen. - **Ziehe die Verschattung nicht noch einmal ab.** `ertrag_kwh_pro_kwp` enthält sie bereits, das Feld `ertrag_enthaelt_verschattung` sagt es dir. - Zwei Flächenangaben, nicht verwechseln: `grundflaeche_m2` ist die Fläche in der Draufsicht, `dachflaeche_m2` die geneigte, also die echte Dachfläche. ## Standardlastprofile | Kennung | Bezeichnung | |---|---| | `H0` | Haushalt (Vorgabe) | | `L0` | Landwirtschaft allgemein | | `L1` | Landwirtschaft mit Milchwirtschaft | | `L2` | Sonstige Landwirtschaft | | `G0` | Gewerbe allgemein | | `G1` | Werktags 8-18 Uhr | | `G2` | Abends mit Ladenbeleuchtung | | `G3` | Durchlaufend | | `G4` | Laden/Friseur | | `G5` | Bäckerei mit Backstube | | `G6` | Wochenendbetrieb | Immer aktuell unter . Das Profil wird geprüft und zum Projekt gespeichert. Gerechnet wird damit heute in der Anwendung. Für die Flächenauswahl der Schnittstelle zählt vorerst allein der Jahresverbrauch. ## Fehler Jeder Fehler trägt `fehler.code` zum Verzweigen, `fehler.meldung` für den Menschen und `fehler.tu` mit dem nächsten Schritt. Das gilt auch für 404, 405, 415, 429 und 500. | Status | Code | Was du tust | |---|---|---| | 401 | `schluessel_fehlt`, `schluessel_ungueltig` | Den Benutzer bitten, unter einen Schlüssel anzulegen. | | 400 | `lastprofil_unbekannt` | Eine Kennung aus `fehler.erlaubt` verwenden. | | 400 | `verbrauch_fehlt` | Nach dem Jahresverbrauch fragen. Zahl größer null, höchstens hundert Millionen. | | 400 | `adresse_zu_lang` | Nur Straße, Hausnummer, Postleitzahl und Ort senden, höchstens 200 Zeichen. | | 404 | `adresse_nicht_gefunden` | Nach vollständiger Adresse fragen. Nur AT, DE, CH. | | 404 | `adresse_nicht_eindeutig` | Es wurde nichts gefunden, das zu Ort und Postleitzahl passt. Die Fundstellen stehen in `fehler.gefunden`. **Nimm keine davon auf gut Glück**, frage den Benutzer, welche gemeint ist, und sende deren Schreibweise erneut. | | 404 | `analyse_fehlt` | Das Ergebnis ist verfallen, Ergebnisse werden **einen Tag** vorgehalten. **Lege kein neues Projekt an**, das scheitert an der Dublettenregel. Stoße stattdessen `POST` auf die `analyse_url` aus `fehler.analyse_url` an. | | 403 | `testkontingent_erschoepft` | Der Testzugang erlaubt eine Adresse, sie ist verbraucht. **Lege kein weiteres Projekt an.** Rechne mit dem bestehenden weiter, `GET /api/v1/projekte` listet es samt `analyse_url`. Für mehr Adressen braucht der Benutzer ein reguläres Konto, office@schnee.co.at. | | 404 | `modell_fehlt`, `orthofoto_fehlt` | Diese Datei entsteht erst beim Speichern in der Anwendung. Sag das dem Benutzer, statt es zu erklären. Die Belegungsbilder gibt es trotzdem. | | 404 | `projekt_unbekannt` | Zu dieser Kennung gibt es kein Projekt deines Schlüssels. `GET /api/v1/projekte` listet die eigenen. | | 404 | `keine_belegten_flaechen` | Zu diesem Projekt ist keine Fläche mit Modulen gespeichert, es gibt also kein Bild. Frage zuerst die Dachanalyse ab. | | 404 | `flaeche_unbekannt` | Diese Flächennummer gibt es nicht. Die vorhandenen stehen in `fehler.vorhanden`, ausführlich in `/medien`. | | 404 | `bild_nicht_zeichenbar` | Zu dieser Fläche ließ sich kein Bild zeichnen. Frage `/medien` ab, dort steht, welche Bilder es gibt. | | 500 | `format_nicht_moeglich` | Das PNG ließ sich nicht erzeugen. Rufe dieselbe Adresse ohne `format=png` auf, das SVG kommt. Warten hilft nicht. | | 500 | `analyse_unlesbar` | Die gespeicherte Analyse ist beschädigt. **Stoße keinen neuen Lauf an**, er würde sie überschreiben. Nenne dem Benutzer die Projektkennung. | | 409 | `projekt_besteht_bereits` | **Kein zweites Projekt anlegen.** An einer Adresse ist je Konto nur ein Projekt möglich. Nimm `bestehendes_projekt.analyse_url` für die Zahlen und gib `bestehendes_projekt.url` als Link aus. | | 415 | `inhaltstyp_falsch` | Kopfzeile `Content-Type: application/json` setzen. | | 429 | `ratengrenze` | Warten, die Dauer steht in `fehler.tu` und in der Kopfzeile `Retry-After`. Grenzen siehe unten. | | 503 | `dienst_ueberlastet`, `dienst_nicht_erreichbar` | Der Geodienst antwortet gerade nicht. Die Wartezeit steht in `Retry-After`, danach `POST` auf die `analyse_url`. | | 503 | `analyse_abgebrochen` | Der Lauf wurde unterbrochen, etwa durch einen Neustart. Einmal neu anstoßen mit `POST` auf die `analyse_url`. | | 422 | `kein_dach` | An dieser Stelle gibt es kein auswertbares Dach. Adresse prüfen. | | 500 | `analyse_fehlgeschlagen`, `interner_fehler` | Erneut anstoßen mit `POST` auf die `analyse_url`. Bleibt es dabei, dem Benutzer die Projektkennung nennen. | ## Ratengrenzen Gezählt wird je Konto, nicht je Schlüssel. Mehrere Schlüssel bringen also nichts. | Was | Grenze je Stunde | |---|---| | Projekte anlegen und Analysen neu anstoßen | 20 | | Stand abfragen, Projekte auflisten | 900 | | Der kurze Weg `/api/v1/analyse`, Anlegen **und** Abfragen zusammen | 40 | | Bilder, Orthofoto und 3D-Modell abrufen, alle Medienadressen zusammen | 120 | Daneben gilt eine anwendungsweite Grenze **je Adresse**, nicht je Konto: 500 Aufrufe je Stunde und 5000 je Tag. Wer aus einer einzigen Adresse arbeitet, erreicht die 900 Statusabfragen oben also nicht. ## Grenzen - Ergebnisse sind eine Vorplanung aus Fernerkundungsdaten, keine Ausführungsplanung. Sag das dem Benutzer. - Die Zahlen gelten für den gerechneten Standort und sind nicht übertragbar. - **Ergebnisse werden einen Tag lang vorgehalten.** Danach liefert die Abfrage 404 `analyse_fehlt`, und der Weg zurück ist ein neuer Anstoß per POST, nicht ein neues Projekt. - Es rechnen höchstens zwei Analysen gleichzeitig, für alle Nutzer zusammen. Deshalb gibt es den Wartezustand. - Bei Weitergabe der Daten ist die Namensnennung mitzuführen, sie steht in jeder Antwort im Feld `quellen`. - Die Adresse wird zur Geokodierung an Nominatim des OpenStreetMap-Vereins gesendet und im angelegten Projekt gespeichert. - Die vollständige Wirtschaftlichkeitsrechnung über die Schnittstelle ist vorbereitet, aber noch nicht verfügbar. `wirtschaftlichkeit.verfuegbar` zeigt an, ob es sie gibt. Betreiber: Ing. Martin Schneeweiss B.Eng., Mösl 5, 4841 Ungenach, office@schnee.co.at