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

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

В заголовке Authorization должен быть передан OAuth-токен: Authorization: OAuth <ваш-OAuth-токен>.
Для идемпотентных операций в заголовке X-Idempotency-Token передается <unique-token>.
В запросе должен быть указан идентификатор компании-клиента: company_id: <company-id>.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

{}

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

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

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

Важно

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

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

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

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

{
  "shift_id": "shift-42"
}

Обновление статуса смены

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

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

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

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

{}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

{
  "status_update": {
    "was_updated": true
  }
}

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

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

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

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

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

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

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

Построение маршрута

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

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

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

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

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

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

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

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

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

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

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

{}

Ручное создание маршрута

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

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

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

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

{
  "route_id": "route-2"
}

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

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

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

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

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

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

{}

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

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

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

arrival — прибытие курьера на точку;
departure — отправление курьера с точки.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

{
  "status_update": {
    "was_updated": true
  }
}

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

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

Сценарии работы с API

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