Climate Solutions Community

joeH68 · ‎22.06.2022

Hi,

I've been using openHab in combination with pyvicare to monitor my Viessmann heater for some time, with mixed results. My target is to add the necessary logic to optimize the system's heating / hotwater state based on environmental information which I have already available in openHab.

The logic is already implemented and mostly works. My problem is that from time to time pyvicare will report missing features eventhough the very same unchanged code was working well the day before. The development changelog shows no changes on the Viessmann server either. What's going wrong?

To debug my environment I've been told to use Postman, which is what I'm trying to do now. However I'm new with Postman and could not find much helpful information on how to set it up in combination with the Viessmann API.

Could somebody please point me to a Viessmann-Postman help / cookbook article on this topic?

Thanks!

MichaelHanna · ‎22.06.2022

Hi @joeH68 ,

happy to support you on using Postman for the Viessmann API! You can use this collection, which you can import to your Postman. It contains all basic API requests using and testing the Viessmann API. Unfortunately, I cannot upload a JSON file here, this is why you need to copy the code below and paste it. to a text file, which you save with the ending .json. This file can be imported to your Postman by clicking on "Import".

Let. meknow if this helps.

Best regards,

Michael

{
"info": {
"_postman_id": "b288f3fa-9548-4a95-8a65-feec846291d3",
"name": "VIessmann API example collection",
"description": "This is a Postman collection for the Viessmann API. It contains the following sections:\n\n* Authentication\n* User Management\n* IoT \n \n\nFor the general steps to use the API, please got to [https://documentation.viessmann.com/static/getting-started](https://documentation.viessmann.com/static/getting-started)",
"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
},
"item": [
{
"name": "Authentication",
"item": [
{
"name": "Authorization request",
"request": {
"method": "GET",
"header": [
{
"key": "Content-Type",
"name": "Content-Type",
"value": "application/x-www-form-urlencoded",
"type": "text"
}
],
"url": {
"raw": "https://iam.viessmann.com/idp/v2/authorize?client_id={{client_id}}&redirect_uri={{redirect_uri}}&response_type=code&code_challenge={{code_challenge}}&scope=IoT User offline_access",
"protocol": "https",
"host": [
"iam",
"viessmann",
"com"
],
"path": [
"idp",
"v2",
"authorize"
],
"query": [
{
"key": "client_id",
"value": "{{client_id}}"
},
{
"key": "redirect_uri",
"value": "{{redirect_uri}}"
},
{
"key": "response_type",
"value": "code"
},
{
"key": "code_challenge",
"value": "{{code_challenge}}"
},
{
"key": "scope",
"value": "IoT User offline_access"
}
]
},
"description": "The /authorize endpoint of our IAM platform is used to request an authorization code."
},
"response": []
},
{
"name": "Authorization code exchange",
"request": {
"method": "POST",
"header": [
{
"key": "Content-Type",
"name": "Content-Type",
"value": "application/x-www-form-urlencoded",
"type": "text"
}
],
"body": {
"mode": "urlencoded",
"urlencoded": []
},
"url": {
"raw": "https://iam.viessmann.com/idp/v2/token?grant_type=authorization_code&client_id={{client_id}}&redirect_uri={{redirect_uri}}&code_verifier={{code_verifier}}&code={{code}}",
"protocol": "https",
"host": [
"iam",
"viessmann",
"com"
],
"path": [
"idp",
"v2",
"token"
],
"query": [
{
"key": "grant_type",
"value": "authorization_code"
},
{
"key": "client_id",
"value": "{{client_id}}"
},
{
"key": "redirect_uri",
"value": "{{redirect_uri}}"
},
{
"key": "code_verifier",
"value": "{{code_verifier}}"
},
{
"key": "code",
"value": "{{code}}"
}
]
},
"description": "With the authorization code you can request an access token."
},
"response": []
},
{
"name": "Authorization code exchange - Refresh Token",
"request": {
"method": "POST",
"header": [
{
"key": "Content-Type",
"name": "Content-Type",
"value": "application/x-www-form-urlencoded",
"type": "text"
}
],
"body": {
"mode": "urlencoded",
"urlencoded": []
},
"url": {
"raw": "https://iam.viessmann.com/idp/v2/token?client_id={{client_id}}&grant_type=refresh_token&refresh_token={{refresh_token}}",
"protocol": "https",
"host": [
"iam",
"viessmann",
"com"
],
"path": [
"idp",
"v2",
"token"
],
"query": [
{
"key": "client_id",
"value": "{{client_id}}"
},
{
"key": "grant_type",
"value": "refresh_token"
},
{
"key": "refresh_token",
"value": "{{refresh_token}}"
}
]
},
"description": "With the authorization code you can request an access token."
},
"response": []
}
],
"description": "Visit the API documentatin for more information: [https://documentation.viessmann.com/static/authentication](https://documentation.viessmann.com/static/authentication)"
},
{
"name": "User Management",
"item": [
{
"name": "Logged In User",
"request": {
"auth": {
"type": "bearer",
"bearer": [
{
"key": "token",
"value": "{{Token}}",
"type": "string"
}
]
},
"method": "GET",
"header": [],
"url": {
"raw": "https://api.viessmann-platform.io/users/v1/users/me?sections=identity",
"protocol": "https",
"host": [
"api",
"viessmann-platform",
"io"
],
"path": [
"users",
"v1",
"users",
"me"
],
"query": [
{
"key": "sections",
"value": "identity"
}
]
},
"description": "Gets logged in user data. The response will only contain information from sections that were included in the request."
},
"response": []
}
],
"description": "Gets logged in user data. The response will only contain information from sections that were included in the request."
},
{
"name": "IoT",
"item": [
{
"name": "Service documents",
"item": [
{
"name": "List Errors From Database",
"request": {
"auth": {
"type": "bearer",
"bearer": [
{
"key": "token",
"value": "{{Token}}",
"type": "string"
}
]
},
"method": "GET",
"header": [],
"url": {
"raw": "https://api.viessmann.com/service-documents/v3/error-database?materialNumber={{material_number}}&countryCode=DE&languageCode=de",
"protocol": "https",
"host": [
"api",
"viessmann",
"com"
],
"path": [
"service-documents",
"v3",
"error-database"
],
"query": [
{
"key": "materialNumber",
"value": "{{material_number}}"
},
{
"key": "errorCode",
"value": "0E",
"disabled": true
},
{
"key": "countryCode",
"value": "DE"
},
{
"key": "languageCode",
"value": "de"
}
]
},
"description": "Returns array of errors and their possible solutions for selected material from error database. Can be filtered by error code.\n\nThe response contains list of available locales for given material. If requested locale is not supported then closest match is selected and returned."
},
"response": []
}
],
"description": "Possession and collection of service documents act as a pillar and supporting element to your system. Technical documents and data about devices are integral and should be able to be easily accessed. Using the Service Documents API will allow developers to retrieve and access important system documents."
},
{
"name": "Installations",
"request": {
"auth": {
"type": "bearer",
"bearer": [
{
"key": "token",
"value": "{{Token}}",
"type": "string"
}
]
},
"method": "GET",
"header": [],
"url": {
"raw": "https://api.viessmann.com/iot/v1/equipment/installations?includeGateways=true",
"protocol": "https",
"host": [
"api",
"viessmann",
"com"
],
"path": [
"iot",
"v1",
"equipment",
"installations"
],
"query": [
{
"key": "includeGateways",
"value": "true"
}
]
}
},
"response": []
},
{
"name": "Installation features",
"request": {
"auth": {
"type": "bearer",
"bearer": [
{
"key": "token",
"value": "{{Token}}",
"type": "string"
}
]
},
"method": "GET",
"header": [],
"url": {
"raw": "https://api.viessmann.com/iot/v1/equipment/installations/{{installationID}}/features",
"protocol": "https",
"host": [
"api",
"viessmann",
"com"
],
"path": [
"iot",
"v1",
"equipment",
"installations",
"{{installationID}}",
"features"
]
}
},
"response": []
},
{
"name": "Gateways",
"request": {
"auth": {
"type": "bearer",
"bearer": [
{
"key": "token",
"value": "{{Token}}",
"type": "string"
}
]
},
"method": "GET",
"header": [],
"url": {
"raw": "https://api.viessmann.com/iot/v1/equipment/gateways/",
"protocol": "https",
"host": [
"api",
"viessmann",
"com"
],
"path": [
"iot",
"v1",
"equipment",
"gateways",
""
]
}
},
"response": []
},
{
"name": "Gateway features",
"request": {
"auth": {
"type": "bearer",
"bearer": [
{
"key": "token",
"value": "{{Token}}",
"type": "string"
}
]
},
"method": "GET",
"header": [],
"url": {
"raw": "https://api.viessmann.com/iot/v1/equipment/installations/{{installationID}}/gateways/{{gatewaySerial}}/features/",
"protocol": "https",
"host": [
"api",
"viessmann",
"com"
],
"path": [
"iot",
"v1",
"equipment",
"installations",
"{{installationID}}",
"gateways",
"{{gatewaySerial}}",
"features",
""
]
}
},
"response": []
},
{
"name": "Devices",
"request": {
"auth": {
"type": "bearer",
"bearer": [
{
"key": "token",
"value": "{{Token}}",
"type": "string"
}
]
},
"method": "GET",
"header": [],
"url": {
"raw": "https://api.viessmann.com/iot/v1/equipment/installations/{{installationID}}/gateways/{{gatewaySerial}}/devices/",
"protocol": "https",
"host": [
"api",
"viessmann",
"com"
],
"path": [
"iot",
"v1",
"equipment",
"installations",
"{{installationID}}",
"gateways",
"{{gatewaySerial}}",
"devices",
""
]
}
},
"response": []
},
{
"name": "Device features",
"request": {
"auth": {
"type": "bearer",
"bearer": [
{
"key": "token",
"value": "{{Token}}",
"type": "string"
}
]
},
"method": "GET",
"header": [
{
"key": "Content-Type",
"value": "application/json",
"type": "text"
}
],
"url": {
"raw": "https://api.viessmann.com/iot/v1/equipment/installations/{{installationID}}/gateways/{{gatewaySerial}}/devices/{{deviceId}}/features/",
"protocol": "https",
"host": [
"api",
"viessmann",
"com"
],
"path": [
"iot",
"v1",
"equipment",
"installations",
"{{installationID}}",
"gateways",
"{{gatewaySerial}}",
"devices",
"{{deviceId}}",
"features",
""
]
}
},
"response": []
},
{
"name": "Heating schedule",
"request": {
"auth": {
"type": "bearer",
"bearer": [
{
"key": "token",
"value": "{{Token}}",
"type": "string"
}
]
},
"method": "GET",
"header": [],
"url": {
"raw": "https://api.viessmann.com/iot/v1/equipment/installations/{{installationID}}/gateways/{{gatewaySerial}}/devices/{{deviceId}}/features/heating.circuits.0.heating.schedule",
"protocol": "https",
"host": [
"api",
"viessmann",
"com"
],
"path": [
"iot",
"v1",
"equipment",
"installations",
"{{installationID}}",
"gateways",
"{{gatewaySerial}}",
"devices",
"{{deviceId}}",
"features",
"heating.circuits.0.heating.schedule"
]
}
},
"response": []
}
],
"description": "Information regarding the operational condition of your system is a major component of system longevity. Consuming information provided by every node on your system ensures that your product is functional and enables you to connect your system to the components in your environment. Whether you want to identify the status of a gateway or of a heating compressor, our IoT API provides you with the information you need.\n\nFor using IoT features, you need essential three numbers of your heating device: *installationID*, *gatewaySerial* and *deviceID*. In this section, you will also find a short glossary that explains all relevant terms.\n\nPlease visit our API documentation for more information: [https://documentation.viessmann.com/static/iot/overview](https://documentation.viessmann.com/static/iot/overview)"
}
],
"event": [
{
"listen": "prerequest",
"script": {
"type": "text/javascript",
"exec": [
""
]
}
},
{
"listen": "test",
"script": {
"type": "text/javascript",
"exec": [
""
]
}
}
]
}

