Frequently asked questions

Please get in touch with API Developer Support. They will set up client credentials for you.

No, the contract includes the set-up of client credentials. You will be able to monitor any system to which you have access once you have obtained the credentials. There is no need for a contract for each plant.

The administrator has the same rights as an installer and can assign the system owner role to another user.

The Authorization Code Flow transfers an Authorization Code for a token. Because you must also pass along your application's Client Secret during the exchange, which must always be kept secure and stored in your client, your app must be server-side. Therefore, redirect URLs are a critical part of the OAuth flow. After a user successfully authorizes an application, the authorization server will redirect the user back to the application with either an authorization code or access token in the URL.

• Access token is user-related, access only possible to the systems of the authenticated user.

• Typically used in end-user (mobile) apps where consent can be given directly/online/synchronously via e.g., an SMA-Connect button.

When the client is seeking access to protected resources of another or a specific resource owner, as previously agreed upon with the authorization server ((sandbox-)auth.smaapis.de/oauth2/token), it has the ability to seek an access token solely through its client credentials. That means:

1. Access Token is client-based, allowing access to systems from many system owners (requires asynchronous consent).

2. Normally used in O&M (web) applications (monitoring/reporting/alerting…), usually not used by the end user/system owner, but only by the O&M partner himself.

SMA will present a user-consent/permission screen on behalf of your application access request. In order to setup your client credentials and configure the according permission-screen for your application, we will need to receive data from you which will be embedded on this screen. This includes an app-logo as well as the T&C and DataPrivacy URL of your application/homepage.

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.

The reason is mentioned in the response: the User used as loginHint is not a system-owner.

The procedure is as follows: you must perform the bc-authorize step, which causes an eMail to be sent to the system-owner. The eMail contains a link which redirects you to a consent-screen, which is only accessible in ennexOS.  That is, you must be already-signed in to see the user consent screen (even if you only have Classic systems, the systems will be displayed in ennexOS anyway).

a. To access the User Management on SMA Sunny Portals, the user must have at least an administrator or installer role.

b. Definition of the “plant owner"

• On SP Classic the "plant owner" flag can be assigned to any user (role : admin, installer, user, guest)

• On ennexOS the "plant owner" flag can be assigned to standard user and administrator

Once this “ownership flag” has been defined for the user, the user has the permission to decide on the 3rd party application request.

Please make yourself familiar with the following description & dependencies to optimise the request-and data-traffic load of our data integration. There is no need to request data more often than the processing speed (on Classic systems), because no new data will be available.

Most importantly, there is a huge difference regarding the supported data refresh rates for systems on Sunny Portal Classic (Webconnect, Home Manager, Cluster Controller) and the new ennexOS Sunny Portal with Data Managers.

For Sunny Portal Classic systems new data sets are only provided on completion of data processing (validation, aggregation of time-intervals). Even if the system/device uploads new (raw) data every 15 minutes it takes up to 2hours until the new data is provisioned on the UI (and API alike). The refresh rate can be reduced to about 15min by obtaining a “Professional Package” for the individual system (in certain countries). The “Pro” Option can be purchased on “Sunny Portal Online Store”.

On the ennexOS we changed the procedure. Data Manager uploads data as a default every 5 minutes (depending on the communication profile set in the portal). The difference now is the processing of the data. We do the processing on the fly when you either select a view in Sunny Portal or access is it via the API.

--- Classic ----
Home Manager
Upload: every 15 minutes
Processing: up to 2 hours
with Professional package for system: about 15 minutes

Webconnect
Upload: every 15 minutes
Processing: up to 2 hours
with Professional package for system: about 15 minutes

Cluster Controller
Upload: every 15 minutes
Processing: up to 2 hours
with Professional package for system: about 15 minutes

--- ennexOS ----
Data Manager
Upload: every 5 minutes
Processing: On the fly

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 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 certain properties of a measurement set are unavailable/not configured, they will be excluded from the result set. Kindly review the /measurements/sets endpoint before utilizing/monitoring a specific period/ timespan. Please also check your configurations in the Portal(s).

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.

