API docs by Redocly

HecConnect 360 API (1.0.0)

Download OpenAPI specification:Download

Revision history

Revision Date Remark
1.0 12 May 2023
  • Added examples for errors
1.1 7 Sept 2023
  • Add description for point_number and device_state
  • Adapt charging preparation flow in sequence diagram
1.2 27 Sept 2023
  • terminal Backend in CPMS Login
  • New Timezone format
  • Charging flow
    • payment medium adaptions
    • article state
  • Update running transaction
    • update 2 articles
    • remove invoice
1.3 29 Sept 2023
  • Added examples for errors
1.4 9 Oct 2023
  • adaption of authentication method (terminal backend towards CPMS)
  • Additional usage notes
  • Removed unnecessary enums
  • change in Response (more optional fields)
  • Information of Stop charging flow
    • PATCH Transaction is always required (even when stop was triggered by the terminal or the charging device)
1.5 30 Oct 2023
  • Start charging
    • optional field in start charging request
    • add quantity and tax_amount
  • Update charging with meter values
    • In Request add quantity and tax_amount
    • Response was changed to Http Status Code: 204
  • Stop charging from charging device / finalization of charging
    • In Request add quantity and tax_amount
    • Response was changed to Http Status Code: 204
  • Finalizing payment
    • Response was changed to Http Status Code: 204
  • Adaption or wording
    • unite_price changed to unit_price
  • Updating of HTTP Response Codes
1.6 28 Nov 2023
  • the fields for Opening Hours are now mandatory instead of optional
1.7 22 Jan 2024
  • start_time is optional for response from start transaction
  • added start_time & end_time as optional parameters for patch transaction
1.8 31 May 2024
  • update patch point API requests and responses
1.9 13 June 2024
  • Change response of update point to return an array of objects
2.0 17 July 2024
  • Adjust URLs for login and start charging APIs
  • Add request direction on each endpoint for clarity
2.1 15 July 2024
  • Add update CDR request on Patch Transaction endpoint
2.2 20 Sept 2024
  • added new endpoint for retrieving terminals
2.3 14 Oct 2024
  • Add enums for plug types
  • Add lengths for field specifications
  • Update unit_measure in examples
  • Add examples for charging with more than one article
  • Set default value for default_language field
  • Add payment fields accepted values
  • Add product unit measure accepted values

Abbreviations

CPMSCharge Point Management System
EV DriverElectric car driver
EVSEElectric Vehicle Supply Equipment
OCPPOpen Charge Point Protocol

Ocpp states

OCPP States Mapped states
available available
Preparing (received from charging point when a plug was plugged in the vehicle) occupied
Preparing (received as result of RemoteStart) reserved
Charging in_use
SuspendedEV in_use
SuspendedEVSE in_use
Finishing occupied
Unavailable out_of_order
Faulted out_of_order
Offline out_of_order

Introduction

This documentation describes how a CPMS and Terminal backend can communicate with each other for allowing physical debit and credit payments.

Terminology

  • Site: A Site is a limited geographical area. Examples: CityCenter (Parking), Refuelling-Station
  • Device: Each Device is a Point of Sale. Customer using this to buy Products
  • Point A Point is used to consume a Product. One Point can only be used by one customer at a time. Example: ParkingLot, Gas-Pump, Charging-Station
  • Product A Product is a consumable resource. Example: Parking-Tariff, Diesel, AC, DC, ...


An example how a charging site can look is shown in the picture below:


Sequence diagram


State handling


Auth


The authorization process can differ between the CPMS System and the Terminal Backend System. The Terminal Backend System authorization method is described below. The CPMS authorization method can differ and needs to be discussed and defined with the terminal backend system. A suggestion is also added below.

oAuth-Client credentials

  • Every tenant in the CPMS system will have it´s own client_id & client_secret. The terminal backend request the token after initial onboarding phase and will use the received Bearer-Token for each request
  • The CPMS system will have only one client_id & client_secret in the terminal backend system. The same token will be used for patching different transaction, sites, product of different tenants
Direction: terminal backend -> CPMS

Login into HecConnect

Direction: CPMS → terminal backend

Authorizations:
Authorization
Request Body schema: application/json

Credentials for connection into HecConnect

client_id
required
string
client_secret
required
string

Responses

Request samples

Content type
application/json
{
  • "client_id": "string",
  • "client_secret": "string"
}

Response samples

Content type
application/json
{
  • "access_token": "jwt access token",
  • "expires_in": 3600,
  • "token_type": "Bearer",
  • "refresh_token": "jwt refresh token"
}

Onboarding


Requests the terminal backend will do on CPMS API to onboard Sites, Devices, Points and Products

Get CPMS Sites

This request will:

  • return all available sites for the client that he has access to
  • return basic information to show a list of sites

Direction: terminal backend → CPMS

Authorizations:
Authorization
query Parameters
sort
string
Example: sort=name

order ascending or descending the list of items by a property. For descending order the sort field should be prefixed with a minus('-')