joeH68 · ‎22.06.2022

Hi @MichaelHanna ,

thanks for your support. In the meantime I:

created a text file containing the "collection" you supplied
registered a Postman userid
login to my userid (via browser) and tried to "import" this collection, but cannot find an "Import" button

Am I on the right track? in which Menu/Submenu I need to get to find the import option?

Sorry for the very dumb questions, I've no Postman knowledge whatsoever.

Thanks.

MichaelHanna · ‎23.06.2022

No problem!

If you use the web version of Postman, you login and you will find the "Workspaces" menu in the top left. Click on it and go to "My Workspace"

On the next page, you will find an "Import" button to import collections to your workspace.

Then you should be able to see a collection that contains the requests similar to this

Let me know if this helps.

Best,

Michael

joeH68 · ‎23.06.2022

Hi @MichaelHanna !

thanks for your patience. With your help I have now created myWorkspace importing the collection you provided.

Then I went to Authentication / GET Authorization Request and set client_id to the 32-characters string from "your clients" in my Viessmann's developer account.

I clicked then the Postman GUI SEND button and got: "error": "Invalid redirection URI."

What should I enter as "redirect_uri" ? and what as "code_challenge"?

My goal is to test the API data points that are giving me problems under pyVicare.

Thanks!

MichaelHanna · ‎23.06.2022

