# List all Charge Sessions for an Entity Source: https://docs.der-connect.dev/api-reference/endpoint/charge-sessions-api/list-charging-records-1 get /v1/entities/{entityId}/charge-sessions Returns the list of Charging Records for the Entity for the defined time frame. # Cancel a Command Source: https://docs.der-connect.dev/api-reference/endpoint/commands-api/cancel-a-command patch /v1/entities/{entityId}/commands/{commandId} Cancels a specific Commmand and returns that Command with the updated status. # List all Commands for an Entity Source: https://docs.der-connect.dev/api-reference/endpoint/commands-api/list-commands get /v1/entities/{entityId}/commands Returns a page with a list of Commands in a given time frame. If no time frame is given, it will return all available Commands. # Retrieve a Command Source: https://docs.der-connect.dev/api-reference/endpoint/commands-api/retrieve-a-specific-command-by-its-id get /v1/entities/{entityId}/commands/{commandId} Retrieves a specific Command by its id and returns that Command. # Schedule Commands for VPP Source: https://docs.der-connect.dev/api-reference/endpoint/commands-api/trigger-schedule/schedule-for-VPP post /v1/collectives/{collectiveId}/commands/schedule Schedules a list of Commands for execution in the future and returns that list of Commands. # Schedule Commands for Entity Source: https://docs.der-connect.dev/api-reference/endpoint/commands-api/trigger-schedule/schedule-for-entity post /v1/entities/{entityId}/commands/schedule Schedules a list of Commands for execution in the future and returns that list of Commands. # Trigger a Command for VPP Source: https://docs.der-connect.dev/api-reference/endpoint/commands-api/trigger-schedule/trigger-for-VPP post /v1/collectives/{collectiveId}/commands Sends a new Command for immediate execution and returns the new Command. # Trigger a Command for Entity Source: https://docs.der-connect.dev/api-reference/endpoint/commands-api/trigger-schedule/trigger-for-entity post /v1/entities/{entityId}/commands Sends a new Command for immediate execution and returns the new Command. # Add a member to a Collective Source: https://docs.der-connect.dev/api-reference/endpoint/core-resources/collective-members/add-a-member-to-a-collective post /v1/collectives/{collectiveId}/members Adds a member to a Collective and returns that Collective with a list of members associated with it. # List all members of a Collective Source: https://docs.der-connect.dev/api-reference/endpoint/core-resources/collective-members/list-members-by-collective get /v1/collectives/{collectiveId}/members Returns a page listing the members in a Collective. # Remove a member from a Collective Source: https://docs.der-connect.dev/api-reference/endpoint/core-resources/collective-members/remove-a-member-from-a-collective delete /v1/collectives/{collectiveId}/members/{memberId} Removes a member from a Collective and returns that Collective with a list of members associated with it. # Add an Entity to a Collective Source: https://docs.der-connect.dev/api-reference/endpoint/core-resources/collectives/add-an-entity-to-a-collective post /v1/collectives/{collectiveId}/entities Adds an Entity to a Collective and returns that Collective with a list of Entities, including the newly added Entity. # The Collective object Source: https://docs.der-connect.dev/api-reference/endpoint/core-resources/collectives/collective-object A Collective represents a group of users and clients (members) who collectively can be granted permissions on one or more Entities. Collectives are created by completing an [Collective Onboarding Request](/api-reference/endpoint/onboarding-api/onboard-collectives/create-a-collective-onboarding-request). # List all Collectives Source: https://docs.der-connect.dev/api-reference/endpoint/core-resources/collectives/list-collectives get /v1/collectives Returns a list of Collectives accessible to the authenticated user. # List all Entities by Collective Source: https://docs.der-connect.dev/api-reference/endpoint/core-resources/collectives/list-entities-by-collective get /v1/collectives/{collectiveId}/entities # Remove an Entity from a Collective Source: https://docs.der-connect.dev/api-reference/endpoint/core-resources/collectives/remove-an-entity-from-a-collective delete /v1/collectives/{collectiveId}/entities/{entityId} Removes an Entity from a Collective and returns that Collective with a list of Entities associated with it. # Retrieve a Collective Source: https://docs.der-connect.dev/api-reference/endpoint/core-resources/collectives/retrieve-a-collective get /v1/collectives/{collectiveId} Returns a specific Collective by id. # Update a Collective Source: https://docs.der-connect.dev/api-reference/endpoint/core-resources/collectives/update-a-collective patch /v1/collectives/{collectiveId} Updates a Collective and returns the updated Collective. # The Entity object Source: https://docs.der-connect.dev/api-reference/endpoint/core-resources/entities/entity-object An Entity represents a connected device, like a PV inverter, home battery, or an electric vehicle. Entities are created by completing an [Entity Onboarding Request](/api-reference/endpoint/onboarding-api/onboard-entities/create-an-entity-onboarding-request). # List all Entities Source: https://docs.der-connect.dev/api-reference/endpoint/core-resources/entities/list-entities get /v1/entities Returns a page of Entities of the given type (if provided) and active feature (if provided) # Retrieve an Entity Source: https://docs.der-connect.dev/api-reference/endpoint/core-resources/entities/retrieve-an-entity get /v1/entities/{entityId} Returns Entity data for an Entity with a given id # Add permissions for an Entity Source: https://docs.der-connect.dev/api-reference/endpoint/core-resources/entity-permissions/add-permissions-to-an-entity post /v1/entities/{entityId}/permissions # List permissions for an Entity Source: https://docs.der-connect.dev/api-reference/endpoint/core-resources/entity-permissions/list-permissions-by-entity get /v1/entities/{entityId}/permissions Returns a page listing the permissions associated with this Entity. # Managing permissions Source: https://docs.der-connect.dev/api-reference/endpoint/core-resources/entity-permissions/managing-permissions Each connected Entity has at least one owner, usually the User or Client who onboarded it. Owners can share access to their Entities by assigning permissions to others. ## Assigning permissions to Principals Permissions can be assigned to Principals, which represent individual actors or groups of actors on our platform, each uniquely identified by a `principalId`. Principals include Users, Clients, Collectives, and Tenants. You can grant permissions to individual Users and Clients or to groups like Collectives and Tenants. ## Types of permissions Each Entity supports four types of permissions that can be assigned to a Principal: * **Viewer** – Can access Readings, settings, and previously triggered Commands. * **Contributor** – Can trigger Commands. * **Administer** – Can manage certain settings. * **Owner** – Can manage permissions and all settings. ## Inheritance Individual Users and Clients may automatically inherit **Viewer** and **Contributor** permissions on an Entity, when they are an administrator of it's Tenant or part of a shared Collective. # Remove permissions for an Entity Source: https://docs.der-connect.dev/api-reference/endpoint/core-resources/entity-permissions/remove-permissions-from-an-entity delete /v1/entities/{entityId}/permissions/principals/{principalId} # Delete the battery capacity of an Entity Source: https://docs.der-connect.dev/api-reference/endpoint/entity-settings/battery-capacity/delete-the-battery-capacity-of-an-entity delete /v1/entities/{entityId}/battery-capacity Deletes the battery capacity from the Entity # Retrieve the battery capacity of an Entity Source: https://docs.der-connect.dev/api-reference/endpoint/entity-settings/battery-capacity/retrieve-the-battery-capacity-of-an-entity get /v1/entities/{entityId}/battery-capacity Returns the battery capacity of the Entity # Update the battery capacity of an Entity Source: https://docs.der-connect.dev/api-reference/endpoint/entity-settings/battery-capacity/update-the-battery-capacity-of-an-entity put /v1/entities/{entityId}/battery-capacity Set the battery capacity of an Entity and returns the updated battery capacity of that Entity # Update the custom properties of an Entity Source: https://docs.der-connect.dev/api-reference/endpoint/entity-settings/custom-properties/update-the-custom-properties-of-an-entity put /v1/entities/{entityId}/properties Set the custom properties of an Entity and returns the updated custom properties of that Entity # Add a disaggregator for an Entity Source: https://docs.der-connect.dev/api-reference/endpoint/entity-settings/disaggregators/add-a-disaggregator-to-an-entity patch /v1/entities/{entityId}/disaggregators Returns the updated list of disaggregators that are set up for the Entity # Remove a disaggregator for an Entity Source: https://docs.der-connect.dev/api-reference/endpoint/entity-settings/disaggregators/delete-a-disaggregator-of-an-entity delete /v1/entities/{entityId}/disaggregators Removes the disaggregator from the collection of disaggregators that are set up for the Entity # List all disaggregators for an Entity Source: https://docs.der-connect.dev/api-reference/endpoint/entity-settings/disaggregators/list-the-disaggregators-of-an-entity get /v1/entities/{entityId}/disaggregators Returns the set of disaggregators that are set up for the Entity # Activate or deactivate a feature for an Entity Source: https://docs.der-connect.dev/api-reference/endpoint/entity-settings/features/activate-or-deactivate-an-entity-feature patch /v1/entities/{entityId}/features Activates or deactivates a feature for an Entity. The platform offers some capabilities (ex: CDRs) that have to be explicitly enabled on an Entity to become available # List all features for an Entity Source: https://docs.der-connect.dev/api-reference/endpoint/entity-settings/features/list-entity-features get /v1/entities/{entityId}/features Returns all the Entity features and their activation status # Delete the heated area of an Entity Source: https://docs.der-connect.dev/api-reference/endpoint/entity-settings/heated-area/delete-the-heated-area-of-an-entity delete /v1/entities/{entityId}/heated-area Deletes the heated area from the Entity # Retrieve the heated area of an Entity Source: https://docs.der-connect.dev/api-reference/endpoint/entity-settings/heated-area/retrieve-the-heated-area-of-an-entity get /v1/entities/{entityId}/heated-area Returns the heated area of the Entity # Update the heated area of an Entity Source: https://docs.der-connect.dev/api-reference/endpoint/entity-settings/heated-area/update-the-heated-area-of-an-entity put /v1/entities/{entityId}/heated-area Set the heated area of an Entity and returns the updated heated area of that Entity # Create a Location for an Entity Source: https://docs.der-connect.dev/api-reference/endpoint/entity-settings/locations/create-a-location-for-an-entity post /v1/entities/{entityId}/locations Set up a Location for a given Entity by providing an address or its coordinates # Delete a Location for an Entity Source: https://docs.der-connect.dev/api-reference/endpoint/entity-settings/locations/delete-a-location-for-an-entity delete /v1/entities/{entityId}/locations/{locationId} Delete a Location for a given Entity # List all Locations of an Entity Source: https://docs.der-connect.dev/api-reference/endpoint/entity-settings/locations/list-all-locations-of-an-entity get /v1/entities/{entityId}/locations List all Locations for a given Entity # Retrieve a Location for an Entity Source: https://docs.der-connect.dev/api-reference/endpoint/entity-settings/locations/retrieve-a-location-for-an-entity get /v1/entities/{entityId}/locations/{locationId} Retrieve the details of a single Location for a given Entity # Update a Location for an Entity Source: https://docs.der-connect.dev/api-reference/endpoint/entity-settings/locations/update-a-location-for-an-entity patch /v1/entities/{entityId}/locations/{locationId} Update just the label or all details of a Location for a given Entity # Delete the nominal power of an Entity Source: https://docs.der-connect.dev/api-reference/endpoint/entity-settings/nominal-power/delete-the-nominal-power-of-an-entity delete /v1/entities/{entityId}/nominal-power Deletes the nominal power from the Entity # Retrieve the nominal power of an Entity Source: https://docs.der-connect.dev/api-reference/endpoint/entity-settings/nominal-power/retrieve-the-nominal-power-of-an-entity get /v1/entities/{entityId}/nominal-power Returns the nominal power setting of the Entity # Update the nominal power of an Entity Source: https://docs.der-connect.dev/api-reference/endpoint/entity-settings/nominal-power/update-the-nominal-power-of-an-entity put /v1/entities/{entityId}/nominal-power Set the nominal power of an Entity and returns the updated nominal power of that Entity # Cancel an Entity Offboarding Request Source: https://docs.der-connect.dev/api-reference/endpoint/offboarding-api/offboard-entities/cancel-an-offboarding-request patch /v1/offboarding/entities/{offboardingRequestId}/cancel Cancels an Offboarding Request and returns the cancelled Offboarding Request. Only Offboarding Requests in 'Pending' status can be cancelled. # Create an Entity Offboarding Request Source: https://docs.der-connect.dev/api-reference/endpoint/offboarding-api/offboard-entities/create-an-offboarding-request post /v1/offboarding/entities Creates an Offboarding Request and returns the created Offboarding Request. If there is already a pending Offboarding Request for the specified Entity, the existing Offboarding Request must be cancelled first. # List all Entity Offboarding Requests Source: https://docs.der-connect.dev/api-reference/endpoint/offboarding-api/offboard-entities/list-offboarding-requests get /v1/offboarding/entities Returns a list of all Offboarding Requests available to the authenticated user # Retrieve an Entity Offboarding Request Source: https://docs.der-connect.dev/api-reference/endpoint/offboarding-api/offboard-entities/retrieve-an-offboarding-request get /v1/offboarding/entities/{offboardingRequestId} Returns a specific Offboarding Request # Cancel an Entity Onboarding Request Source: https://docs.der-connect.dev/api-reference/endpoint/onboarding-api/onboard-entities/cancel-an-entity-onboarding-request patch /v1/onboarding/entities/{onboardingRequestId}/cancel Cancels the specified Entity Onboarding Request and returns that Entity Onboarding Request with updated status. # Create an Entity Onboarding Request Source: https://docs.der-connect.dev/api-reference/endpoint/onboarding-api/onboard-entities/create-an-entity-onboarding-request post /v1/onboarding/entities Creates an Entity Onboarding Request and returns the created Entity Onboarding Request. ### Important Parameters Specify the type of device or vehicle that you want to connect with.\ Available options are `Battery`, `ChargePoint`, `EV`, `HeatPump`, `SolarPlant`, `RetrofitMeter`, `Meter`, and `Inverter`. Specify the manufacturer (for example: “Audi” or “Huawei”) of the device or vehicle you want to connect with. [List all available Entity brands](/api-reference/endpoint/onboarding-api/onboard-entities/retrieve-available-entity-brands-and-types) to learn about the available options. A unique identifier asigned by the vehicle or device manufacturer. ### Additional Parameters Some manufacturers may require additional identifiers or special parameters to be set to complete this request. Read our [dedicated onboarding guides](/guides/onboarding-requests) for more information. ## Detailed Endpoint Reference # Retrieve an Entity Onboarding Request Source: https://docs.der-connect.dev/api-reference/endpoint/onboarding-api/onboard-entities/retrieve-an-entity-onboarding-request get /v1/onboarding/entities/{onboardingRequestId} Returns the Entity Onboarding Request with specified id. # List all available brands and Entity types Source: https://docs.der-connect.dev/api-reference/endpoint/onboarding-api/onboard-entities/retrieve-available-entity-brands-and-types get /v1/onboarding/types/entities Returns a list with the available Entity types and the possible brand for each type. # List all Entity Onboarding Requests Source: https://docs.der-connect.dev/api-reference/endpoint/onboarding-api/onboard-entities/retrieve-entity-onboarding-requests get /v1/onboarding/entities Returns a page of Entity Onboarding Requests for a specific brand and type, optionally with additional filters. # Generate aggregations for an Entity Source: https://docs.der-connect.dev/api-reference/endpoint/readings-api/aggregations/retrieve-aggregations get /v1/entities/{entityId}/aggregations Returns a page of raw data Aggregations, statistically averaged over a specified resolution and time period, with optional filtering # Generate a total aggregation for an Entity Source: https://docs.der-connect.dev/api-reference/endpoint/readings-api/aggregations/retrieve-the-total-aggregation get /v1/entities/{entityId}/aggregations/total Returns a single total Aggregation for an Entity between specific dates # The Reading object Source: https://docs.der-connect.dev/api-reference/endpoint/readings-api/readings/reading-object A Reading represents a single snapshot of the state of an Entity. Entities of the same type, produce similarly structured Readings. This allows you to process them uniformly, regardless of type of device or vehicle your working with. Each Reading may contain several independent metrics. Depending on the type of Entity or it's manufacturer, **some metrics may be omitted** because they are irrelevant, temporarly not available, or due to manufacturer limitations. ## Metrics ### Related to electricity use & production The current flowing through the device at a specific moment, measured in amperes (A). The voltage level of the device at a specific moment, measured in volts (V). The total amount of energy sent back to the grid, measured in kilowatt-hours (kWh). Breakdown of returned energy by phase, for multi-phase systems. The real-time power being sent back to the grid, measured in watts (W). The total amount of energy consumed by the device, measured in kilowatt-hours (kWh). Breakdown of consumed energy by phase, for multi-phase systems. The real-time power being consumed by the device, measured in watts (W). The reactive energy consumed by the device, typically measured in kilovolt-amperes reactive hours (kVA). ### Related to gas use & offset The total volume of gas consumed, measured in cubic meters (m³). The volume of gas returned or offset, measured in cubic meters (m³). ### Related to EVs Indicates whether the device is currently charging (true/false). Shows whether the device is physically connected to a power source (true/false). The current geographic location of the device in latitude and longitude coordinates. Only available upon request. An array of Entity-Locations that we've matched to this Reading. The total distance the device has traveled, typically measured in kilometers (km) or miles. The estimated distance the device can travel or operate before recharging (or refuelling, in case of PHEV). The current charge level of the device's battery, expressed relative to the maximum charge level. ## The full object # Retrieve the last Reading for an Entity Source: https://docs.der-connect.dev/api-reference/endpoint/readings-api/readings/retrieve-the-last-reading get /v1/entities/{entityId}/readings/last Returns the most recent normalized Reading for an Entity # List all Readings for an Entity Source: https://docs.der-connect.dev/api-reference/endpoint/readings-api/readings/retrieves-readings get /v1/entities/{entityId}/readings Returns a page of normalized Readings for a specific Entity, optionally with additional filters # Retrieve a temporary access token Source: https://docs.der-connect.dev/guides/authenticate Use your application credentials to retrieve a temporary bearer access token. To get started you'll need your application credentials. Request or find yours on Traxes. illustration related to authentication

