↑
Planning

List of parameters

Mandatory parameters are denoted with “*“, the others are optional. The list of parameters is described separately by the groups they belong to:

startDate

The parameter startDate indicates the start date and time to be considered for every calculation of the logistical problem.

It is a mandatory parameter and must be in the timestamp format. Example:

"startDate": 1583492400000

depots*

The parameter depots is an array of objects, where each object represents a warehouse or distribution center. It could also be a physical store from where the product will be delivered.

The depots will be referenced in the operations as the origin of the product for delivery, or as the destination if it is a collection operation.

In the request, you can define one or more depots to handle the operations.

Below are the parameters available in depots:

  • name – Single text of the deposit name. Used to refer to Operations and identify it in the result.
  • coordinates – Geographical coordinates in decimal degrees of latitude and longitude:
    • latitude – Numerical value in decimal degrees. It should be between -90.0 and 90.0. Example: -23.6987.
    • longitude – Numerical value in decimal degrees. It should be between -180.0 and 180.0. Example: -45.7347.
  • logisticConstraints – Text with reference to the name of logisticConstraint .
  • logisticZones – (Optional) Array with the names of the logistics zones to which the depot belongs. They must be unique and must have the same name declared on logisticZones.
"depots": [
        {
            "name": "MG - BELO HORIZONTE DEPÓSITO",
            "coordinates": {
                "latitude": -19.9251768,
                "longitude": -43.9509008
            },
            "logisticConstraints": "DEFAULT",
            "logisticZones": ["bh"]
        },
        {
            "name": "BH - Loja 1",
            "coordinates": {
                "latitude": -19.8849981,
                "longitude": -44.0089124
            },
            "logisticConstraints": "DEFAULT",
            "logisticZones": ["bh"]
        }
]

logisticConstraints*

The parameter logisticConstraints is an array of objects, where each object will represent a group of logistics rules to be considered in planning and optimization, such as loading and unloading times, for example.

Each logistical rule must be associated with the depots or site to which it applies.

  • name – Text of the logistics rule name. Used to reference in depots and websites.
  • siteLoadingFixedTime – (Optional) Integer with fixed charging time in seconds.
  • siteUnloadingFixedTime – (Optional) Integer with fixed download time in seconds.
  • unloadingPositionInRoute – (Optional) Position on the route for unloading. Possible values: [INDIFFERENT, FIRST, LAST, ALONE].
    • Example 1: If a site has the rule of "unloadingPositionInRoute": "FIRST", this site’s operation will be executed first on the route to make the delivery.
    • Example 2: If a site has the rule of "unloadingPositionInRoute"": "LAST", this site’s operation will run last on the route to make the delivery.
    • Example 3: If a site has the rule of "unloadingPositionInRoute"": "ALONE", the operation of this site will be carried out alone, with an exclusive route to carry out the delivery.
    • Example 4: If a site has the rule of "unloadingPositionInRoute"": "INDIFFERENT", this site’s operation will be executed at any position on the delivery route.
  • loadingPositionInRoute – (Optional) Position on the route for loading. Possible values: [INDIFFERENT, FIRST, LAST, ALONE].
"logisticConstraints": [
        {
            "name": "Regras-Depot",
            "siteLoadingFixedTime": 1200
        },
        {
            "name": "Regras-Entrega-Rápida",
            "siteUnloadingFixedTime": 300,
            "unloadingPositionInRoute": "FIRST"
        }
],

vehicleTypes*

The parameter vehicleTypes is an array of objects, where each object represents a type of vehicle. Vehicle types are the characteristics of the vehicles that will be used in the planning, such as weight and volume supported, for example.

API will check the capacity of the vehicles to distribute the weights and volumes of the products in each operation for the best logistical optimization.

Mandatory parameters

  • name – Single text with vehicle type. Used to be referenced in vehicles.
  • maxVolume – Numeric value (double) with the maximum volume supported by the vehicle.
  • maxWeight – Numeric value (double) with the maximum weight supported by the vehicle.
  • size – Numeric value (integer) with the size of the vehicle.

Example with mandatory parameters

"vehicleTypes": [
        {
            "name": "VUC",
            "maxVolume": 20,
            "maxWeight": 1200,
            "size": 1
        },
        {
            "name": "3/4",
            "maxVolume": 30,
            "maxWeight": 1500,
            "size": 1
        }
],

