Drivers

This section of the API is for managing your delivery personnel master data.

It includes driver’s:

• Contact details

• Delivery personnel defined skills when available.

• Restricted or allowed vehicles.

• Delivery personnel availability schedule

• Rest times and remaining driving hours when available.

• Additionally, it empowers you to update each set of information individually.

Driver Object

To create a new driver, the below-listed information details should be presented, starting with the ID, code, and name of the driver, in addition to other information about the driver when applicable.

{
  "id": "string",
  "code": "string",
  "name": "string",
  "phone": "string",
  "driverSkills": {
    "hasFirstDegreeLicense": true,
    "canTransportDangerousGoods": true,
    "dutchSpeaker": true,
    "englishSpeaker": true,
    "adr": true,
    "forkliftLicense": true
  },
  "remainingDrivingHours": {
    "remainingInBlock": 0,
    "requiredRestAfterBlock": 0,
    "remainingInDay": 0,
    "remainingInWeek": 0,
    "remainingInTwoWeeks": 0,
    "eventTime": "2023-08-20T13:32:14.906Z",
    "cardID": "string",
    "isCo": true,
    "coCardID": "string",
    "cardStatus": true,
    "activity": 0,
    "duration": 0,
    "startDay": "2023-08-20T13:32:14.906Z",
    "driveBreak": 0,
    "continuousDrive": 0,
    "continuousDriveAlarm": 0,
    "dayDrive": 0,
    "dayDriveAlarm": 0,
    "dayDriveDisposable": 0,
    "dayDriveDisposableAlarm": 0,
    "dayRest": 0,
    "weekDrive": 0,
    "weekDriveAlarm": 0,
    "weekDriveDisposable": 0,
    "weekDriveDisposableAlarm": 0,
    "twoWeekDriveDisposable": 0,
    "weekLabour": 0,
    "weekLabourAlarm": 0,
    "extendedDriving": 0,
    "extendedDrivingAlarm": 0,
    "reducedDayRests": 0,
    "reducedDayRestsAlarm": 0,
    "dayDriveMaxAllowed": 0,
    "weekDriveMaxAllowed": 0,
    "twoWeekDriveMaxAllowed": 0,
    "remainingDrivingPauseTime": 0
  },
  "availability": {
    "timeWindows": [
      {
        "date": "2023-08-20T13:32:14.906Z",
        "timeSlots": [
          {
            "startTime": 0,
            "endTime": 0
          }
        ]
      }
    ]
  },
  "restrictedVehicleCodes": [
    "string"
  ]
}

Attributes Description

Driver Object

Attribute	Data Type	Required	Description
id	String	Required	Unique identifier for the driver
code	String	Required	Unique code for the driver
name	String	Required	Name of the driver
phone	String	-	Contact number of the driver
driverSkills	Object of driver skills	-	Driver Skills is holding various skills possessed by the driver
remainingDrivingHours	Object of remaining driving hours	-	RemainingDrivingHours holding details about rest and remaining driving hours for this driver based on what is reported from the board computer when applicable
availability	Object of schdule info	-	Availability details of the driver to include his working shifts and exclude any off days
restrictedVehicleCodes	List of strings	-	List of certain vehicle codes that are only allowed for the driver

Driver Skills

Through driver skills, the driver will be identified with all or a subset of these skills, like his license type, his ability to deliver risky goods, and his speaking language. A driver with specific skills may be needed to fulfill shipments that require these skills

Attribute	Data Type	Required	Description
hasFirstDegreeLicense	Boolean	-	Indicates if the driver has a first-degree license
canTransportDangerousGoods	Boolean	-	Indicates if the driver can transport dangerous goods
dutchSpeaker	Boolean	-	Indicates if the driver is a Dutch speaker
englishSpeaker	Boolean	-	Indicates if the driver is an English speaker
adr	Boolean	-	Indicates if the driver has ADR training certificate
forkliftLicense	Boolean	-	Indicates if the driver has a forklift license

Remaining Driving Hours

This function updates the system with the driver status of rest and remaining driving hours as it comes from the board computer at a certain moment.