Access tokens allow us to identify you or your application as part of your organisation and give you access to the resources that belong to you or have been shared with you. ## Authenticate with OAuth We use OAuth 2.0 Client Authorisation. This allows us to secure your data so that only you and those who you allow access can see it. In order to authenticate with OAuth, you may provide a `client_id` and `client_secret`. After successful authentication, you receive a temporarily valid access token (a Bearer token) that you can use to authorise other API requests. ### 1. Creating an access (Bearer) token Access tokens can be temporarily used to authorise API requests. You can request a (new) token by making an API request using your application credentials (`client_id` and `client_secret`). You can get an access token by making a `POST` request on a dedicated authentication endpoint managed by Signin.Energy, like in this example: ```bash Request theme={null} curl --request POST \ --url https://signin.energy/am/oauth2/realms/root/realms/difesp/access_token \ --header 'accept: application/json' \ --header 'content-type: application/x-www-form-urlencoded' \ --data-urlencode 'grant_type=client_credentials' \ --data-urlencode 'client_id=REPLACE_WITH_YOUR_CLIENT_ID' \ --data-urlencode 'client_secret=REPLACE_WITH_YOUR_CLIENT_SECRET' \ --data-urlencode 'scope=esp' ``` ```json Response theme={null} { "access_token": "eyJ0eXAi[...]", "expires_in": 3599, "token_type": "Bearer" } ``` ### 2. Authorise an API request To authorise your API requests, you'll have to provide a valid Bearer token in the `Authorization` header of that request. The Bearer token is your access token. In the following example request, `REPLACE_WITH_YOUR_BEARER_TOKEN` has to be replaced with your token: ```bash Request theme={null} curl --request GET \ --url https://api.traxes.io/connect/v1/onboarding/types/entities \ --header 'accept: application/json' \ --header 'authorization: Bearer REPLACE_WITH_YOUR_BEARER_TOKEN' ``` # Charge Sessions API Source: https://docs.der-connect.dev/guides/charge-sessions See when and where a vehicle charged and how much energy it consumed. A Charge Session captures a complete charging event for an electric vehicle or charge point. Detailing when charging started, when it ended, how much energy was used, and where it happened. While the Readings API gives you snapshots of a vehicle’s state over time, the Charge Sessions API gives you a summarized view of each session. This is useful for building timelines, estimating charging costs, or tracking behavior over time. ## How sessions are calculated Depending on the Entity type and hardware manufacturer, sessions are either calculated based on the vehicle’s Readings (most common), or measured directly by the hardware manufacturer. Calculated sessions are based on either power flow or changes in state of charge. We automatically select the best method based on the data available for each vehicle. However, the calculation method doesn’t affect how sessions appear to you. All sessions are normalized and reliable for most common use cases. We calculate each Entity's Charge Sessions once per day. Ongoing sessions won't show up until they are completed. ## Activate the feature to get started Before you can use this API, you'll have to enable the `CaptureChargeSessions` [Feature](/api-reference/endpoint/entity-settings/features) on an Entity of type `EV` or `CP`. We'll show you how to do that in this guide. When you enable this feature, we'll check if the Entity is compatible. In some cases, we may require the vehicle’s [Battery Capacity](/api-reference/endpoint/entity-settings/battery-capacity) to be set before the feature can be activated. In rare cases, the feature may not be available due to limitations from the hardware manufacturer. ## What you'll need * A valid access (bearer) token * An Entity of type `EV` or `CP` ## Let's try it out You may need to set the vehicle's [Battery Capacity](/api-reference/endpoint/entity-settings/battery-capacity/update-the-battery-capacity-of-an-entity) before sessions can be captured. If you’re unsure whether this applies to your vehicle, or if you are working with a charge point instead, you can skip this step and try enabling the feature directly. If the Battery Capacity is required, the request will return an error asking you to provide it. You'll need to specify the entityId and batteryCapacity in kWh. You'll have to enable an [Entity Feature](/api-reference/endpoint/entity-settings/features) to start capturing Charge Sessions. [Activate the feature for your Entity](/api-reference/endpoint/entity-settings/features/activate-or-deactivate-an-entity-feature), identified by its entityId, setting feature to `CaptureChargeSessions` and enabled to `true`. ```json Request (Body) theme={null} { "feature": "CaptureChargeSessions", "enabled": true } ``` It might be time for a break.\ A Charge Session may take up to 24 hours to appear after the vehicle has finished charging. Once you're ready, use the entityId to [List all Charge Sessions](/api-reference/endpoint/charge-sessions-api/list-charging-records-1) for it. You'll also have to specify a start date. Sessions that started before this time won't be part of the response. ```json Response (Body) [expandable] theme={null} { "data": [ { "id": "3c90c3cc-[...]-8dd25736052a", "entityId": "7ac991f9-[...]-1577b91625b5", "created": "2024-06-10T01:31:56Z", "data": { "start": "2024-06-09T14:35:21.384Z", "end": "2024-06-09T15:15:25.685Z", "charge": { "total": { "total": 49.2450, "unit": "kWh" }, "averagePower": { "unit": "kW", "value": 85.7777 }, "start": { "unit": "%", "value": 23 }, "end": { "unit": "%", "value": 90 }, }, "range": { "start": { "unit": "km", "value": 104.3498 }, "end": { "unit": "km", "value": 405.3132 } }, "locationMatches": [ { "accuracy": 0.9, "location": { "id": "0db9516e-[...]-41de6cb46af4", "label": "Home" } } ] } } ], ... } ``` Caution\ The location object might not be available to you. However, our [Location Matching](/guides/location-matching) feature is a privacy-friendly alternative available to all users. ## Good to know * Charge Sessions are generated once every day, as long as the feature is enabled. * In most cases, Charge Sessions won’t be generated retroactively. * Unfinished Charge Sessions won't show up. * Exact locations are usually hidden to protect privacy. If your use case requires exact locations, reach out to our team. In most cases, we recommend using Location Matching — a privacy-friendly alternative. * Information about a vehicle's range or state of charge is only available when connected to a vehicle directly. # Commands API Source: https://docs.der-connect.dev/guides/commands Use the Commands API to schedule or directly send instructions to Entities. illustration related to commands