Optional parameters

  • characteristics – Free text to describe the vehicle’s characteristics.
  • maxSitesNumber – Integer with the maximum number of sites the vehicle will visit per route.
  • compartmentsAccessMode – Text with how to access the vehicle’s load compartment. Allowed values:
    • ALL_COMPARTMENTS – Indicates possible access to all compartments;
    • REAR_ACCESS – Access to the rear compartment of the vehicle only;
  • compartmentConfigurations – Array with the characteristics of the cargo compartment.
    • name – (Mandatory) Single text with the name of the compartment;
    • type – (Mandatory) Text with the type of compartment. Possible values: [FIXED, VARIABLE].
    • loadingRule – (Mandatory) Integer with the rule considered for loading the compartment. Possible values:
      • NONE –No defined rule;
      • IDENTICAL_PACKAGINGS –Compartment will only accept products from the same package;
      • SINGLE_OPERATION – The compartment can only be used for one operation per route;
      • IDENTICAL_PRODUCTS –Compartment will only accept one type of product;;
      • IDENTICAL_SITE_PRODUCTS – Compartment will only accept one type of product and it must be from the same site;
    • maximumCapacity – (Mandatory) Decimal number with the maximum capacity of the compartment.
    • minimumCapacity – Decimal number with the minimum capacity of the compartment. Mandatory when type is VARIABLE and optional when type é FIXED.
    • increment – Decimal number with compartment capacity increment. Mandatory when type is VARIABLE and optional when type é FIXED.
    • allowedPackagings – Array with the names of the packages allowed to be loaded into the compartment. It must be unique in one type of compartment.
  • trip – This indicates that in addition to sorting the logistics points, the route must also be returned. All parameters accepted by the Trip API are accepted here.

Example with optional parameters

This example shows how to describe the characteristics of two different vehicles: the first a motorcycle "Moto" and the second a car "Carro". The "Moto" has a smaller load capacity, but can only carry packages named "Carga_Resistente". "Carro" has a larger load capacity, but can only carry packages named "Carga_fragil".

This way we can detail what kind of package/product one vehicle can carry and the other cannot.

"vehicleTypes": [
    {
        "name": "Moto",
        "maxWeight": 100,
        "maxVolume": 50,
        "size": 30,
        "maxSitesNumber": 24,
        "characteristics": null,
        "compartmentsAccessMode": "REAR_ACCESS",
        "compartmentConfigurations": [
            {
                "name": "compartimentoMoto",
                "compartments": [
                    {
                        "name": "bau_moto",
                        "type": "FIXED",
                        "maximumCapacity": 1000,
                        "loadingRule": "NONE",
                        "allowedPackagings": [
                            "Carga_Resistente"
                        ]
                    }
                ]
            }
        ],
        "trip": {
            "calculationMode": "THE_FASTEST",
            "toll": {
                "vehicleType": "MOTORCYCLE"
            }
        }
    },
    {
        "name": "Carro",
        "maxWeight": 400,
        "maxVolume": 100,
        "size": 30,
        "maxSitesNumber": 24,
        "characteristics": null,
        "compartmentsAccessMode": "REAR_ACCESS",
        "compartmentConfigurations": [
            {
                "name": "compartimentoCarro",
                "compartments": [
                    {
                        "name": "porta_malas",
                        "type": "FIXED",
                        "maximumCapacity": 1000,
                        "loadingRule": "NONE",
                        "allowedPackagings": [
                            "Carga_fragil"
                        ]
                    }
                ]
            }
        ],
        "trip": {
            "calculationMode": "THE_FASTEST",
            "toll": {
                "vehicleType": "MOTORCYCLE"
            }
        }
    }
],

vehicles*

The parameter vehicles is an array of objects, where each object will represent a vehicle available to carry out operations activities, which make up the fleet to meet logistics planning.

For each object on vehicles , the place of origin and return will be defined, as well as the time available to carry out the operations.

