Cellect Partner API (v1)

Download OpenAPI specification:Download

Introduction

Welcome to the Cellect Partner API User Guide!

Our API allows partners to connect to energy storage systems in a standardized way.

It enables to control energy storage systems (ESS) by providing an operational schedule consisting of a time series of one or multiple entries.
The schedule will be validated and transferred to the Cellect Box, which is installed on-site. The Cellect Box stores the operational schedule locally and executes the planned operation by interacting on-site with the power plant controller.
The Cellect Box can also execute the locally stored operational schedule in case of a loss of internet connectivity for a maximum of 48 hours.

Overview

The API User Guide provides information about how to retrieve and send data from and to the Cellect Platform in a programmatic way.

With this service, you get real-time updates of the available data from the ESS and the option to implement an operational schedule, which Cellect will execute.

The API returns JSON responses. To access it, users require credentials.
These are available from Cellect as part of a subscription package.

The Cellect BESS Control service starts by fetching an operational schedule, which has been transferred via the API as a JSON payload.
This schedule is saved locally, and it is then applied within a defined period. This period can’t exceed a time frame longer than the following 48 hours of operation.

Even in the event of an internet connection loss, this schedule can still be applied since it's saved locally.

Cellect Partner API

The service is hosted at the following URL:

Please note that the service supports HTML only. Furthermore, only https (secure http) address is supported.







Request Methods

The API is a synchronous interface. It supports two request methods:

  • HTTPS Get
  • HTTPS Post

Any date or filter parameters are part of the submitted URL query string.

The following methods are supported:

  • getAccessToken
  • getTimeSeries
  • postTimeSeries
  • getSiteEvents
  • getMasterData

Definition of API Data Fields

Term Format Description Example
refreshToken JWT (JSON Web Token) Authorization token to access protected resources eyJhbGciOiJIUzUxMiJ9.b2tlbklzU2...
accessToken JWT (JSON Web Token) Token to access protected resources eyJhbGciOiJIUzUxMiJ9.b2tlbklzU2...
siteId number Unique identifier for a site 1
Symbol string Parameter used within a method to specify the data which is accessed EssPowerAC
startDate string (date-time format, UTC timezone) Start date for a t<ime series entry 2023-04-19T08:45:15Z
endDate string (date-time format, UTC timezone) End date for a time series entry 2023-04-19T08:45:15Z
essPowerAC number [kW] Power to be applied -1 / 0 / 2
implementationStatus number Status of a time series data point 1
siteName string Name of the site Hamburg Power Plant
country string Country where the site is located Germany
latitude number Latitude of the site location 53.551157327869184
longitude number Longitude of the site location 53.551157327869184
essSoC number [%] State of charge of the energy storage system 60.5
essInstalledEnergyCapacity number [kW] Installed energy capacity of the energy storage system 300
essPowerACRatedDischarge number [kWh] Rated discharge power of the energy storage system 250
essPowerACRatedCharge number [kWh] Rated charge power of the energy storage system 150
availabilityStatus number Availability status of the energy storage system 1
reason number Reason for the change 1
source number Source of the time series data point 1






Error Codes

Error HTTPS Status Code Error Code
Post Time Series Failed 500 Internal Server Error 30000
Time Series Fetch Failed 500 Internal Server Error 30001
Site Data Fetch Failed 500 Internal Server Error 30003
Invalid Site Ownership 403 Forbidden 30004
Time Series Status Not Found 404 Not Found 30005
ESS Power AC Time Series Save Failed 500 Internal Server Error 30006
Site ID Required 400 Bad Request 30007
Invalid Site ID 400 Bad Request 30008
Start Date Required 400 Bad Request 30009
Invalid Start Date 400 Bad Request 30010
End Date Required 400 Bad Request 30011
Invalid End Date 400 Bad Request 30012
Power Value Required 400 Bad Request 30013
Invalid Power Value 400 Bad Request 30014
Symbol Required 400 Bad Request 30017
Invalid Symbol 400 Bad Request 30018
Symbol Not Implemented 501 Not Implemented 30019
Partner Account Not Found 404 Not Found 30021
Partner Account ID Required 400 Bad Request 30042
Invalid Partner Account ID 400 Bad Request 30043
Failed to get Site Status 500 Bad Request 30047
Resource Type Required 400 Bad Request 30064
Resource Type Invalid 400 Bad Request 30065
Refresh Token Not Found 400 Bad Request 30069
Invalid Refresh Token 401 Unauthorized 30072
Access Token Private Key Not Found 500 Internal Server Error 30078
Refresh Token Identifier Required 400 Bad Request 30082
Invalid Refresh Token Identifier 400 Bad Request 30083
Site Not Found 404 Not Found 30085
Partner Account Sites Not Found 404 Not Found 30086
Partner Account Site Not Found 404 Not Found 30087
Time Series Dates Overlap 400 Bad Request 30088
Start and End Date is bigger or equal to Time Series 400 Bad Request 30089
Failed to Delete Time Series 500 Internal Server Error 30090
Time Series Start Date is Less Than 5 Minutes from Now 400 Bad Request 30091
Time Series Start Date is More Than 48 Hours from Now 400 Bad Request 30092
Time Series Start Date Later Than End Date 400 Bad Request 30103
Time Series Dates Are Not In the Past 400 Bad Request 30104
ESS Power AC Time Series Charge Power AC Bigger Than Allowed 400 Bad Request 30113
ESS Power AC Time Series Discharge Power AC Bigger Than Allowed 400 Bad Request 30114
Get Site Events Failed 500 Bad Request 30115







