Получение маршрутов

Маршруты строятся на день и склад: Orda распределяет заказы со статусом new по машинам с учётом грузоподъёмности и объёма, окон доставки, смены и обеда водителя, места выезда (склад или дом водителя) и считает время прибытия, километры и топливо.

Построить план

curl -s -X POST "$ORDA_API/plans" -H "X-Api-Key: $ORDA_KEY" -H "Content-Type: application/json" \
  -d '{ "date": "2026-11-20", "warehouseId": "<uuid склада>", "quality": "best" }'

• vehicleIds — только эти машины (по умолчанию все активные машины склада);
• quality: fast или best (дольше, но точнее).

Результат — черновик плана. Повторное построение на тот же день заменяет черновик. Обычно план строит и правит диспетчер в кабинете, а учётная система только получает утверждённый результат.

Прочитать план

GET /plans?date=2026-11-20 — планы дня; GET /plans/{id} — план целиком:

{
  "id": "…", "date": "2026-11-20", "status": "approved",
  "totals": { "routes": 4, "orders": 28, "unassigned": 1, "distanceKm": 212.4, "fuelL": 31.2 },
  "unassigned": [ { "orderId": "…", "number": "РТ-00017", "reason": "does_not_fit" } ],
  "routes": [ {
    "id": "…",
    "vehicle": { "id": "…", "plateNumber": "345ABK02", "model": "Isuzu NPR" },
    "driver": { "id": "…", "fullName": "Серик Ахметов" },
    "startMode": "depot", "endMode": "depot",
    "leaveAt": "08:40", "returnAt": "16:55", "distanceKm": 58.3, "durationMin": 495,
    "stops": 7, "loadKg": 1840, "loadPct": 61, "fuelL": 8.2, "fuelCost": 1886,
    "timeline": [
      { "seq": 0, "kind": "load", "arriveAt": "08:40", "departAt": "09:10" },
      { "seq": 1, "kind": "delivery", "orderId": "…", "orderNumber": "РТ-00001",
        "customerName": "Магазин «Арман»", "address": "Алматы, ул. Сатпаева, 30",
        "location": { "lat": 43.2365, "lon": 76.9286 },
        "arriveAt": "09:32", "departAt": "09:47", "waitingMin": 0, "distanceKm": 6.1 }
    ]
  } ]
}

Типы точек kind: home (выезд из дома), load (погрузка на складе), delivery, break (обед), end. Время — в часовом поясе компании. Причины нераспределения: no_location (нет координат), does_not_fit (не хватает машин, вместимости или времени).

Утвердить план

POST /plans/{id}/approve (право routes.approve) — план становится окончательным, заказы получают статус assigned. Утверждать может диспетчер в кабинете или ваша система.

Как забирать маршруты в учётную систему

Рекомендуется: подписаться на вебхук plan.approved — в нём список заказов плана; затем один раз запросить GET /plans/{planId} и создать в своей системе маршрутные листы / рейсы. Черновые маршруты приходят событием route.planned — полезно, если вы показываете прогноз до утверждения.

Без вебхуков: опрашивайте GET /plans?date=… не чаще раза в минуту и забирайте планы со status: "approved".