Custom route fields
To consider route information that is not covered by the standard fields, you can create custom fields custom_fields
.
This feature is only available in the API.
To add and delete fields, contact support. You can also ask which custom fields have already been added.
When working with custom fields, note the following:
- You can only apply fields to a route that have been added in the company settings.
- The user determines the field format and content on their own.
- No more than 10 fields can be added for one company.
- The maximum length of the field, including the name and value, is 255 characters.
- If you delete a field, it will remain in routes that have already been created.
- If you edit a route, only the fields in the request will be saved. All other fields will be deleted from the route.
Custom fields are displayed:
- In the Map section.Example
- In the courier card.Example
- In the Courier performance report.Example
Creating a route
To create a route with custom fields:
- Contact support and tell them the names of the fields to add. For example,
route_type
androute_priority
. Send a POST request to the routes resource. Go to the
custom_fields
array element. Enter the name in thekey
field and the value in thevalue
field. In the sample request below, we'll enter the valueintercity
forroute_type
and0
forroute_priority
.
- Query
-
cURL
curl -H "Content-Type: application/json" -H "Authorization: Auth your-token" -X POST -d @<File_path_in_UTF-8_encoding> https://courier.yandex.ru/api/v1/companies/<your-company-id>/routes
Copied to clipboardFile
{ "courier_number": "Courier 1", "date": "2022-05-12", "number": "add-custom-fields", "depot_number": "111", "route_start": "8:00:00", "route_finish": "19:00:00", "custom_fields": [ { "key": "route_type", "value": "intercity" }, { "key": "route_priority", "value": "0" } ] }
Copied to clipboard - Result
-
{ "id": <route-id>, "company_id": <your-company-id>, "courier_id": <courier-id>, "car_id": null, "custom_fields": [ { "key": "route_type", "value": "intercity" }, { "key": "route_priority", "value": "0" } ], "depot_id": <depot-id>, "number": "add-custom-fields", "date": "2022-05-12", "imei": null, "rented_courier_id": null, "courier_violated_route": false, "routing_mode": "driving", "tracking_start_h": null, "route_start": "08:00:00", "route_finish": "19:00:00", "imei_str": null }
Copied to clipboard
Editing a route
To change custom field values, send a PATCH request to the routes resource. For example, you can leave only the route_priority
field with the value 1
in the route.
- Query
-
cURL
curl -H "Content-Type: application/json" -H "Authorization: Auth your-token" -X PATCH -d @<File_path_in_UTF-8_encoding> https://courier.yandex.ru/api/v1/companies/<your-company-id>/routes/<route-id>
Copied to clipboardFile
{ "courier_number": "Courier 1", "date": "2022-05-12", "number": "add-custom-fields", "depot_number": "111", "route_start": "8:00:00", "route_finish": "19:00:00", "custom_fields": [ { "key": "route_priority", "value": "1" } ] }
Copied to clipboard - Result
-
{ "id": <route-id>, "company_id": <your-company-id>, "courier_id": <courier-id>, "car_id": null, "custom_fields": [ { "key": "route_priority", "value": "1" } ], "depot_id": <depot-id>, "number": "add-custom-fields", "date": "2022-05-12", "imei": null, "rented_courier_id": null, "courier_violated_route": false, "routing_mode": "driving", "tracking_start_h": null, "route_start": "08:00:00", "route_finish": "19:00:00", "imei_str": null }
Copied to clipboard
Getting a route
To get routes with custom field values, send a GET request to the routes resource.
- Query
-
cURL
curl -H "Content-Type: application/json" -H "Authorization: Auth your-token" -X GET -d @<File_path_in_UTF-8_encoding> https://courier.yandex.ru/api/v1/companies/<your-company-id>/routes
Copied to clipboard - Result
-
[ { "id": <route-id>, "company_id": <your-company-id>, "courier_id": <courier-id>, "car_id": null, "custom_fields": [ { "key": "route_priority", "value": "1" } ], "depot_id": <depot-id>, "number": "add-custom-fields", "date": "2022-05-12", "imei": null, "rented_courier_id": null, "courier_violated_route": false, "routing_mode": "driving", "tracking_start_h": null, "route_start": "08:00:00", "route_finish": "19:00:00", "imei_str": null } ]
Copied to clipboard