---
metadata:
  - name: generator
    content: Diplodoc Platform v5.52.0
alternate:
  - https://yandex.kz/routing/doc/ru/oob/guidelines/assignment.md
  - href: ru/oob/guidelines/assignment.md
    type: text/markdown
    title: Markdown version
  - href: ../llms.txt
    type: text/markdown
    title: llms.txt
title: Яндекс Маршрутизация — экспресс-доставка — управление очередями курьеров
---
> **Documentation Index:** Fetch the complete configuration index at https://yandex.kz/routing/doc/ru/llms.txt


# Управление очередями курьеров

Настройте очередность назначения курьеров на заказы и управляйте ей для балансировки загрузки.

При назначении заказа курьер перемещается в конец очереди. Изменение очереди происходит после завершения маршрута (возврата на склад).

Сервис поддерживает два способа назначения курьеров на заказы (тип параметра `assignment`):

1. `queue` (с указанием `queue_id`) — курьер добавляется в указанную очередь, обеспечивается балансировка загрузки.

    {% cut "Подробнее о балансировке" %}

    Сервис отслеживает для каждого курьера и использует при автоматической балансировке следующие метрики:

    * количество назначенных заказов;

    * время последнего назначения;

    * `score` — оценка для балансировки.

    {% endcut %}

1. `none` — назначение без определенной логики, система не гарантирует балансировку или справедливое распределение.

Очередь задается через параметр `assignment_state` в смене курьера, где `rank` — монотонно возрастающий номер позиции в очереди:

```json
{
  "type": "queue",
  "queue_id": "<id>",
  "rank": <number>
}
```

## Сценарий 1. Включение курьера в очередь при создании смены

Курьер попадает в очередь двумя способами:

