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

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

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

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

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

   Подробнее о балансировке

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

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

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

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

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

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

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

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

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

1. Автоматически при переходе смены в статус ongoing (через обновление статуса смены).

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

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

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"
    }
  }
}

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

При автоматическом построении маршрута сервис:

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

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

3. Обновляет очередь — курьеры, получившие заказы, отправляются в конец очереди с новым 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) ← отправлен в конец после выполнения заказа
  

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

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

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"
    }
  }
}

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"
    }
  }
}

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

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

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

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

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"
  }
}

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

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

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"
    }
  }
}

{}

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

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

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

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

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

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"
    }
  }
}