Skip to content

SolarUser OCPP API

Jump to bottom Edit New page
Matt Magoffin edited this page May 25, 2024 · 28 revisions

The SolarUser OCPP API provides methods to manage OCPP entities within SolarNetwork. All dates and times are represented in the Gregorian calendar system. All requests must provide a valid user authentication token. See SolarNet API authentication for information on how to use authentication tokens.

For general information about OCPP support in SolarNetwork see the OCPP guide. See the SolarUser OCPP API - Instructions document for details on sending OCPP messages to chargers.

Endpoints

Verb Endpoint Description
POST /user/ocpp/authorizations Create or update authorizations.
GET /user/ocpp/authorizations List authorizations.
GET /user/ocpp/authorizations/{id} Get a specific authorization.
DELETE /user/ocpp/authorizations/{id} Delete an authorization.
POST /user/ocpp/chargers Create or update chargers.
GET /user/ocpp/chargers List chargers.
GET /user/ocpp/chargers/{id} Get a specific charger.
DELETE /user/ocpp/chargers/{id} Delete a charger.
GET /user/ocpp/chargers/action-status List charger action status.
POST /user/ocpp/chargers/settings Create or update charger settings.
GET /user/ocpp/chargers/settings List charger settings.
GET /user/ocpp/chargers/status List charger status.
GET /user/ocpp/chargers/{id}/settings Get a specific charger's settings.
DELETE /user/ocpp/chargers/{id}/settings Delete a charger's settings.
POST /user/ocpp/connectors Create or update connectors.
GET /user/ocpp/connectors List connectors.
GET /user/ocpp/connectors/{chargePointId}/{connectorId} Get a specific connector.
DELETE /user/ocpp/connectors/{chargePointId}/{connectorId} Delete a specific connector.
POST /user/ocpp/credentials Create or update charger credentials.
GET /user/ocpp/credentials List charger credentials.
GET /user/ocpp/credentials/{id} Get a specific charger credential.
DELETE /user/ocpp/credentials/{id} Delete a charger credential.
GET /user/ocpp/credentials?username={username} Get a charger credential by its username.
GET /user/ocpp/sessions List charge sessions.
POST /user/ocpp/sessions/end End a charge session.
GET /user/ocpp/sessions/{id} Get a charge session by its ID.
GET /user/ocpp/sessions/incomplete/{chargePointId} List incomplete charge sessions for a particular charger.
POST /user/ocpp/settings Create or update account settings.
GET /user/ocpp/settings View account settings.
DELETE /user/ocpp/settings Delete account settings.

Date formatting

For endpoints that return timestamp values (full date and time) the timestamps will be rendered as string values using the ISO 8601 timestamp format YYYY-MM-dd'T'HH:mm:ss.SSSSSS'Z' in the UTC time zone, for example 2020-03-01T10:30:49.346827Z. The fractional second can contain up to 6 digits for nanosecond level precision, and will only display up to the precision set in the timestamp. That means the fractional seconds might not appear if the timestamp has no fractional seconds.

For endpoints that accept timestamp values, the same ISO 8601 timestamp format is required, however the fractional seconds may be omitted. For example 2020-03-01T10:30:49Z is a valid value.

Authorizations save

Create or update an authorization entity. An authorization represents an identifier presented by someone wishing to use a charger. Often these identifiers come from things like RFID cards. Use the Authorizations list endpoint to view all saved authorizations.

POST /solaruser/api/v1/sec/user/ocpp/authorizations

The request must be submitted as application/json with a JSON object with the following properties:

Property Type Description
id number A unique identifier assigned by SolarNetwork. If provided, then update an existing entity. If not provided, then a new entity will be created.
userId number The ID of the user that owns the entity.
token string The authorization token value, up to 20 characters long. This value must be unique amongst all other token values owned by the same user.
enabled boolean true if the authorization can be used for charge sessions, false otherwise.
expiryDate string An optional expiration date after which the authorization cannot be used for charge sessions, in ISO 8601 timestamp format in the UTC time zone. If not present then the authorization never expires.

For example:

{
  "id": 4,
  "userId": 1,
  "token": "tt",
  "enabled": false,
  "expiryDate": "2020-03-01T00:00:00Z"
}

Authorizations save response

The response will be an authorization entity object. If a new entity was created then its assigned id property will be provided. See the list response for more details.

Authorizations list

List the available authorizations previously submitted via the Authorizations save endpoint.

GET /solaruser/api/v1/sec/user/ocpp/authorizations

Authorizations list response

The response contains a list of authorization entities. Authorizations have the following properties:

Property Type Description
id number A unique identifier assigned by SolarNetwork.
created string The date the entity was created, in ISO 8601 timestamp format in the UTC time zone.
userId number The ID of the user that owns the entity.
token string The authorization token value, up to 20 ASCII characters long. Must be unique amongst all other token values owned by the same user.
enabled boolean true if the authorization can be used for charge sessions, false otherwise.
expired boolean true if the authorization has an expiryDate value in the past, false otherwise.
expiryDate string An optional expiration date after which the authorization cannot be used for charge sessions, in ISO 8601 timestamp format in the UTC time zone. If not present then the authorization never expires.