1. Автоматически при переходе смены в статус `ongoing` (через [обновление](https://yandex.kz/routing/doc/ru/oob/guidelines/base.md#update-shift-status) статуса смены).

2. При использовании очереди, указанной в параметре `assignment.queue_id` при создании смены.

Чтобы включить курьера в конкретную очередь, при создании смены явно укажите `assignment`.

{% cut "Пример запроса" %}

```json
POST /api/integration/v1/couriers/shift/store?company_id={company_id}
Authorization: Bearer <token>
Accept-Language: en
Content-Type: application/json

{
  "client_courier_id": "courier-42",
  "client_shift_id": "shift-morning-001",
  "region_id": "zone-1",
  "status": "planned",
  "assignment": {
    "type": "queue",
    "queue_id": "priority_queue"
  },
  "shift_info": {
    "planned_time_interval": {
      "from": "2025-10-23T09:00:00Z",
      "to": "2025-10-23T18:00:00Z"
    }
  }
}
```

{% endcut %}

## Сценарий 2. Работа с очередью при автоматическом построении маршрута

При [автоматическом](https://yandex.kz/routing/doc/ru/oob/guidelines/base.md#auto) построении маршрута сервис:

1. Выбирает курьеров из очереди — берет курьеров с наименьшим `rank` (первые в очереди).

1. Назначает заказы — распределяет заказы между выбранными курьерами.

1. Обновляет очередь — курьеры, получившие заказы, отправляются в конец очереди с новым `rank` после выполнения маршрута.

Пример поведения очереди:

* исходное состояние очереди:

    ```
    1. courier-1 (rank: 100)
    2. courier-2 (rank: 101)
    3. courier-3 (rank: 102)
    ```

* состояние очереди после назначения заказов **courier-1** и **courier-2**: 

    ```
    1. courier-3 (rank: 102)
    2. courier-1 (rank: 103) ← отправлен в конец после выполнения заказа
    3. courier-2 (rank: 104) ← отправлен в конец после выполнения заказа
    ```

{% note warning %}

Очередь изменится только после выполнения маршрута курьером.

{% endnote %}

## Сценарий 3. Использование множественных очередей

Сервис поддерживает несколько независимых очередей с помощью разных `queue_id`. Вы можете создать смены для разных очередей.

{% cut "Пример запроса на создание смены для курьера в очереди bikes" %}

```json
POST /api/integration/v1/couriers/shift/store?company_id={company_id}
Authorization: Oauth <token>
Accept-Language: en
Content-Type: application/json

{
  "client_courier_id": "courier-42",
  "client_shift_id": "shift-bike-001",
  "region_id": "zone-1",
  "status": "planned",
  "assignment": {
    "type": "queue",
    "queue_id": "bikes_zone1"
  }
},
  "shift_info": {
    "planned_time_interval": {
      "from": "2025-10-23T09:00:00Z",
      "to": "2025-10-23T18:00:00Z"
    }
  }
}
```

{% endcut %}

{% cut "Пример запроса на создание смены для курьера в очереди pedestrian" %}

```json
POST /api/integration/v1/couriers/shift/store?company_id={company_id}
Authorization: Oauth <token>
Accept-Language: en
Content-Type: application/json

{
  "client_courier_id": "courier-43",
  "client_shift_id": "shift-walk-001",
  "region_id": "zone-1",
  "status": "planned",
  "assignment": {
    "type": "queue",
    "queue_id": "pedestrian_zone1"
  }
},
  "shift_info": {
    "planned_time_interval": {
      "from": "2025-10-23T09:00:00Z",
      "to": "2025-10-23T18:00:00Z"
    }
  }
}
```

{% endcut %}

## Сценарий 4. Исключение курьера из очереди

Курьер автоматически исключается из очереди и параметр `assignment_state` сбрасывается:

* при завершении смены — статус `completed`;

* при отмене смены — статус `cancelled`.

{% cut "Пример запроса на завершение смены" %}

```json
POST /api/integration/v1/couriers/shift/event-handler/shift_updated?company_id={company_id}
Authorization: Bearer <token>
Accept-Language: en
X-Idempotency-Token: shift-end-001
Content-Type: application/json

{
  "client_courier_id": "courier-42",
  "client_shift_id": "shift-morning-001",
  "occurred_ts": "2025-10-23T18:00:00Z",
  "shift_updated_payload": {
    "status": "completed",
    "actual_ended_ts": "2025-10-23T18:00:00Z"
  }
}
```

{% endcut %}

## Сценарий 5. Изменение очереди во время смены

Чтобы немедленно переместить курьера из текущей очереди в нужную, отправьте запрос на [обновление](https://yandex.kz/routing/doc/ru/oob/guidelines/base.md#update-shift-status) статуса смены.

{% cut "Пример запроса" %}

```json
POST /api/integration/v1/couriers/shift/event-handler/shift_updated?company_id={company_id}
Authorization: Bearer <token>
Accept-Language: en
X-Idempotency-Token: change-queue-001
Content-Type: application/json

{
  "client_courier_id": "courier-42",
  "client_shift_id": "shift-morning-001",
  "occurred_ts": "2025-10-23T12:00:00Z",
  "shift_updated_payload": {
    "assignment": {
      "type": "queue",
      "queue_id": "priority_queue"
    }
  }
}
```

{% endcut %}

{% cut "Пример ответа" %}

```json
{}
```

{% endcut %}

## Сценарий 6. Использование назначения без определенной логики

Используйте сценарий в случае, если у вас нет очередей или вы только интегрируетесь с сервисом экспресс-доставки.

В случае задания параметру `assignment` типа `none` сервис будет назначать курьеров на маршруты, используя внутреннюю логику:

* курьер не попадает ни в одну очередь;

* сервис назначает заказы без гарантии балансировки.

{% cut "Пример запроса на создание смены" %}

```json
POST /api/integration/v1/couriers/shift/store?company_id={company_id}
Authorization: Bearer <token>
Accept-Language: en
Content-Type: application/json

{
  "client_courier_id": "courier-42",
  "client_shift_id": "shift-morning-001",
  "region_id": "zone-1",
  "status": "planned",
  "assignment": {
    "type": "none"
  },
  "shift_info": {
    "planned_time_interval": {
      "from": "2025-10-23T09:00:00Z",
      "to": "2025-10-23T18:00:00Z"
    }
  }
}
```

{% endcut %}


<!-- source: ru/oob/_includes/feedback.md -->
<a href="feedback">
  <span class="button">Написать в службу поддержки</span>
</a>


<!-- endsource: ru/oob/_includes/feedback.md -->