Guides
HomeFAQSupportSDK

Data exchange using OCPP formatted messages

Suggest Edits

Overview

This guide describes how a CPO can forward relevant charger data based on OCPP formatted messages. The API uses a RESTful architecture and exchanges messages in JSON format.

Versioning

The API supports versioning that matches OCPP versions, with the initial release designed according to the OCPP 2.0.1 specification.

Schema Validation

The API implements strict schema validation for incoming messages based on the respective OCPP version specification, ensuring that the messages are correctly formatted.

Error Handling

The API provides error codes and messages for various scenarios, such as 400 for Bad Request and 401 for Unauthorized, helping clients understand and rectify issues.

Authentication and Authorization

Authentication Process

Clients must utilize the provided credentials to secure an access token, utilizing the OAuth 2.0 protocol. This protocol is employed to create an Access token, which plays a crucial role in verifying the client's identity and granting the necessary permissions to access various API resources.

Authorization Mechanism

Alongside the access token, every API request must also include a static API key within the header. This API key serves to identify the caller, adding an additional layer of security to the interactions. This combination of an access token and a static API key ensures that only authorized entities can access the API, safeguarding the integrity and confidentiality of the exchanged data.

Reference Documentation

For a more comprehensive understanding and for implementation details of authentication and authorization, developers are encouraged to refer to the Jedlix Developer Documentation.

Send TransactionEvents

The TransactionEvent endpoint is crucial for Jedlix to be informed about significant events during a charging session that could impact optimization or other calculations. This endpoint allows the CPO to forward events to the Jedlix Smart Charging platform, when it takes place.

Use Cases

  • Informing when a transaction at the Charging Station starts.
  • Informing when a transaction at the Charging Station stops.
  • Informing about changes in the charging state during a transaction at the Charging Station.

Endpoint details

URL: POST /v1/scsp/chargingstations/{uid}/events/{payload-protocol}/TransactionEvent/

Path parameters:

  • uid: Unique identifier of the charging station in the CPO platform.
  • payload-protocol: Specifies the protocol used in the payload (e.g., ocpp1.6, ocpp2.0.1).

Request Body:

  • A TransactionEvent object, structured according to the schema as defined in the respective OCPP version.

Response Codes:

  • 200: OK
  • 400: Bad Request
  • 401: Unauthorized
  • 500: Internal Server Error

Examples

  1. To inform that a transaction at the Charging Station has started
POST https://api.jedlix.com/v1/scsp/chargingstations/6502dd967c6c0071804a7108/events/ocpp2.0.1/TransactionEvent/
Content-Type: application/json
Authorization: Bearer exampleToken123
ApiKey: exampleToken456
{
    "timestamp": "2023-09-21T14:00:00Z",
    "eventType": "Started",
    "evse": {
        "id": 123,
        "connectorId": 1
    },
    "triggerReason": "Authorized",
    "transactionInfo": {
        "transactionId": "123",
        "chargingState": "Charging"
    }
}
  1. To inform that a transaction at the Charging Station has stopped
POST https://api.jedlix.com/v1/scsp/chargingstations/6502dd967c6c0071804a7108/events/ocpp2.0.1/TransactionEvent/
Content-Type: application/json
Authorization: Bearer exampleToken123
ApiKey: exampleToken456

{
    "timestamp": "2023-09-21T15:00:00Z",
    "eventType": "Ended",
    "evse": {
        "id": 123,
        "connectorId": 1
    },
    "triggerReason": "RemoteStop",
    "transactionInfo": {
        "transactionId": "123",
        "chargingState": "Idle"
    }
}
  1. To inform that the charging state during the transaction at the Charging Station has changed
POST https://api.jedlix.com/v1/scsp/chargingstations/6502dd967c6c0071804a7108/events/ocpp2.0.1/TransactionEvent/
Content-Type: application/json
Authorization: Bearer exampleToken123
ApiKey: exampleToken456

{
    "timestamp": "2023-09-21T14:30:00Z",
    "eventType": "Updated",
    "evse": {
        "id": 123,
        "connectorId": 1
    },
    "triggerReason": "ChargingStateChanged",
    "transactionInfo": {
        "transactionId": "123",
        "chargingState": "SuspendedEV"
    }
}

Best Practices

  • Fields to include:
    • evse object: The EVSE identifier and connector.
    • triggerReason: It's crucial to specify the reason that triggered the event for better understanding and processing.
    • transactionInfo: Include the chargingState and stoppedReason for comprehensive transaction details.
  • Latency: Event should be send to Jedlix within 30 seconds after the event was created on the CPO backend.

Send MeterValues

The MeterValues endpoint is essential for Jedlix to receive important measurements or Measurands. These measurements are vital for calculating an optimal charging profile, determining the costs (and savings) during a session, and providing energy market players with the necessary information for settlement. This endpoint allows the CPO to forward a meter value message to the Jedlix Smart Charging platform.

Use Cases

  • Receiving important measurements or Measurands for calculating optimal charging profiles.
  • Determining the costs and savings during a charging session.
  • Providing necessary information for settlement to energy market players.

Endpoint details

URL: POST /v1/scsp/chargingstations/{uid}/events/{payload-protocol}/MeterValues

Path parameters:

  • uid: Unique identifier of the charging station in the CPO platform.
  • payload-protocol: Specifies the protocol used in the payload (e.g., ocpp1.6, ocpp2.0.1).

Request Body:

  • A MeterValue object according to the schema as defined in the respective OCPP version.

Response Codes:

  • 200: OK
  • 400: Bad Request
  • 401: Unauthorized
  • 500: Internal Server Error

Example

  1. To send meter values to Jedlix:

    POST https://api.jedlix.com/v1/scsp/chargingstations/6502dd967c6c0071804a7108/events/ocpp2.0.1/MeterValues
Content-Type: application/json
Authorization: Bearer exampleToken123
ApiKey: exampleToken456
{
        "evseId": 123,
        "MeterValue": [
            {
                "timestamp": "2023-09-21T14:00:00Z",
                "sampledValue": [
                    {
                        "value": 5324,
                        "measurand": "Energy.Active.Import.Register",
                        "unitOfMeasure": {
                            "unit": "Wh"
                        }
                    },
                    {
                        "value": 10200,
                        "measurand": "Power.Active.Import",
                        "unitOfMeasure": {
                            "unit": "W"
                        }
                    }
                ]
            }
        ]
    }

Best Practices

  • Fields to include:
    • Energy.Active.Export.Register and Energy.Active.Import.Register: Always include these values to track energy exported to and imported from the grid.
    • Power.Active.Export and Power.Active.Import: Include these instantaneous values to track active power exported by and imported by the EV.
    • Energy.Active.Export.Interval and Energy.Active.Import.Interval: Include these values to determine the amount of energy exported and imported during a specific interval.
    • SoC: If available, always include the State of Charge of the charging vehicle in percentage for better optimization.
  • Update Frequency: Meter values should be sent to Jedlix at an update frequency of 300 seconds or lower.

Updated 11 months ago