物流运输

场景简介

本平台适用于物流运输场景，支持多车辆、多司机、多任务的智能调度。平台可灵活配置团队、司机、车辆、任务等信息，并支持多种业务约束（如优先级、时间窗、重量、体积等），满足实际运输业务的复杂需求。通过 API 可实现团队创建、司机与车辆管理、任务下发、批量调度、结果查询等全流程操作。

准备工作

注册获取平台账号。
获取 API 访问地址、账号邮箱、密码、团队编码等信息。
推荐使用 VSCode 并安装 rest-client 插件，便于直接运行 HTTP 脚本。

操作流程

1. 登录获取 Token

首先通过登录接口获取访问令牌（token），后续所有接口均需携带该 token。

http

@server_url=https://kd1.kuaihe.tech/api/v1

POST {server_url}/auth/login
Content-Type: application/json

{
  "email": "{email}",
  "password": "{password}"
}

登录成功后，返回的 token 用于后续接口的 Authorization 头部。

2. 创建团队

团队是调度的基本单位。创建团队时可配置地图中心点、调度约束、时间窗口、导航服务等参数。

http

POST {server_url}/teams/
Authorization: Bearer {jwtoken}
Content-Type: application/json

{
    "code": "demo", "name": "测试团队", 
    "geo_longitude": 120.3784, 
    "geo_latitude": 36.1086, 
    "planner_service": {"code": "single_opti6"}, 
    "flex_form_data": {
        "fixed_horizon_flag": "0", 
        "window_refresh_at": "0;30;1;30",
        "env_start_datetime": "2025-06-04T00:00:00", 
        "nbr_minutes_planning_windows_duration": 1440,
        "nbr_minutes_backward_planning_window": 0,
        "timezone": "Asia/Shanghai",
        "enable_priority_constraint": 1,
        "enable_time_window_constraint": 1,
        "enable_driver_assignment": 1,
        "enable_weight_constraint": 1,
        "enable_volume_constraint": 1,
        "enable_max_order_constraint": 1,
        "enable_max_travel_time": 1,
        "max_ratio_weight": 0.9,
        "max_ratio_volume": 0.8,
        "front_routing_type": "osrm",
        "front_routing_url": "https://routing.kandbox.tech/china",
        "tile_server": "tianditu"
    }
}

@team_code=demo

code：团队唯一标识（必选）。
name：团队名称。
geo_longitude、geo_latitude：配置团队所在位置，地图中心点。
fixed_horizon_flag 、window_refresh_at：1 固定，0 不固定。 fixed_horizon_flag=0时根据window_refresh_at配置的每天0:30-1:30 会自动刷新调度开始时间。
env_start_datetime：调度窗口开始时间，格式为：YYYY-MM-DDTHH:MM:SS。
nbr_minutes_planning_windows_duration：调度窗口时长，单位：分钟。
nbr_minutes_backward_planning_window：调度窗口回退时长，单位：分钟。
enable_priority_constraint：开启优先级约束，0 关闭，1 开启。
enable_time_window_constraint：开启送达时间约束，0 关闭，1 开启。
enable_driver_assignment：开启司机分配约束，0 关闭，1 开启。
enable_weight_constraint: 开启重量约束，0 关闭，1 开启。
enable_volume_constraint：开启体积约束，0 关闭，1 开启。
enable_max_order_constraint：开启最大订单量约束，0 关闭，1 开启。
enable_max_travel_time：开启最大行驶时间约束，0 关闭，1 开启。
max_ratio_weight: 最大载负载 0-1 0.9 代表载重量80%
max_ratio_volume: 最大载体积 0-1 0.8 代表载体积80%
timezone：配置时区。
tile_server：配置地图组件默认地图: osm[OSM]、 tianditu[天地图]、autonavi[高德]。
front_routing_type：配置导航服务类型，osrm[道路距离]polyline[直线距离]。
front_routing_url：配置导航服务地址。

我们同样提供可独立使用的地图组件(拥有区域管理、独立调度、圈选任务、装箱动画、轨迹查看等功能)，如有需要可联系获取

3. 创建司机

每个司机可配置工作时间，支持每天单独设置。

http

POST {server_url}/drivers/
Authorization: Bearer {jwtoken}
Content-Type: application/json

{
    "code": "d1", 
    "name": "司机1",
    "team": {"code": "{team_code}"},
    "business_hour": {
        "monday": [{"open": "0005", "close": "2330", "id": "a0", "isOpen": true}], 
        "tuesday": [{"open": "0005", "close": "2330", "id": "a1", "isOpen": true}], 
        "wednesday": [{"open": "0005", "close": "2330", "id": "a2", "isOpen": true}], 
        "thursday": [{"open": "0005", "close": "2330", "id": "a3", "isOpen": true}], 
        "friday": [{"open": "0005", "close": "2330", "id": "a4", "isOpen": true}], 
        "saturday": [{"open": "0005", "close": "2330", "id": "a5", "isOpen": true}], 
        "sunday": [{"open": "0005", "close": "2330", "id": "a6", "isOpen": true}]
    },
    "is_active": true
}