Authentications

The Cellect Partner API provides the following three-step authentication process to protect access to its resources and operations:

  • Cellect Partner Dashboard Login:

    • The Login operation enables you to log in to your account and access the dashboard.
    • You can manage resources from the dashboard, such as Refresh tokens and webhook configuration.
  • Refresh Token:

    • Partners can generate a refresh token from the dashboard, with a custom expiration time.
    • You will need the refresh token to obtain an Access Token
  • Access Token:

    • By providing a valid refresh token, you can get a short-lived (6 hours) access token using the Generate Access Token method.
    • The Access Token is required to access Resources .

This process provides partners a convenient and secure way to access their resources and operations.

  • Note: The Refresh Token and Access Token generated by the Cellect Partner API's authentication process must be included in the req.headers.authorization field of API requests.

  • Please include these tokens in the authorization header to access the API's Resources.









Time Series

Time Series Status

Our API uses statuses to represent time series data for battery systems. The possible statuses are:

Status Code Description
InProgress 1 The time-series has been sent to the API, and it is in progress to be sent to the IoT device and saved in its local database
Implemented 2 The time-series has been saved in the local database of the IoT device.
ImplementationFailed 3 The time-series could not be implemented into the local IoT device on time.
Deleted 4 The time-series has been deleted and is no longer available.
Overwritten 5 The time-series has been replaced or overwritten by new data.

Gaps in Time Series

Gaps in time-series are defined as periods where no operation is planned. When Cellect receives a time-series which includes "gaps", these are translated to periods where the energy storage system will be put into standby mode. This means that the power will be equal to 0 during the "gap" period.


Planned Maintenance

Planned maintenance periods cannot be planned via the API. To specify planned maintenance periods, please contact Cellect support team.

support@cellectenergy.com
+34 611 55 82 39







Dashboard

We provide a dashboard so you can manage your account, password, tokens, and webhook subscriptions.

The image

The dashboard is accessible at the following URL:
https://partner-dashboard.cellectenergy.com/

Here's a brief overview of the sections provided with the tool:

  • Partner Data:

    • Basic account information.
    • Logged in user information.
  • Credential tokens:

    • Generate a new refresh token.
    • Delete existing refresh tokens for specific resources.
  • Password Reset:

    • Allows to change the password of your account.
  • Notifications:

    • Notification section. Here you can configure your webhook subscriptions.


Refresh Token

Overview

The Refresh Token is a key component of the Cellect Partner API's secure authentication process.
You can use a Refresh Token to generate a new Access Token without the need to log in again.
This extends the life of the authentication session and allows partners to access protected resources that require authentication.


Usage

  • The Refresh Token and Access Token generated by the Cellect Partner API's authentication process should be included in the req.headers.authorization field of API requests.
  • The Refresh Token is used to generate a new Access Token, while the Access Token is used to authenticate API requests.
  • Please ensure that you include these tokens in the authorization header to access the API's Resources.

It's important to note that the Refresh Token and Access Token generated by the Cellect Partner API's authentication process should be kept secure and not shared with unauthorized parties.
If a Refresh Token or Access Token is compromised, it should be revoked immediately to prevent unauthorized access to protected resources.

Generating a Refresh Token

You can generate a refresh token from the Cellect Partner Dashboard.
The refresh token can be customized with an expiration time to meet your needs.
Once generated, the refresh token can be used to generate a new access token.


The image

Note: The refresh token must be valid to generate a new access token.







Access Token