An example response looks like:

{
  "success": true,
  "data": [
    {
      "id": 1,
      "created": "2020-02-27T21:32:21.559037Z",
      "userId": 1,
      "token": "test",
      "enabled": true,
      "expired": false
    },
    {
      "id": 4,
      "created": "2020-03-01T20:52:08.236365Z",
      "userId": 1,
      "token": "tt",
      "enabled": false,
      "expired": true,
      "expiryDate": "2020-03-01T00:00:00Z"
    }
  ]
}

Authorizations view

Get a specific authorization entity previously submitted via the Authorizations save endpoint.

GET /solaruser/api/v1/sec/user/ocpp/authorizations/{id}
id The unique ID of the authorization entity to get.

Authorizations view response

The response will be an authorizations entity object. See the list response for more details.

Authorizations delete

Delete a specific authorizations entity previously submitted via the Authorizations save endpoint.

DELETE /solaruser/api/v1/sec/user/ocpp/authorizations/{id}
id The unique ID of the authorization entity to delete.

Authorizations delete response

The response will be a empty.

Chargers save

Create or update a charger entity. A charger represents a physical device someone connects to another device, such as an electric vehicle, to recharge. A charger can offer one or more connectors, which are individual connections between the charger and the device being charged, such as a cable attached to the charger that plugs into an electric vehicle.

For a charger to be used with SolarNetwork, it must be associated with a SolarNode. Any number of chargers can be associated with a node. Once a charger entity has been created in SolarNetwork and its registration status set to Accepted then the charger can be configured to use OCPP to integrate with SolarNetwork. The metering data published by the charger (via OCPP) will be turned into datum streams associated with the SolarNode configured for that charger.

In SolarNetwork the term charge point and charger are used interchangeably.

Use the Chargers list endpoint to view all saved chargers.

POST /solaruser/api/v1/sec/user/ocpp/chargers

The request must be submitted as application/json with a JSON object with the following properties:

Property Type Description
id number A unique identifier assigned by SolarNetwork. If provided, then update an existing entity. If not provided, then a new entity will be created.
userId number The ID of the user that owns the entity.
nodeId number The ID of the SolarNode associated with the charger.
enabled boolean Optional true if the charger can be used for charge sessions, false otherwise. Defaults to false if not provided.
registrationStatus string A Registration Status value. Only chargers with an Accepted registration status may be used for charging.
connectorCount number The number of charging connectors available in the charger.
info object Detailed information about the charger.
info.id string A unique identifier for the charger, up to 48 characters long. This value must be unique amongst all other chargers owned by the same user.
info.chargePointVendor string The vendor of the charger, up to 20 characters long.
info.chargePointModel string The model of the charger, up to 20 characters long.
info.chargePointSerialNumber string The optional serial number of the charger, up to 25 characters long.
info.chargeBoxSerialNumber string The optional serial number of the charge box, up to 25 characters long.
info.firmwareVersion string The optional firmware of the charger, up to 50 characters long.
info.iccid string The optional ICCID of the charger, up to 20 characters long.
info.imsi string The optional IMSI of the charger, up to 20 characters long.
info.meterType string The optional meter type of the charger, up to 25 characters long.
info.meterSerialNumber string The optional meter serial number of the charger, up to 25 characters long.

For example:

{
  "userId": 1,
  "nodeId": 1,
  "enabled": true,
  "registrationStatus": "Pending",
  "connectorCount": 2,
  "info": {
    "chargePointModel": "SolarNode",
    "id": "CP0001",
    "chargePointVendor": "SolarNetwork",
    "chargePointSerialNumber": "ABC123XYZ"
  }
}

Chargers Registration Status type

Chargers have a registration status that specifies if a charger has been approved for use with SolarNetwork.

Value Description
Unknown The registration status is not known.
Pending The registration has been submitted but is not yet approved.
Accepted The registration has been submitted and accepted, so the charger may be used.
Rejected The registration has been submitted but rejected, so the charger may not be used.

Chargers save response

The response will be a charger entity object. If a new entity was created then its assigned id property will be provided. See the list response for more details.

Chargers list

List the available chargers previously submitted via the Chargers save endpoint.

GET /solaruser/api/v1/sec/user/ocpp/chargers

Chargers list response

The response contains a list of charger entities. Chargers have the following properties:

