Упрощенный сценарий работы с API

Шаг 1. Построение маршрута

Отправьте запрос на создание маршрута и передайте в нем следующую информацию:

список доступных на складе курьеров со сменами и настройками назначения курьера в очередь;
список заказов, готовых к доставке;
пресеты (опционально).

Cервис Экспресс-доставки обработает запрос и запланирует маршрут.

Пример запроса

POST /api/integration/v1/routes/create?company_id={company_id}

Authorization: Oauth <token>
Accept-Language: en
X-Idempotency-Token: build-routes-000
Content-Type: application/json

{
  "region_id": "string",
  "planning_time_info": {
    "current_planning_time": "2025-08-13T07:00:00.000Z",
    "next_planning_time": "2025-08-13T07:00:00.000Z"
  },
  "courier_list": [
    {
      "client_courier_id": "string",
      "courier_info": {
        "home_region_id": "string",
        "vehicle_type": "pedestrian",
        "carrying_capacity": {
          "weight_g": 0,
          "units_count": 0
        },
        "route_limits": {
          "stop_count_limit": 1,
          "distance_km_limit": 0
        },
        "courier_tag_list": [
          "string"
        ]
      },
      "shift": {
        "client_shift_id": "string",
        "shift_info": {
          "depot_id": "string",
          "planned_time_interval": {
            "from": "2025-08-13T07:00:00.000Z",
            "to": "2025-08-13T07:00:00.000Z"
          },
          "actual_started_ts": "2025-08-13T07:00:00.000Z",
          "actual_ended_ts": "2025-08-13T07:00:00.000Z",
          "break_time_interval_list": [
            {
              "from": "2025-08-13T07:00:00.000Z",
              "to": "2025-08-13T07:00:00.000Z"
            }
          ]
        },
        "assignment": {
          "type": "queue",
          "queue_id": "string",
          "rank": 0
        }
      }
    }
  ],
  "order_list": [
    {
      "client_order_id": "string",
      "status": "created",
      "client_order_status": "string",
      "location": {
        "address": {
          "country": "string",
          "city": "string",
          "street": "string",
          "house": 1,
          "building": 1,
          "floor": 4,
          "entrance": 4,
          "full_text": "string"
        },
        "coordinates": {
          "latitude": 0,
          "longitude": 0
        }
      },
      "delivery_policy": {
        "type": "time_interval",
        "time_interval": {
          "from": "2025-08-13T07:00:00.000Z",
          "to": "2025-08-13T07:00:00.000Z"
        }
      },
      "content": {
        "carrying_requirements": {
          "weight_g": 0,
          "units_count": 0
        },
        "verbose_item_list": [
          {
            "item_verbose_name": "пицца",
            "quantity": 1
          }
        ]
      },
      "required_tag_list": [
        "string"
      ],
      "order_priority": "standard",
      "depot_id": "string",
      "stage_durations": {
        "order_preparing_duration_s": 0,
        "source_order_exchange_service_duration_s": 0,
        "destination_order_exchange_service_duration_s": 0,
        "parking_service_durations": {
          "car_parking_duration_s": 0,
          "bike_parking_duration_s": 0
        }
      },
      "payment_info": {
        "payment_method": "string"
      },
      "recipient_info": {
        "recipient_id": "some_recipient_id"
      }
    }
  ],
  "solver_options_preset_id": "fast_delivery_preset"
}

Пример ответа

{
  "id": "task-id-12345",
  "status": {
    "queued": 0,
    "started": 0,
    "completed": 0,
    "cancelled": 0,
    "estimate": 0
  },
  "message": "string"
}

Шаг 2. Обновление маршрута

Чтобы актуализировать маршрут, отправьте повторный POST-запрос. Сервис обновит данные и сформирует новый маршрут.

Обновление заказов

Алгоритм сопоставляет заказы из полученного запроса с теми, что уже передавались в сервис, и обновляет данные:

Заказы, которые были переданы ранее, но отсутствуют в новом запросе, удаляются.
Заказы, которые не были переданы ранее, добавляются как новые.
Для заказов, которые были переданы ранее и присутствуют в новом запросе:
- обновляются все поля (приоритет, адрес и др.), которые переданы в запросе;
- остальные поля сохраняются без изменений.

Обновление курьеров

Алгоритм сопоставляет курьеров из запроса с теми, что уже зарегистрированы в сервисе, и обновляет данные:

Курьеры, которые были переданы ранее, но отсутствуют в новом запросе, считаются временно недоступными.
Курьеры, которые не были переданы ранее, регистрируются в сервисе.
Для курьеров, которые которые были переданы ранее и присутствуют в новом запросе:
- обновляются все поля (смена, настройки назначения и др.), которые переданы в запросе;
- остальные поля сохраняются без изменений.

Шаг 3. Запрос результата

Получите информацию о статусе задачи с помощью метода FetchBuildRoutesResult, используя task_id, который вы получили на шаге 1.

Написать в службу поддержки

Была ли статья полезна?

Основной сценарий работы с API

Полный цикл доставки заказа