---
metadata:
  - name: generator
    content: Diplodoc Platform v5.19.6
alternate:
  - https://docs.routeq.com/doc/en/delivery/load-data.md
title: RouteQ — Track & Trace — uploading data
---
> **Documentation Index:** Fetch the complete configuration index at https://docs.routeq.com/doc/en/llms.txt


# Uploading data

In Routing Workspace, you can upload routes to Track & Trace in the following two ways:

- Export the results of a planning task if you create routes using the Planning service.
- Import data from an Excel file if you set the order delivery sequence yourself.

{% note info %}

You can also upload routes to Track & Trace using the [Track & Trace API](https://yandex.ru/routing/doc/en/delivery/redoc/index.html#operation/). For more information, see [Setting routes for the day](https://docs.routeq.com/doc/en/delivery/quickstart/start-work.md).

{% endnote %}


## Preparing data {#data-preparation}

To upload routes to Track & Trace successfully, you should know the following:

- How you want couriers to receive information about routes and [send their coordinates](https://docs.routeq.com/doc/en/delivery/courier-coordinates.md).
- If the courier needs to call the recipient.
- Which depots will be included in the routes in Track & Trace.

**Mobile apps or GPS trackers**

To get information about their route and share their location, couriers can use a GPS tracker or the [Yandex Courier](https://docs.routeq.com/doc/en/delivery/app.md) app.

{% list tabs %}

- GPS trackers

  1. Ask your GPS tracker provider to add data relay to the Yandex server.
  2. Get GPS tracker numbers from your provider.
  3. In the Planning file, open the **Vehicles** sheet and add a **GPS tracker number** (`IMEI`) column.
  4. In the **Number of the GPS tracker** column, enter the numbers you received.

  You can edit the GPS tracker number in the file and the Planning interface.

- Yandex Courier

  1. In the Planning file, open the **Vehicles** sheet and add a **Courier ID** column.
  2. Enter a unique username for each courier.

  You can edit the courier's username in the file and in the Planning interface.

  If you enter the courier's phone number in `+1хххххххххх` format in the **Courier ID** and **Phone number** fields, they won't have to enter their username to log in to [Yandex Courier](https://docs.routeq.com/doc/en/delivery/app.md).

  ![](./_images/id-phone.png)

  {% note info %}

  For phone numbers with the `+` symbol to be uploaded to Track & Trace correctly, enter the `'` (single quote) symbol before the plus.

  {% endnote %}

{% endlist %}

**Clients' mobile phone numbers**

Before departing for a delivery, the courier may need to confirm the client's availability or notify them of any delays and arrange a new delivery time.

To allow the courier to contact clients by phone, provide the clients' phone numbers. There are two ways to do this:

  * Specify the client's phone numbers on the **Orders** sheet. This will make the **Call** button appear in the Yandex Courier app.

  * On the **Orders** sheet, specify the client's phone number in the order comments in the format: `<a href="tel:+79123456789">Call</a>`. To specify the extension number, use separators (`,`, `;`, `*`, or `#`): `<a href="tel:+79123456789,12">Call</a>`. The **Call** link will appear in the **Logistics coordinator's note** field in the app, enabling the courier to contact the client.

**Link in the order comment**

If the courier needs additional order information, such as parking rules at the client's address, you can add a link in the order comment. 

To do this, in the order comment on the **Orders** sheet, specify a link like this: `<a href="https://red-rose.com">Parking rules</a>`. The **Parking rules** link will appear in the **Logistics coordinator's note** field in the app, enabling the courier to find and read the necessary information.

**Depot**

{% note alert %}

To upload a route to Track & Trace successfully, be sure to [specify the depot](https://docs.routeq.com/doc/en/delivery/interface/settings.md) in the [company settings](https://docs.routeq.com/doc/en/delivery/interface/depots.md) and the Planning file (task).

{% endnote %}

1. Specify the depot number:
    - In the Planning file on the **Depot** sheet in the **Depot number** column.
    - In the Planning task on the **Depots** tab.
2. Upload the planning file or fill in the data in the interface and run planning.

**Manual route configuration**

{% note alert %}

Make sure routes are created for all orders specified on the **Orders** sheet. Otherwise, the system returns an error when importing data. See an example of a [route file](https://doc-static.yandex.net/src/dev/routing/templates/сourier-example-with-routes-en.xlsx) that's filled out correctly.

{% endnote %}

If you set the order delivery sequence yourself, add several more settings in the planning file:

1. Go to the **Routes** sheet and fill out the following columns:
    - **Vehicle ID**
    - **Shift**
    - **Order number**
1. Match the order number with the **Vehicle ID** and the **Shift** during which the courier delivers the order.
1. Set the order delivery sequence.


## Export to Track & Trace {#export-monitoring}

Once you've planned and edited the routes, export them to Track & Trace for tracking.

{% note warning %}

[Cross-docking](https://docs.routeq.com/doc/en/vrp/supported-use-cases.md#cross-docking) solutions are not exported to Track & Trace.

{% endnote %}

### Export via Routing Workspace {#export-routing-workspace}

{% list tabs %}

- Full export

  1. In the upper-right corner of the screen, click **Export**.
  2. Select **Track & Trace**.
  3. Select the [status](https://docs.routeq.com/doc/en/delivery/load-data.md#order-status) to create orders with.
  4. Click **Upload to Track & Trace** → **View**.
  5. You can see the planned routes in the **Dashboard** section.

  For more information, see [Export](https://docs.routeq.com/doc/en/vrp/solution-export.md).

- Partial export

  If you don't need to track some of the routes, filter or hide them. For more information, see [Partial export](https://docs.routeq.com/doc/en/vrp/solution-export.md#partial-export).

  After that:

  1. In the upper-right corner of the screen, click **Export**.
  2. Enable **Only visible routes**.
  3. Select **Track & Trace**.
  4. Select the [status](https://docs.routeq.com/doc/en/delivery/load-data.md) to create orders with.
  5. Click **Upload to Track & Trace** → **View**.
  6. You can see the planned routes in the **Dashboard** section.

{% endlist %}


{% include [duplicates](_includes/duplicates-a5af884da9a7.md) %}

### Export via the API {#export-routing-api}

{% note info %}
 
Only a manager or company administrator can export the solution.

{% endnote %}

To export the solution from Planning to Track & Trace via the API, send a request to the [routes-import](https://yandex.ru/routing/doc/en/delivery/redoc/index.html#tag/routes-import) resource.

**Request:**

{% list tabs %}

- Windows

  cURL

  ```html
  curl -H "Content-Type: application/json" -H "Authorization: OAuth <your-token>" -X POST https://courier.yandex.ru/api/v2/companies/<your-company-id>/routes:vrp-task-import/?vrp_task_id=<vrp_task_id>
  ```

- MacOS/Linux
  
  cURL
  
  ```html
  curl -H "Content-Type: application/json" -H "Authorization: OAuth <your-OAuth-token>" -X POST https://courier.yandex.ru/api/v2/companies/<your-company-id>/routes:vrp-task-import/?vrp_task_id=<vrp_task_id>
  ```

{% endlist %}

where `<vrp_task_id>` is the [solution ID](https://docs.routeq.com/doc/en/vrp/interface-result.md) from Planning. 

**Result:**

```json
{
  "id": "<vrp_task_import_id>",
  "status": "IN_PROGRESS",
  "create_time": "<creation-time>",
  "update_time": "<update-time>"
}
```
where `<vrp_task_import_id>` is the ID of the exported solution in Track & Trace.

To obtain the export result, send a GET request:

**Request:**

{% list tabs %}

- Windows

  cURL

  ```html
  curl -H "Content-Type: application/json" -H "Authorization: OAuth <your-token>" -X GET http://courier.yandex.ru/api/v2/companies/<your-company-id>/routes:vrp-task-import/<vrp_task_import_id>
  ```

- MacOS/Linux
  
  cURL

  
  ```html
  curl -H "Content-Type: application/json" -H "Authorization: OAuth <your-OAuth-token>" -X GET http://courier.yandex.ru/api/v2/companies/<your-company-id>/routes:vrp-task-import/<vrp_task_import_id>
  ```

{% endlist %}

where `<vrp_task_import_id>` is the ID of the exported solution in Track & Trace.

Depending on the status of the request, you'll receive one of the results:

* Request in progress:

  ```json
  {
    "id": "<vrp_task_import_id>",
    "status": "IN_PROGRESS",
    "create_time": "<creation-time>",
    "update_time": "<update_time>"
  }
  ```

* Request completed successfully:

  ```json
  {
    "id": "<vrp_task_import_id>",
    "status": "SUCCESS",
    "create_time": "<creation-time>",
    "update_time": "<update_time>",
    "result": {
      "routes": [...]
      }
  }
  ```

  where the `routes` array contains the created routes.

* An error occurred while executing the request:

  ```json
  {
    "id": "<vrp_task_import_id>",
    "status": "ERROR",
    "create_time": "<creation-time>",
    "update_time": "<update_time>",
    "error": {
      "message": "<error-description>"
      }
  }
  ``` 

Special considerations when exporting via the API:

* Requests from one company are executed sequentially in the order they're received.
* If a request ends with an error (for example, the specified depot doesn't exist), the response will return an error message, and the solution will not be exported.

## Import from Excel {#import-excel}

Import manually created routes to Track & Trace:

1. In the left menu of Routing Workspace, select **Track & Trace** → **Dashboard**.
1. In the upper-right corner, click **Import**. The import interface opens.
1. In the upper-left corner, click **Upload file** and upload the necessary file from your computer.
1. Check the system notifications on all tabs and correct the data if necessary.

   If the order numbers are duplicated, the system will suggest [solutions](#duplicate-orders). If you select **Keep duplicates and rename numbers in the new route**, the duplicate orders will be renamed. The planning date in the `YYYY-MM-DD` format will be added to their name.

1. Go to the **Settings** tab:
    - Select the date when couriers must perform these routes.
    - Select the necessary [order status](https://docs.routeq.com/doc/en/delivery/load-data.md#order-status).
1. In the lower-left corner, click **Import**.
1. You can see the planned routes in the **Dashboard** section.


### Populating Excel files {#excel-file}

{% cut "Orders sheet" %}

Orders by all routes.

#|
|| **Field** | **Description** ||
|| `id` | Order number in your system. The value must be unique for the entire sheet and meet the [requirements](https://docs.routeq.com/doc/en/vrp/properties-of-orders.md#order-id).

The maximum length is 80 characters. ||
|| `point.lat` | Order delivery point latitude. ||
|| `point.lon` | Order delivery point longitude. ||
|| `title` | Point name/Client name. Displayed in the app. For example, `Red Rose` or `John Doe`.

The maximum length is 1023 characters. ||
|| `address` | The address of the location. It is displayed in the app.

The maximum length is 1023 characters. ||
|| `phone` | Phone number for an SMS notification of the courier's arrival.
If there are multiple numbers separated by commas, the [Yandex Courier app](https://docs.routeq.com/doc/en/delivery/app.md) lets the courier select one of them. No SMS notification is sent in this case.

The maximum length is 80 characters. You can leave this field empty. ||
|| `time_window` | Delivery time window. All routes are uploaded as of the shipment date. For example, the shipment date is May 1. If the delivery window is May 2 from 9:00 to 10:00, specify the window in `1.9:00–1.10:00` format, and if the delivery is scheduled for May 3, in `2.9:00–2.10:00` format, and so on. ||
|| `shared_service_duration_s` | Handling time at an address, in seconds. This includes time for document delivery or parking. It affects the time when the delivery status is registered. ||
|| `service_duration_s` | Order handling time, in seconds. This includes time for delivering the order. ||
|| `shipment_size.weight_kg` | Order weight, kg. ||
|| `comments` | Order comment.

There is no limit on the maximum length. ||
|| `shared_with_company_ids` | IDs of the companies that have access to the order. [Learn more](https://docs.routeq.com/doc/en/delivery/functions/shared.md) ||
|| `shared_with_company_numbers` | Aliases of the companies that have access to the order. [Learn more](https://docs.routeq.com/doc/en/delivery/functions/shared.md) ||
|| `customer_number` | External number of the order's client. ||
|#

{% endcut %}

{% cut "Vehicles sheet" %}

Vehicle parameters.

#|
|| **Field** | **Description** ||
|| `id` | Username used to access the mobile app. A username can be the courier's identification number, the vehicle's license plate, the courier's phone number, and so on.
The maximum length is 80 characters. ||
|| `ref` | Vehicle number or any other unique identifier of the vehicle. Displayed in the interface.
The maximum length is 255 characters. ||
|| `imei` | GPS tracker number (if available).
Accepts a value from 1 to 9223372036854775807. ||
|| `phone` | Courier's phone number (if available).
The maximum length is 80 characters. ||
|| `depot_id` | ID of the depot (the `id` column on the **Depot** sheet). ||
|| `shifts.0.time_window` | Start and end time of the shift. Tracking starts after the shift start time. For more information, see [Route tracking](https://docs.routeq.com/doc/en/delivery/functions/tracking.md). ||
|| `shifts.1.time_window` | If the vehicles don't make second runs on the current day, this field can be left empty. If they do, specify the time window for the second run. ||
|#

{% endcut %}

{% cut "Depot sheet" %}

Depot parameters. If there are multiple depots, fill in a separate row for each depot.

#|
|| **Field** | **Description** ||
|| `id` | Depot number.
The maximum length is 80 characters. ||
|| `ref` | Additional depot ID.
The maximum length is 1023 characters. ||
|| `title` | Depot name.
The maximum length is 1023 characters. ||
|| `point.lat` | Depot latitude. ||
|| `point.lon` | Depot longitude. ||
|| `address` | Depot address.
The maximum length is 1023 characters. ||
|| `time_window` | Depot working hours. Does not affect tracking. You can specify `00:00–23:59`. ||
|#

{% endcut %}

{% cut "Routes sheet" %}

A binding between orders and vehicles.

#|
|| **Field** | **Description** ||
|| `vehicle_id` | Vehicle ID (`id` on the **Vehicles** sheet).
The maximum length is 80 characters. ||
|| `shift_index` | Shift number. If the vehicles don't make second runs on the current day, set `0`. ||
|| `location_id` | Order number (`id` on the **Orders** sheet).
The maximum length is 80 characters. ||
|| `route_number` | Route ID. Used if a client has their own unique `route_number` that they want to identify routes by. For the route number in Track & Trace to match the `route_number`, specify one or multiple shifts `shifts.N.time_window` on the **Vehicles** sheet. ||
|#

{% endcut %}

### Working with duplicates {#duplicate-orders}

Duplicates are orders with duplicate numbers.

If there are duplicates in the route that you import from Excel, Track & Trace will warn you about this. Notifications and possible actions will be shown in the **Import routes** window on the **Orders** tab.

![](./_images/duplicates-actions.png)

To import data, select one of the following actions:

**Keep duplicates and rename numbers in the new route**

Duplicate orders will be renamed so that the route date is added to the duplicate number.

{% cut "Example" %}

As of July 1, you need to import a route where `Order 1224047488` is a duplicate of the order from the route for June 30.

Once imported with the **Keep duplicates and rename numbers in the new route** condition, the order from the June 30 route still has the number `Order 1224047488`, while the number of the order from the July 1 route is changed to `Order 1224047488 2021-07-01`.

{% endcut %}

**Keep duplicates in the new route only**

A duplicate is moved from the old to the new route.

{% cut "Example" %}

As of July 1, you need to import a route where `Order 1224047488` is a duplicate of the order from the route for June 30.

Once imported with the **Keep duplicates in the new route only** condition, the order with the number `Order 1224047488` from the June 30 route is deleted, while its duplicate remains in the July 1 route with the number unchanged.

{% endcut %}

**Leave unchanged**

This option means that the system doesn't perform any actions with duplicates.

If you try to import a route immediately after selecting this option, Track & Trace returns an error saying "Couldn't send imported data". First, replace duplicate orders on the Orders tab.

To avoid this error, manually delete the duplicate from Track & Trace before importing the route:

1. Right-click on the row with the duplicate.
2. Click **Delete row**.

   ![](./_images/duplicates-delete.png)

3. Go to the **Routes** tab.
4. In the route table, delete the row with the duplicate.
5. Click **Import**.

If you changed your mind and want to undo an action, click **Cancel**. You'll return to choosing an action with duplicates again.


## Order statuses when uploading routes {#order-status}

When uploading routes to Track & Trace, you need to select a status for newly created orders.

| Status  | When it's assigned | Buttons in the Yandex Courier app                                                                      |
| ---- | ---- | ------ |
| **Not approved** | If the courier needs to call the recipient before going to the delivery address. | The **Optimize route** and **Confirm order delivery** buttons are only available after a call is made. |
| **Approved** | If there is no need to make a call before delivering the order. | All buttons are available at once. |


## Uploading additional routes {#additional-load}

You can upload routes for a date that already has planned orders (for example, in case of [additional planning](https://docs.routeq.com/doc/en/vrp/additional-planning.md)).

When you add new routes for a day for which they already exist, you receive a warning:

- When exporting data from Planning: In the export to Track & Trace window.
- In the import interface: On the **Routes** tab.

Then you need to choose the appropriate action.

#|
|| **Option** | **Action** ||
|| **Only add new routes** | All old routes remain and new ones are uploaded.

{% note info "Limitation" %}

This option can be used when the routes you are uploading do not include any orders whose IDs are already present in Track & Trace.

{% endnote %} ||

|| **Replace all** | All old routes are deleted and new ones are added. ||

|| **Replace all except routes in progress** | Only routes that have not been started yet are deleted. New routes are uploaded. ||
|#


## Troubleshooting {#typical-problems}

Most often, when exporting or importing data, the system warns you about issues related to order IDs or depot numbers. You can resolve these issues both in the Planning file and the interface.

Below is a table with their possible reasons and ways to resolve them.

#|
|| **Issue** | **Possible cause** | **Solution** ||
|| **Order with ID <order_id> is already in Track & Trace** |
* Identical order numbers.
* Orders have not been completed on the current day and have been uploaded again to be used when planning routes for the next day. |
In the **Export solution** window, click **Duplicate repeat orders**.

These orders will have their numbers changed automatically, with the route date added at the end of `<order_id>`. ||
|| **Depot with number <depot_id> not found** |
* The depot isn't added in Routing Workspace.
* Incorrect depot number is given in the Planning file on the **Depot** sheet. |
* [Add the depot](https://docs.routeq.com/doc/en/delivery/interface/depots.md#add-depot) and specify its number in the Planning file or the interface (if the depot is not added).
* Edit the depot number in the Planning file or the interface (if the depot number is incorrect). ||
|#

{% include [warehouse-feedback](_includes/feedback-head-4e3f2a482500.md) %}