Property Type Description
id number A unique identifier assigned by SolarNetwork.
created string The date the entity was created, in ISO 8601 timestamp format in the UTC time zone.
userId number The ID of the user that owns the entity.
nodeId number The ID of the SolarNode associated with the charger.
enabled boolean true if the charger can be used for charge sessions, false otherwise.
registrationStatus string A Registration Status value. Only chargers with an Accepted registration status may be used for charging.
connectorCount number The number of charging connectors available in the charger.
info object Detailed information about the charger.
info.id string A unique identifier for the charger, up to 48 characters long. This value must be unique amongst all other chargers owned by the same user.
info.chargePointVendor string The vendor of the charger, up to 20 characters long.
info.chargePointModel string The model of the charger, up to 20 characters long.
info.chargePointSerialNumber string The optional serial number of the charger, up to 25 characters long.
info.chargeBoxSerialNumber string The optional serial number of the charge box, up to 25 characters long.
info.firmwareVersion string The optional firmware of the charger, up to 50 characters long.
info.iccid string The optional ICCID of the charger, up to 20 characters long.
info.imsi string The optional IMSI of the charger, up to 20 characters long.
info.meterType string The optional meter type of the charger, up to 25 characters long.
info.meterSerialNumber string The optional meter serial number of the charger, up to 25 characters long.

An example response looks like:

{
  "success": true,
  "data": [
    {
      "id": 1,
      "created": "2020-02-26T23:48:04.263066Z",
      "userId": 1,
      "nodeId": 1,
      "enabled": true,
      "registrationStatus": "Accepted",
      "connectorCount": 2,
      "info": {
        "id": "CP0001",
        "chargePointVendor": "SolarNetwork",
        "chargePointModel": "SolarNode",
        "chargePointSerialNumber": "ABC123XYZ"
      }
    },
    {
      "id": 2,
      "created": "2020-03-01T19:47:37.905822Z",
      "userId": 1,
      "nodeId": 1,
      "enabled": true,
      "registrationStatus": "Accepted",
      "connectorCount": 1,
      "info": {
        "id": "CP0002",
        "chargePointVendor": "SolarNetwork",
        "chargePointModel": "SolarNode",
        "chargePointSerialNumber": "ABC234XYZ"
      }
    }
  ]
}

Chargers view

Get a specific charger entity previously submitted via the Chargers save endpoint.

GET /solaruser/api/v1/sec/user/ocpp/chargers/{id}
id The unique ID of the charger entity to get.

Chargers view response

The response will be an charger entity object. See the list response for more details.

Chargers delete

Delete a specific charger entity previously submitted via the Chargers save endpoint. Any associated connectors and settings will automatically deleted as well.

DELETE /solaruser/api/v1/sec/user/ocpp/chargers/{id}
id The unique ID of the charger entity to delete.

Chargers delete response

The response will be a empty.

Charger settings save

Create or update SolarNetwork charger-specific settings. Each charger can have a single settings entity, which provides charger-level settings that override the account-wide settings. Charger setting entities will be automatically deleted when their associated charger is deleted.

Use the Charger settings list endpoint to view the saved charger settings.

POST /solaruser/api/v1/sec/user/ocpp/chargers/settings

The request must be submitted as application/json with a JSON object with the following properties:

Property Type Description
chargePointId number The ID of the charger associated with the settings.
userId number The ID of the user that owns the entity.
publishToSolarIn boolean true to publish datum for this charger to SolarIn.
publishToSolarFlux boolean true to publish datum for this charger to SolarFlux.
sourceIdTemplate string The default charger source ID template to use if one is not defined in a charger settings entity for a given charger.

For example:

{
  "chargePointId": 2,
  "userId": 1,
  "publishToSolarIn": true,
  "publishToSolarFlux": true,
  "sourceIdTemplate": "/ocpp/cp/{chargerIdentifier}/{connectorId}/{location}"
}

If a setting is not defined for a charger (or an account setting default), the settings used by SolarNetwork are:

Setting Default value
publishToSolarIn true
publishToSolarFlux true
sourceIdTemplate /ocpp/cp/{chargerIdentifier}/{connectorId}/{location}

Charger settings source ID template

This is the same template as specified in account settings.

Charger settings save response

The response will be a charger settings entity object. See the view response for more details.

Charger settings list

List the available charger settings previously submitted via the Charger settings save endpoint.

GET /solaruser/api/v1/sec/user/ocpp/chargers/settings

Charger settings list response

The response contains a list of charger settings entities. See the view response for more details. For example:

{
  "success": true,
  "data": [
    {
      "chargePointId": 2,
      "userId": 1,
      "created": "2020-03-03T03:17:42.221539Z",
      "publishToSolarIn": true,
      "publishToSolarFlux": true,
      "sourceIdTemplate": "/ocpp/{chargerIdentifier}/{connectorId}/{location}"
    }
  ]
}

Charger settings view

View the charger settings for a specific charger previously submitted via the Charger settings save endpoint.

GET /solaruser/api/v1/sec/user/ocpp/chargers/{chargePointId}/settings
chargePointId The ID of the charger to get the settings for.

Charger settings view response

A charger setting contains the following properties:

