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.

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.

The service is hosted at the following URL:

• https://partner-api.cellectenergy.com
  

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

---

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:

• getTimeSeries
• postTimeSeries
• getEvent
• getMasterData

The following formats will be used for the data fields of the API.

Term	Description	Example
dateTime	Time format. Information of a point in time. All points in time are in UTC.	2023-01-17T01:00:00Z
string	Alphanumeric string, used for text information.	Battery
number	The number data type is used to specify a numeric value, including the zero.	100.99
boolean	The boolean data type is used to specify a true or false value.	true

Term	Format	Description	Example
authorization	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

Field Name	Value	Translation
DowntimeType	Planned	If the disturbance takes place after the notification is sent.
DowntimeType	Unplanned	If the disturbance has already begun before the notification is sent.
Reason	External factor	Official instructions, environmental legislation requirements, work stoppages or the like lead to a restriction in output or to the standstill of the production, consumption or storage facility.
Reason	Maintenance	Regular planned outages for the renewal, maintenance, and review of components.
Reason	Other	There is a reason which is not covered by the reasons below.
Reason	Outage	There is a technical malfunction on at least one or several components of the production, consumption, or storage unit.
Source	ESS	Energy Storage System

---

Error	HTTPS Status Code	Error Code
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
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

---

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.

The Cellect Partner API includes the following validation checks to ensure the quality and accuracy of the data received:

• Overlapping in operational schedule received:

  • All time series entries received must not overlap with each other.
  • In case the start date of an Entry is set to an earlier date than the end date of the previous Entry, the time-series is rejected, an error is risen and sent to the user via the specified channels.

• Order of “start date” and “end date”:

  • The “end date” of an Entry must define a timestamp bigger than the “start date” of the same entry.

• Missing data:

  • All the fields of the object sent via the Cellect API must be filled in.
  • In case of nulls, nones, blank spaces, or similar, the time-series is rejected, and an error is risen and sent to the user via the specified channels.

• Wrong Formats:

  • The format of the payload must be as specified in the API documentation.
  • If the format does not match the exact format required, the time-series is rejected, and an error is risen and sent to the user via the specified channels.

• Rated power value check:

  • The power that needs to be applied cannot exceed the rated power of the energy storage system.

---

The Cellect Partner API supports webhooks. These are used to provide updates of the status of the data packages (operational schedules) transferred via the API, as well as additional notifications, to a user-defined endpoint.

Webhooks are managed on account level and send data to the defined endpoint. Currently we offer one type of webhook notification:

Time Series Webhooks

Attribute	Description	Type
siteId	ID of Site.	number
schedule	Object containing start and end timestamp, with status.	object
start	The start timestamp of the operational.	timestamp
end	The end timestamp of the operational.	timestamp
status	The status of the operational schedule.	number

{
siteId: number,
schedule: [
    {
      start: timestamp,
      end: timestamp,
      status: number
    },
    {
      start: timestamp,
      end: timestamp,
      status: number
    },
    {
      start: timestamp,
      end: timestamp,
      status: number
    }]
  }
}

---

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.

Time Series Constraints

48 hours constrain:

The “end date” of the last entry of all time-series sent to Cellect via the Partner API must not exceed the 48 hours limit, counting from the timestamp marked when the time-series is sent.

5 minutes “start date” constrain:

The “start date” of the first entry contained in the time-series must not start earlier than 5 minutes counting from the timestamp marked when the time-series is sent.

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

---

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

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.

You can manage webhooks subscriptions using the Partner Dashboard. Here, we allow partners to subscribe to and manage webhook subscriptions for their accounts.

The following operations are supported:

• Subscribe / Generate:

  • Enables the subscription to a webhook for their account. The partner must provide a valid webhook ID in the request body.

• Update:

  • Update an existing webhook subscription for your account.
  • You must provide the webhook ID in the URL path and a request body with the updated subscription information.

• Delete / Remove:

  • Delete an existing webhook subscription for your account.
  • You must provide the webhook ID in the URL path.

• Webhooks Overview:

  • Allows a partner to see the list of all webhook subscriptions for their account.

These operations provide partners with the ability to manage webhook subscriptions easily and efficiently.
By accessing these operations, you can control which events trigger webhook notifications for the account, update or delete existing subscriptions, and retrieve information about your current subscriptions.

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.

Note: The refresh token must be valid to generate a new 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.

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 Events:

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

Symbols are used as query parameters to access specific resources when calling the API methods.
The data available for each of the and their symbols are listed below.
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:

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

Get Time Series:

• ExAnteInformationEssPowerAC:

  • When using this symbol, the time series retrieved will describe:
    • The planned (future 48h) power schedule for the unit (e.g., ESS) to be executed.
    • The status of the implementation of the operational set points.
      
  • The Power AC information will return the following data types:
    • startDate
    • endDate
    • essPowerAC
    • implementationStatus
      

• ExPostInformationEssPowerAC:

  • When using this symbol, the time series retrieved will describe:
    • The Power AC information contains details about the executed power schedule of the unit.
      
  • The Power AC information will return the following data types:
    • startDate
    • endDate
    • essPowerAC
    • implementationStatus
      
      

Master data:

• SiteInformation:
  • The Site Information is used for the publication of site information of one site.
    * The Site Information will return the following data types:
    • SiteID
    • SiteName
    • Country
    • Latitude
    • Longitude
    • EesSoc
    • EesPower
    • EssInstalledEnergyCapacity
    • EssPowerACRatedDischarge
    • EssPowerACRatedCharge

• PortfolioOverview:
  • The Portfolio Overview information is used for the publication of site information of all sites.
    * The Portfolio Overview will return the following data types:
    • SiteID
    • SiteName
    • Country
    • Latitude
    • Longitude
    • EesSoc
    • EesPower
    • EssInstalledEnergyCapacity
    • EssPowerACRatedDischarge
    • EssPowerACRatedCharge

Events:

• Availability:
  • The ESS Availability information is used for the publication of events regarding the availability of ESS sites.
    * The ESS Availability Information will return the following data types:
    • SiteID
    • SiteName
    • Country
    • Latitude
    • Longitude
    • AvailabilityStatus
    • Type
    • Reason
    • Source

---