API docs by Redocly

Hectronic POI WebAPI (3.0.0)

Download OpenAPI specification:Download

URL: https://helpdesk.hectronic.com/ License: Use of this API is restricted to authorized Hectronic partners. Terms of Service

Revision history

Revision Remark
1.0.0 The basic POI API's
2.0.0 Included authentication and transactions
3.0.0 Included the WebAPI keys

Abbreviations

  • POI: Point of Interest

Point Status

Point Status Actual Meaning
Occupied Point is available
OutOfService Point is out of service
Reserved Point is reserved
Unknown Point status is unknown

Hectronic POI WebAPI

The HecOne WebAPI allows 3rd parties to integrate with Hectronic's ecosystem.

🔍 Overview

  • Access Point of Interests (POIs) such as refuelling or EV charging locations.
  • Start and manage transactions (refuel, charge).
  • Get transaction statistics data.

💡 Use Cases

  • Show available charging stations in a mobile app
  • Show available refuelling stations in a mobile app
  • Filter based on
    • the geolocation (radius and polygon)
    • the charging or refuelling operator
  • Start a charging or refuelling transaction
  • Request status of a transaction
  • Stop a transaction

🔐 Authentication

All endpoints require a valid access token (see POST /users/login). Use the token in the Authorization header:

Authorization: Bearer <access_token>

Tokens expire and must be refreshed using POST /users/refresh_token.

🌍 Environments

  • Development: https://api.develop.hectronic.cloud
  • Test: https://api.test.hectronic.cloud
  • Production: https://api.one.hectronic.cloud

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, ...
  • POI: A Point of Interest.

Auth

This service allows the user to login into the HecOne platform in a secure way. Use access_token from the response to access the API. The token's lifetime is limited. After expiration, token has to be requested again.

Login a user to the system

Authorizations:
Authorization
Request Body schema: application/json

User credentials that needs to login. The user can login with either the pair username/password or client_id/client_secret

email
string [ 3 .. 30 ] characters .*\S.*

User Email. If this is added then we have to provide the "password" field as well.

password
string

User Password.

client_id
string.*\S.*

Client ID. If this is added then we have to provide the "client_secret" field as well.

client_secret
string

Client Secret.

Responses

Request samples

Content type
application/json
{
  • "email": "email@company.com",
  • "password": "password",
  • "client_id": 2134,
  • "client_secret": "GiJ0[R5Jr[59tb_9"
}

Response samples

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

Returns the new token based on the refresh token

Authorizations:
Authorization
Request Body schema: application/json

Refresh token of the user

refresh_token
required
string

Current refresh token

Responses

Request samples

Content type
application/json
{
  • "refresh_token": "string"
}

Response samples

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

Transactions

The Transaction Service is used for managing all of your transactions in the HecOne platform. Using this service you can create a transaction, view transaction status and patch existing transactions with more details to move forward in the business flow.

Adds Transaction

This service adds a new transaction to the system.

Authorizations:
Authorization
Request Body schema: application/json

Transaction object that needs to be added to the system. Wherever site_id is required the poi_id have to be provided.

site_id
required
string <uuid>

The unique identifier of the site for which the transaction is taking place.

point_id
string <uuid>

The unique identifier of the point for which the transaction is taking place.

Array of objects (articles)

List of articles used.

Array of objects (payments)

List of payments.

object (customer_data_object)
object (receiptV3)
terminal_transaction_number
string

Has possible two parts. First is number of fiscal printer which can be empty. Second Is a number between 0 and 9999 or 0 and 99999 (Customer-dependent). This number helps with identification, but is not unique on its own (overflow).

session_id
string <uuid>

The unique identifier of the session for which the transaction is taking place.

Responses

Request samples

Content type
application/json
{
  • "site_id": "72771e6a-6f5e-4de4-a5b9-1266c4197811",
  • "point_id": "cd99f0d9-6824-4d90-b67f-24518d22d7b6",
  • "articles": [
    ],
  • "payments": [
    ],
  • "customer_data": {
    },
  • "receipt": {
    },
  • "terminal_transaction_number": "string",
  • "session_id": "1ffd059c-17ea-40a8-8aef-70fd0307db82"
}

Response samples

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

Return a list of all transactions

Authorizations:
Authorization
query Parameters
mandator_id
required
string <uuid>

It is internal unique ID of the Mandator/Tenant of the transactions to be returned. The mandator_id is the same as the one used for the authorization token.

sort
string
Example: sort="name"