Mandatory parameters

  • name – Single text with the name of the vehicle. Used to be referenced in operations and to identify the vehicle that will run the route.
  • vehicleType – Text with the declared vehicle type in vehicleTypes .
  • legislationProfile – Text with the profile of legislation, declared in legislationProfiles .
  • availablePeriods – Describes the characteristics of the vehicle driver’s available working hours. There are mandatory and optional parameters. The mandatory ones are:
    • start – Start time of the working day. Timestamp format in milliseconds. Example: 1511901826456.
    • end – End time of the working day. Timestamp format in milliseconds. Example: 1511904661038.

Example with mandatory parameters

"vehicles": [
    {
        "name": "VUC_1",
        "vehicleType": "VUC",
        "legislationProfile": "DEFAULT",
        "availablePeriods": [
            {
                "timeWindow": {
                    "start": 1513753200000,
                    "end": 1513796400000
                }
            }
        ]
    }


],

Optional parameters

  • availablePeriods – Describes the characteristics of the vehicle driver’s available working hours. The optional parameters are:
    • departureSite – Text with the vehicle’s starting point at the beginning of the route. If not declared, the Planning API will decide the start depot .
    • arrivalSite – Text with the vehicle’s return location at the end of the route. If not declared, the Planning API will decide on the last site of the last operation to finalize the route.
    • maxRoutesNumber – Integer with the number of maximum routes for the available period. For example, if "maxRoutesNumber": 1, the vehicle will perform all operations on the same route.
  • legislationProfile – Text with the profile of legislation, declared in legislationProfiles .
  • logisticZones – Array with the names of the logistics zones in which the vehicle can carry out operations. They must be unique and have the same name declared in logisticZones

Example with optional parameters

This example shows two products of the same type that are associated with different packages. We can use the parameter packagings to later associate it with the type of vehicle that will transport the product.

"vehicles": [
    {
        "name": "154",
        "vehicleType": "Moto",
        "legislationProfile": "DEFAULT",
        "availablePeriods": [
            {
                "timeWindow": {
                    "start": 1611057600000,
                    "end": 1611082800000
                },
                "departureSite": "maam2",
                "arrivalSite": "maam2",
                "maxRoutesNumber": 1
            }
        ]
        "logisticZones": ["CE - ZONA LESTE","CE - ZONA SUL"]
    },
    {
        "name": "150",
        "vehicleType": "Carro",
        "legislationProfile": "DEFAULT",
        "availablePeriods": [
            {
                "timeWindow": {
                    "start": 1611057600000,
                    "end": 1611082800000
                },
                "departureSite": "fkebvlkbvgrvg",
                "arrivalSite": "ufwevidevgre",
                "maxRoutesNumber": 1
            }
        ],
        "logisticZones": ["CE - ZONA NORTE","CE - ZONA OESTE"]
    }
]

products*

The parameter products is an array of objects, where each object represents a product to be transported by the vehicles. Each product must be associated with an operation.

It is also possible to define packages, or packagings, to associate products with a specific type of vehicle.

Below are the parameters available at products:

  • name – Single text with the product name. Used to be referenced at operations.
  • type – (Optional) Text describing the type of product. Used to identify groups and categories.
  • packagings – (Optional) Array with the names of the packages associated with the product.

Example

This example shows two products of the same type that are associated with different packages. We can use the parameter packagings to later associate it with the type of vehicle that will transport the product.

"products": [
        {
            "name": "Vidro",
            "type": "Bebidas",
            "packagings": ["Carga_fragil"]
        },
        {
            "name": "Lata",
            "type": "Bebidas",
            "packagings": ["Carga_Resistente"]
        }
]

legislationProfiles*

The parameter legislationProfiles is an array of objects, where each object represents a legislation profile. Each legislation profile will define the characteristics of the driver’s working day, such as continuous driving time and time for lunch breaks.

One or more legislation profiles can be created according to the characteristics of the operation, for example, for journeys lasting more than one day.

They are referenced at vehicles to define which profile applies to the vehicle/driver.

