Get finished charges

Description#

This endpoint is used to retrieve the charges performed on your chargeboxes in a specific time span.

Request format#

Method: GET

Endpoint: https://api.thor.tools/latest/integration/charges/finished

Querystring parameters:

Name	Default value	Description
chargebox	null	Optional. If you want to retrieve only the charges performed on a specific chargebox, please provide here its ID.
from	null	Mandatory. The date from which you want to retrieve the charges. Must be in the `YYYYMMDD` format
to	null	Mandatory. The date to which you want to retrieve the charges. Must be in the `YYYYMMDD` format

Response format#

The response is a JSON containing the information related to the requested chargebox with the following fields:

Field name	Type	Description
count	Integer	The number of charges retrieved.
items	Array	The list of charges.
items[].chargebox	String	The chargebox id.
items[].connector	Integer	The connector number where the charge was performed.
items[].date_finished	Integer	The epoch in milliseconds that represents the time of the charge stop.
items[].date_started	Integer	The epoch in milliseconds that represents the time of the charge start.
items[].energy	Integer	The energy in Wh that was delivered to the vehicle.
items[].id	Integer	The transaction identifier.
items[].id_tag	String	The RFID used to start the charge (`null` if the charge was started remotely or using the API).
items[].payment	Object	The payment information (`null` if the charge was free).
items[].payment.currency	Currency	The currency of the payment.
items[].payment.start	Float	The amount added at the start of the transaction.
items[].payment.method	Method	The payment method used to pay for the charge.
items[].payment.price	Float	The amount paid for the charge.
items[].payment.success	Boolean	`true` if the payment has be done succesfully.
items[].payment.transaction	String	The transaction ID given by the payment provider.
items[].payment.nayaxID	String	The transaction ID given by Nayax in their dashboard.
items[].payment.machineID	String	The machine ID given by Nayax in their dashboard.
items[].payment.siteID	String	The ID of the Nayax server that processed the transaction.
items[].type	ChargeType	The type of transaction.
items[].user	String	The Thor registered user identifier who started the charge.
users	Object	The details of the users who started the charges provided in the `items` element.
users[].address	String	The user's address.
users[].city	String	The user's city.
users[].country	String	The user's country.
users[].email	String	The user's e-mail address.
users[].name	String	The user's name.
users[].tax_vat	String	The user's tax code or VAT number.
users[].zip_code	String	The user's zip code.

A succesful response is returned with an HTTP status code 200 - OK

caution

The energy fields might be equal to 0 if the chargebox does not provide metering data related to the charges.

Example response#

{
    "count": 5,
    "items": [
        {
            "chargebox": "cb-kmn12iuhn313ui1",
            "connector": 3,
            "date_finished": 1611051111690,
            "date_started": 1611051097702,
            "energy": 0,
            "id": 4,
            "id_tag": null,
            "payment": null,
            "type": "remote",
            "user": "53015afc-435a-4396-bf31-2c599da5c595"
        },
        {
            "chargebox": "cb-oi12j398uiuh123",
            "connector": 4,
            "date_finished": 1611051289690,
            "date_started": 1611051124654,
            "energy": 0,
            "id": 5,
            "id_tag": null,
            "payment": null,
            "type": "remote",
            "user": "53015afc-435a-4396-bf31-2c599da5c595"
        },
        {
            "chargebox": "cb-oi12j398uiuh123",
            "connector": 1,
            "date_finished": 1611053266588,
            "date_started": 1611053249000,
            "energy": 0,
            "id": 1,
            "id_tag": "9871238783",
            "payment": null,
            "type": "local",
            "user": "53015afc-435a-4396-bf31-2c599da5c595"
        },
        {
            "chargebox": "cb-183u123oix92d32",
            "connector": 1,
            "date_finished": 1612167079046,
            "date_started": 1612167051594,
            "energy": 0,
            "id": 628,
            "id_tag": null,
            "payment": {
                "currency": "eur",
                "method": "stripe",
                "price": 14.35,
                "success": true,
                "transaction": "pi_xxxxxxxxxxxxxxxxx"
            },
            "type": "remote",
            "user": "731f9244-2768-43bd-a3c0-cbfcdbea5307"
        }
    ],
    "users": {
        "731f9244-2768-43bd-a3c0-cbfcdbea5307": {
            "address": "Nostrand Ave., Brooklyn",
            "city": "New York",
            "country": "US",
            "email": "john.doe@gmail.com",
            "name": "John Doe",
            "tax_vat": "XXXYYY123QQABC",
            "zip_code": "11225"
        },
        "53015afc-435a-4396-bf31-2c599da5c595": {
            "address": "Allen St",
            "city": "New York",
            "country": "US",
            "email": "jane.morris@gmail.com",
            "name": "Jane Morris",
            "tax_vat": "AAASSDDDD999ZXC",
            "zip_code": "10002"
        }
    }
}

Error response#

The following errors are returned if something went wrong while processing the request:

HTTP status code	Message	Description
400	MissingDates	You didn't provide the `from` and `to` parameters in the querystring
400	InvalidDateFormat	The `from` and `to` parameters are not in the `YYYYMMDD` format
403	APIKeyNotFound	An invalid API key was given in the header of the request.
403	RestAPINotEnabled	REST API integration is set as disabled in the administration dashboard.
403	InvalidSourceIPAddr	The request comes from an IP address that is different from the one given in the REST API integration configuration.
500	InternalServerError	Something unexpected went wrong while executing the request.

Enums#

Currency#

Type: String

These are the possible types of currency:

eur for Euros
usd for United State Dollars
gpb for Great Britain Pounds

Method#

These are the possible types of payment method:

"stripe" for charges started with Stripe
"paypal" for charges started with PayPal
"nayax" for charges started with Nayax
"rfid" for charges started with a RFID card
"gratis" for charges started on a chargebox with a free custom payment set
"free" for charges started from Thor dashboard
null for charges started on a chargebox with a free payment set from webapp
undefined for charges started with a RFID card with infinite budget

ChargeType#

These are the possible types of charge:

remote for charges started using the web app
local for charges started using an RFID card
api for charges started using an API request