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


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

## Обязательные параметры запросов

1. В заголовке `Authorization` должен быть передан OAuth-токен: `Authorization: OAuth <ваш-OAuth-токен>`.

2. Для идемпотентных операций в заголовке `X-Idempotency-Token` передается `<unique-token>`.

3. В запросе должен быть указан идентификатор компании-клиента: `company_id: <company-id>`.

## Шаг 1. Создание склада

Создайте склад. 

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

```json
POST /api/integration/v1/refbook/depot/create?company_id={company_id}
Authorization: OAuth <token>
Accept-Language: en
Content-Type: application/json

{
  "depot_id": "depot-warehouse-1",
  "region_id": "zone-1",
  "is_primary": true,
  "location": {
    "address": {
      "full_text": "Москва, ул. Примерная, д. 1",
      "city": "Москва",
      "street": "ул. Примерная",
      "house": "1"
    },
    "coordinates": {
      "latitude": 55.751244,
      "longitude": 37.618423
    }
  },
  "depot_properties": {
    "service_duration_s": 300,
    "parking_duration_s": 180
  }
}
```

{% endcut %}

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

```json
{
  "depot_id": "depot-warehouse-1"
}
```

{% endcut %}

## Настройка зон доставки

**Здесь пока ничего нет. Нужна инфа.**

## Шаг 2. Управление курьерами

Зарегистрируйте курьеров и создайте им смены.

### Регистрация курьера

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

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

{
  "client_courier_id": "courier-42",
  "courier_contract_status": "working",
  "courier_info": {
    "home_region_id": "zone-1",
    "capabilities": {
      "vehicle_type": "bike",
      "max_weight_g": 15000,
      "units_quota": 6
    },
    "courier_tag_list": ["cold_chain"]
  }
}
```

{% endcut %}

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

```json
{
  "courier_id": "e1a196b3-3f9a-4f9f-8b3c-df4d0a7e2d1a"
}
```

{% endcut %}

### Обновление данных о курьере

При необходимости обновите данные о курьере.

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

```json
POST /api/integration/v1/couriers/courier/event-handler/courier_updated?company_id={company_id}
Authorization: OAuth <token>
Accept-Language: en
X-Idempotency-Token: courier-update-001
Content-Type: application/json

{
  "client_courier_id": "courier-42",
  "occurred_ts": "2025-10-23T10:00:00Z",
  "version": 2,
  "courier_updated_payload": {
    "courier_tag_list": ["cold_chain", "priority"],
    "capabilities": {
      "vehicle_type": "bike",
      "max_weight_g": 20000,
      "units_quota": 8
    }
  }
}
```

{% endcut %}

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

```json
{}
```

{% endcut %}

### Создание смены

Для назначения курьера на заказы передайте в запросе на создание смены обязательный параметр `assignment`. Допустимые типы параметра:

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

<!-- В перспективе возможно добавление иных типов (например, `score‑based`). -->

{% note warning %}

Курьер автоматически попадает в очередь при переходе смены в статус `ongoing`.

{% endnote %}

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

```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-morning-001",
  "region_id": "zone-1",
  "status": "planned",
  "assignment": {
    "type": "queue",
    "queue_id": "default"
  },
  "shift_info": {
    "planned_time_interval": {
      "from": "2025-10-23T09:00:00Z",
      "to": "2025-10-23T18:00:00Z"
    }
  }
}
```

{% endcut %}

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

```json
{
  "shift_id": "shift-42"
}
```

{% endcut %}

### Обновление статуса смены {#update-shift-status}

Чтобы начать смену, обновите статус.

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

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

{
  "client_courier_id": "courier-42",
  "client_shift_id": "shift-morning-001",
  "occurred_ts": "2025-10-23T09:00:10Z",
  "shift_updated_payload": {
    "status": "ongoing",
    "actual_started_ts": "2025-10-23T09:00:10Z"
  }
}
```

{% endcut %}

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

```json
{}
```

{% endcut %}

#### Возможные статусы смен

| Статус | Описание |
| --- | --- |
| `planned` | Смена запланирована |
| `ongoing` | Смена в процессе |
| `completed` | Смена завершена |
| `cancelled` | Смена отменена |

## Шаг 3. Управление заказами

Добавьте заказы в систему и обновите их статусы.

#### Возможные статусы заказов

| Статус | Описание |
| --- | --- |
| `created` | Заказ создан |
| `preparing_for_delivery` | Заказ готовится к доставке |
| `ready_for_delivery` | Заказ готов к доставке |
| `assigned` | Заказ назначен на курьера (в маршруте) |
| `delivery_in_progress` | Заказ в процессе доставки |
| `completed` | Заказ доставлен |
| `cancelled` | Заказ отменён |