Property Type Description
chargePointId number The ID of the charger associated with the settings.
userId number The ID of the user that owns the entity.
created string The date the entity was created, in ISO 8601 timestamp format in the UTC time zone.
publishToSolarIn boolean true to publish datum for this charger to SolarIn.
publishToSolarFlux boolean true to publish datum for this charger to SolarFlux.
sourceIdTemplate string The default charger source ID template to use if one is not defined in a charger settings entity for a given charger.

An example response looks like:

{
  "success": true,
  "data": {
    "chargePointId": 2,
    "userId": 1,
    "created": "2020-03-03T03:17:42.221539Z",
    "publishToSolarIn": true,
    "publishToSolarFlux": true,
    "sourceIdTemplate": "/ocpp/{chargerIdentifier}/{connectorId}/{location}"
  }
}

Charger settings delete

Delete a charger settings entity previously submitted via the save endpoint. Charger setting entities will be automatically deleted when their associated charger is deleted.

DELETE /solaruser/api/v1/sec/user/ocpp/chargers/{chargePointId}/settings
chargePointId The ID of the charger to get the settings for.

Charger settings delete response

The response will be a empty.

Charger status list

Query for charger connectivity status entities. A status entity details when a charger's connectivity with SolarNetwork last changed, either by having the connection established or closed. This can be used to help with troubleshooting or monitoring charger connectivity. See the Charger action status list for help monitoring charger messaging.

GET /solaruser/api/v1/sec/user/ocpp/chargers/status
startDate An inclusive starting date to filter by the connectedDate value of each action, in YYYY-MM-dd or YYYY-MM-ddTHH:mm patterns. The date must be provided in the UTC time zone.
endDate An exclusive ending date to filter by the connectedDate value of each action, in YYYY-MM-dd or YYYY-MM-ddTHH:mm patterns. The date must be provided in the UTC time zone.
chargePointId The ID of a single charger.
chargePointIds A comma-delimited list of charger IDs, or as single ID parameters provided multiple times.
identifier A single session ID.
identifiers A comma-delimited list of session IDs, or as single ID parameters provided multiple times.
orderBy A comma-delimited list of sort order keys. See below for the supported values.

Charger status list sorting

Charger action status list queries support the following orderBy query parameter keys:

  • charger
  • created
  • time (the connectedDate property)
  • user

The default sort order, if none provided, is user,charger.

Charger status list response

The response contains a list of charger action status entities. A charger action status contains the following properties:

Property Type Description
created string The date the entity was created, in ISO 8601 timestamp format in the UTC time zone.
userId number The ID of the user that owns the entity.
chargePointId number The charger ID.
connectedTo string An identifier of the SolarNetwork application instance the charger is connected to. If null or missing, then the charger is not connected to SolarNetwork.
sessionId string An identifier of the connection the charger is connected with. If null or missing, then the charger is not connected to SolarNetwork.
connectedDate string The last connection or disconnection date, in ISO 8601 timestamp format in the UTC time zone. If connectedTo is null or missing, this is when the connection was closed, otherwise this is when the connection was established.

An example response in JSON looks like this:

{
  "success": true,
  "data": [
    {
      "created": "2022-11-18 03:15:05.659802Z",
      "userId": 123,
      "chargePointId": 321,
      "connectedTo": "70cc0964",
      "sessionId": "883c009d-420d-4ff0-72bb-b6c54b3a09c3",
      "connectedDate": "2022-11-18 03:15:18.553223Z"
    }
  ]
}

Charger action status list

Query for charger "action" status entities. An action status entity details when a charger last posted an OCPP message. This can be used to help with troubleshooting or monitoring charger activity. See the Charger status list for help monitoring charger connectivity.

GET /solaruser/api/v1/sec/user/ocpp/chargers/action-status
startDate An inclusive starting date to filter by the timestamp value of each action, in YYYY-MM-dd or YYYY-MM-ddTHH:mm patterns. The date must be provided in the UTC time zone.
endDate An exclusive ending date to filter by the timestamp value of each action, in YYYY-MM-dd or YYYY-MM-ddTHH:mm patterns. The date must be provided in the UTC time zone.
chargePointId The ID of a single charger.
chargePointIds A comma-delimited list of charger IDs, or as single ID parameters provided multiple times.
connectorId The ID of a single connector.
connectorIds A comma-delimited list of connector IDs, or as single ID parameters provided multiple times.
action A single action name.
actions A comma-delimited list of action names, or as single ID parameters provided multiple times.
orderBy A comma-delimited list of sort order keys. See below for the supported values.

Charger action status list ordering

Charger action status list queries support the following orderBy query parameter keys:

  • action
  • charger
  • connector
  • created
  • time (the timestamp property)
  • user

The default sort order, if none provided, is user,charger,connector,action.

Charger action status list response

The response contains a list of charger action status entities. A charger action status contains the following properties:

