Overview

Transaction Management API#

A transaction is a charging event that occurs at a specific time for a specific charger on a specific connector. Each transaction is represented by an unique identifier called TransactionID. The Transaction Management API allows you to read the transaction details for a selected time duration. The transaction details can also be retrieved for a selected chargerId, connectorId, vehicleId, or transactionID.

All responses are received in JSON format. The query responses are shown as a list. You can specify the number of list items shown in a page. By default, 100 items are displayed in a single page. The results can be sorted by TransactionID, StartAt, and EndAt of the transaction.

API Usage#

You must be authorized to use Transaction Management API. See Token Management API for more information on how to create and use the access token.

Get All Transaction#

This method allows you to fetch all the transaction details for a selected time duration.

Prepare Request#

You can query with various parameters like from, to, order, and limit. For more information, see Transactions API Reference.

Example Request#

Note

Use the server URL applicable to your region. See [API Reference](./transaction_management_api_reference.md) for available server URLs applicable to your region.

export TOKEN = <YOUR_TOKEN>

export CHARGER_ID = <CHARGER_ID>
export CONNECTOR_ID = <CONNECTOR_ID>
export VEHICLE_ID = <VEHICLE_ID>
export ORDER_BY = <ORDER_BY>
export ORDER = <ORDER>
export PAGE = <PAGE>
export LIMIT = <LIMIT>

curl --location --request GET 'https://api.eu.depot.emobility.io/v2/transactions?chargerId=$CHARGER_ID&connectorId=$CONNECTOR_ID&vehicleId=$VEHICLE_ID&orderBy=$ORDER_BY&order=$ORDER&page=$PAGE&limit=$LIMTIT' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer $TOKEN'

Response Body#

Successful response returns 200 HTTP status code with response body as array of Transaction schema. For more information, see Transactions API Reference.

Example Response#

[
  {
    "TransactionID": 010203,
    "ChargerID": "xyz",
    "ConnectorID": 1,
    "StartAt": "2022-10-27T08:52:34.000Z",
    "EndAt": "2022-10-27T08:53:07.000Z",
    "InitialSoC": 0,
    "VehicleID": "0123",
    "Initiator": "0123",
    "EndSoC": 0,
    "EnergyDelivered": 0,
    "EndResult": "Local",
    "ExtraInfo": {
        "Initiator": "0123"
    },
    "SessionStartTime": null,
    "SessionEndTime": null,
    "InsertedAt": "2022-10-27T08:53:07.000Z"
  },
  {
    "TransactionID": 010204,
    "ChargerID": "xyz",
    "ConnectorID": 1,
    "StartAt": "2022-10-27T06:15:11.000Z",
    "EndAt": "2022-10-27T06:51:34.000Z",
    "InitialSoC": 32,
    "VehicleID": "0123",
    "Initiator": "0123",
    "EndSoC": 100,
    "EnergyDelivered": 12833,
    "EndResult": "Incomplete",
    "ExtraInfo": {
        "Initiator": "0123"
    },
    "SessionStartTime": null,
    "SessionEndTime": null,
    "InsertedAt": "2022-10-27T06:51:34.000Z"
  },
  ...
]

If you are using this API to fetch the transactions periodically for a relative time frame (e.g. fetching transactions for the last 24-hours), then it is recommended to use filter by InsertedAt. This is to ensure that offline transactions that were reported to DepotFinity after the relative time frame, are also included in the response.

Example Scenario: A daily run fetches transactions periodically for the last 24 hours, Initially Charger is online#

03-05-2023 10:00 AM:
- Transaction 1 started
03-05-2023 10:30 AM:
- Transaction 1 stopped
03-05-2023 11:00 AM:
- Charger went offline
03-05-2023 02:00 PM:
- Transaction 2 started
03-05-2023 02:30 PM:
- Transaction 2 stopped
04-05-2023 06:00 AM:
- Daily run `filterBy: StartAt` fetches (Transaction 1)
04-05-2023 10:30 AM:
- Transaction 3 started
04-05-2023 11:00 AM:
- Transaction 3 stopped
04-05-2023 12:00 PM:
- Charger Online
05-05-2023 06:00 AM:
- Daily run `filterBy: StartAt` fetches (No Transactions)
05-05-2023 06:10 AM:
- Daily run with `filterBy: InsertedAt` fetches transactions that were reported in offline (Transaction 2, Transaction 3)

Get Specific Transaction#

This method allows you to fetch the details for a specific transaction.

Prepare Request#

Set the request path parameter TransactionID for the transaction to be retrieved. For more information, see Transactions API Reference.

Example Request#

Note

Use the server URL applicable to your region. See [API Reference](./transaction_management_api.md) for available server URLs applicable to your region.

export ACCESS_TOKEN = <YOUR_ACCESS_TOKEN>

export TRANSACTION_ID = <YOUR_TRANSACTION_ID>

curl --location --request GET 'https://api.eu.depot.emobility.io/v2/transactions/$TRANSACTION_ID' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer "$ACCESS_TOKEN'

Response Body#

Successful response returns 200 HTTP status code with response body as Transaction schema. For more information, see Transactions API Reference.

Example Response#

{
  "TransactionID": 010203,
  "ChargerID": "abcd",
  "ConnectorID": 1,
  "StartAt": "2022-11-18T04:39:02.000Z",
  "EndAt": "2022-11-18T04:40:12.000Z",
  "InitialSoC": 59,
  "VehicleID": "9876",
  "Initiator": "9876",
  "EndSoC": 0,
  "EnergyDelivered": 0,
  "EndResult": "Incomplete",
  "ExtraInfo": {
      "Initiator": "9876"
  },
  "SessionStartTime": null,
  "SessionEndTime": null,
  "InsertedAt": "2022-11-18T04:40:12.000Z"
}