FAQ for SMA Monitoring-API

Pre-requisite for SMA API Access Control: SMA plant owner definition

  • An end-customer decided to invest in a SMA PV-system and placed an order with an electrician company
  • An installer/employee of the electrician company will build and configure the new solar PV system on-site at the customers location
  • With his previously registered/created SMA user account, the installer will login on SMA portals www.sunnyportal.com or ennexos.sunnyportal.com
  • Using the SMA setup wizard, the user will then register the new PV-system and connected devices on the SMA portal
  • In this setup process, the user will also define (or invite) additional users, such as the plant owner, eligible to access a given system. Each user must be assigned a certain permission-role and a relationship (installer, owner, operator)
  • Users with system owner role may then monitor their systems on the SMA portals/Apps or authorize system data transfer to 3rd party applications via the API access flows

SMA will notify the resource owner of a given system using the eMail address provided for the SMA user account. A 3rd party provider will need to know the plant owners SMA eMail-address in order to initiate the custom authorization flow.

The resource owner of a system must be defined for new plants in the PV-plant setup wizards flow or for existing plants in the user administration. Eligible SMA resource owners must be configured on Sunny Portal and SP powered by ennexOS alike.

On SP powered by ennexOS, the plant owner will be defined during Step2 of the setup process (https://ennexos.sunnyportal.com/configuration/view-plant-registration). SMA user (installer) shall provide the plant owners eMail-address in the foreseen input field. In case the plant owners SMA user account already exists, the related PV-system will be added to the user accounts/plant portfolio. Otherwise an invitation to create the SMA account will be send to the provided eMail address.

Add-define plant owner on ennexOS plant setup wizard

In the navigation “user management” on both SMA portals the new plant relationship (plantOwner) can be added to an existing SMA user account. Or you may invite a new user to the plant.

From a conceptual point of view, only one plant owner should be configured for each plant. Even though it increases complexity in the current ennexOS SP implementation, it is not yet prevented that more than one plant owner is configured for a given plant.

Add-define plant owner on ennexOS user management
Add-define plant owner on SP classic user management

General topics on SMA API consumption

As we are still in the beginning of the SMA API journey, currently, there is none configured yet. With increasing API-gateway traffic and experience on traffic priorization, we may introduce client quotas in Autumn 2020.

Please keep in mind that the Monitoring API does NOT provide live data, only “historical data” and it always depends on the configuration of the plant, how often the data is supplied from the plant into our backend systems and then returned in the API with e.g. 5 or 15min resolution.

SMA API access control and authorization flows

Any 3rd party application will need to register with SMA and will be provided client credentials in order to access SMA systems.

O&M providers who has been assigned to monitor a SMA system, will initiate the consent-flow by providing the plant owners eMail (SMA user) address in the “bc-authorize” request of the SMA custom flow. Users consuming Smart-Home or eMobility apps will trigger the consent flow them-self by clicking on a “Connect-SMA” button in the 3rd party app.

From a user perspective, the 3rd party authorization request will look the same for both flows. The plant owner will need to login with his user credentials on the SMA systems, review the information on the user-consent screen and take his decision to permit or decline the access request.

SMA user (being plant owner of a certain number of systems) will grant access to all of his systems at a certain point in time. User-consent will remain to be valid until actively revoked by the user on the SMA portal ennexos.sunnyportal.com/configuration/view-third-party-apps.

In case the (commercial) plant owner adds new systems to the portal over-time, user-consent needs to be re-executed to gather the permission for these new systems (“Permission-scope change”). The older consent will though remain to be valid to ensure access according to the prior permission scope assuming that the plant ownership for these plants still exists. Furthermore, a new (additional) consent-request may become necessary in the future, e.g. in order to enable the usage of a SMA Control-API.

Most likely, you have not yet been provided with user-consent for system on the SMA custom flow. Using the Client-Token on the Monitoring API without a valid plant owner permission, will result in an empty response.

The language setting of the resource owner's user profile in SP is used for distinguishing the language (currently either German or English) of the consent request eMail.

SMA Monitoring API data

Our former “Classic” API provided access to systems which have been setup on the classic portal only and based on XML-data. Our new SMA Monitoring API provides JSON data objects and access to system which have been setup on Classic and ennexOS alike. Key-difference is the new API access / security, which requires that a user with plant owner role/rights must be defined on all systems and on Classic and ennexOS portal alike. This user must permit the access to systems to be consumed by our new API. This was not necessary on the former API.

Our Monitoring-API will provide access to systems stored in either portal backend. To setup a new system you will either use SMA Sunny Portal or Sunny Portal powered by ennexOS.

In the API-request you will not need to define the specific portal backend. You can differentiate the PV-system source by the provided plantID-format. SP Classic systems identifiers are defined as GUID (8-4-4-4-12) value and the ennexOS systems id values are pure number format.

In SP powered by ennexOS UI, the Monitoring API plant and device IDs are part of the URL when navigating to the corresponding plant / device.

In SP UI, the Monitoring API plant ID is part of the URL when clicking on the PV System Logbook navigation tree item. The Monitoring API device IDs are not displayed on SP UI.

  • For (classic) plants, you can configure for each plant in Sunny Portal UI, in which resolution the data shall be provided in UI and thus also via Monitoring API
  • For ennexOS plants, the data is normally uploaded at least every 5 min to the ennexOS backend and thus, normally, can be provided in 5min intervals. For some properties, the interval might be different, see e.g. GridSettings properties.

In our Monitoring API design you cannot request a specific resolution for measurement data and periods “Recent”, “Day” and “Week” as you will be served the highest resolution available. Thus for converting W to kWh, you must use the given timestamps of the provided data in order to do the transformation.

Please be aware, that on Sandbox environment, only ennexOS plant data is simulated with a 15min resolution as this environment is only meant for setting up an application initially.

For ennexOS plants and devices, the logId returned in logs endpoint is the Event ID displayed in SP powered by ennexOS Event monitor.

The messageTagId identifies the message text returned in the logs endpoint.

For classic plants and devices, the logId is currently empty, as the Event ID is not persisted in SP backend.

We plan to implement a mapping from messageTagId to Event ID which is unique in most cases, so that also for classic plants and devices, the logId will contain the Event ID.

If some properties of a measurement set are not available (null) for the requested timespan, then they are not contained in the result set.

If no data is available for the whole timespan, then an empty list is returned.

Example: Request for weekly measurement data (from Mar 1 -> Mar 8), but the plant was not communicating for the last two days of that span. What does the response look like?

Response: Data available between 1st and 8th of May would be provided, thus from 1st to 6th of May. For the 7th and 8th of May, no measurement sets would be returned, if no data values at all are contained in our backend (so it depends also the measurement set properties).

Yes, old data is kept in our backend. In the Portal UIs, you can see this data of deactivated devices. Also e.g. the energy balance of such a plant would still contain the values of the deactivated devices, as the historical data is kept untouched.