Your questions all should be answered in our API documentation. Please have a look in our Authentication section: https://documentation.viessmann.com/static/authentication

If there is still anything unclear after reading through the API documentation, let me know we can have a look.

Best,

Michael

joeH68 · ‎23.06.2022

Ok thanks @MichaelHanna.

I have now entered my client_ID, redirect_uri (vicare://oauth-callback/everest) and created a code_challenge.

After clicking send I get status 200 OK and can see the HTML output, but cannot find the "code" which I believe to need for the next step (POST Authorization code exchange).

I also tried copying the resulting URL into my browser (Edge Win10) as suggested in the documentation. This took me to the login screen. I entered my userid and password which seem to be accepted but got no "code" I could use in the "POST Authorization code exchange" step.

What did I do wrong? how do I get the "code"?

joeH68 · ‎28.06.2022

Good morning @MichaelHanna,

the infos in the documentation allowed me to move a bit forward, but now I'm stacked with the "authorization code". As already mentioned I tried with the browser (as indicated in the documentation) and with Postman (following an earlier recommendation) with no success.

How do I get the "authorization code" so that it can be used with Postman?

Thanks!

MichaelHanna · ‎28.06.2022

For getting the authorization code, you need to execute the command in a web browser, because you need to login with your Viessmann Login and Password. After the successful login, you will have the authorization code in the URL in your browser.

Please also check the the text and the example (including images) on the documentation page: https://documentation.viessmann.com/static/authentication

You could change your redirect URI you set for your API Key to http://localhost:4200/, similar to the example in the documentation. You can change the redirect URI by going to your dashboard of the Developer Portal https://app.developer.viessmann.com/ and edit the field under "Your clients"

I hope this helps.

Best,

Michael

Climate Solutions Community

Viessmann API / Postman cookbook

Weitersurfen