Articles in this section

Fleet API

Niklas Wallner
  • Updated
Follow

General information about API usage

With the help of the be.ENERGISED API you have the possibility to automate and control functions of the software via third party systems. You can make the necessary settings in be.ENERGISED under Settings/System settings/API settings.

 

Please note that the API requires a paid license.

 

User and system tokens are available for accessing the API. User tokens each have limited data access to the user's data, system tokens have access to all information in your client.

 

 

What is the Fleet API?

The Fleet API gives you the possibility to create CRM contact, portal user, and card. Fleet customers can then build their own registration forms for their individual fleets based on this API. The fleet drivers can then register with this user in the respective fleet APP and have the correct contract assigned immediately (registration and contract creation are deactivated in the app). The API is secured with a token that can be read from the settings page in your be.ENERGISED instance. The token must be passed as header x-api-token within each request.

 

 

Requirements to use the Fleet API

  • you have created an API token in the be.ENERGISED backend
  • you have configured a company (in be.ENERGISED under User Mmanagement/Companies/Registered companies)
  • you have configured a billing contact
  • you have configured a rate

 

Endpoints

The API offers two endpoints: first for providing the driver access via creating CRM contact, portal user and card (register endpoint), second for activating portal user and card (confirm endpoint).

 

Register Endpoint

The register endpoint creates a CRM contact, portal user, and card. The endpoint accepts the following parameters:

 

Request Parameters

Parameter Required Description
company_id Yes Unique company ID
contact Yes contact object containing all required fields and optional fields
user Yes user object containing all required fields and optional fields
card Yes card object containing all required fields and optional fields

 

Contact Object Parameters

Parameter Required Description
name Yes Full name of contact
first_name No First name of contact
gender No Gender of the contact, 0 = company, 1 = male, 2 = female
street No Street of contact
zip No Post code of contact
city No City of contact
country No Two-character country code of contact
email No Email of contact
phone No Phone number of contact
customer_number No Customer number of contact
comment No Comment of contact

 

User Object Parameters

Parameter Required Description
email Yes Email of the account
password Yes Password of the account
account_locale No Account locale, e.g. de_DE

 

Card Object Parameters

Parameter Required Description
card_no Yes Card number
rate_id Yes UUID for the rate displayed in be.ENERGISED Rate management
billing_contact_id Yes Unique billing contact identifier
label No Card label
customer_reference No Customer reference
comment No Comment of card
emp No EMP (e.g. AT-HTB) that will be assigned to the card

 

Sample Request

curl --location --request POST 'https://yourinstancename.beenergised.cloud/api/fleet/v1/register' \
    --header 'x-api-token: your_token' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "company_id": "Company UUID",
        "contact": {
            "name": "Name",
            "gender": "Gender",
            "city": "City",
            "customer_number": "Customer Number",
            "comment": "Comment"
        },
        "user": {
            "email": "Email",
            "password": "Password",
            "locale": "Locale"
        },
        "card": {
            "card_no": "Card Number",
            "rate_id": "Rate UUID",
            "billing_contact_id": "Billing Contact UUID"
        }
    }'

 

Sample Response

{
    "status": "success",
    "data": {
        "contact_id": "created_contact_id",
        "user_id": "created_user_id",
        "card_id": "created_card_id"
    }
}

 

 

Confirm Endpoint

The confirm endpoint activates the portal user and a card. The endpoint accepts the following parameters:

 

Request Parameters

Parameter Required Description
card_id Yes Unique card identifier
user_id Yes Unique user identifier

 

Sample Request

curl --location --request PUT 'https://yourinstancename.beenergised.cloud/api/fleet/v1/confirm' \
  --header 'x-api-token: your_token' \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "user_id": user_id_to_activate
      "card_id": card_id_to_activate,
  }'

 

Sample Response

{
    "status": "success",
    "data": {
        "user_id": "activated_user_id",
        "card_id": "activated_card_id"
    }
}

 

 


Version: 2022-09-15 15:58:39 UTC

Related articles