Order ascending or descending the list of transactions by a property. For descending order the sort field should be prefixed with a minus('-'). All general fileds can be sorted and for nested objects only the created_at and amount from invoice, site_name, device_name and point_name

page[offset]
number
Example: page[offset]=10

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

page[limit]
number
Example: page[limit]=20

number of items to be included in the response

start_date
required
string <date-time>
Example: start_date="2020-08-10T10:00:00Z"
end_date
required
string <date-time>
Example: end_date="2020-08-10T10:00:00Z"
fileds
string
Example: fileds=id,created_at,state,payments.amount

Required for OpenSearch approach to get only the needed fields for transactions

composite_filter_descriptor (object) or filter_descriptor (object)

Filters should be sent as encoded URI. All general fields can be filtered and for nested object only the created_at from invoice.

Responses

Response samples

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

Returns a transaction.

Authorizations:
Authorization
path Parameters
transaction_id
required
string <uuid>
Example: "8a159c56-1785-4d8b-a40e-22cb47f56bba"

The ID of the transaction to be returned.

query Parameters
additional_info
boolean
Example: additional_info=true

Key if additional infomation required.

Responses

Response samples

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

Adds or updates a payment or article to a transaction

This service add or update a transaction to the system. Updates the transaction if anything is to be changed/amended in the transaction.

Authorizations:
Authorization
path Parameters
transaction_id
required
string <uuid>
Example: 8a159c56-1785-4d8b-a40e-22cb47f56bba

The ID of the transaction to be returned.

Request Body schema: application/json
site_id
string <uuid>

The unique identifier of the site for which the transaction is taking place

point_id
string <uuid>

The unique identifier of the point for which the transaction is taking place

Array of objects (articles)
Array of objects (payments)
object (customer_data_object)
object (receiptV3)
terminal_transaction_number
null or string

Has possible two parts. First is number of fiscal printer which can be empty. Second Is a number between 0 and 9999 or 0 and 99999 (Customer-dependent). This number helps with identification, but is not unique on its own (overflow).

session_id
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "site_id": "72771e6a-6f5e-4de4-a5b9-1266c4197811",
  • "point_id": "cd99f0d9-6824-4d90-b67f-24518d22d7b6",
  • "articles": [
    ],
  • "payments": [
    ],
  • "customer_data": {
    },
  • "receipt": {
    },
  • "terminal_transaction_number": null,
  • "session_id": "1ffd059c-17ea-40a8-8aef-70fd0307db82"
}

Response samples

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

Returns transaction statistics for a mandator

Authorizations:
Authorization
query Parameters
mandator_id
required
string <uuid>

The ID of the mandator to which the transaction to be returned.

start_date
required
string <date-time>
Example: start_date="2020-08-10T10:00:00Z"
end_date
required
string <date-time>
Example: end_date="2020-08-10T10:00:00Z"
fileds
string
Example: fileds=id,created_at,state,payments.amount

Required for OpenSearch approach to get only the needed fields for transactions

composite_filter_descriptor (object) or filter_descriptor (object)

Filters should be sent as encoded URI. All general fields can be filtered and for nested object only the created_at from invoice.

Responses

Response samples

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

POIs

The Point Of Interest (POI) service fetches various details and data belonging to the sites/locations, devices and refuelling/eCharging points from the HecOne platform to be shared to the external world via custom apps.

The POI service enables mobile and web apps to display charging and refuelling points in a map. Beside the geo-position of those points it also allows to see open hours, products and more information of this site - including the availability of the points (how many are occupied or out of service).

Retrieve POIs

Returns a list of Points of Interest within the specified geographical coordinates and of the specific Refuelling/Charging type.

Usage - The 'Start' and 'End' of Latitudes and Longitudes are to be used like this: on the Map, use the Lat start , Long start for picking up the co-ordinates of the top left corner of the page; then the Lat and Long End to pick the co-ordinates at the bottom right corner of the page. The response provides the POIs within the map area on the screen. For a cleaner user experience, its important to share the Lat and Long of start, end accordingly as the user zooms in and zooms out in the screen.

Authorizations:
Authorization
Request Body schema: application/json
lat_start
required
number

The starting latitude coordinate for the geographical area within which Point of Interest(POI) will be searched.

long_start
required
number

The starting longitude coordinate for the geographical area within which Point of Interest(POI) will be searched.

lat_end
required
number

The ending latitude coordinate for the geographical area within which Point of Interest(POI) will be searched. To be used when we need to fetch the POIs between two locations (useful for routing).

long_end
required
number

The ending longitude coordinate for the geographical area within which Point of Interest(POI) will be searched. To be used when we need to fetch the POIs between two locations (useful for routing).