Using the Refresh Token obtained in the dashboard, you can access the Generate Access Token operation to generate a short lived Access Token.
This token has an expiration time of 6 hours.

This limited lifespan helps to prevent unauthorized access to resources and ensures that access is only granted to authorized parties.

The Access Token is the token needed to authorize the access to the API resources. It must be placed in the header of the API calls as an HTTP authorization header.

Generate an access token.

https method: https://partner-api-token.cellectenergy.com/v1/access-token

This method allows you to generate an access token for their account by providing a valid Refresh Token.

Authorizations:
RefreshToken
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}

Resources

Resource Overview

This section gives an overview of the Cellect Partner API resources.
By accessing these endpoints, you can manage energy storage systems, either by sending operational schedules to control them or retrieving useful data to monitor its operation.

Here's a brief overview of what you can expect from each operation:

  • Post Time Series:

    • Actively send a time series to operate the target site.
    • You must provide the site ID, symbol, and a time series in the request body.
  • Get Time Series:

    • Retrieve time series which have been already sent to the site.
    • You must provide the site ID and symbol.
  • Get Master Data:

    • Retrieve master data for a single site or all sites associated with your account.
    • You must provide the symbol in the query parameters to specify the type of master data to retrieve.
  • Get Site Events:

    • Retrieve events (e.g., failure messages coming from the BMS) for a target site.
    • You must provide the site ID.

Symbols

Symbols are used as query parameters to access specific resources when calling the API methods.
The full details of the returned data for these symbols and the parameters that can be used can be found in the endpoint description.



Post Time Series

HTTPS Method: https://partner-api.cellectenergy.com/resources/sites/:siteId/time-series

Request Example: https://partner-api.cellectenergy.com/v1/resources/sites/1/time-series?Symbol=EssPowerAC



Functionality:

This endpoint allows partners to post a time series data for a designated site using the siteId parameter. Upon successful validation, the API stores the time series data for the site.


Validations:

This operation validates input data against required standards.

  • Validates site ID, partner account ID, symbol, power values, start and end dates.

  • Verifies ownership of the site by the partner account.

  • Enforces constraints on the number of entries (no more than 200).

  • Ensures non-overlapping entry ends and starts for subsequent entries.

  • Validates that the time series falls within the acceptable interval of 4 minutes to 48 hours.

  • Checks power limits for charge and discharge against the site's rated power.

  • If any validation errors occur, the API returns an appropriate error response.


Symbol:

  • EssPowerAC:
    • The Power AC information contains details about the planned power schedule for the unit (e.g., ESS) at various sites. It also indicates the status of the operational set points' implementation for future schedules.

Authorizations:
AccessToken
path Parameters
siteId
required
number >= 1

Target site for the Operational Schedules

query Parameters
required
EssPowerAc (string)
Request Body schema: application/json

Received time series data

required
Array of objects

Responses

Request samples

Content type
application/json
{
  • "data": [
    ]
}

Response samples

Content type
application/json
{ }

Get Time Series.

HTTPS Method: https://partner-api.cellectenergy.com/v1/resources/sites/:siteId/time-series

Request Example: https://partner-api.cellectenergy.com/v1/resources/sites/4/time-series?Symbol=ExAnteInformationEssPowerAC


Functionality:

Retrieves time-series data for a site, identified by the site ID and symbol, validating input and ownership before returning the requested data.


Validations:

The method validates the input data to ensure that it meets the required standards.

  • Validates the site ID, partner account ID and Symbol.
  • Validates the ownership of the site by the partner account.
  • If any validation errors are encountered, the API returns an appropriate error response to the client.

Symbols:

  • ExAnteInformationEssPowerAC:
    • The Power AC information provides details about the future scheduled values for the site.
    • These values reflect the planned schedule set for the selected sites and indicate the status of the implementation of the operational set points.
    • To perform this operation, please ensure that the Start and End Dates are within the next 48 hours.
    • This symbol requires start and end date in the query parameters.

  • ExPostInformationEssPowerAC:
    • The Power AC information provides details about the scheduled values for the past hours.
    • These values reflect the planned schedule set for the selected sites and indicate the status of the implementation of the operational set points.

      Please note that the scheduled values retreived by using this method could not match the exact real operational power values of the site which were provided to the energy storage system, or delivered to the grid.

Response Info:

  • implementationStatus:
    • 1 - InProgress
    • 2 - Implemented
    • 3 - ImplementationFailed
    • 4 - Deleted
    • 5 - Overwritten

