Typical revisions for API-based integrations
The source system interacts with the RouteQ API as follows:
-
The source system sends a routing request.
-
The response returns an ID: it's the unique ID of the solution.
-
The service needs some time to optimize the routes. The source system periodically requests the solution status by its ID.
-
When the route planning is complete, the source system can get the result.
The data exchange format is JSON. The interaction is asynchronous: you can run multiple planning tasks at the same time.
The revisions that are most commonly required for integrating the source system with RouteQ via the API are described below.
Main revisions
Starting a routing task
Usually, the source system is revised so that the user initiates sending the data to the planning service. (Running routing by schedule is a rarely used option.) That's why a form or button is usually created to send a task. Suggested set of tools in the form:
-
Define a selection of items (orders, vehicles/couriers) to be planned.
-
Select the optimization settings.
-
Button to run the task.
Storing new attributes
During the migration to automatic routing, you need to formalize the logistics coordinator's knowledge not reflected in your accounting system. This knowledge may include the information about compatibility between orders (or between orders and vehicles), service duration, time windows, and so on. To store this type of information, you need to add attributes to the existing directories or create new directories in some cases.
Converting source data to JSON
The source system must convert the source data (information about orders, vehicles/couriers, depot, task settings) to JSON format, and generate a request to the service. For the routing result to be realistic, it is important to ensure data validation:
-
Completeness (the required fields must not be empty).
-
Correctness (for example, the service duration can't be zero).
Processing the resulting solution
You need to obtain and process the optimization results. Commonly, the solution output by the service is converted into the source system objects (for example, waybills).
Storing logs
By saving the log of service requests you can troubleshoot errors on the accounting system side. When contacting support about a specific planning, make sure to present your task ID (to define the context of the issue). If you have logs, you always have access to task IDs.
Other possible revisions
Getting a solution edited in the web interface
If you edit the routes built by the service in the web interface, the ID of the edited solution differs from the ID of the original task. For the source system to get the edited result, make sure that it can save the new ID and request the edited solution.
Specifics of parallel runs (with different settings for different depots)
The optimization settings often depend on the input depot of the task. To make parallel runs with different depots, you might need a revision to change the solution settings depending on the depot selected.
Support for additional planning
When you do additional planning (or wave planning), you pass the results of the previous routing within the source data for the new task (for more information, see Regular additional planning of the route). For this purpose, the request structure provides special parameters that need to be reflected in the source system.