Below is the list of parameters available in legislationProfiles:

  • name – Single text with the name of the legislation profile. Used to be referenced in vehicles.
  • maxContinuousDrivingTime – (Optional) Integer with the maximum time in seconds of continuous driving.
  • drivingPauseDuration – (Optional) Integer with the time in seconds of pause for steering. Applies once the sum of maxContinuousDrivingTime has been reached. It can be used to create lunch or rest breaks. The result is presented as an activity called "PAUSE".
  • maxContinuousWorkingTime – (Optional) Integer with the maximum continuous working time in seconds. WorkingTime is considered to be all the time spent on the activities of "LOADING"; "DRIVING"; "DELIVERY"; "COLLECTION"; "WAITING".
  • workingPauseDuration – (Optional) Integer with the time in seconds that the job is paused. The following activities are considered work: "LOADING"; "DRIVING"; "DELIVERY"; "COLLECTION"; "WAITING". This parameter is used for multi-day journeys where the time the driver will rest at the end of the work shift is applied.

Example

The example below shows a legislation profile for multi-day trips.

  • The value of 3 hours and 45 minutes of continuous driving is set at maxContinuousDrivingTime.
  • At drivingPauseDuration 1 hour is set for the lunch break.
  • At maxContinuousWorkingTime an 8-hour work shift is defined.
  • At workingPauseDuration you can take 15 hours off to start work the next day.

Thus, the driver will work the hours of driving and deliveries, take a 1-hour lunch break, continue deliveries in the afternoon and when he has worked a total of 8 hours, he will rest for 15 hours to start the new journey the next day.

"legislationProfiles": [
    {
        "name": "perfil",
        "maxContinuousDrivingTime": 13500,
        "drivingPauseDuration": 3600,
        "maxContinuousWorkingTime": 28800,
        "workingPauseDuration": 54000
    }
]

sites*

The parameter sites is an array of objects, where each object represents a location where a delivery or collection operation is to be carried out. They must be referenced in operations, to associate the location with the operation.

They can also be referenced at vehicles to define the driver’s place of departure and return.

Each object on sites can also be associated with a logistics rule to define, for example, the time taken to load and unload on site.

Below are the parameters available on websites:

  • name – Unique site name text. Used to reference in operations and identify in the result.
  • coordinates – Geographical coordinates in decimal degrees of latitude and longitude:
    • latitude – Numerical value in decimal degrees. It should be between -90.0 and 90.0. Example: -23.6987.
    • longitude – Numerical value in decimal degrees. It should be between -180.0 and 180.0. Example: -45.7347.
  • logisticConstraints – Text with reference to the name of logisticConstraint .
  • logisticZones – (Optional) Array with the names of the logistics zones to which the site belongs. They must be unique and have the same name declared in logisticZones

Example

"sites": [
    {
        "name": "204498250",
        "coordinates": {
            "latitude": -26.2186024,
            "longitude": -48.6656953
        },
        "logisticConstraints": "DEFAULT",
        "logisticZones": ["joinville"]           
    },
    {
        "name": "616188578",
        "coordinates": {
            "latitude": -26.2408157,
            "longitude": -49.3971109
        },
        "logisticConstraints": "DEFAULT",
        "logisticZones": ["sbs"]  
    }
]

operations*

The parameter operations is an array of objects, where each object will represent an operation to be solved in logistics planning. Each object will contain the characteristics of the operation, such as the type (delivery or collection), customer time slot, weight and volume of the delivery, among others.

It is recommended to have a maximum of 200 operations per request for better API performance.

Mandatory parameters

  • customerSite – Text with the name of the site, location of the operation.
  • customerTimeWindows – Time window in which the customer can receive the operation:
    • start – Start time at which the client is active in the operation. Timestamp format in milliseconds: 1511901826456.
    • end – End time that the client is active in the operation. Timestamp format in milliseconds: 1511904661038.
  • depotSite – Origin warehouse for the operation. Used to identify from which warehouse the product will be loaded onto the vehicle until delivery. In the case of a collection operation, the warehouse where the product will be unloaded.
  • id – Unique text with the operation identifier.
  • product – Single text with the product name. It must be stated at products.
  • type – Type of operation, product delivery or product collection. It must be one of the following types: [COLLECTION, DELIVERY].
  • volume – Decimal number with the volume of the product that will be delivered/collected in the operation. It is important that it is in the same unit as it was used in vehicleTypes. For example, cubic meters.
  • weight – Decimal number with the weight of the product that will be delivered/collected in the operation. It is important that it is in the same unit as it was used at vehicleTypes. For example, kilograms.

Example with mandatory parameters

