Sandbox for SMA APIs

This page provides information for the SMA APIs sandbox environment

SMA Monitoring-API, GridControl-API, GeoForecast-API, Live-API, SmartHome-API

To jump-start your integration and anticipate the behaviour of our interfaces, SMA provides a sandbox environment equipped with virtual systems generating dynamic and realistic mock data.

One key aspect is to support integration tests for our permission/user-consent flow, which can be simulated on sandbox environment without end-user interaction. Please note that the sandbox will not provide access to production systems.

Get in touch to get your sandbox client credentials.

Let us know which permission flow you want to test. For the code grant flow, please provide us with a redirectURL.
Once you obtained the credentials, you may want to download the Postman collection below to test our custom flow.

For the Code grant flow, please provide us with a redirect URL to your staging environment.

SMA Sandbox is based on VMs (https://sandbox.smaapis.de/monitoring/index.html)

  • Data simulation limited to ennexOS systems & devices

  • PlantMasterData, e.g. /location

  • Plant and device management data, e.g. /plants/{id}/devices

  • MeasurementData for plantLevel will be provided for EnergyBalance and GridSettings

  • Request /v1/devices/{deviceId}/measurements/sets will provide a list of supported measurementSets

  • MeasurementData for deviceLevel is limited and will provide data for pvGeneration; batteryCharging/Discharging; gridConsumption; gridFeedIn and consumption

User consents - Sandbox specific implementation

  • You can test either permission/user-consent flow on our sandbox environment. Yet your client will only support one of the two flows.

  • Make use of sandbox-specific paths described on our API Access Control page.

Code Grant Flow for end-user application use-cases

  1. Enter the following test credentials on SMA Login-page which will show up after Step1:
    Username: apiTestUser@apiSandbox.com and Password: MyPass123!
  2. Exchange “code” for “token” as described in Step2
  3. Use the bearer token to retrieve data from the API

Custom Grant Flow for O&M, backchannel application use-cases

  1. Request your Token as described in Step1
  2. Use “loginHint”: apiTestUser@apiSandbox.com in Step2 to initiate the permission-flow to the “test” plant-owner
  3. Simulate the button click of the plant-owner using the PUT-request to change the permission-request “status”
    PUT sandbox.smaapis.de/oauth2/v2/bc-authorize/apiTestUser@apiSandbox.com/status Body: “accepted”, “reject” or “revoked”
    In the “real world” (production environment), you will need to wait for the plant-owner to take action.
  4. In this context, your client would make use of the GET request to check the permission request-status (Step3)
  5. Use the Token to retrieve data from the API

Postman Collection

SMA provides you with a Postman collection (.json file) you may want to download to quickly enable your custom flow test on our sandbox environment. Once imported, your will only need to enter the sandbox client credentials provided to you in the Body of the “Token ClientCredential” and “Token Refresh”-requests. You will also find examples of requests for the Monitoring-API, BasicReporting-API, GeoForecast-API and GridControl-API to use after successful permission requests.

Some explanations:

a. If you only execute Step1-request and use the Client-Token on the Monitoring-API before execution of Step2/3 (user-consent requests), the Monitoring-API response will be “empty” as no resource owner has allowed to provide data to your application.

b. Your application can re-request the user consent for a resource owner at any time. This will also be possible if there is an existing valid consents in place, e.g. in order to request access to an additional system which has been deployed after the initial consent has been given (equals: change of resource scope). Or if an initial request eMail has been lost and the resource owner asks for a new request eMail.

c. To use the example requests you have to enter the sandbox client credentials provided to you in the body of the “Token Request (Prerequisite)”. You must have the access rights for the belonging API. You can run the examples in the recommended order to get values for the variables. But you can also set individual values for the collection.

Postman Collection

Download