Versions Compared

Version Old Version 1 New Version 2
Changes made by

Faruk Mercan

Faruk Mercan

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Expand
titleTable of contents
Table of Contents

POST a Vehicle to Transport Allocation

To allocate a vehicle to a transport, you must provide the following URL parameters:

  • The identifier_type that should be used to uniquely identify the transport. The available types are:

  • The identifier_value: The actual value of the identifier.

In the payload of the request, the vehicle license plate number of the vehicle that should be allocated is used.

To execute an allocation, make an authenticated POST request as shown in the example below:

https://api.transporeon.com/rtv/v1/transports/{identifier_type}/{identifier_value}/allocation

Code Block
{
    "license_plate_number": "AB 12 CD"
}
Info

Please note the following:

  • The license plate number provided in the allocation message needs to match the license plate number from the vehicle connected to Transporeon.

  • The input is normalized to alphanumeric characters. Example:

    • If there is an input "AB-12.CD" and a vehicle "AB 12 CD" is available in your connected vehicles list in Visibility Hub, it will match and succeed.

    • If there is an input "AB-12.CD" and a vehicle "AB-12.CD Harry" (or "AB 12 CD/BB 77 FD") is available in your connected vehicles list in Visibility Hub, it will not match. You need to first lookup the vehicle using the /vehicles endpoint described in section /wiki/spaces/AHID/pages/83005356, which supports partial search.

  • You can always lookup which vehicles are available for allocation by using the vehicle listing endpoint. See /wiki/spaces/AHID/pages/83005356 for more details.

  • The response will be empty, showing http code 204 No Content in case of success.

  • In case there is any problem, refer to the error message given in the response.

Allocate multiple vehicles to a transport

Info

Note before your read on: Allocating multiple vehicles to a transport is only needed when the tractor (= the pulling unit) is the part being tracked. If the trailer is tracked, it’s anyway going from the very first to the very last location and therefore no “tractor switch” is needed.

It is possible that multiple tracked vehicles are involved to execute a given transport.

This usually happens when a tractor of a truck (ie. the pulling unit) takes the trailer (where the goods are in) from a loading location A to an intermediate hub location B (cross-dock, warehouse, etc.), where another tractor hooks up the trailer and delivers it to the unloading location C.

In short: Loading (A) → Intermediate (B) → Unloading (C), where tractor 1 does A to B and tractor 2 does B to C (by pulling the trailer respectively).

There can be an arbitrary number of intermediate stops and any combination of loading/unloading stops. The example above will be used to explain the behavior below.

Info

There is no limitation to how many vehicles can be involved in a transport.

The following ways of allocating multiple vehicles to a transport are supported:

  1. Real-time allocation: When you allocate “tractor 2” on top of (the already existing allocation) “tractor 1”, Visibility switches to the tracking stream of “tractor 2” at the time the request is received (“in real-time”).
    This requires the carrier to know when to send the request in order to switch tractors.

    In order to do so, just send another POST allocation request as shown below:

    First:

    Code Block
    {
    "license_plate_number": "AB 12 CD"
}

    And then:

    Code Block
    {
    "license_plate_number": "CD 34 EF"
}
Info

In the example above, the ideal point in time to switch is when tractor 1 already dropped the trailer at intermediate location B and tractor 2 started driving towards this location.

  1. Auto-switch allocation: You can plan the vehicles involved in a transport upfront. In that case, Visibility Hub will automatically detect when and where to switch from one tractor to the next one.
    It’s done when a vehicle break is detected in the same location for both vehicles, time independent (“based on auto-switch”).

    In order to send such an allocation request, you need to include the optional field allocation_switch_type with value auto_switch for the vehicle to be switched to as shown below:

    First:

    Code Block
    {
    "license_plate_number": "AB 12 CD"
}

    And then:

    Code Block
    {
    "license_plate_number": "CD 34 EF",
    "allocation_switch_type": "auto_switch"
}

    Repeat that step until all vehicles involved are allocated. The order of allocations defines the order of switches.

DELETE an Allocation

To delete an allocation, make an authenticated DELETE request as shown in the example below, the transport status will be then unallocated:

https://api.transporeon.com/rtv/v1/transports/{identifier_type}/{identifier_value}/allocation

Info

Note that:

  • It's not needed to delete an allocation, unless you want the transport to stay unallocated or you allocated the wrong license plate accidentally.

  • If multiple vehicles are involved in the transport execution, you can just allocate on top of the existing allocation, and from this point in time, the new vehicle will be tracked (keeping the data from the previous vehicle) - see section above on how to “allocate multiple vehicles to a transport”.

  • An allocation deletion does not remove the history of the vehicle tracking data already received. It stops the vehicle tracking from this point in time.

GET the Vehicle Allocated to a Transport

To receive the allocated vehicle that is actively tracked at the moment for the given transport, make an authenticated GET request as shown in the example below:

https://api.transporeon.com/rtv/v1/transports/{identifier_type}/{identifier_value}/allocation

The response contains the vehicle license plate number as well as the datetime when the allocation was created:

Code Block
{
    "transport_allocation": {
        "created_at": "2022-12-15T02:03:47.179Z",
        "license_plate_number": "UL-RTV 24163"
    }
}