---
metadata:
- name: generator
content: Diplodoc Platform v5.19.6
alternate:
- https://docs.routeq.com/doc/en/vrp/integration-variants.md
title: RouteQ — integration architecture options
---
> **Documentation Index:** Fetch the complete configuration index at https://docs.routeq.com/doc/en/llms.txt
# Integration architecture options
## Choosing an architecture {#types-of-schemes}
When choosing an integration architecture and designing tracking system customizations, keep the following in mind:
1. Planning and Track & Trace are different services. They are independent of each other. Even if your data is available in the Planning service, you may not necessarily be able to use them in Track & Trace (and vice versa).
1. When calling the Planning API, all data on references, settings, and previously planned routes must be stored on the tracking system side.
1. The Planning service solves problems independently, so the data required to solve a problem must be passed in the request each time. For example, with [additional planning](https://docs.routeq.com/doc/en/vrp/additional-planning.md).
You can upload data to or download data from a service via Excel or the API. You can open a planning task from the RouteQ interface and export it to Track & Trace.
Support for unique order numbers in Track & Trace is an important feature of all the integration architectures. If you need to postpone a scheduled order until the following day, add a prefix to the order number when re-submitting the order to Planning (for manual export).
**Basic integration with RouteQ services**
#|
||**Method\Service** | **Planning** | **Track & Trace** | **Planning and Track & Trace integration**||
||Via Excel | [Planning via Excel](https://docs.routeq.com/doc/en/vrp/excel-template-filling_index-page.md) | [Manually via Excel](https://docs.routeq.com/doc/en/vrp/excel-template-filling_index-page.md) requires you to complete the Routes sheet | Planning via Excel, manual export to Track & Trace.[Learn more](#excel-and-manual)||
||Via API | [Planning API](https://yandex.ru/routing/doc/en/vrp/redoc/index.html#tag/Multiple-Vehicles-Routing-(MVRP)) | [Track & Trace API](https://yandex.ru/routing/doc/en/delivery/redoc/index.html#operation/) | Planning via API, manual export to Track & Trace.[Learn more](#api-and-manual)
Full API integration.[Learn more](#api-and-api)||
|#
{% note info %}
Using [presets](https://docs.routeq.com/doc/en/vrp/presets.md) (ready settings for route planning) can significantly ease and speed up integration, and in the future simplify the optimization of various planning scenarios.
During integration, specify the preset name. Any changes to the planning parameters will be done in the preset and will not affect the integration settings.
{% endnote %}
## Geocoding {#geocoding}
When you load data via Excel, the built-in geocoder is used. It automatically finds the coordinates for the addresses you have uploaded.
API requests are not processed through the geocoder. When using the API, you need to pass point coordinates rather than addresses. Therefore, you must geocode in advance on the side of the tracking system.
If the point list does not change, you can enter point coordinates in a look-up table for later use. If delivery addresses change regularly, you need additional integration with a [geocoder](https://yandex.com/dev/maps/geocoder/).
With geocoding, the address must be accurate. You're more likely to get inaccurate coordinates if:
- The address is unstructured: it's stored as a single address line and doesn't provide enough information (the placename is very common, but the region or city district isn't specified, or the street name is specified without the name of the city) or the information is irrelevant for determining coordinates (for example, the apartment number and intercom number are indicated).
- The address line contains additional information, like phone numbers and comments.
We recommend the following:
- Enable search suggestions and [address verification](https://yandex.com/dev/maps/jsbox/2.1/input_validation/) during input (for example, for clients on the website and managers who place orders).
- Separate the boxes for entering addresses, contact details, and comments on the side of the tracking system. This way, the geocoder only receives an address string with enough data necessary to determine the coordinates: the region, city, street, and building number.
- To limit the coordinate search area, use the geocoder parameter [bbox](https://yandex.com/dev/geocode/doc/en/request).
- When you receive a response from the geocoder, use the [precision](https://yandex.com/dev/geocode/doc/en/response) tag value to precisely determine the building. If the precision isn't equal to `exact` or `number`, inform the user that they need to provide a precise address.
## Planning via Excel, manual export to Track & Trace {#excel-and-manual}
**When to use this method**
This integration method is a good choice for quickly rolling out the service to production or for a pilot implementation using small amounts of data.
We don't recommend using this integration method for tasks that require [additional planning](https://docs.routeq.com/doc/en/vrp/additional-planning.md) or where implementation will require a large number of manual steps.
{% note info %}
Additional planning tasks using small amounts of data can use the manual order input function in Track & Trace.
{% endnote %}
**Diagram**
**Implementing integration**
1. Download an Excel file from the tracking system in the [required format](https://docs.routeq.com/doc/en/vrp/excel-template-filling_index-page.md).
1. Upload the resulting file to the [Planning web interface](https://docs.routeq.com/doc/en/vrp/interface-import.md) and run the task. The addresses in the file will be geocoded automatically.
1. If necessary, [edit the solution](https://docs.routeq.com/doc/en/vrp/interface-result.md#editing-a-solution) in the web interface.
1. Take the result from step 3 (with your edits) and [upload it to Excel](https://docs.routeq.com/doc/en/vrp/solution-export.md). As an option, you can upload a file to the tracking system to get information on scheduled routes.
1. Take the result from step 3 and [export it to Track & Trace](https://docs.routeq.com/doc/en/vrp/solution-export.md).
1. When the couriers are done, [job performance](https://docs.routeq.com/doc/en/delivery/interface/quality-report.md) data can be saved in Excel or uploaded to the tracking system for internal reports.
## Planning via API, manual export to Track & Trace {#api-and-manual}
**When to use this method**
This integration method is suitable for most tasks. It can be used as an intermediate solution prior to [full API integration](https://docs.routeq.com/doc/en/vrp/integration-variants.md#api-and-api).
**Diagram**
**Implementing integration**
1. Before launching the task, the tracking system sends addresses to be geocoded. The geocoder returns coordinates and an [accuracy flag](https://yandex.com/dev/geocode/doc/en/response).
1. If the coordinates are not accurate enough, adjust them manually.
1. After receiving the coordinates, the tracking system sends a request to [add the task](https://yandex.ru/routing/doc/en/vrp/redoc/index.html#operation/addMVRPTask), which launches the planning process.
The service must return [one of the following responses](https://yandex.ru/routing/doc/en/vrp/redoc/index.html#operation/addMVRPTask):
- Code for successful task queuing and task `ID`.
- Error code.
Planning time depends on the number of points in a request. The tracking system sometimes [requests information](https://yandex.ru/routing/doc/en/vrp/redoc/index.html#operation/getMVRPTaskResult) about the task status.
{% note info %}
At this stage, you can open the solution at `https://yandex.ru/courier/companies//depots/all/mvrp/`, where:
- `` is the company ID. You can find it in **Settings** → **Company** → **Company ID**.
- `` is the task `id`.
{% endnote %}
1. If necessary, [edit the solution](https://docs.routeq.com/doc/en/vrp/interface-result.md#editing-a-solution) in the web interface.
1. The final task `ID` depends on whether a task has been updated:
- If a solution has not been updated, routing information is available based on the original task `ID`.
- If a solution is edited, its task `ID` will change. To get information about the adjusted solution, [use the API](https://docs.routeq.com/doc/en/vrp/interaction-with-api.md).
1. Take the result from step 4 and [export it to Track & Trace](https://docs.routeq.com/doc/en/vrp/solution-export.md).
1. When the couriers are done, [job performance](https://docs.routeq.com/doc/en/delivery/interface/quality-report.md) data can be saved in Excel.
## Full API integration {#api-and-api}
**When to use this method**
This integration method is suitable when you need maximum flexibility or when you need to eliminate manual operations. This option assumes that planned routes must be stored on the side of the tracking system.
{% note info "" %}
You can see the diagram showing the process of importing planning results to Track & Trace [here](https://doc-static.yandex.net/src/dev/routing/schema/import-to-track-and-trace-en.pdf).
{% endnote %}
**Diagram**
**Implementing integration**
1. Before launching the task, the tracking system sends addresses to be geocoded. The geocoder returns coordinates and an [accuracy flag](https://yandex.com/dev/geocode/doc/en/response).
1. If the coordinates are not accurate enough, adjust them manually.
1. After receiving the coordinates, the tracking system sends a request to [add the task](https://yandex.ru/routing/doc/en/vrp/redoc/index.html#operation/addMVRPTask), which launches the planning process.
The service must return [one of the following responses](https://yandex.ru/routing/doc/en/vrp/redoc/index.html#operation/addMVRPTask):
- Code for successful task queuing and task `ID`.
- Error code.
Planning time depends on the number of points in a request. The tracking system sometimes [requests information](https://yandex.ru/routing/doc/en/vrp/redoc/index.html#operation/getMVRPTaskResult) about the task status.
{% note info %}
At this stage, you can open the solution at `https://yandex.ru/courier/companies//depots/all/mvrp/`, where:
- `` is the company ID. You can find it in **Settings** → **Company** → **Company ID**.
- `` is the task `id`.
{% endnote %}
1. If necessary, [edit the solution](https://docs.routeq.com/doc/en/vrp/interface-result.md#editing-a-solution) in the web interface.
1. The final task `ID` depends on whether a task has been updated:
- If a solution has not been updated, routing information is available based on the original task `ID`.
- If a solution is edited, its task `ID` will change. To get information about the adjusted solution, [use the API](https://docs.routeq.com/doc/en/vrp/interaction-with-api.md).
1. Save the planned routes on the tracking system side. In certain cases, you can plan without assigning a specific courier.
After receiving data on planned routes, you can assign specific couriers on the side of the tracking system. This will be useful if:
- Your couriers' exact schedule is unknown for the moment.
- Ground transportation is used.
1. After assigning specific couriers, pass the route data to Track & Trace using the [Track & Trace API](https://docs.routeq.com/doc/en/delivery/index.md). Take into account the [API features](https://docs.routeq.com/doc/en/delivery/specifics.md) when you update the following data:
- [Depots](https://yandex.ru/routing/doc/en/delivery/redoc/index.html#operation/editsMultipleDepots).
- [Couriers](https://yandex.ru/routing/doc/en/delivery/redoc/index.html#operation/editsMultipleMobileEmployees) and their [phone numbers](https://yandex.ru/routing/doc/en/delivery/redoc/index.html#operation/addsThePhoneNumberOfTheCourierWhoWillWorkWithTheMobileApplication).
- [Routes](https://yandex.ru/routing/doc/en/delivery/redoc/index.html#operation/editsMultipleRoutes).
- [Orders](https://yandex.ru/routing/doc/en/delivery/redoc/index.html#operation/editsMultipleOrders)
1. Track & Trace can provide the following information after couriers have completed their tasks or while they are working:
- [Information about orders for a specific date](https://yandex.ru/routing/doc/en/delivery/redoc/index.html#tag/verification).
- [Information about current order status](https://yandex.ru/routing/doc/en/delivery/redoc/index.html#tag/tracking).
- [Order notifications](https://yandex.ru/routing/doc/en/delivery/redoc/index.html#tag/order-notifications).
- [Information about the delivery quality](https://yandex.ru/routing/doc/en/delivery/redoc/index.html#tag/courier_report).
## Additional planning at the depot (vehicles have not left yet) {#additional-planning-depot}
**When to use this method**
This integration method is suitable when information on some orders is available in advance, but others continue coming in until the couriers leave. This will require new orders to be included in previously planned routes.
**Note**
- The tracking system must store planned route data.
- The frequency and interval of [additional planning](https://docs.routeq.com/doc/en/vrp/additional-planning.md) depend on the specific business model.
**Diagram**
**Implementing integration**
1. The tracking system sends a task for initial planning using the [Planning API](https://yandex.ru/routing/doc/en/vrp/redoc/index.html#tag/Multiple-Vehicles-Routing-(MVRP)) and receives the result.
1. Save the resulting solution in the tracking system to use built routes for additional planning. In the meantime, new orders accumulate.
1. The tracking system sends a task for additional planning using the Planning API. Among other things, the tracking system must pass on:
- Order data from the initial plan and previous additional planning.
- Bindings between orders and vehicles based on previous additional planning (not to modify previously created routes).
- New order data.
1. Save the new planned routes on the side of the tracking system for subsequent iterations of additional planning. In the meantime, new orders continue to accumulate.
1. Repeat Steps 3 and 4 as many times as necessary until you get the final version of the solution.
1. The tracking system sends the final version of the routes via the [Track & Trace API](https://yandex.ru/routing/doc/en/delivery/redoc/index.html#operation/).
## Additional planning en route {#additional-planning-route}
**When to use this method**
This integration method is a good choice when couriers are already on their planned routes but new orders continue coming in during their work shift.
**Note**
- The tracking system must store planned route data.
- The frequency and interval of [additional planning](https://docs.routeq.com/doc/en/vrp/additional-planning.md) depend on the specific business model.
- The Planning service uses current vehicle location data. Normally, data on the most recent completed order is sufficient.
**Diagram**
**Implementing integration**
1. The tracking system sends a task for initial planning using the [Planning API](https://yandex.ru/routing/doc/en/vrp/redoc/index.html#tag/Multiple-Vehicles-Routing-(MVRP)) and receives the result.
1. Save the resulting solution in the tracking system to use for additional planning. In the meantime, new orders accumulate.
1. Information about routes is sent via the [Track & Trace API](https://yandex.ru/routing/doc/en/delivery/redoc/index.html#operation/).
1. In the meantime, the tracking system accumulates new orders to be added to the current plan. By this time, the couriers are already en route.
1. The Track & Trace service returns information on completed orders to the tracking system, including completion time for the most recent one (this can be a point in time in the past).
1. The tracking system sends a task for additional planning using the Planning API. A task must include:
- Bindings between orders and vehicles based on previous additional planning (not to modify previously created routes).
- The most recent completed order if it is used to determine vehicle location.
- Other completed orders if they are `pickup` orders that need to be taken into account in load capacity calculations.
- A sequence of the next few orders if couriers are following the planned order delivery sequence.
1. Save the new planned routes on the side of the tracking system for subsequent iterations of additional planning. In the meantime, new orders continue to accumulate.
1. The tracking system updates route information via the Track & Trace API. Repeat Steps 6 and 7 as many times as necessary until you get the final version of the solution.
**Example sequence of the next few orders**
A courier was delivering orders 1 through 5 when a new order number 6 came in. During additional planning, orders 1 through 3 have already been completed, so the additional planning request must contain information about order 3 (this being the vehicle starting point) and orders 4 through 6.
You also need:
- To bind orders 3 through 5 to the courier since they were previously assigned to them.
- To set orders 3 and 4 to be at the start of the route because the courier was already en route to order 4 at the time of additional planning.
This way, the courier will be able to deliver order 4, and the service will find an optimized sequence to complete orders 5 and 6.
{% note info "" %}
You can find charted samples for additional planning requests [in this file](https://doc-static.yandex.net/src/dev/routing/schema/additional-planning-en.pdf).
{% endnote %}
## Integration with the Yandex Courier app {#courier}
**When to use this method**
This integration method makes it easier for couriers to use the [Yandex Courier](https://docs.routeq.com/doc/en/delivery/app.md) app.
**Note**
- The courier's phone number and username must match and be formated as `+1xxxxxxxxxx`.
- If the courier is registered in multiple companies, they'll be asked to select one.
- If the courier has multiple routes planned for today, they'll be asked to select one.
**Implementing integration**
1. Via [Routing Workspace](https://docs.routeq.com/doc/en/delivery/interface/add-couriers.md) or the[API](https://yandex.ru/routing/doc/en/delivery/redoc/index.html#operation/addsThePhoneNumberOfTheCourierWhoWillWorkWithTheMobileApplication), add the phone numbers of couriers who need to use the Yandex Courier app.
1. Plan routes:
- Via Excel: Enter the courier's phone number in the **Courier's username** and **Courier's phone number** fields.
To correctly upload phone numbers with the `+` symbol to Track & Trace, enter the `'` (single quote) symbol before the plus.
- Via the API: Enter the courier's phone number in the `vehicles.id` and `vehicles.phone` fields.
1. Take the result from step 2 and [export it to Track & Trace](https://docs.routeq.com/doc/en/vrp/solution-export.md).
As a result, the courier won't have to enter their username to use the app.
{% include [warehouse-feedback](_includes/feedback-81845556eeea.md) %}