Property Type Description
created string The date the entity was created, in ISO 8601 timestamp format in the UTC time zone.
userId number The ID of the user that owns the entity.
chargePointId number The charger ID.
connectorId number The index ID of the connector, starting with 1 for the first connector and increasing by 1 for each additional connector. Can be 0 if the action is related to the charger as a whole.
action string The OCPP message name, such as BootNotification or MeterValues.
messageId string A message identifier, from the message itself.
timestamp string The date the action occurred, in ISO 8601 timestamp format in the UTC time zone.

An example response in JSON looks like this:

{
  "success": true,
  "data": [
    {
      "created": "2022-11-18 03:15:11.062149Z",
      "userId": 123,
      "chargePointId": 321,
      "connectorId": 2,
      "action": "MeterValues",
      "messageId": "c07f5685-5d30-4bac-95c6-523cdc80fbbb",
      "ts": "2022-11-18 03:15:26.454872Z"
    }
  ]
}

Connectors save

Create or update a connector entity. A connector represents a physical connection on a charger that connects the charger to devices to charge, such as a cable attached to the connector that plugs into an electric vehicle.

Connectors are always associated with a charger. They have an indexed ID value that starts at 1 and increases by one for each additional connector on the same charger. In some situations a connector ID of 0 is used to represent all connectors on a charger. Connector entities will be automatically created when OCPP status messages are received from connected chargers, so invoking this endpoint is generally not necessary. Connector entities will be automatically deleted when their associated charger is deleted.

Use the Connectors list endpoint to view all saved connectors.

POST /solaruser/api/v1/sec/user/ocpp/connectors

The request must be submitted as application/json with a JSON object with the following properties:

Property Type Description
chargePointId number The ID of the charger associated with the connector.
connectorId number The index ID of the connector, starting with 1 for the first connector and increasing by 1 for each additional connector.
userId number The ID of the user that owns the entity.
info object Detailed information about the connector.
info.status string A Charge Point Status value.
info.errorCode string An optional Charge Point Error Code value.
info.info string Optional general information about the connector, up to 50 characters long.
info.timestamp string The last modified date of the connector information, in ISO 8601 timestamp format in the UTC time zone.
info.vendorId string Optional vendor-specific identity information, up to 255 characters long.
info.vendorErrorCode string Optional vendor-specific error code information, up to 50 characters long.

For example:

{
  "chargePointId": 2,
  "connectorId": 1,
  "userId": 1,
  "info": {
    "status": "Available",
    "errorCode": "NoError"
  }
}

Connectors Charge Point Status type

Connectors have a status that specifies if a connector is available for use, in use, or disabled.

Value Description
Unknown The status is not known.
Available The connector is available for a new user.
Faulted The charge point or connector has reported an error and is not available for use.
Unavailable The connector is unavailable as the result of a ChangeAvailability command or an event upon which the charger transitions to unavailable at its discretion.
Reserved The connector is reserved as a result of a ReserveNow command.
Preparing When a connector becomes no longer available for a new user but there is no ongoing charge session (yet). Typically a connector is in this state when a user presents a tag, inserts a cable or a vehicle occupies the parking bay.
Charging The connector is attached to device and allowing the device to charge.
SuspendedEV A device (e.g. electric vehicle) is connected to the connector and the connector is offering energy but the device is not taking any energy.
SuspendedEVSE A device (e.g. electric vehicle) is connected to the connector but the connector is not offering energy to the device, e.g. due to a smart charging restriction, local supply power constraints, or as the result of StartTransaction command indicating that charging is not allowed.
Finishing When a charge session has stopped at a connector, but the connector is not yet available for a new user, e.g. the cable has not been removed.

Connectors Charge Point Error Code type

Connectors have an error code that specifies the general state of the connector.

Value Description
Unknown The status is not known.
ConnectorLockFailure Failure to lock or unlock the connector.
HighTemperature Temperature inside the charger is too high.
NoError No error to report.
PowerMeterFailure Failure to read electrical/energy/power meter.
PowerSwitchFailure Failure to control power switch.
ReaderFailure Failure with authorization token reader, e.g. RFID reader.
ResetFailure Unable to perform a reset.
GroundFailure Ground fault circuit interrupter has been activated.
OverCurrentFailure Over current protection device has tripped.
UnderVoltage Voltage has dropped below an acceptable level.
WeakSignal Wireless communication device reports a weak signal.
OtherError Other type of error. More information might be available in the connector's vendorErrorCode property.
EVCommunicationError Communication failure with the vehicle, might be Mode 3 or other communication protocol problem.
InternalError Error in internal hardware or software component.
LocalListConflict The authorization information received from SolarNetwork is in conflict with the charger's local authorization list.
OverVoltage Voltage has risen above an acceptable level.

Connectors save response

The response will be a connector entity object. See the list response for more details.

Connectors list

List the available connectors previously submitted via the Connectors save endpoint.