• www.sunnyportal.com to setup systems with Home Manager, WebConnect, Cluster Controller and Webbox

• ennexos.sunnyportal.com to setup systems with Data Manager M or Data Manager L

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.

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.

• 1. Pre-condition
  Make sure than any related system has a system-owner (user) defined. For SunnyPortal systems in system configuration > user management > flag "system-owner". For ennexOS systems, the user needs to have owner-role.

• 2. Adding new systems

  • 2.1System-owner with existing 3rd party application approval in place

    • 2.1.1Login to Sunny Portal powered by ennexOS and navigate to 3rd party application menu. Click on edit button on 3rd party application, select additional systems (owned by user) to be approved.

    • 2.1.2Alternatively, the 3rd party client can re-initiate the bc-authorize for the additional access scope (new systems) by using the owners’ eMail as LoginHint. Here the owner has to re-approve the (new) access scope request sent by SMA eMail.

• 3. New System-owner who have not granted the initial approval.

  • 3.1 Use the bc-authorize flow with loginHint (owners eMail address) to trigger the initial permission request to be send out to the owner by SMA (via eMail).

The refresh tokens are currently valid for 2 days. This value may change in the future. When using the refresh token every 2 days, the session can be extended up to a maximum of 30 days (then the session max is reached).

Please take a look at Developer Page https://sma-developer.relaunch.mysma.de/api-access-control. You will be informed on how to use the optional scope = offline_access to get an “offline-token”. This solution will lead to no expiration of a token.

If you pull data in which periods are listed as following:

[2021-03-22T13:55:00-14:00:00]

[2021-03-22T14:00:00-14:05:00]

The data refers to the first period.

The timestamp refers to UTC_END.

No, the data for the given timestamp is a Mean value. The value includes data which is before the timestamp.

• In (classic) plants, the resolution in which the data should be provided in the UI and thus also via the Monitoring API was initially configured for each system during installation (and can no longer be changed).

• 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.

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.

The MonitoringAPI provides historical master-data, measurements and logs from plant-groups, plants, sub-plants, and devices whereas the LiveAPI provides 'live', more precisely near time data from plants/sub-plants/devices. However, the MonitoringAPI provides far more requests than the LiveAPI since it is designed to monitor. The LiveAPI provides live data directly from SMA systems and devices. In order not to burden the infrastructure unnecessarily, a correspondingly moderate and sensible basic call frequency must be implemented.

Each schedule command corresponds to a SEP 2.0 command. Unless otherwise noted, all supported commands can currently be executed for the following plants:

• classic-WebConnect plants without self-consumption

• classic plants with SMA HomeManager (currently limited to FeedInLimit command)

• ennexOS plants with SMA DataManager (currently limited to FeedInLimit command, direct selling interface, labeled as "SPOT" on DataManager "local" User-Interface must be activated)

SMA GridControl API provides remote-control functions (schedule commands) to change system settings and operation modes of plants and connected devices. Schedule commands are treated as asynchronous tasks that can be executed from a given start time for a given duration and are assigned to a given plant via a schedule.

SMA sees its API portfolio as (B2B) SaaS-enabling product propositions, and it is constantly improving, operating, and supporting those API services and functional scopes. We have built a very strong global partner base in the last two years, and our service offering is heavily used by them. Therefore, according to SMA API price model principles, SMA charges for the consumption of a system in any given month and our per system (monthly flat) rate related to the system capacity including any device/inverter related calls.

It refers to one 50kWac system and for the whole year, if the system has monitored in only one month.

Same as EUR.

Our SMA Invoice & Finance Team will send the invoice quarterly or annually.

Yes, see https://sma-developer.de/faq. 
If you prefer an annual payment option in general, please inform the API Developer Support.

1 PU refers to 1 month.

The Invoice & Finance Team will only create an invoice, if the consumption fee exceeds 1000 EUR. Otherwise, the invoice will be generated at the end of the year. See following example:

Q1 242€ -> no invoice

Q2 759€ -> invoice for 1001 € will be generated (Q1 + Q2)

Q3 450€ -> no invoice

Q4 450€ -> invoice for 900 € will be generated (Q3 + Q4)