Driver handover actions

POST 
/api/v2/microservices/driver/action

This endpoint supports multiple actions that drivers can execute in the field. Currently supported workflows include booking handover to another vehicle or driver, which involves transferring bookings from one driver to another (a shuttling concept in logistics).

The API sends action messages to the backend, where the request payload and response payload depend on the action type.

Limitations:

• Booking handover initiation is supported only for enroute source bookings.

Sequence of Actions:

1. Initiate the transfer by obtaining a transfer token. Action type: bookings_handover_init.
2. (Optionally) Refresh the handover token if the original has expired. Action type: bookings_handover_token_update.
3. Accept the transfer of the booking by another driver by entering the token. Action type: bookings_handover_accept.
4. (Optionally) Check the status of the handover. Action type: bookings_handover_get_state. The final state must be committed; if it is not, the handover may not have been fully completed.

As soon as the transfer of the booking is confirmed by both drivers, the following actions occur:

• Source Booking: This is copied to the destination booking for the new driver and marked as completed.
• Destination Booking: The group_uid is set to the uid of the source booking and remains in the enroute state.
• Nodes of Source Booking: These are copied to new nodes assigned to the destination booking, with their state set to completed.
• Nodes of Destination Booking: These are assigned to the destination vehicle, linked to the destination booking, and their state is preserved as the original state of the source node.

To determine whether a booking has been transferred from another vehicle, you can use the group_uid. If there is a booking in the completed stage with a uid that matches the group_uid of the booking in question, it indicates that the booking has been transferred.

To retrieve a list of handovers (initiated, completed) to identify what has been handed over to audit purposes or for viewing in the UI get data mode API

Additionally, API supports optional resequencing of stops with take_next_ongoing_stop action.

If PIN has been lost, it can be requested using get data from system API

Request

Responses

200

OK

403

Error driver receieving the booking (in case the source and teh destination are the same)

{
    "error": "Handover can not be accepted by the initiator",
    "context": {}
}

404

Incorrect drvier\vehicle combination

{
    "error": "Source vehicle <id> not found or does not belong to the specified driver",
    "context": {}
}

Incorrect booking\vehicle combination

{
    "error": "Bookings <id> do not exist, have wrong state or are not assigned to vehicle <id>",
    "context": {}
}

Token expired and needs to be refreshed

{
    "error": "Token is invalid or expired.",
    "context": {}
}

Handover was not found

{
    "error": "Handover 20 not found.",
    "context": {}
}

Can't resequence nodes

{ "error":"Point nodes can not be selected: 223ce1b8-eebb-4420-9c80-cbc3e5932fcd", "context":{} }

Broken constraint

{ "error":"Node a51dc4a6-4e5b-4c2b-8a36-8a0276d7c933(b00c0003-2024-1126-0000-000000000004) at position 4 breaks PDP constraint", "context":{} }