Some Entities can be controlled remotely through our Commands API. Commands can instruct a device to take action or change its configuration. ## What makes this API powerful Just like Readings, Commands are normalized across all Entities. This allows you to send consistent instructions to any supported device across different manufacturers, models, and device variations. ## Command types and compatibility Whether an Entity supports a Command depends on the type of Entity and its manufacturer. | **Command** | **Use** | **Value** | **Compatibility** | | :------------------- | :--------------------------------------------------- | :--------- | :---------------- | | StartCharging | Start a new charging session. | N/A | EV[^1], CP[^2] | | StopCharging | Stop an active charging session. | N/A | EV[^1], CP[^2] | | Reset | Set the default configuration. | N/A | PV | | Disconnect | Disconnect the system from the grid. | N/A | PV[^3] | | LimitFeedIn | Sets a feed-in limit. Used for curtailing injection. | Limit in W | PV | | StopFeedIn | Limits feed-in to a minimum. | N/A | PV | ## The cooldown time In rare cases, a Command can’t be executed immediately. The device might process it with a delay, or it may take some time for the Command to reach it. To prevent latency issues, we’ve introduced a cooldown period between Commands sent to the same Entity. The cooldown period lasts 10 minutes. You can disable the cooldown if needed, but we recommend avoiding this whenever possible to maintain reliability. When you [Trigger a Command for an Entity](/api-reference/endpoint/commands-api/trigger-schedule/trigger-for-entity), you can disable the cooldown by setting the ignoreCooldown query parameter to `true`. ## What you’ll need * A valid access (bearer) token * Contributor permission on an Entity that supports Commands ## Let’s try it out Use the entityId to [Trigger a Command](/api-reference/endpoint/commands-api/trigger-schedule/trigger-for-entity) for it. You'll also have to specify the Command type and you may need to set a value. Available options: `StartCharging`, `StopCharging`, `Reset`, `Disconnect`, `LimitFeedIn`, and `StopFeedIn`. Reference the [compatibility table](#command-types-and-compatibility) to understand what's expected. ```json Response (Body) {4} theme={null} { "id": "9671cc39-[...]-803eb4022baa", "entityId": "3c90c3cc-[...]-8dd25736052a", "status": "Pending", "triggerTime": "2023-11-07T05:31:56Z", "type": "Reset", } ``` After creating it, your Command will typically be in a `Pending` state. Fetch its updated status at a later time by [Retrieving your Command](/api-reference/endpoint/commands-api/retrieve-a-specific-command-by-its-id). *** [^1]: Charging Commands aren't available for BMW vehicles unless onboarded through Enode. We partner with Enode to extend our support for vehicles through reversed-engeneered connectivity solutions. Read more about Enode's capabilities [on their website](https://developers.enode.com/api/capabilities/vehicle). [^2]: Direct charge point connections over OCPP may not all support Charging Commands. [^3]: The Disconnect Command is currently not supported by Huawei. # Command scheduler Source: https://docs.der-connect.dev/guides/commands-scheduler Schedule commands with precise trigger times. Please reach out to our team for direct support while we are updating this guide. # Connect to an electric vehicle Source: https://docs.der-connect.dev/guides/connect/electric-vehicles Get access to vehicle readings, control charging, and list charge sessions. ## What you'll need * A valid access (bearer) token * The vehicle's identification number (VIN) and its brand * A way to reach out to the vehicle's owner for consent ### Locating the VIN Illustration detailing how to find the VIN