Authorizations:
AccessToken
path Parameters
siteId
required
number

Site ID

query Parameters
required
ExAnteInformationEssPowerAC (object) or ExPostInformationEssPowerAc (object)

Symbol

Responses

Response samples

Content type
application/json
Example
{
  • "results": [
    ]
}

Get Master Data for one site

HTTPS Method: https://partner-api.cellectenergy.com/v1/resources/sites/:siteId/master-data

Request Example: https://partner-api.cellectenergy.com/v1/resources/sites/1/master-data?Symbol=SiteInformation


Functionality:

Retrieves all data for a partner's site, ensuring input validation and ownership verification.


Validations:

This operation validates the input data to ensure that it meets the required standards.

  • Validates the site ID, partner account ID and Symbol.
  • Validates the ownership of the site by the partner account.
  • If any validation errors are encountered, the API returns an appropriate error response.

Symbol:

  • SiteInformation:
    • The Site Information is used for the publication of site information of one site.

Authorizations:
AccessToken
path Parameters
siteId
required
number

The ID of the site to retrieve master data for. Required if Symbol is SiteInformation.

query Parameters
required
SiteInformation (string)

The symbol used to get the master data for one site

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Master Data for all sites

HTTPS Method: https://partner-api.cellectenergy.com/v1/resources/sites/master-data

Request Example: https://partner-api.cellectenergy.com/v1/resources/sites/master-data?Symbol=PortfolioOverview


Functionality:

Retrieves all data for all of the partner's sites, ensuring input validation and ownership verification.


Validations:

This operation validates the input data to ensure that it meets the required standards.

  • Validates the partner account ID and Symbol.
  • If any validation errors are encountered, the API returns an appropriate error response.

Symbol:

  • PortfolioOverview:

    • The Portfolio Overview information is used for the publication of site information of all sites.


Authorizations:
AccessToken
query Parameters
required
PortfolioOverview (string)

The symbol used to get the master data for all sites

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Get Events for a site

HTTPS Method: https://partner-api.cellectenergy.com/v1/resources/sites/:siteId/events

Request Example: https://partner-api.cellectenergy.com/v1/resources/sites/2/events?Symbol=Availability


Functionality:

Retrieves active events associated with a specific site, ensuring input validation and ownership verification.


EVENT_REASON

ID REASON
1 NoReason
2 ExternalFactor
3 Maintenance
4 Outage
5 Other

EVENT_SOURCE

ID SOURCE
1 Cellect
2 ESS
3 SystemBMS
4 Inverter

AVAILABILITY_EVENT_STATUS

ID EVENT_STATUS
1 Avalaible
2 NotAvailable

Validations:

This operation validates the input data to ensure that it meets the required standards.

  • Validates the site ID, partner account ID and Symbol.
  • Validates the ownership of the site by the partner account.
  • If any validation errors are encountered, the API returns an appropriate error response.

Symbol:

  • Availability:
    • The ESS Availability information is used for the publication of events regarding the availability of ESS sites.

Response Info:

  • availabilityStatus:

    • 1 - Available
    • 2 - UnAvailable
  • reason:

    • 1 - NoReason
    • 2 - ExternalFactor
    • 3 - Maintenance
    • 4 - Outage
    • 5 - Other
  • source:

    • 1 - Cellect
    • 2 - ESS
    • 3 - SystemBMS
    • 4 - Inverter

Authorizations:
AccessToken
path Parameters
siteId
required
number >= 1

The ID of the site to retrieve events for

query Parameters
required
Availability (string)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Site Status

HTTPS Method: https://partner-api.cellectenergy.com/v1/resources/sites/:siteId/status

Request Example: https://partner-api.cellectenergy.com/v1/resources/sites/5/status?Symbol=SiteOverview


Functionality:

Retrieves the status for a partner's site, ensuring input validation and ownership verification.

  • A response of -1 in any field means there's no data to be retrieved.

Validations:

This operation validates the input data to ensure that it meets the required standards.

  • Validates the site ID, partner account ID and Symbol.
  • Validates the ownership of the site by the partner account.
  • If any validation errors are encountered, the API returns an appropriate error response.

Symbol:

  • SiteOverview:
    • The Site Overview returns all real-time state of charge and power AC for one site.

Authorizations:
AccessToken
path Parameters
siteId
required
number

The ID of the site to retrieve real-time data for one site. Required if Symbol is SiteOverview.

query Parameters
required
SiteOverview (string)

The symbol used to get the real-time data for one site

Responses

Response samples

Content type
application/json
[
  • {
    }
]