"operations": [
    {
        "customerSite": "MERCADO02GLICERIO",
        "depotSite": "DEPOSITO01",
        "type": "DELIVERY",
        "customerTimeWindows": [
            {
                "end": 1583506800000,
                "start": 1583499600000
            }
        ],
        "id": "NUMORDEM30",
        "product": "HD_DIVERSOS",
        "volume": 1,
        "weight": 0.15
    },
    {
        "customerSite": "MERCADO10SCAETANO",
        "depotSite": "DEPOSITO01",
        "type": "DELIVERY",
        "customerTimeWindows": [
            {
                "end": 1583528400000,
                "start": 1583492400000
            }
        ],
        "id": "NUMORDEM27",
        "product": "HD_DIVERSOS",
        "volume": 1,
        "weight": 0.15
    }
]

Optional parameters

  • customerHandlingDuration – Integer with the time in seconds that will be spent at the client to carry out the operation. For collection operations ("COLLECTION"), use the parameter siteLoadingFixedTime in logisticConstraints.
  • depotHandlingDuration – Integer with the time in seconds that will be spent in the depot to carry out the operation. For collection operations ("COLLECTION"), use the parameter siteUnloadingFixedTime in logisticConstraints.
  • depotTimeWindows – Time window of the warehouse in which the operation is to take place. For example, if it is an operation with the activity of "DELIVERY", the product will be loaded onto the vehicle inside the warehouse at this time interval (in the API response, the activity will appear as "LOADING"). If it is an operation with activity from "COLLECTION", the product will arrive in the warehouse at this time interval (in the API response, the activity will appear as "UNLOADING"):
    • start – Start time of the operation on depot. Timestamp format in milliseconds: 1511901826456.
    • end – End time depot acts in the operation. Timestamp format in milliseconds: 1511904661038.
  • group – Text with the operations group. Used to group operations from the same location manually. Operations that have the same value will be executed together. For example, operations in different stores in the same shopping center.
  • preAllocatedVehicleName – Text with the name of the vehicle that will carry out the operation in a predefined way. The Planning API will then allocate this associated vehicle to place the operation on its route. Use this parameter for examples in which a favorite driver must serve a customer or a specific vehicle needs to perform the operation.
  • priority – Integer of the operation’s priority. Used to define priority in the load, not in the delivery sequence. The priority scale can be ascending or descending depending on the optimizationProfile used.
  • quantity – Decimal number with the operation quantity. For description only, it does not interfere with how the operation is processed.

Example with optional parameters

This example shows 2 delivery operations to be carried out between 10:00 and 12:00 (customerTimeWindows). The operation on MERCADO01MOOCA has depotTimeWindows set to load at the depot between 11:00 and 12:00 with a duration of 10 minutes (depotHandlingDuration).

Due to this characteristic, the truck will only leave the warehouse at 11:10 to carry out the two operations and will have until 12:00 to carry out the two operations.

Both operations are from the same "group": "A" and will be served by "preAllocatedVehicleName": "VUC01".

"operations": [
    {
        "customerSite": "MERCADO01MOOCA",
        "depotSite": "DEPOSITO01",
        "preAllocatedVehicleName": "VUC01",
        "priority": 20,
        "type": "DELIVERY",
        "customerTimeWindows": [
            {
                "start": 1583499600000,
                "end": 1583506800000
            }
        ],
        "depotTimeWindows": [
            {
                "start": 1583503200000,
                "end": 1583506800000
            }
        ],
        "depotHandlingDuration": 600,
        "id": "NUMORDEM25",
        "product": "HD_DIVERSOS",
        "volume": 12,
        "weight": 1,
        "quantity": 10,
        "group": "A"
    },
    {
        "customerSite": "MERCADO02GLICERIO",
        "depotSite": "DEPOSITO01",
        "preAllocatedVehicleName": "VUC01",
        "type": "DELIVERY",
        "customerTimeWindows": [
            {
                "start": 1583499600000,
                "end": 1583506800000
            }
        ],
        "customerHandlingDuration": 300,
        "id": "NUMORDEM30",
        "product": "HD_DIVERSOS",
        "volume": 1,
        "weight": 0.15,
        "group": "A"
    }
],

logisticZones

The parameter logisticZones is an array of objects, where each object represents a logistics zone that can be associated with depots, sites and vehicles to define the relationship between them.

