API · v1
订单进来，路线出去
从你已经在用的系统推送工单，取回排好序的路线，你自己的标识原样保留。三个接口，无需 SDK。
基础 URL
api.routemate.app/v1
鉴权
OAuth2 client_credentials
令牌有效期
3600 s
适用范围
Team 及以上套餐
三个调用，接口面就这么大
| 方法 | 路径 | 用途 |
|---|---|---|
| POST | /v1/integration-token | 用客户端凭据换取 bearer 令牌，有效期一小时 |
| POST | /v1/integration-import | 导入工单及其站点、对地址做地理编码、优化路线并分配司机 — 一次请求完成 |
| GET | /v1/integration-jobs | 工单与站点状态：进度计数、每个站点的状态、优化后的顺序 |
导入、地理编码、优化、分配
请求
POST /v1/integration-import HTTP/1.1
Authorization: Bearer {token}
Content-Type: application/json
{
"external_job_id": "WMS-2026-07-30-A",
"driver_email": "driver@fleet.com.au",
"optimize": true,
"stops": [
{ "external_stop_id": "SO-88214",
"address": "3/216 Brunswick St, Fitzroy VIC 3065",
"parcel_count": 2,
"duration_minutes": 4 }
]
}响应 · 200 OK
{
"job_id": "job_7Yq2c",
"external_job_id": "WMS-2026-07-30-A",
"assigned_to": "driver@fleet.com.au",
"optimized": true,
"stops_imported": 142,
"stops": [
{ "external_stop_id": "SO-88214",
"stop_id": "stp_9f2",
"sequence": 38,
"status": "pending" }
],
"warnings": []
}你的标识会保留
你传入的每个标识都会随返回结果一起回来，工单上有，每个站点上也有。你不必维护自己的订单号与我们的编号之间的映射表。
| external_job_id | 你自己的批次标识 — 每个站点都会带回来，因此无需维护映射表 |
| external_stop_id | 你的订单号或运单号，一直沿用到状态与完成环节 |
| address | 单行地址；导入时做地理编码，失败项以警告形式返回 |
| parcel_count | 用于该站点的装载与操作假设 |
| duration_minutes | 门口的作业时长 — 在模型中被真实消耗，而不是当作不存在 |
| driver_email | 把完成的路线分配给账户中已有的司机 |
出问题时会怎样
幂等写入
重复导入同一个 external_job_id 会更新原工单，而不是新建第二个。超时后重试是安全的。
部分成功
无法完成地理编码的站点会出现在 warnings[] 中，工单其余部分照常导入。不会因为一个地址有问题就让整个请求失败。
版本管理
版本包含在路径中。同一版本内只增加字段，不会删除或改作他用，因此今天写的集成会一直可用。