code：司机唯一标识（必选）。
name：司机名称。
team：司机所属团队。
business_hour：配置司机工作时间。
- monday 表示周一 0005-2330 表示周一工作时间从0005到2330 , isOpen 表示是否开启。
is_active：是否激活司机。

4. 创建车辆

车辆可配置容量、尺寸等参数，并可手动绑定司机。

http

POST {server_url}/workers/
Authorization: Bearer {jwtoken}
Content-Type: application/json

{
    "code": "w1", 
    "name": "车辆1",
    "team": {"code": "{team_code}"},
    "driver": {"code": "d1"},
    "geo_longitude": 120.3784,
    "geo_latitude": 36.1086,
    "flex_form_data": {
        "area_code": "A",
        "capacity_volume": "10",
        "capacity_weight": "1000",
        "depth": "500",
        "height": "200",
        "width": "200"
    },
    "business_hour": {
        "monday": [{"open": "0005", "close": "2330", "id": "a0", "isOpen": true}], 
        "tuesday": [{"open": "0005", "close": "2330", "id": "a1", "isOpen": true}], 
        "wednesday": [{"open": "0005", "close": "2330", "id": "a2", "isOpen": true}], 
        "thursday": [{"open": "0005", "close": "2330", "id": "a3", "isOpen": true}], 
        "friday": [{"open": "0005", "close": "2330", "id": "a4", "isOpen": true}], 
        "saturday": [{"open": "0005", "close": "2330", "id": "a5", "isOpen": true}], 
        "sunday": [{"open": "0005", "close": "2330", "id": "a6", "isOpen": true}]
    },
    "auto_planning": true,
    "is_active": true
}

code：车辆唯一标识（必选）。
name：车辆名称。
team：车辆所属团队。
geo_longitude、geo_latitude：配置车辆所在位置
is_active：是否激活车辆。
auto_planning：是否允许被自动分配， true 允许 false 不允许
business_hour：配置车辆工作时间。
- monday: 表示周一 0005-2330 表示周一工作时间从0005到2330 , isOpen 表示是否开启。
  - open: 0005 表示周一工作开始时间
  - close: 2330 表示周一工作结束时间
  - id: a0 表示周一工作id
  - isOpen: true 表示周一是否工作
flex_form_data：配置车辆扩展字段。
- area_code：配置车辆所在区域。
- capacity_volume: 配置车辆容量，单位：立方米。
- capacity_weight：配置车辆容量，单位：千克。
- max_nbr_orders：可选配置车辆接受最大订单数量。
- depth、width、height：配置车辆长宽高，单位：厘米。
driver：手动绑定配置车辆司机，不传入则不绑定司机。

5. 创建运输任务

任务可配置优先级、包裹信息、送达时间窗等参数。

创建含优先级的任务

http

POST {server_url}/jobs/
Authorization: Bearer {jwtoken}
Content-Type: application/json

{
    "code":"J30-1",
    "team": {"code": "{team_code}"},
    "job_type": "visit",
    "auto_planning": false,
    "is_active": true,
    "planning_status": "U",
    "geo_longitude": 120.3350,
    "geo_latitude": 36.0664,
    "requested_start_datetime": "2025-06-03T09:00:00",
    "requested_duration_minutes": 1,
    "flex_form_data": {
        "area_code": "A",
        "priority": 10
    }
}

code：任务唯一标识（必选）。
team：任务所属团队。
job_type：任务类型，visit[送货]、pickup[取货]。
auto_planning：是否立刻分配 true 允许 false 不允许
is_active：是否激活任务。
planning_status：任务状态，U[未规划]、I[已规划]。
geo_longitude、geo_latitude：配置任务所在位置。
requested_start_datetime 请求开始时间，格式为：YYYY-MM-DDTHH:MM:SS。
requested_duration_minutes 停留时间，单位：分钟。
flex_form_data 扩展字段，用于配置任务的优先级、送达时间窗等参数。
- area_code 区域编码。包裹所属区域
- priority 优先级 1-100 越大优先级越高，默认1。
- weight 任务总重量
- volume 任务总体积
- service_window 送达时间窗，格式为：YYYYMMDDHHMM:YYYYMMDDHHMM，表示送达时间窗的开始和结束时间。
- packages 包裹信息 list
  - name 包裹名称
  - width 包裹宽度米
  - depth 包裹深度米
  - height 包裹高度米
  - weight 包裹重量克
  - quantity 包裹数量

创建带包裹信息的任务

创建任务时，可以传入包裹信息，用于计算任务的重量和体积。

http

POST {server_url}/jobs/
Authorization: Bearer {jwtoken}
Content-Type: application/json