start
number
Example: start=10

number of items that should be skipped and not included in the response

limit
number
Example: limit=20

number of items to be included in the response

Responses

Response samples

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

Get CPMS Devices

This request will:

  • return all available devices for the client that he has access to
  • return basic informations to show a list of devices

Direction: terminal backend → CPMS

Authorizations:
Authorization
query Parameters
sort
string
Example: sort=name

order ascending or descending the list of items by a property. For descending order the sort field should be prefixed with a minus('-')

start
number
Example: start=10

number of items that should be skipped and not included in the response

limit
number
Example: limit=20

number of items to be included in the response

Responses

Response samples

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

Get CPMS Points

This request will:

  • return all available points for the client that he has access to
  • return basic informations to show a list of points
  • return information of linked products

Direction: terminal backend → CPMS

Authorizations:
Authorization
query Parameters
sort
string
Example: sort=name

order ascending or descending the list of items by a property. For descending order the sort field should be prefixed with a minus('-')

start
number
Example: start=10

number of items that should be skipped and not included in the response

limit
number
Example: limit=20

number of items to be included in the response

Responses

Response samples

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

Get CPMS Products

This request will:

  • return all available products for the client that he has access to
  • return basic information to show a list of products

Direction: terminal backend → CPMS

Authorizations:
Authorization
query Parameters
sort
string
Example: sort=name

order ascending or descending the list of items by a property. For descending order the sort field should be prefixed with a minus('-')

start
number
Example: start=10

number of items that should be skipped and not included in the response

limit
number
Example: limit=20

number of items to be included in the response

Responses

Response samples

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

Trigger CPMS onboarding of sites, devices, points and products

This request will:

  • onboard all CPMS sites, devices, points and products into the terminal backend's system

Direction: CPMS → terminal backend

Authorizations:
Authorization
Request Body schema: application/json

The action the request shall accomplish - onboard or sync

action
required
string
Enum: "onboard" "sync"

Responses

Request samples

Content type
application/json
{
  • "action": "onboard"
}

Response samples

Content type
application/json
{
  • "data": "onboarding process has started"
}

Updating


Update a state of a charging point, update of prices for a product/ charging point

Update charging point

This request will:

  • update a state of a certain charging point
  • OR update a price of a certain product/tariff of a certain point

Direction: CPMS → terminal backend

Authorizations:
Authorization
path Parameters
site_id
required
string <uuid>
point_id
required
string <uuid>
Request Body schema: application/json

The new status of the charging point OR the new prices for point products

One of
object (update_point_status_request)

Responses

Request samples

Content type
application/json
Example
{
  • "data": {
    }
}

Response samples

Content type
application/json
Example

Point status was successfully updated

{
  • "data": {
    }
}

Charging

Start Charging

This request will:

  • inform the CPMS that a charging session on the selected charging point can be started

Direction: terminal backend → CPMS

Authorizations:
Authorization
Request Body schema: application/json
One of
object

Responses

Request samples

Content type
application/json
Example

Start charging for one article

{
  • "data": {
    }
}

Response samples

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

Patch Transaction

This request will: (for update of meter values)

  • update the article information based on the received meter values of the charger
  • will finalize a transaction after receiving the “accepted” information of a RemoteStop and receiving the final values in Stop transaction

OR, in case of updating CDR:
  • update the Charge Detail Record for a transaction

OR, in case of stopping transaction from charging device:
  • inform the terminal backend system that a charging session on the selected charging point has stopped

Direction: CPMS → terminal backend

Authorizations:
Authorization
path Parameters
transaction_id
required
string <uuid>
Request Body schema: application/json

Updated article with new meter values OR Article with state done on transaction stopped from charging device. In case of multiple articles, all of them need to be updated.

One of
object

Responses

Request samples

Content type
application/json
Example

Stop charging for one article

{
  • "data": {
    }
}

Response samples

Content type
application/json

Parse error

{
  • "errors": [
    ]
}

Stop charging from payment terminal / Finalize payment

This request will: (for Stop charging from payment terminal)

  • inform the CPMS that a charging session on the selected charging point can be stopped
OR, for finalizing payment:
  • inform the CPMS that the clearing was successfully done and the transaction is completed

Direction: terminal backend → CPMS

Authorizations:
Authorization
path Parameters
transaction_id
required
string <uuid>
Request Body schema: application/json
One of
object

Responses

Request samples

Content type
application/json
Example
{
  • "data": {
    }
}

Response samples

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

Terminals

Get terminals

This request will:

  • return all available terminals for the client that he has access to
  • return basic information to show a list of terminals

Direction: CPMS → terminal backend

Authorizations:
Authorization
query Parameters
sort
string
Example: sort=name

order ascending or descending the list of items by a property. For descending order the sort field should be prefixed with a minus('-')

start
number
Example: start=10

number of items that should be skipped and not included in the response

limit
number
Example: limit=20

number of items to be included in the response

Responses

Response samples

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