Illustration detailing how to find the VIN

## Let's get started Create an [Entity Onboarding Request](/api-reference/endpoint/onboarding-api/onboard-entities/create-an-entity-onboarding-request), setting the type to `EV`.\ You'll need to specify a supported brand and the VIN as a unique device identifier. [List all available brands Entity types](/api-reference/endpoint/onboarding-api/onboard-entities/retrieve-available-entity-brands-and-types) to learn about the available options. EVs are identified by their VIN (Vehicle Identification Number). In most cases, the onboarding request will have the status `Pending` until a required action is completed. How an action should be completed, depends on its type. * Actions of type `Redirect` (most common) contain a redirectLink. You can redirect your user here or share this link directly with the vehicle's owner to complete the action. * Actions of type `Consent` have to be completed through the vehicle manufacturer's app or by responding to a notification. They also contain a documentationLink for more information on how to complete the action. ```json Response (Body) [expandable] {3, 5-8} theme={null} { "id": "3c90c3cc-[....]-8dd25736052a", "status": "Pending", "requestType": "Entity", "action": { "type": "Redirect", "redirectLink": "" }, "data": { ... }, ... } ``` Available options: `Consent`, `Redirect` A link to redirect the user to complete the action. A link to our documentation, explaining the user how to proceed. Periodically poll the Onboarding API to check if the status of your request has updated to `Succeeded`. Once it's complete, you'll find the newly created Entity and its ID in the data object. You can reference the entityId when using our Readings API, Commands API, and our Charge Sessions API. ```json {3, 6} theme={null} { "id": "3c90c3cc-[....]-8dd25736052a", "status": "Succeeded", "data": { "entity": { "id": "3c90c3cc-[...]-8dd25736052a", ... }, }, ... } ``` ## Work with your newly created Entity **Tip:** Take note of your Entity ID before you get started with our APIs. Observe the state of the vehicle. Send charging instructions. See when the vehicle charged. ```json Onboarding Request (Body) {4} theme={null} { "type": "EV", "brand": "Tesla", "identifier": "1ABC36600TL029015", } ``` # Connect to a Huawei PV system Source: https://docs.der-connect.dev/guides/connect/huawei-pv-systems Connect and control solar plants remotely. ## What you'll need * A valid access (bearer) token * The plant owner needs a Huawei account to provide consent ## Let's get started Create an [Entity Onboarding Request](/api-reference/endpoint/onboarding-api/onboard-entities/create-an-entity-onboarding-request), setting the type to `SolarPlant` and brand to `Huawei`. In most cases, the onboarding request will have the status `Pending` until a required action is completed. Huawei always requires an action of type `Redirect`. Such actions contain a redirectLink. You can redirect your user here or share this link directly with the plant's owner to complete the action. ```json Response (Body) [expandable] {3, 5-8} theme={null} { "id": "3c90c3cc-[....]-8dd25736052a", "status": "Pending", "requestType": "Entity", "action": { "type": "Redirect", "redirectLink": "" }, "data": { ... }, ... } ``` Available options: `Consent`, `Redirect` A link to redirect the user to complete the action. A link to our documentation, explaining the user how to proceed. Periodically poll the Onboarding API to check if the status of your request has updated to `Succeeded`. Once it's complete, you'll find the newly created Entity and its ID in the data object. You can reference the entityId when using our Readings API and the Commands API. ```json {3, 6} theme={null} { "id": "3c90c3cc-[....]-8dd25736052a", "status": "Succeeded", "data": { "entity": { "id": "3c90c3cc-[...]-8dd25736052a", ... }, }, ... } ``` ## Work with your newly created Entity **Tip:** Take note of your Entity ID before you get started with our APIs. Observe the state of the plant. Curtail or deactivate the inverter. ```json Onboarding Request (Body) theme={null} { "type": "SolarPlant", "brand": "Huawei" } ``` # Connect to an SMA PV system Source: https://docs.der-connect.dev/guides/connect/sma-pv-systems Connect and control solar plants remotely. ## What you'll need * A valid access (bearer) token * The plant ID for the PV system * The email address of the plant owner ### Locating the plant ID In SMA's Sunny Portal, the plant ID is part of the URL when navigating to the corresponding plant or when clicking on the PV System Logbook navigation tree item. The plant ID may not be visible in the UI itself. ## Let's get started Create an [Entity Onboarding Request](/api-reference/endpoint/onboarding-api/onboard-entities/create-an-entity-onboarding-request), setting the type to `SolarPlant` and brand to `SMA`. You'll also need to specify the plant ID as its identifier, and the plant owner’s associatedEmail address. In most cases, the onboarding request will have the status `Pending` until a required action is completed. SMA always requires an action of type `Consent`. This means that the action has to be completed through SMA's website or by responding to a notification they have sent to the plant owner. Such actions also contain a documentationLink leading to more information on how to complete the action. ```json Response (Body) [expandable] {3, 5-8} theme={null} { "id": "3c90c3cc-[....]-8dd25736052a", "status": "Pending", "requestType": "Entity", "action": { "type": "Consent", "documentationLink": "" }, "data": { ... }, ... } ``` Available options: `Consent`, `Redirect` A link to redirect the user to complete the action. A link to our documentation, explaining the user how to proceed. Periodically poll the Onboarding API to check if the status of your request has updated to `Succeeded`. Once it's complete, you'll find the newly created Entity and its ID in the data object. You can reference the entityId when using our Readings API and the Commands API. ```json {3, 6} theme={null} { "id": "3c90c3cc-[....]-8dd25736052a", "status": "Succeeded", "data": { "entity": { "id": "3c90c3cc-[...]-8dd25736052a", ... }, }, ... } ``` ## Work with your newly created Entity **Tip:** Take note of your Entity ID before you get started with our APIs. Observe the state of the plant. Curtail or deactivate the inverter. ```json Onboarding Request (Body) {4-5} theme={null} { "type": "SolarPlant", "brand": "SMA", "identifier": "0987654321", "associatedEmail": "somebody@example.com" } ``` # Entity statistics Source: https://docs.der-connect.dev/guides/entity-statistics Use our new statstics endpoint to analyse and aggregate Entity Readings. Please reach out to our team for direct support while we are updating this guide. # Location matching Source: https://docs.der-connect.dev/guides/location-matching Match pre-defined locations to Readings and Charge Sessions. Please reach out to our team for direct support while we are updating this guide. # Onboarding devices and vehicles as Entities Source: https://docs.der-connect.dev/guides/onboarding-requests To connect with a new device, start by creating an Entity Onboarding Request. illustration related to onboarding