Attribute	Data Type	Required	Description
remainingInBlock	Number	-	Remaining driving time within the current block
requiredRestAfterBlock	Number	-	Required rest time after the current block
remainingInDay	Number	-	Remaining driving time within the current day
remainingInWeek	Number	-	Remaining driving time within the current week
remainingInTwoWeeks	Number	-	Remaining driving time within the next two weeks
eventTime	String	-	The timestamp of the event
cardID	String	-	ID of the card.
isCo	Boolean	-	Indicates if it's a co-driver
coCardID	String	-	ID of the co-driver's card
cardStatus	Boolean	-	Status of the card
activity	Number	-	Activity indicator
duration	Number	-	Duration of the activity
startDay	String	-	Timestamp indicating the start of the day
driveBreak	Number	-	Break time during drive
continuousDrive	Number	-	Continuous driving time
continuousDriveAlarm	Number	-	Alarm for continuous driving time
dayDrive	Number	-	Driving time within the day
dayDriveAlarm	Number	-	Alarm for driving time within the day
dayDriveDisposable	Number	-	Disposable driving time within the day
dayDriveDisposableAlarm	Number	-	Alarm for disposable driving time within the day
dayRest	Number	-	Rest time within the day
weekDrive	Number	-	Driving time within the week
weekDriveAlarm	Number	-	Alarm for driving time within the week
weekDriveDisposable	Number	-	Disposable driving time within the week
weekDriveDisposableAlarm	Number	-	Alarm for disposable driving time within the week
twoWeekDriveDisposable	Number	-	Disposable driving time within the next two weeks.
weekLabour	Number	-	Labour time within the week.
weekLabourAlarm	Number	-	Alarm for labour time within the week
extendedDriving	Number	-	Extended driving time
extendedDrivingAlarm	Number	-	Alarm for extended driving time
reducedDayRests	Number	-	Reduced day rests
reducedDayRestsAlarm	Number	-	Alarm for reduced day rests
dayDriveMaxAllowed	Number	-	Maximum allowed driving time within the day
weekDriveMaxAllowed	Number	-	Maximum allowed driving time within the week
twoWeekDriveMaxAllowed	Number	-	Maximum allowed driving time within the next two weeks
remainingDrivingPauseTime	Number	-	Remaining driving pause time

Availability

Availability represents the schedule info of the driver working shifts and when he would be available to execute a planned trip.

Attribute	Data Type	Required	Description
timeWindows	List	-	List of time windows for availability
date	Datetime	-	The date of the time window
timeSlots	List	-	List of time slots within the time window
startTime	Time	-	The start time of the time slot
endTime	Time	-	The end time of the time slot

Restricted Vehicle Codes

Restricted Vehicle Codes are like special labels for certain vehicles, indicating specific rules or conditions they need to follow.

Attribute	Data Type	Required	Description
restrictedVehicleCodes	List of strings	-	List of restricted vehicle codes

Descriptive Response Object

This object is indicating the overall success or failure.

Attribute	Data Type	Required	Description
Value	String	Required	The response message.
IsErrorState	Boolean	Required	Indicates if an error occurred.
ErrorMessage	String	-	The error message (if IsErrorState is true).
ErrorCode	String	-	The error code (if IsErrorState is true).

Available Endpoints

Send Driver

POST https://api.normalive.ai/SendDriver

This endpoint will add a new driver if its ID doesn’t exist and will update it if it already exists.

Headers

Name	Type	Description
authentication *	String	Bearer token acquired after authentication

Request Body

Name	Type	Description
Driver*	Object	Driver Object

200: OK Message Received Successfully

400: Bad Request Text message or code error

Descriptive Response

401: Unauthorized Invalid token

Example

In this example, a request is made to send driver details, including ID, code, name, etc. Send Driver will internally handle if the driver is new or already exists, and therefore the driver data will be updated.

{
  "id": "D123",
  "code": "DR001",
  "name": "John Doe",
  "phone": "[phone]",
  "driverSkills": {
    "hasFirstDegreeLicense": true,
    "canTransportDangerousGoods": true,
    "dutchSpeaker": true,
    "englishSpeaker": true,
    "adr": true,
    "forkliftLicense": true
  },
  "remainingDrivingHours": {
    "remainingInBlock": 480,
    "requiredRestAfterBlock": 120,
    "remainingInDay": 540,
    "remainingInWeek": 3240,
    "remainingInTwoWeeks": 7200,
    "eventTime": "2023-08-20T13:32:14.906Z",
    "cardID": "CARD001",
    "isCo": false,
    "coCardID": "",
    "cardStatus": true,
    "activity": 1,
    "duration": 60,
    "startDay": "2023-08-20T13:32:14.906Z",
    "driveBreak": 30,
    "continuousDrive": 120,
    "continuousDriveAlarm": 0,
    "dayDrive": 540,
    "dayDriveAlarm": 0,
    "dayDriveDisposable": 480,
    "dayDriveDisposableAlarm": 0,
    "dayRest": 780,
    "weekDrive": 3240,
    "weekDriveAlarm": 0,
    "weekDriveDisposable": 2760,
    "weekDriveDisposableAlarm": 0,
    "twoWeekDriveDisposable": 6000,
    "weekLabour": 20,
    "weekLabourAlarm": 0,
    "extendedDriving": 60,
    "extendedDrivingAlarm": 0,
    "reducedDayRests": 2,
    "reducedDayRestsAlarm": 0,
    "dayDriveMaxAllowed": 600,
    "weekDriveMaxAllowed": 4320,
    "twoWeekDriveMaxAllowed": 7200,
    "remainingDrivingPauseTime": 0
  },
  "availability": {
    "timeWindows": [
      {
        "date": "2023-08-20T13:32:14.906Z",
        "timeSlots": [
          {
            "startTime": 480,
            "endTime": 960
          }
        ]
      }
    ]
  },
  "restrictedVehicleCodes": [
    "V001",
    "V002"
  ]
}