For example, if you define a logistics zone for a vehicle, it will only serve the sites that belong to the same logistics zone.

Below are the parameters available in logisticZones:

  • name – Text of the name of the logistics zone. Used for referencing in depots, vehicles e sites.
  • zonePriority– Zone priority. It will influence which logistics zone is served first. Possible values: [PRIORITARY, SECUNDARY]

Example

"logisticZones": [
        {
            "name": "blumenau",
            "zonePriority": "PRIORITARY"
        },
        {
            "name": "jaragua",
            "zonePriority": "PRIORITARY"
        },
        {
            "name": "joinville",
            "zonePriority": "PRIORITARY"
        }
    ]
}

callback

The parameter callback is an object that contains the webhook data that will be used to receive the problem calculation events.

This way you don’t have to check the status of the problem to see if it has been processed. The API will notify the webhook when the solution is available for consultation.

The following parameters are required:

  • url – URL with the address that will receive the callback.
  • user – (Optional) Text with the user name if the endpoint requires authentication.
  • password – (Optional) Password text if the endpoint requires authentication.

Example

"callback": {
    "password": "nome_usuario",
    "url": "https://enqkbfcos3dhgchuikd.webhook.net",
    "user": "senha"
},

For more details, see: How to receive the current problem status via webhook?

optimizationProfile*

The parameter optimizationProfile indicates which optimization profile the Planning API will use to process the data. Each optimization profile has characteristics that will be considered to optimize the logistics problem, and each profile is suitable for a specific scenario.

Example

"optimizationProfile": "BRAZIL46"

Optimization profiles available

BRAZIL37: Profile for large problems, distributing routes between vehicles instead of creating more than one route per vehicle. The allocation of vehicles with greater capacity begins.

BRAZIL46: Profile for smaller problems, initial construction with more than 10 locations per route and handling of several different service windows.

BRAZIL_AVG_LOAD_RATE: This profile is used for multiple vehicle routing problems (VRP) and has the characteristic of meeting the priorities of the operations and with the valuation criteria that highlight the average load capacity in volume/weight for the vehicles.

BRAZIL_VRP_PICKUP: Profile used for multiple vehicle routing problem (VRP). For cases where routes need to be carried out, allowing products to be collected from the warehouse and from other stores during the route to make deliveries. Useful in cases of last mile use, where the vehicle will depart from the distribution center and collect from stores along the way.

tripsProfile*

tripsProfile is a mandatory parameter in the Planning API request so that the logistics planning calculation takes into account the characteristics of circulation on the road system that will influence routing.

We recommend that you always use "MAPLINK", as it contains the most up-to-date maps.

Example

"tripsProfile": "MAPLINK"

trip

The parameter trip is an object and indicates that in addition to sorting the logistics points, the coordinates that make up the route should also be returned. All parameters accepted by the Trip API are accepted here.
If the parameter has already been declared in vehicleTypesThe parameters defined there for each type of vehicle will be taken into account.

Example

"trip": {
    "calculationMode": "THE_FASTEST",
    "crossedBorders": {
        "level": "CITY"
    },
    "toll": {
        "vehicleType": "TRUCK_WITH_TWO_DOUBLE_AXLES"
    }
}

calculationMode

The parameter calculationMode indicates the calculation method to be used for route planning. There are two options available:

  • THE_FASTEST – Returns planning to the fastest route. (Higher average speed)
  • THE_SHORTEST – Returns the planning to the route with the lowest mileage.

If the parameter is not entered, the value THE_FASTEST will be taken into account.

Example

"calculationMode": "THE_FASTEST",

restrictionZones

The parameter restrictionZones is an array containing the constraint areas to be considered when solving the logistics problem.

The restriction areas must be previously registered via the Restriction Zones API and used as an argument in the parameter restrictionZones. So the routes will divert away from these areas.

If there is a stopping point within the restriction area, the Planning API will serve the stopping point via the path with the least overlap with the restriction area.

Example

"restrictionZones": [
        "SP_BR381_90_km_Alt_Esq_5_3_Cen_5_45_Dir_5_6",
        "SP_BR381_87_km_Alt_Esq_6_7_Cen_6_7_Dir_6_7"
]