Onboarding a device to our platform is the first step toward using many of our APIs. Once a device is onboarded, it becomes available on our platform as an Entity. Entities are digital representations of the physical devices you can interact with through our APIs. To connect devices, you first need to onboard them. We’ve built [Entity Onboarding Requests](/api-reference/endpoint/onboarding-api/onboard-entities/create-an-entity-onboarding-request) to help you gather the required information and user consent needed to start the onboarding flow for a variety of energy devices. ## Understanding the onboarding process Onboarding is an asynchronous process that may take some time to complete, depending on the type of device and the actions required from the device's physical owner. After creating an Onboarding Request, your system can track its status and wait for the user to finish providing any required information and consent. Once the onboarding is complete, the connected device or vehicle becomes available as an Entity on our platform. This Entity can then be accessed and used across our APIs. ## Compatible devices and manufacturers Our platform connects with a wide range of devices and vehicles — including EVs, PV systems, smart meters, and more. When onboarding a new device, you’ll always need to specify the type of device you’re connecting with, along with its brand. We recommend to use our API to [List all available brands and Entity types](/api-reference/endpoint/onboarding-api/onboard-entities/retrieve-available-entity-brands-and-types) for an always up-to-date overview of the devices we support. ## Onboard your first Entity Connect to manage charging sessions. Connect to control solar plants. Connect to control solar plants. # Readings API Source: https://docs.der-connect.dev/guides/readings Observe the state of an Entity over time. illustration related to readings

