{"id":1855,"date":"2023-01-16T15:02:15","date_gmt":"2023-01-16T14:02:15","guid":{"rendered":"https:\/\/www.rustimation.eu\/?p=1855"},"modified":"2025-11-26T11:43:48","modified_gmt":"2025-11-26T10:43:48","slug":"1_zugang_api","status":"publish","type":"post","link":"https:\/\/www.rustimation.eu\/index.php\/1_zugang_api\/","title":{"rendered":"Viessmann API und Node-Red – Teil 2 – API Zugriff"},"content":{"rendered":"

Der Zugang zur Viessmann API ist nicht ganz trivial. Die Beschreibung auf den Viessmann Seiten<\/a> l\u00e4sst auch zu w\u00fcnschen \u00fcbrig. Trotzdem schadet es nicht, sich das alles dort einmal durchzulesen. Ich beschreibe hier den Ablauf analog dazu aber eben auf Node-Red angepasst. Ist der API Zugriff erst einmal funktionsf\u00e4hig, ist alles Weitere ein Klacks.<\/p>\n

<\/p>\n

Mit jeder Erkenntnis wird dieser Beitrag aktualisiert und dadurch leider auch l\u00e4nger und etwas un\u00fcbersichtlich. Wichtige \u00c4nderungen in meiner Anleitung sind entsprechend hervorgehoben und zus\u00e4tzlich haben meine Beitr\u00e4ge jetzt auch ein Inhaltsverzeichnis.<\/p>\n

Schritt f\u00fcr Schritt<\/h2>\n

Vorbemerkung:<\/strong> diese Anleitung geht davon aus, dass Node-Red native<\/strong> auf einem Linux Rechner, das hei\u00dft einem Raspberry Pi<\/strong> installiert wird also ohne ein Hausautomatisierungsframework darum herum. F\u00fcr Spezialrechner auf Linux Basis (z.B. CCU3) oder Windows PCs, Synology Disk Stations etc. gelten unter Umst\u00e4nden andere Voraussetzungen – zum Beispiel spezielle Client Firewall Regeln und Port-Einstellungen, die hier nicht behandelt werden. Dasselbe gilt f\u00fcr ein embedded Node-Red im Homeassistant<\/strong> oder IO Broker<\/strong>. Auch Docker<\/strong> macht immer wieder Probleme. Ich kann hier auch nur eingeschr\u00e4nkten Support leisten. Schaut euch auch bitte die untenstehenden \"Hinweise zur Fehlersuche\" an, wo ich L\u00f6sungsm\u00f6glichkeiten dank der Hinweise von einigen Lesern zusammengetragen habe.<\/p>\n

A propos Firewall: Der Router braucht keine<\/strong> Portfreischaltung im Firewall. H\u00fctet euch unbedingt<\/strong> davor, den Node-Red Port 1880 im Router freizuschalten. Damit h\u00e4ttet ihr ein riesiges Sicherheitsproblem.<\/p>\n

Achtung: Neu ab Sommer 2025<\/span><\/h4>\n

Im Zuge der \"Eingemeindung\" von Viessmann in die US-amerikanische Firma Carrier \u00e4ndern sich leider die aufzurufenden URLs. Aus viessmann.com<\/strong> wird durchg\u00e4ngig viessmann-climatesolutions.com. <\/strong>Ab Jahresende 2025 gilt dann nur noch die neue URL. Bis dahin sind beide URLs zul\u00e4ssig.<\/p>\n

Ich habe meine Beitr\u00e4ge zum Thema Viessmann API entsprechend angepasst. Screenshots werde ich sukzessive auch migrieren, was allerdings sehr aufwendig ist. Sollte jemand noch eine alte URL in den Node-Red JSON Snippets finden, bitte ich um eine kurze Mitteilung \u00fcber die Kommentarfunktion.<\/p>\n

Ansonsten: Wem das Gewese um die Viessmann API zu bl\u00f6d geworden ist, dem empfehle ich den alternativen Zugriff auf die Heizanlage \u00fcber den Optolink-Splitter<\/a> oder open3e<\/a> f\u00fcr neuere Ger\u00e4te ohne Vitoconnect K\u00e4stchen. Ich selbst arbeite nur noch damit und nicht mehr \u00fcber die API.<\/p>\n

Voraussetzungen – Vorarbeiten<\/h3>\n

Grundvoraussetzung ist, die ViCare App zum Laufen zu bringen. Mit der App wird ein Viessmann Account angelegt und die Anlage registriert. Damit kennen die Viessmann-Server deine Installation. Es ist dann auch sichergestellt, dass die internetseitige Verbindung funktioniert. Darauf achten, dass das Vitoconnect K\u00e4stchen – sofern verwendet – eine ausreichende Empfangsst\u00e4rke hat. 1 Balken ist definitiv zu wenig. Siehe hier<\/a> (Abschnitt Anleitung<\/em>).<\/p>\n

Anschlie\u00dfend, bzw. nach Erhalt und Quittierung des Best\u00e4tigungsmails solltest du dich bei developer.viessmann-climatesolutions.com<\/a> einloggen. Dabei sind dieselben Zugangsdaten zu verwenden,\u00a0 die bei der Registrierung der ViCare App verwendet wurden. Das Ganze ist weitestgehend selbsterkl\u00e4rend.<\/p>\n

Nach dem Login hat man Zugriff auf die Dokumentation und das Viessmann Developer Dahboard. Dort muss zuerst einmal die<\/p>\n

Client ID<\/h3>\n

angelegt werden. Mit Klick auf My Dashboard<\/em> wird dieses angezeigt. Auf der Kachel \"Your Clients\" klicken wir das Stiftsymbol an. Es kann nur ein Client angelegt werden. Normalerweise braucht du nur eine URI. Zwei URIs sind ggf. vonn\u00f6ten, wenn Node-Red zusammen mit dem Viessmann API Adapter auf einem IO Broker laufen soll.<\/p>\n

\"\"<\/p>\n

Bei Name<\/em> tr\u00e4gst du denselben Namen ein, den du deiner\u00a0 Anlage in der App verpasst hast – ich bin mir aber nicht sicher, ob das wirklich so sein muss. Die Client ID wird automatisch erzeugt, wenn du am Ende \"Save Client\" anklickst.<\/p>\n

Zuvor muss aber noch das Google reCAPTCHA<\/em> ausgeschaltet und eine Redirect URI<\/em> eingegeben werden.<\/p>\n

Die Redirect URI ist die Aufrufadresse (Callback Adresse) deiner Applikation, an die bei Aufruf ein AuthCode \u00fcbermittelt wird. In der generischen Viessmann Anleitung<\/a> steht\u00a0 http:\/\/localhost:4200<\/span> . Wir hingegen verwenden http:\/\/localhost:1880\/authcode<\/span>\u00a0 – das ist die Adresse bzw. der Port, auf dem Node-Red auf Input lauscht. Das \/authcode<\/span> ist ein beliebiger Pfad<\/strong>, der unbedingt erforderlich ist<\/strong>, sonst ruft Viessmann den Node-Red Editor anstatt des Flows auf. Merke dir diesen Pfad, du brauchst ihn in den n\u00e4chsten Schritten.<\/p>\n

Die Client ID ist statisch und bleibt so lange g\u00fcltig, bis du sie im Dashboard l\u00f6schst.
\nMerke<\/strong>: Die ClientID wird im Folgenden insgesamt dreimal in einen http Request Node eingetragen. Das wird gerne \u00fcbersehen, wenn man die ClientID sp\u00e4ter einmal ge\u00e4ndert hat.<\/p>\n

Authcode abrufen<\/h3>\n

Das Erzeugen der Client ID war der letzte manuelle Schritt und muss auch nur einmalig durchgef\u00fchrt werden. Der Rest ist k\u00fcnftig automatisiert:<\/p>\n

Wir ziehen uns nun in Node-Red drei Nodes auf das Editiertableau und \"verkabeln\" diese.<\/p>\n

\"\"<\/a><\/p>\n

Timestamp <\/em>zum Triggern, http request<\/em> zum Abfragen und Debug<\/em> f\u00fcr das Ergebnis.<\/p>\n

ACHTUNG<\/strong><\/span>: Der Debug Node (hier debug 5) wird erst dann ein sinnvolles Ergebnis liefern, wenn ihr auch den weiter unten stehenden Schritt mit dem http in<\/em> Node gegangen seid. Erst der http in<\/em> Node erzeugt das virtuelle Verzeichnis, in das der Viessmann Server hineinschreibt.<\/p>\n

In die URL Zeile des\u00a0 http request <\/em>kommt folgender Inhalt:<\/p>\n

https:\/\/iam.viessmann-climatesolutions.com\/idp\/v3\/authorize?client_id=DeineclientID&redirect_uri=http:\/\/localhost:1880\/authcode&response_type=code&code_challenge=2e21faa1-db2c-4d0b-a10f-575fd372bc8c-575fd372bc8c&scope=IoT%20User%20offline_access<\/pre>\n
Deine Client ID<\/strong> an der entsprechenden Stelle eintragen, den gesamten anderen Kram k\u00f6nnt ihr so stehen lassen. In der Viessmann Anleitung ist etwas von Oauth\u00a0<\/em> die Rede f\u00fcr Code Challenge und -Response. Ich habe nie verstanden, wie das funktioniert. Es reicht, hier dieselbe Challenge\/Response wie in der Viessmann Dokumentation zu nehmen.<\/p>\n
Die Redirect URI 1:1 aus dem ClientID Prozess auf den Viessmann Seiten \u00fcbernehmen.<\/p>\n
scope= IoT User<\/em> (bzw. scope=IoT%20User<\/span> ) ist vorgegeben, offline_access<\/em> veranlasst die API noch ein Refresh Token mitzugeben, was die sp\u00e4tere Nutzung deutlich vereinfacht.<\/p>\n
Den Rest des http requests wie folgt ausf\u00fcllen:<\/p>\n
\"\"
Achtung: neue URL viessmann-climatesolutions.com<\/figcaption><\/figure>\n
Methode ist GET, Nutzdaten ignorieren, Basis Authentifizierung verwenden – hier die Viessmann Account Daten<\/strong> (Username\/eMail und Passwort aus der App – nicht den Namen aus dem Viessmann \u201eEdit Client\u201c Fenster) eintragen – und schlie\u00dflich bei R\u00fcckgabe eine UTF-8 Zeichenfolge ausw\u00e4hlen.<\/p>\n
So lange du die Client ID nicht \u00e4nderst, brauchst du diese Bl\u00f6cke nicht mehr anfassen.<\/p>\n
Mit dem http Request Node<\/em> haben wir die Anfrage losgeschickt, mit einem http In Node<\/em> empfangen wir die Antwort. Im Prinzip bauen wir hier einen winzigen Webserver auf.<\/p>\n
\"\"<\/a><\/p>\n
Der http In Node<\/em> wird wie folgt konfiguriert:<\/p>\n
\"\"<\/a><\/p>\n
Das URL Feld muss dem Pfad entsprechen, der beim Anlegen der Client ID verwendet wurde. Allerdings ohne Localhost und Portnummer.<\/p>\n
Der Response Node wird lediglich auf Status 200 gesetzt. Der Response Node ist wichtig, um die Anfrage des Viessmann Servers korrekt abzuschlie\u00dfen!<\/p>\n
Bitte beachte ferner, dass der Sende- und der Empfangsteil sind nicht<\/strong> miteinander verdrahtet sind. Hier zaubert das Internet.<\/p>\n
Jetzt – erst jetzt – k\u00f6nnt ihr testen: Wenn alles funktioniert, sollte der Debug Node<\/em> am Empfangsende den Authorization Code anzeigen wenn der Trigger auf der Sendeseite ausgel\u00f6st wurde. Der Code steckt jetzt in msg.payload.code<\/span>\u00a0.<\/p>\n
Den kompletten JSON Flow findest du am Ende des Artikels.<\/p>\n
Hinweise zur Fehlersuche<\/span><\/h4>\n
Cannot get \/authcode<\/h5>\n
Wie man manchen Kommentaren entnehmen kann, kommt es gelegentlich zu Fehlern der Art \"Cannot GET \/authcode<\/span><\/em>\".
\nDer Fehler tritt immer dann auf, wenn der Viessmann Server unter der angegebenen Adresse nichts findet. Das kann an einer falsch konfigurierten URL liegen, einer falschen Portnummer oder daran, dass der in NR eingebaute Webserver nicht angesprochen werden kann. Hauptursache ist aber wahrscheinlich, dass der zum ersten http Request passende http in Node noch nicht eingebaut wurde. Siehe mit Achtung<\/em> markierten Absatz weiter oben. Erst der http in<\/em> Node, oben mit\u00a0 [get] \/authcode<\/span>\u00a0 bezeichnet, erzeugt das vom Viessmann Server ben\u00f6tigte virtuelle Verzeichnis. Gern genommen wird auch die propriet\u00e4re Adressierung bei Homeassistant, Docker oder Homematic – siehe weiter unten.<\/p>\n
connect ECONNREFUSED<\/span><\/h5>\n
Unter bestimmten Umst\u00e4nden, z.B. wegen einer nicht ganz standardm\u00e4\u00dfgen Konfiguration auf eurer Seite, durchl\u00e4uft Node Red eine Identit\u00e4tskrise und wei\u00df auf einmal nicht mehr, dass es selbst durch localhost aufgerufen wird. Demzufolge wird der Viessmann-Callback abgelehnt und es gibt eine Fehlermeldung der Art:<\/p>\n
RequestError: connect ECONNREFUSED ::1:1880<\/span>\u00a0<\/span><\/p>\n
Test<\/strong>: probiert mal Folgendes:<\/p>\n
[{\"id\":\"e008437fd10a7172\",\"type\":\"tab\",\"label\":\"Flow 1\",\"disabled\":false,\"info\":\"\",\"env\":[]},{\"id\":\"19375c41d180b1f7\",\"type\":\"http in\",\"z\":\"e008437fd10a7172\",\"name\":\"\\\"http in\\\" Node\",\"url\":\"test\",\"method\":\"get\",\"upload\":false,\"swaggerDoc\":\"\",\"x\":990,\"y\":160,\"wires\":[[\"62d56fd0194be715\"]]},{\"id\":\"cb7ae7e2d1498dd5\",\"type\":\"http response\",\"z\":\"e008437fd10a7172\",\"name\":\"\",\"statusCode\":\"200\",\"headers\":{\"content-type\":\"text\/plain\"},\"x\":1460,\"y\":160,\"wires\":[]},{\"id\":\"62d56fd0194be715\",\"type\":\"template\",\"z\":\"e008437fd10a7172\",\"name\":\"\",\"field\":\"payload\",\"fieldType\":\"msg\",\"format\":\"html\",\"syntax\":\"mustache\",\"template\":\"This is the payload!\",\"output\":\"str\",\"x\":1240,\"y\":160,\"wires\":[[\"cb7ae7e2d1498dd5\"]]},{\"id\":\"59871b13fa1668f2\",\"type\":\"http request\",\"z\":\"e008437fd10a7172\",\"name\":\"\",\"method\":\"GET\",\"ret\":\"txt\",\"paytoqs\":\"ignore\",\"url\":\"localhost:1880\/test\/?helloword\",\"tls\":\"\",\"persist\":false,\"proxy\":\"\",\"insecureHTTPParser\":false,\"authType\":\"\",\"senderr\":false,\"headers\":[],\"x\":1190,\"y\":80,\"wires\":[[\"e961ab6d8dca2a1f\"]]},{\"id\":\"53be7c837e4a97d8\",\"type\":\"inject\",\"z\":\"e008437fd10a7172\",\"name\":\"\",\"props\":[{\"p\":\"payload\"},{\"p\":\"topic\",\"vt\":\"str\"}],\"repeat\":\"\",\"crontab\":\"\",\"once\":false,\"onceDelay\":0.1,\"topic\":\"\",\"payload\":\"trigger\",\"payloadType\":\"str\",\"x\":1010,\"y\":80,\"wires\":[[\"59871b13fa1668f2\"]]},{\"id\":\"e961ab6d8dca2a1f\",\"type\":\"debug\",\"z\":\"e008437fd10a7172\",\"name\":\"debug 145\",\"active\":true,\"tosidebar\":true,\"console\":false,\"tostatus\":false,\"complete\":\"false\",\"statusVal\":\"\",\"statusType\":\"auto\",\"x\":1410,\"y\":80,\"wires\":[]}]<\/pre>\n
\"\"<\/p>\n
Mit dem Trigger wird ein http request<\/em> angestupst, der an die Adresse localhost:1880\/test<\/span>\u00a0 eine belanglose Nachricht schickt. Der http in<\/em> Node empf\u00e4ngt diese – vorausgesetzt localhost ist nicht blockiert – und gibt an den http request eine Nachricht zur\u00fcck, die ihr im Debugfenster lesen k\u00f6nnt. Funktioniert das nicht, erscheint eine Fehlermeldung \"Cannot GET \/test<\/em><\/span>\".<\/p>\n
Um zu sehen, ob Node-Red \u00fcberhaupt antwortet, k\u00f6nnt ihr den gerade erzeugten Microwebserver \u00fcber einen Browser auf einem anderen Ger\u00e4t im lokalen Netz aufrufen: http:\/\/IPdesNodeRedServers:1880\/test<\/span> . Wenn das nicht funktioniert, hat NR ein generelles Problem oder ihr habt euch irgendwo verschrieben.<\/p>\n
Dem ECONNREFUSED Problem kann man oft abhelfen, indem man durchgehend 127.0.0.1<\/strong> anstatt localhost verwendet. Logisch betrachtet ist beides dasselbe aber manchmal hilft es, anstatt des lokalen Namens, die IP Adresse zu verwenden .<\/p>\n
Daf\u00fcr die Viessmann Client ID l\u00f6schen und dort die redirect URI neu mit<\/p>\n
http:\/\/127.0.0.1:1880\/authcode<\/span><\/p>\n
anlegen. Dann noch die neu generierte Client ID und die neue URI in den obersten Request Node \u00fcbertragen.<\/p>\n
Dank an G\u00fcnter f\u00fcrs geduldige Ausprobieren und die R\u00fcckmeldung!<\/p>\n
Home Assistant:<\/h5>\n
Bei einem \"embedded Node Red\" ist die Adressierung des NR internen Servers anders.<\/p>\n
Als virtuelles NR Verzeichnis f\u00fcr den Autorisierungsvorgang haben wir weiter oben \/authcode<\/span>\u00a0 verwendet. Der Verzeichname\u00a0 ist beim native NR wahlfrei. Bei HA allerdings nicht! Das Verzeichnis muss \/endpoint\/…<\/span>\u00a0 lauten. Also z.B. \/endpoint\/authcode<\/span>\u00a0. Und zwar \u00fcberall:<\/p>\n
Bisherige Nutzer der API aufgepasst<\/strong>: seit Februar 2023 gibt es eine neue Version des API Authentifizierungsprozesses: Anstatt https:\/\/iam.viessmann.com\/idp\/v2\/authorize…<\/em> hei\u00dft es jetzt https:\/\/iam.viessmann.com\/idp\/<\/em>v3<\/em><\/span><\/strong>\/authorize<\/em>… <\/span>sonst \u00e4ndert sich nichts. Der Vorteil liegt in konkreteren Fehlermeldungen beim Login. Siehe Viessmanm API Changelog<\/span><\/a> Abschnitt Februar 2023. \u00dcbernimmt man die \u00c4nderung, sollte weiter unten d.h. bei https:\/\/iam.viessmann.com\/idp\/v3<\/strong><\/span>\/token… ebenfalls <\/em>v3 anstatt v2 verwendet werden.<\/span>
\n<\/span><\/span><\/p>\n