Response

{
  "Value": "Ok",
  "IsErrorState": false,
  "ErrorMessage": "Message Received Successfully",
  "ErrorCode": "200"
}

Update Driver Availability

POST https://api.normalive.ai/UpdateDriverAvailability

This endpoint is for updating the availability of the driver.

Headers

Name	Type	Description
Authorization*	String	Bearer token acquired after authentication

Request Body

Name	Type	Description
driverID*	String	Driver ID
availability*	Object	Availability object

200: OK Message Received Successfully

400: Bad Request Text message or code error

Descriptive Response

401: Unauthorized Invalid token

{
  "driverID": "string",
  "availability": {
    "timeWindows": [
      {
        "date": "2023-12-07T12:02:16.771Z",
        "timeSlots": [
          {
            "startTime": 0,
            "endTime": 0
          }
        ]
      }
    ]
  }
  }
  

Update Driver Remaining Hours

POST https://api.normalive.ai/UpdateDriverRemainingHours

Updating the driver's occupation and remaining time.

Headers

Name	Type	Description
Authorization*	String	Bearer token acquired after authentication

Request Body

Name	Type	Description
driverID*	String	Driver ID
remainingDrivingHours*	Object	Remaining Driving hours Object

200: OK Message Received Successfully

400: Bad Request Text message or code error

Descriptive Response

401: Unauthorized Invalid token

{
  "driverID": "string",
  "remainingDrivingHours": {
    "eventTime": "2023-12-07T12:02:45.736Z",
    "cardID": "string",
    "isCo": true,
    "coCardID": "string",
    "cardStatus": true,
    "activity": 0,
    "duration": 0,
    "startDay": "2023-12-07T12:02:45.736Z",
    "driveBreak": 0,
    "continuousDrive": 0,
    "continuousDriveAlarm": 0,
    "dayDrive": 0,
    "dayDriveAlarm": 0,
    "dayDriveDisposable": 0,
    "dayDriveDisposableAlarm": 0,
    "dayRest": 0,
    "weekDrive": 0,
    "weekDriveAlarm": 0,
    "weekDriveDisposable": 0,
    "weekDriveDisposableAlarm": 0,
    "twoWeekDriveDisposable": 0,
    "weekLabour": 0,
    "weekLabourAlarm": 0,
    "extendedDriving": 0,
    "extendedDrivingAlarm": 0,
    "reducedDayRests": 0,
    "reducedDayRestsAlarm": 0,
    "dayDriveMaxAllowed": 0,
    "weekDriveMaxAllowed": 0,
    "twoWeekDriveMaxAllowed": 0,
    "remainingDrivingPauseTime": 0
  },
}

Update Driver Data

POST https://api.normalive.ai/UpdateDriverData

This endpoint is for any changes or updates in the main driver's data.

Headers

Name	Type	Description
Authorization*	String	Bearer token acquired after authentication

Request Body

Name	Type	Description
id*	String	Driver ID
code*	String	Driver Code
name*	String	Driver's Name
phone	String	Driver's phone number
driverSkills	Object	Driver skills object
restrictedVehicles	List of strings	List of vehicle codes that are restricted to the driver

200: OK Message Received Successfully

400: Bad Request Text message or code error

Descriptive Response

401: Unauthorized Invalid token

{
  "id": "string",
  "code": "string",
  "name": "string",
  "phone": "string",
  "driverSkills": {
    "hasFirstDegreeLicense": true,
    "canTransportDangerousGoods": true,
    "dutchSpeaker": true,
    "englishSpeaker": true,
    "adr": true,
    "forkliftLicense": true
  },
  "restrictedVehicles": [
    "string"
  ]
  }

Delete Driver

POST https://api.normalive.ai/DeleteDriver

Endpoint for deleting a driver from your system.

Headers

Name	Type	Description
Authorization*	String	Bearer token acquired after authentication

Request Body

Name	Type	Description
driverId*	String	Driver ID

200: OK Message Received Successfully

400: Bad Request Text message or code error

Descriptive Response

401: Unauthorized Invalid token

{
  "driverId": "string"
}