A Reading captures a snapshot of an Entity's state. We periodically create Readings for each Entity to track how their state changes over time. Entities of the same type produce similarly structured Readings, allowing you to process them uniformly regardless of their manufacturer. ## What makes Readings useful Our Readings API is built for performance and designed to handle large volumes of data. Because Readings are consistent and normalized across all Entities, they provide a solid foundation for building real-time experiences, reporting tools, and cloud-based services that interact with your devices. And in most cases, Readings are stored indefinitely. This gives you long-term access to historical data, ideal for building timelines, tracking changes, and powering applications that rely on deeper analysis. ## What you’ll need * A valid access (bearer) token * An Entity of any type ## Let's try it out Use the entityId to [List all Readings](/api-reference/endpoint/readings-api/readings/retrieves-readings) for it. You'll also have to specify a start date. Readings that came in before this time won't be part of the response. The [Reading Object](/api-reference/endpoint/readings-api/readings/reading-object) for your Entity might look different from the one in the example below. ```json Response (Body) [expandable] theme={null} { "data": [ { "id": "71795703-1d72-[...]", "entityId": "bd297b95-5579-[...]", "measured": "2024-09-03T02:06:39Z", "received": "2024-09-03T02:06:44.6020711Z", "processed": "2024-09-03T02:06:44.9891195Z", "data": { "instantaneousCurrent": { "l1": 2.95, "total": 2.95, "unit": "A" }, "instantaneousVoltage": { "l1": 242.3, "total": 242.3, "unit": "V" }, "negativeActiveEnergy": { "t1": 12794452, "t2": 5067134, "total": 17861586, "unit": "Wh" }, "negativeActiveInstantaneousPower": { "total": 715, "unit": "W" }, "positiveActiveEnergy": { "t1": 6538224, "t2": 8590571, "total": 15128795, "unit": "Wh" }, "positiveActiveInstantaneousPower": { "total": 0, "unit": "W" } } }, ... ] } ``` Caution\ The location object might not be available to you. However, our [Location Matching](/guides/location-matching) feature is a privacy-friendly alternative available to all users. # Sharing access Source: https://docs.der-connect.dev/guides/sharing-access Learn how to share Entities with other Applications. Each connected Entity has at least one owner, usually the Application who onboarded it. Owners can share access to their Entities by assigning permissions directly to other Applications or to a Collective of them. Permissions can be assigned to any Application, uniquely identified by an applicationId. ## Collectives Permissions can also be assigned to a Collective of Applications, identified by a collectiveId. Applications automatically inherit all permissions assigned to a Collective when they are or become a member of it. ## Types of permissions Each Entity supports four types of permissions that can be assigned to an Application: * **Viewer** – Can access Readings, settings, and previously triggered Commands. * **Contributor** – Can trigger Commands. * **Administer** – Can manage certain settings. * **Owner** – Can manage permissions and all settings. ## What you’ll need * A valid access (bearer) token * An Entity of any type that your Application owns * The ID of a Collective or another Application (principalId) ## Let's try it out Our endpoints refer to a `principalId` as a common name for both Application and Collectives IDs. We currently updating the naming of these properties. You may want to [List all permissions for an Entity](/api-reference/endpoint/core-resources/entity-permissions/list-permissions-by-entity), to understand who can access it. To do so, you must specify the entityId of an Entity you own. ```json Response (Body) {5, 7} theme={null} { "data": [ { "entityId": "3c90c3cc-[...]-8dd25736052a", "principalId": "b8a4d7e5-[...]-572a00302df9", "permissionLevels": [ "Viewer" ], } ], ... } ``` You'll find an array of permissionLevels for each principalId you've shared access with. To share access with someone else, [Add permissions for them on your Entity](/api-reference/endpoint/core-resources/entity-permissions/add-permissions-to-an-entity). Specify the entityId of an Entity you own, and set the principalId to the Application you're sharing access with. Lastly, set the permissionLevel you are assigning to them. You may need to make multiple requests to assign multiple permission levels. ```json Request (Example) theme={null} { "principalId": "b8a4d7e5-[...]-572a00302df9", "permissionLevel": "Administer" } ``` # Virtual power plants Source: https://docs.der-connect.dev/guides/virtual-power-plants Use our Commands API alongside VPPs to dispatch bulk instructions across entities. Please reach out to our team for direct support while we are updating this guide. # Quickstart Source: https://docs.der-connect.dev/quickstart To get started you'll need your application credentials. Request or find yours on Traxes. Use your application credentials to retrieve a temporary access token. Having an Entity onboarded is essential to try out many of our features. Therefore, the onboarding guides are **a great place to start before exploring the other APIs**. Headless onboarding, completely managed through our APIs. Try one of our APIs to access your Entity's Readings, Charge Sessions or to trigger Commands. Use the Readings API to observe the state of an Entity over time. Use the Commands API to schedule or send instructions to Entities. See when and where an Entity charged and how much energy it consumed.