poi_type
required
Array of strings

The type of Point of Interest (POI) to be searched based of fuel type such as "ChargingStation" or "RefuellingStation".

con_type
Array of strings

The type of Charging Connector to be searched. Valid for ChargingStation only.

max_power
string

This field/value indicates the maximum power that a device can dispense via the point. The above example helps in filtering out POIs that have a maximum power output of 50 KwH or more.

Responses

Request samples

Content type
application/json
{
  • "lat_start": 49.18531,
  • "long_start": 7.18531,
  • "lat_end": 51.142391,
  • "long_end": 10.392011,
  • "poi_type": [
    ],
  • "con_type": [
    ],
  • "max_power": "50+"
}

Response samples

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

Get POI details by ID

Returns detailed information about a specific Point of Interest(POI) identified by its ID.

Authorizations:
Authorization
path Parameters
poi_id
required
string

The unique internal identifier for the Point of Interest(POI)/location.

Responses

Response samples

Content type
application/json
{
  • "poi_id": "4d3c9dad-dd74-4abe-a57d-06822ef04ac8",
  • "code": null,
  • "name": "BERANGER - SIEGE - 92183",
  • "operator_name": "Liikennevirta Oy (CPO)",
  • "payment_method": "App;HecOne",
  • "protocol": "OICP",
  • "street": "12 boulevard Claude Antonetti",
  • "city": "la penne sur huveaune",
  • "country": "FRA",
  • "zip": null,
  • "poi_type": "ChargingStation",
  • "lat": "43.28654",
  • "long": "5.51344",
  • "working_hours": null,
  • "total": 4,
  • "available": 1,
  • "points": [
    ],
  • "pumps": [
    ],
  • "is_favorite": false
}

Retrieve POI data using polyline.

Retrieve POI data using polyline coordinates.

Authorizations:
Authorization
Request Body schema: application/json
encoded_polyline
required
string

The polyline data to be encoded.

range
required
number

The range(in meters) the polyline data to be encoded.

poi_type
required
Array of strings

The type of Point of Interest (POI) to be searched based of fuel type such as "ChargingStation" or "RefuellingStation".

include_restricted
boolean

Whether to include restricted POIs. If this is true the response includes the restriced access POIs as well.

max_power
string

The maximum power in KwH that charging points at a particular POI (Point of interest) can dispense. This will be valid only for eCharging POIs only. The above example helps in filtering out POIs that have a maximum power output of 50 KwH or more.

Responses

Request samples

Content type
application/json
{
  • "encoded_polyline": "H4sIAAAAAAAAE219y85tO4/Vu9BGv3",
  • "range": 500,
  • "poi_type": "ChargingStation",
  • "include_restricted": false,
  • "max_power": "50+"
}

Response samples

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

Retrieve All POI filters

Retrieves various filters such as access types, connection types, product names, payment methods, protocols, refuelling operators, charging operators, and max power.

Authorizations:
Authorization

Responses

Response samples

Content type
application/json
{
  • "access": [
    ],
  • "max_power": [
    ]
}

Retrieve Specific filters for POIs

Retrieve available options for a specified filter type such as payment methods, operator names, access types, connection types, and protocols.

Authorizations:
Authorization
path Parameters
filter_type
required
string
Enum: "payment_method" "max_power" "operator_name" "access" "con_type" "product_name" "protocol"

The type of filter to retrieve.

Responses

Response samples

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

Add POI as a favorite

Add POI as a favorite

Authorizations:
Authorization
path Parameters
user_id
required
string
Example: "david"

The unique internal identifier of the user.

Request Body schema: application/json
poi_id
required
string

The unique internal identifier for the Point of Interest (POI).

Responses

Request samples

Content type
application/json
{
  • "poi_id": "ed2ad63b-eea0-4fc6-9e51-c23f9fbe18f3"
}

Response samples

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

Get POI as a favorite

Get POI as a favorite

Authorizations:
Authorization
path Parameters
user_id
required
string
Example: "david"

The unique internal identifier of the user.

Responses

Response samples

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

Remove POI as a favorite

Remove POI as a favorite

Authorizations:
Authorization
path Parameters
user_id
required
string
Example: "david"

The unique internal identifier of the user.

Request Body schema: application/json
poi_id
required
string

The unique internal identifier for the Point of Interest (POI).

Responses

Request samples

Content type
application/json
{
  • "poi_id": "ed2ad63b-eea0-4fc6-9e51-c23f9fbe18f3"
}

Response samples

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