GET /solaruser/api/v1/sec/user/ocpp/connectors

Connectors list response

The response contains a list of connector entities. See the Connectors view response section for details.

An example response looks like:

{
  "success": true,
  "data": [
    {
      "chargePointId": 2,
      "connectorId": 1,
      "userId": 1,
      "created": "2020-03-02T23:02:42.244548Z",
      "info": {
        "connectorId": 1,
        "timestamp": "2020-03-02T23:02:42.244548Z",
        "status": "Available",
        "errorCode": "NoError"
      }
    },
    {
      "chargePointId": 2,
      "connectorId": 2,
      "userId": 1,
      "created": "2020-03-02T23:09:45.658396Z",
      "info": {
        "connectorId": 2,
        "timestamp": "2020-03-02T23:09:45.658396Z",
        "status": "Unavailable",
        "errorCode": "EVCommunicationError"
      }
    }
  ]
}

Connectors view

View a specific connector entity previously submitted via the Connectors save endpoint.

GET /solaruser/api/v1/sec/user/ocpp/connectors/{chargePointId}/{connectorId}
chargePointId number
connectorId number

Connectors view response

The response contains a connector entity. Connector entities have the following properties:

Property Type Description
chargePointId number The ID of the charger associated with the connector.
evseId number The ID of the EVSE associated with the connector (OCPP 2 only).
connectorId number The index ID of the connector, starting with 1 for the first connector and increasing by 1 for each additional connector.
userId number The ID of the user that owns the entity.
created string The date the entity was created, in ISO 8601 timestamp format in the UTC time zone.
info object Detailed information about the connector.
info.status string A Charge Point Status value.
info.errorCode string An optional Charge Point Error Code value.
info.info string Optional general information about the connector, up to 50 characters long.
info.timestamp string The last modified date of the connector information, in ISO 8601 timestamp format in the UTC time zone.
info.vendorId string Optional vendor-specific identity information, up to 255 characters long.
info.vendorErrorCode string Optional vendor-specific error code information, up to 50 characters long.

An example response looks like:

{
  "success": true,
  "data": {
    "chargePointId": 2,
    "evseId": 0,
    "connectorId": 1,
    "userId": 1,
    "created": "2020-03-02T23:02:42.244548Z",
    "info": {
      "evseId": 0,
      "connectorId": 1,
      "timestamp": "2020-03-02T23:02:42.244548Z",
      "status": "Available",
      "errorCode": "NoError"
    }
  }
}

Connectors delete

Delete a specific connector entity previously submitted via the Connectors save endpoint.

DELETE /solaruser/api/v1/sec/user/ocpp/connectors/{chargePointId}/{connectorId}
chargePointId number
connectorId number

Credentials save

Create or update a charger credential entity. A charger credential represents the username and password required for chargers to connect to SolarNetwork via OCPP. Use the Credentials list endpoint to view all saved credentials.

POST /solaruser/api/v1/sec/user/ocpp/credentials

The request must be submitted as application/json with a JSON object with the following properties:

Property Type Description
id string A unique identifier assigned by SolarNetwork. If provided, then update an existing entity. If not provided, then a new entity will be created.
userId number The ID of the user that owns the entity.
username string The username, up to 64 characters long. This value must be globally unique within SolarNetwork.
password string The password, or omit to have a random password generated by SolarNetwork. If SolarNetwork generates the password, it will be returned in the response to the save request.
allowedChargePoints array An optional array of charger identifiers (info.id values) allowed to use these credentials. If not specified then any charger owned by the credential's user is allowed to use these credentials.

⚠️ WARNING: SolarNetwork only saves a cryptographically hashed copy of the credential password. Once the password has been saved in SolarNetwork, it will not be possible to get the original password out of SolarNetwork again.

For example, to create a new credentials entity with a randomly generated password, a request like:

{
  "userId": 1,
  "username": "supercharger123"
}

would return a response with the generated password, like:

{
  "id": 8,
  "created": "2020-03-02T00:11:08.983295Z",
  "userId": 1,
  "username": "supercharger123",
  "password": "abc123def456hij789"
}

To create a new credentials entity with a provided password, a request like:

{
  "userId": 1,
  "username": "supercharger123",
  "password": "secret"
}

would return a response without the password (because you provided it on the request), like:

{
  "id": 8,
  "created": "2020-03-02T00:11:08.983295Z",
  "userId": 1,
  "username": "supercharger123"
}

Credentials save response

The response will be a credentials entity object. If a new entity was created then its assigned id property will be provided. See the list response for more details.

Credentials list

List the available credentials previously submitted via the Credentials save endpoint.

GET /solaruser/api/v1/sec/user/ocpp/credentials

Credentials list response

The response will be a list of charger credentials. See the view response for more details.

An example response looks like:

{
  "success": true,
  "data": [
    {
      "id": 1,
      "created": "2020-02-26T07:18:03.713232Z",
      "userId": 1,
      "username": "foobar",
      "allowedChargePoints": [
        "CP0001"
      ]
    },
    {
      "id": 2,
      "created": "2020-03-01T19:37:26.398956Z",
      "userId": 1,
      "username": "bimbam"
    }
  ]
}

Credentials view

Get a specific charger credentials entity previously submitted via the Credentials save endpoint.

GET /solaruser/api/v1/sec/user/ocpp/credentials/{id}
id The unique ID of the charger credential entity to get.

Credentials view response

Credentials have the following properties:

Property Type Description
id number A unique identifier assigned by SolarNetwork.
created string The date the entity was created, in ISO 8601 timestamp format in the UTC time zone.
userId number The ID of the user that owns the entity.
username string The authorization token value, up to 20 ASCII characters long. Must be unique amongst all other token values owned by the same user.
allowedChargePoints array An optional array of charger identifiers (info.id values) allowed to use these credentials. If not specified then any charger can use these credentials.

An example response looks like:

{
  "success": true,
  "data": {
    "id": 1,
    "created": "2020-02-26T07:18:03.713232Z",
    "userId": 1,
    "username": "foobar",
    "allowedChargePoints": [
      "CP0001"
    ]
  }
}

Credentials delete

Delete a specific charger credentials entity previously submitted via the Credentials save endpoint.

DELETE /solaruser/api/v1/sec/user/ocpp/credentials/{id}
id The unique ID of the charger credential entity to delete.

Credentials get by username

Get a charger credentials by its username instead of its ID.

GET /solaruser/api/v1/sec/user/ocpp/credentials?username={username}
username The username of the charger credential entity to get.

Credentials get by username response

The response will be a charger credentials entity. See the view response for more details.

An example response looks like:

{
  "success": true,
  "data": {
    "id": 1,
    "created": "2020-02-26T07:18:03.713232Z",
    "userId": 1,
    "username": "foobar",
    "allowedChargePoints": [
      "CP0001"
    ]
  }
}

Sessions view

View the details of a specific charge session.

GET /solaruser/api/v1/sec/user/ocpp/sessions/{id}
id The charge session ID to view.

Sessions view response

The response contains a charge session entity. Sessions have the following properties:

Property Type Description
id string The session ID that uniquely identifies the entity.
created timestamp The date the entity was created, in ISO 8601 timestamp format in the UTC time zone.
authId number The authorization ID that started the session.
chargePointId number The unique ID of the charger entity.
evseId number The EVSE ID value of the connector entity (OCPP 2 only).
connectorId number The connector ID value of the connector entity.
transactionId string The ID charge session transaction.
ended timestamp If provided, the date the charge session finished, in ISO 8601 timestamp format in the UTC time zone.
endAuthId number If provided, the authorization ID that ended the session.
endReason ChargeSessionEndReason If not Unknown the reason the session ended. See ChargeSessionEndReason for possible values.

⚠️ Note that in OCPP 1.6 transactionId values will be generated as numbers, and must be treated as such in OCPP 1.6 messages. In OCPP 2 the values are strings.

An example response looks like:

{
  "success": true,
  "data": {
    "id": "4372ced0-5555-4444-3333-fabe454cf141",
    "created": "2020-12-14 03:13:14Z",
    "authId": "E10F2832",
    "chargePointId": 2,
    "evseId": 0,
    "connectorId": 1,
    "transactionId": "3",
    "ended": "2020-12-14 03:24:36Z",
    "endAuthId": "E10F2832",
    "endReason": "Local",
    "posted": "2020-12-14 03:24:37.92Z"
  }
}

ChargeSessionEndReason enumeration

The ChargeSessionEndReason enumeration contains the following values:

Value Description
Unknown There is no end reason given, which is also the reason given when the session is incomplete (i.e. has no ended timestamp).
EmergencyStop Emergency stop button was used.
EVDisconnected The disconnecting of a cable, or vehicle moved away from inductive charge unit.
HardReset A hard reset command was received.
Local Stopped locally on request of the user at the Charge Point. This is a regular termination of a transaction. Examples: presenting an RFID tag, pressing a button to stop.
Other Any other reason.
PowerLoss Complete loss of power.
Reboot A locally initiated reset/reboot occurred (for instance watchdog kicked in).
Remote Stopped remotely on request of the user. This is a regular termination of a transaction. Examples: termination using a smartphone app, exceeding a (non local) prepaid credit.
SoftReset A soft reset command was received.
UnlockCommand An unlock connector command was received.
DeAuthorized The transaction was stopped because of the authorization status in a start transaction.

Sessions list

Find charge sessions matching a search criteria.