### Создание заказа

Создайте заказ.

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

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

{
  "client_order_id": "order-12345",
  "region_id": "zone-1",
  "status": "created",
  "client_order_status": "waiting_for_pickup",
  "delivery_policy": {
    "type": "time_interval",
    "time_interval": {
      "from": "2025-10-23T12:00:00Z",
      "to": "2025-10-23T14:00:00Z"
    }
  },
  "location": {
    "address": {
      "full_text": "Москва, проспект Мира, 2"
    },
    "coordinates": {
      "latitude": 55.789,
      "longitude": 37.632
    }
  },
  "content": {
    "dimensions": {
      "units_count": 1,
      "weight_gross_g": 5200
    }
  },
  "required_tag_list": ["cold_chain"],
  "order_priority": "standard",
  "depot_id": "depot-warehouse-1",
  "payment_info": {
    "payment_method": "cash"
  },
  "stage_durations": {
    "order_preparing_duration_s": 1000,
    "source_order_exchange_service_duration_s": 100,
    "destination_order_exchange_service_duration_s": 120
  },
  "recipient_info": {
    "recipient_id": "recipient-1"
  },
  "order_ready_for_delivery_eta": "2025-10-23T11:00:00Z"
}
```

{% endcut %}

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

```json
{
  "order_id": "a2b0d6aa-8d43-4b21-9c51-b7ac44e493b1"
}
```

{% endcut %}

### Обновление статуса заказа

Обновите статус заказа, например, на `Готов к доставке`.

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

```json
POST /api/integration/v1/orders/order/event-handler/order_updated?company_id={company_id}
Authorization: Oauth <token>
Accept-Language: en
X-Idempotency-Token: order-ready-001
Content-Type: application/json

{
  "client_order_id": "order-12345",
  "occurred_ts": "2025-10-23T10:55:00Z",
  "order_updated_payload": {
    "status": "ready_for_delivery",
    "client_order_status": "ready"
  }
}
```

{% endcut %}

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

```json
{
  "status_update": {
    "was_updated": true
  }
}
```

{% endcut %}

## Шаг 4. Построение маршрутов

Постройте маршруты и управляйте ими.

Маршрут может быть создан двумя способами:

* [автоматически](#auto);
* [вручную](#manual).

#### Возможные статусы маршрутов

| Статус | Описание |
| --- | --- |
| `draft` | Маршрут создан, но не принят (заказы не привязаны жестко) |
| `accepted` | Маршрут принят (заказы привязаны жестко) |
| `ongoing` | Маршрут выполняется |
| `completed` | Маршрут завершен |
| `cancelled` | Маршрут отменен |

### Автоматическое создание маршрута {#auto}

В этом сценарии система автоматически назначает заказы из копилки доступным курьерам (со сменой в статусе `ongoing`).  

#### Построение маршрута {#auto-add-route}

В запросе передайте параметр `expected_next_call` — время следующего вызова системы для построения маршрутов.

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

```json
POST /api/integration/v1/routes/build-routes?company_id={company_id}
Authorization: Oauth <token>
Accept-Language: en
X-Idempotency-Token: build-routes-001
Content-Type: application/json

{
  "region_id": "zone-1",
  "expected_next_call": "2025-10-23T11:00:00Z"
}
```

{% endcut %}

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

```json
{
  "route_list": [
    {
      "route_id": "route-1",
      "client_route_id": "auto-route-20251023-100000-abc123",
      "shift_id": "shift-42",
      "courier_id": "e1a196b3-3f9a-4f9f-8b3c-df4d0a7e2d1a",
      "point_list": [
        {
          "point_type": "depot",
          "depot_id": "depot-warehouse-1",
          "position": 1
        },
        {
          "point_type": "order",
          "order_id": "a2b0d6aa-8d43-4b21-9c51-b7ac44e493b1",
          "client_order_id": "order-12345",
          "position": 2
        }
      ]
    }
  ],
  "total_orders_assigned": 1
}
```

{% endcut %}

#### Принятие маршрута (жесткая привязка заказов)

После автоматического построения маршрут находится в статусе `draft`. Чтобы активировать маршрут, отправьте запрос на принятие. После принятия маршрута:

* статус маршрута меняется на `accepted`;

* все заказы жестко привязываются к маршруту;

* другие маршруты с этими заказами можно будет принять, только если отменить текущий маршрут.

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

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

{
  "client_route_id": "auto-route-20251023-100000-abc123"
}
```

{% endcut %}

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

```json
{}
```

{% endcut %}

### Ручное создание маршрута {#manual}