{
    "code":"J30-2",
    "team": {"code": "{team_code}"},
    "job_type": "visit",
    "auto_planning": false,
    "is_active": true,
    "planning_status": "U",
    "geo_longitude": 120.3253,
    "geo_latitude": 36.0608,
    "requested_start_datetime": "2025-06-03T10:30:00",
    "requested_duration_minutes": 5,
    "flex_form_data": {
        "area_code": "A",
        "packages": [
            {"name": "small", "width": "1", "depth": "1", "height": "1", "weight": "10", "quantity": 1},
            {"name": "big", "width": "2", "depth": "2", "height": "2", "weight": "50", "quantity": 1}
        ]
    }
}

创建带送达时间窗的任务

创建带送达时间窗的约束的任务

http

POST {server_url}/jobs/
Authorization: Bearer {jwtoken}
Content-Type: application/json

{
    "code":"J30-3",
    "team": {"code": "{team_code}"},
    "job_type": "visit",
    "auto_planning": false,
    "is_active": true,
    "planning_status": "U",
    "geo_longitude": 120.3240,
    "geo_latitude": 36.0622,
    "requested_start_datetime": "2025-06-03T12:00:00",
    "requested_duration_minutes": 15,
    "flex_form_data": {
        "area_code": "A",
        "service_window": "202506030200:202506030230"
    }
}

6. 重置调度环境

在添加或修改团队配置、车辆（排班）、任务后建议重置调度窗口以刷新调度环境。

http

POST {server_url}/planner_service/reset_planning_window/
Authorization: Bearer {jwtoken}
Content-Type: application/json

{
    "team_code":  "{team_code}"
}

7. 执行批量调度

所有任务创建完成后，调用批量调度接口进行自动分配。

http

POST {server_url}/planner_service/run_batch_optimizer/
Authorization: Bearer {jwtoken}
Content-Type: application/json

{
    "team_code": "{team_code}",

    "worker_codes": "w1;w2",
    "job_codes": "J30-1;J30-2"
}

team_code 团队编码
worker_codes 可选，限定只分配给固定的worker，不传入则分配给所有worker
job_codes 可选，限定只分配固定的job ，不传入则分配所有job

8. 查询调度结果

可按车辆查询任务分配结果及司机分配情况。

http

POST {server_url}/planner_service/get_env_jobs/
Authorization: Bearer {jwtoken}
Content-Type: application/json

{
    "team_code": "{team_code}", 
    "worker_codes": "w1;w2;",
    "reset_start_datetime": false,
    "active_only": false
}

返回示例：

json

{
  "w1": [
    {
      "code": "J30-1",
      "scheduled_start_datetime": "2025-06-03T09:00:00",
      "prev_travel": 2.0,
      "scheduled_duration_minutes": 10.0,
      "driver_code": "d1"
    }
  ],
  "w2": [
    {
      "code": "J30-2",
      "scheduled_start_datetime": "2025-06-03T10:30:00",
      "prev_travel": 0.0,
      "scheduled_duration_minutes": 5.0,
      "driver_code": "d2"
    }
  ]
}

w1: worker code
- code: job code
- scheduled_start_datetime: 调度开始时间
- driver_code: 司机code

结果查看

规划结束后，您可以登录快盒调度平台。或者在Map组件上该能在看到已被规划的业务和工作人员及执行路径。

调试用接口

批量删除jobs

可以删除指定jobs，用于测试。

http

POST {server_url}/jobs/utils/batch_delete
Authorization: Bearer {jwtoken}
Content-Type: application/json

{
    "team_code": "{team_code}"
    "job_codes": ["J30-1","J30-2"]
}

team_code 团队编码
job_codes 可选，限定只删除固定的job ，不传入则删除所有job

删除团队

可以删除团队及团队下所有job、worker、driver，用于测试。

http

POST {server_url}/teams/utils/batch_delete
Authorization: Bearer {jwtoken}
Content-Type: application/json

{
    "team_code": "{team_code}"
}

物流运输 ​

场景简介 ​

准备工作 ​

操作流程 ​

1. 登录获取 Token ​

2. 创建团队 ​

3. 创建司机 ​

4. 创建车辆 ​

5. 创建运输任务 ​

创建含优先级的任务 ​

创建带包裹信息的任务 ​

创建带送达时间窗的任务 ​

6. 重置调度环境 ​

7. 执行批量调度 ​

8. 查询调度结果 ​

结果查看 ​

调试用接口 ​

批量删除jobs ​

删除团队 ​

物流运输

场景简介

准备工作

操作流程

1. 登录获取 Token

2. 创建团队

3. 创建司机

4. 创建车辆

5. 创建运输任务

创建含优先级的任务

创建带包裹信息的任务

创建带送达时间窗的任务

6. 重置调度环境

7. 执行批量调度

8. 查询调度结果

结果查看

调试用接口

批量删除jobs

删除团队