GET /solaruser/api/v1/sec/user/ocpp/sessions
startDate An inclusive minimum session starting date to use in the query, in YYYY-MM-dd or YYYY-MM-ddTHH:mm patterns. The date must be provided in the UTC time zone.
endDate An exclusive maximum session starting date to use in the query, in YYYY-MM-dd or YYYY-MM-ddTHH:mm patterns. The date must be provided in the UTC time zone.
chargeSessionId The ID of a single charge session to filter by.
chargeSessionIds A comma-delimited list of charge session IDs to filter by.
transactionId The ID of a single charge session transaction ID to filter by.
transactionIds A comma-delimited list of transaction IDs to filter by.
chargePointId The ID of a single charger entity to filter by.
chargePointIds The comma-delimited list of charger entity IDs to filter by.
identifier The info.id of a single charger entity to filter by.
identifiers The comma-delimited list of charger entity info.id values to filter by.
connectorId The ID of a single connector entity to filter by.
connectorIds A comma-delimited list of connector entity IDs to filter by.
active Either true to only include incomplete sessions or false to only inclue completed (ended) sessions.
endReason A single end reason to filter by. See ChargeSessionEndReason for possible values.
endReasons A comma-delimited list of end reasons to filter by. See ChargeSessionEndReason for possible values.

Session list queries support the following sort query parameter keys:

  • DATE - the session start date
  • CHARGER - the charger ID
  • CONNECTOR - the connector ID
  • ID - the session ID

The default sort order is CHARGER,CONNECTOR,DATE.

Sessions list response

The response will be a list of charge session entities. See Sessions view response for more details.

Sessions end

POST /solaruser/api/v1/sec/user/ocpp/sessions/end
id The ID of the session to end.
endReason The ChargeSessionEndReason to save.
endAuthId An optional end authorization ID to save.

Sessions end response

The response will be true if the session was successfully ended, or false if the session was already ended or not found.

Sessions list incomplete for charger

List all incomplete charge sessions for a given charger. A session is considered incomplete if it has no ended value.

GET /solaruser/api/v1/sec/user/ocpp/sessions/incomplete/{chargePointId}
chargePointId The ID of the charger to list sessions for.

Sessions view response

The response will be a list of charge session entities. See Sessions view response for more details.

Settings save

Create or update SolarNetwork account-wide OCPP settings. Each account can have a single settings entity, which provides account-level settings and defaults for charger settings. In addition, a unique hid property will be generated by SolarNetwork the first time a settings entity is saved (see Settings view response for more information).

Use the Settings view endpoint to view the saved settings.

POST /solaruser/api/v1/sec/user/ocpp/settings

The request must be submitted as application/json with a JSON object with the following properties:

Property Type Description
userId number The ID of the user that owns the entity.
publishToSolarIn boolean true to publish datum for chargers to SolarIn unless overridden in a charger setting.
publishToSolarFlux boolean true to publish datum for chargers to SolarFlux unless overridden in a charger setting.
sourceIdTemplate string The default charger source ID template to use if one is not defined in a charger settings entity for a given charger.

For example:

{
  "userId": 1,
  "publishToSolarIn": true,
  "publishToSolarFlux": true,
  "sourceIdTemplate": "/ocpp/{chargerIdentifier}/{connectorId}/{location}"
}

Settings source ID template

The sourceIdTemplate accepts template parameters in the form {parameterName} which are replaced by the value of the named parameter at runtime. The following parameters are supported:

Parameter Description
chargePointId The unique ID of the charger entity.
chargerIdentifier The info.id charger identity value of the charger entity.
connectorId The connector ID value of the connector entity.
location The measurement location.

Settings save response

The response will be a settings entity object. See the view response for more details.

Settings view

View the SolarNetwork account-wide OCPP settings.

GET /solaruser/api/v1/sec/user/ocpp/settings

Settings view response

The response contains a settings entity. Settings have the following properties:

Property Type Description
userId number The ID of the user that owns the entity.
created string The date the entity was created, in ISO 8601 timestamp format in the UTC time zone.
hid string A short unique ID that be be used as part of the OCPP connection URL. ⚠️ This value is generated when the settings are created, and then will never change.
publishToSolarIn boolean true to publish datum for chargers to SolarIn unless overridden in a charger setting.
publishToSolarFlux boolean true to publish datum for chargers to SolarFlux unless overridden in a charger setting.
sourceIdTemplate string The default charger source ID template to use if one is not defined in a charger settings entity for a given charger.

An example response looks like:

{
  "success": true,
  "data": {
    "userId": 1,
    "created": "2020-03-03T03:31:39.778707Z",
    "hid": "SkB8NBq3",
    "publishToSolarIn": true,
    "publishToSolarFlux": true,
    "sourceIdTemplate": "/ocpp/cp/{chargerIdentifier}/{connectorId}/{location}"
  }
}

Settings delete

Delete the account settings entity previously submitted via the Settings save endpoint.

DELETE /solaruser/api/v1/sec/user/ocpp/settings

Settings delete response

The response will be a empty.

Add a custom footer
Clone this wiki locally