API docs by Redocly

HecOne 360 WebAPI - Transactions (1.0.0)

Download OpenAPI specification:

License: Proprietary

The Hectronic HecOne-WebAPI allows third-parties to access the HecOne ecosystem.

Terminology

Key Concepts

Understanding the following terms is essential for working with the HecOne API.

Term Description Examples
Site A limited geographical area where services are provided CityCenter (Parking), Refuelling-Station
Device A Point of Sale terminal used by customers to purchase Products Terminal, Kiosk
Point A resource consumption location. One Point can only be used by one customer at a time ParkingLot, Gas-Pump, Charging-Station
Product A consumable resource or service Parking-Tariff, Diesel, AC, DC
Transaction A record that tracks the complete lifecycle of a customer interaction, including consumed products, identification, authorization, invoice and payments
Article A product instance within a transaction with quantity, price and state
Payment A payment record within a transaction with amount, method and state

Authentication

All API requests require a valid JWT bearer token.

Authentication Flow

Authentication Flow

  1. Call the login endpoint with your credentials
  2. Receive a JWT token in the response
  3. Include the token in the Authorization header for all subsequent requests:
    Authorization: Bearer <your-token>

Authorize with HecOne 360 API

Authorize with HecOne 360 API to get a token

Request Body schema: application/json

Credentials for authorization with HecOne 360 API

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"
}

Transactions

A transaction holds the current state of a customer process. It collects consumed products, identification, authorization, invoice and payments. A transaction is assigned to one Point.

Transaction State Machine

The transaction state is computed based on the combination of Article and Payment states. Article and Payment states are set directly via the API, while the Transaction state is derived automatically.

Transaction State Diagram

State Computation Rules

Transaction State Condition
created Article is reserved + any payment state
pending Article is released or ongoing + any payment state
consumed Article is done + Payment is open/reserved (or collected with amount < invoice)
completed Article is done + Payment is collected (with amount ≥ invoice)
declined Any error or declined state in Article OR Payment
error Any error state in Article OR Payment

Article States

State Description
reserved Article is reserved but consumption has not started
released Article consumption has been authorized
ongoing Article is currently being consumed
done Article consumption is complete
declined Article was declined
error Article processing failed due to an error

Payment States

State Description
open Payment initiated but not yet processed
reserved Payment amount has been reserved
collected Payment has been collected
declined Payment was declined
error Payment processing failed due to an error

Adds a new transaction to the system

Creates a new transaction in the system. The transaction will be initialized with state created.

Authorizations:
Authorization
Request Body schema: application/json
required

Transaction object that needs to be added to the system

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)
Array of objects (payments)
object (customer_data_object)
object (receipt)
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

Hubject Session ID

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": "string"
}

Response samples

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

Return a list of transactions for the current mandator of the user

Authorizations:
Authorization
query Parameters
mandator_id
string <uuid>
Deprecated

The field is deprecated. It was added as a fallback, should not be used for new integrations and removed from older ones whenever possible.

sort
string
Example: sort=name

order ascending or descending the list of sites 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 from invoice, site_name and device_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
composite_filter_descriptor (object) or filter_descriptor (object)

Filters should be sent as encoded URI. You can filter by: created_at, amount, paid_amount, client_id, client_type, receipt_state, receipt_email, site_name, site_code, device_name, device_code, point_name, point_number, license_plate, customer_odometer, customer_driver_number, customer_vehicle_number, customer_additional_info, card_vehicle_number, card_driver_number

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
query Parameters
additional_info
boolean
Example: additional_info=true

Responses

Response samples

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

Adds or updates a payment or article to a transaction

Updates an existing transaction by adding or modifying articles and/or payments. The transaction state will be automatically recomputed based on the updated article and payment states.

Authorizations:
Authorization
path Parameters
transaction_id
required
string <uuid>
Example: 8a159c56-1785-4d8b-a40e-22cb47f56bba
Request Body schema: application/json
required
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 (receipt)
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

Hubject Session ID

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": "string"
}

Response samples

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

Returns transaction statistics for a mandator

Authorizations:
Authorization
query Parameters
mandator_id
required
string <uuid>
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
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": [
    ]
}