При необходимости создайте маршрут вручную.

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

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

{
  "client_route_id": "manual-route-001",
  "region_id": "zone-1",
  "status": "draft",
  "shift_identity": {
    "client_shift_id": "shift-morning-001"
  },
  "route_info": {
    "planned_start_ts": "2025-10-23T11:00:00Z"
  },
  "point_list": [
    {
      "point_type": "depot",
      "depot_id": "depot-warehouse-1",
      "position": 1
    },
    {
      "point_type": "order",
      "order_identity": {
        "client_order_id": "order-12345"
      },
      "position": 2
    }
  ]
}
```

{% endcut %}

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

```json
{
  "route_id": "route-2"
}
```

{% endcut %}

### Отмена маршрута

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

* статус маршрута меняется на `cancelled`;

* все заказы отвязываются от маршрута;

* можно будет принять другие маршруты с этими заказами.

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

```json
POST /api/integration/v1/routes/route/cancel?company_id={company_id}
Authorization: Oauth <token>
Accept-Language: en
X-Idempotency-Token: cancel-route-001
Content-Type: application/json

{
  "client_route_id": "manual-route-001",
  "occurred_ts": "2025-10-23T10:45:00Z"
}
```

{% endcut %}

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

```json
{}
```

{% endcut %}

## Шаг 5. Отслеживание исполнения заказов

Зафиксируйте события выполнения заказов (прибытие курьера на склад, отправление со склада, доставка).

Возможны следующие значения параметра `checkpoint_type`:

* `arrival` — прибытие курьера на точку;

* `departure` — отправление курьера с точки.

### Прибытие курьера на склад — забор заказа

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

```json
POST /api/integration/v1/orders/order/depot/checkpoint?company_id={company_id}
Authorization: Oauth <token>
Accept-Language: en
X-Idempotency-Token: depot-arrival-001
Content-Type: application/json

{
  "checkpoint_type": "arrival",
  "occurred_ts": "2025-10-23T11:05:00Z",
  "client_order_id_list": ["order-12345"]
}
```

{% endcut %}

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

```json
{
  "result_list": [
    {
      "client_order_id": "order-12345",
      "is_success": true
    }
  ]
}
```

{% endcut %}

### Отправление курьера со склада

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

```json
POST /api/integration/v1/orders/order/depot/checkpoint?company_id={company_id}
Authorization: Oauth <token>
Accept-Language: en
X-Idempotency-Token: depot-departure-001
Content-Type: application/json

{
  "checkpoint_type": "departure",
  "occurred_ts": "2025-10-23T11:10:00Z",
  "client_order_id_list": ["order-12345"]
}
```

{% endcut %}

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

```json
{
  "result_list": [
    {
      "client_order_id": "order-12345",
      "is_success": true
    }
  ]
}
```

{% endcut %}

### Прибытие курьера к клиенту

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

```json
POST /api/integration/v1/orders/order/destination/checkpoint?company_id={company_id}
Authorization: Oauth <token>
Accept-Language: en
X-Idempotency-Token: destination-arrival-001
Content-Type: application/json

{
  "checkpoint_type": "arrival",
  "occurred_ts": "2025-10-23T11:30:00Z",
  "client_order_id_list": ["order-12345"]
}
```

{% endcut %}

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

```json
{
  "result_list": [
    {
      "client_order_id": "order-12345",
      "is_success": true
    }
  ]
}
```

{% endcut %}

### Успешная доставка заказа

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

```json
POST /api/integration/v1/orders/order/destination/checkpoint?company_id={company_id}
Authorization: Oauth <token>
Accept-Language: en
X-Idempotency-Token: destination-departure-001
Content-Type: application/json

{
  "checkpoint_type": "departure",
  "occurred_ts": "2025-10-23T11:35:00Z",
  "client_order_id_list": ["order-12345"]
}
```

{% endcut %}

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

```json
{
  "result_list": [
    {
      "client_order_id": "order-12345",
      "is_success": true
    }
  ]
}
```

{% endcut %}

### Обновление статуса заказа — заказ доставлен

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

```json
POST /api/integration/v1/orders/order/event-handler/order_updated?company_id={company_id}
Authorization: Oauth <token>
Accept-Language: en
X-Idempotency-Token: order-completed-001
Content-Type: application/json

{
  "client_order_id": "order-12345",
  "occurred_ts": "2025-10-23T11:35:00Z",
  "order_updated_payload": {
    "status": "completed",
    "client_order_status": "delivered"
  }
}
```

{% endcut %}

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

```json
{
  "status_update": {
    "was_updated": true
  }
}
```

{% endcut %}

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


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