物流履约 API
物流履约 API
本文归纳物流基础资料、发货单、包裹、运单、车次、批次、仓入库、仓库存、仓中转、仓派送、配送员任务、退货物流和报关接口。
使用场景
物流履约接口覆盖订单发货后的完整链路：
| 场景 | 主要接口 | 说明 |
|---|---|---|
| 商户发货 | 发货单、发货单明细 | 商户根据订单履约任务发货 |
| 包裹建档 | 包裹、包裹类型、件级单元 | 建立包裹和运单关系 |
| 干线运输 | 车次、批次、运单、轨迹 | 车次封批、装车、发运和轨迹同步 |
| 仓内入库 | 仓入库查询、仓入库操作 | 到仓确认、预查询、正式入库和回退 |
| 仓内库存 | 仓库存查询、仓库存操作 | 库位、包裹库存、复核、移库 |
| 仓间中转 | 仓中转查询、仓中转操作 | 创建中转任务、加包、封批、封车、出库 |
| 末端派送 | 仓派送查询、仓派送操作、配送员任务 | 分拣、分配配送员、签收、失败、退仓 |
| 逆向和报关 | 退货物流单、报关单 | 售后退货和跨境报关资料 |
核心对象关系
| 对象 | 说明 | 上下游 |
|---|---|---|
| 发货单 | 订单进入履约后的业务单据 | 上游订单，下游发货明细 |
| 发货明细 | 单个订单商品的履约明细 | 上游发货单，下游包裹 |
| 包裹 | 物流流转核心实体 | 可进入车次、批次、仓库存、派送任务 |
| 车次 | 一段运输计划 | 包含批次 |
| 批次 | 车次中的包裹集合 | 用于封批和装车 |
| 运单 | 对内或对外物流单据 | 关联轨迹、包裹和件级单元 |
| 仓库存 | 包裹在仓内的状态和库位 | 入库、复核、移库、中转、派送 |
| 分拣任务 | 中转或派送前的仓内分拣动作 | 关联包裹和任务明细 |
| 派送任务 | 配送员执行的末端任务 | 关联派送明细和签收结果 |
后端物流状态机
物流接口大多不是简单 CRUD，而是状态机动作。入库、复核、中转、派送和签收都需要后端校验当前状态、仓库、库位、任务归属和业务占用。
| 动作 | 前置校验 | 结果 |
|---|---|---|
| 到仓确认 | 车次存在、目标仓匹配、未重复确认 | 车次和批次进入可入库状态 |
| 入库预查询 | 编号可识别、包裹属于该车次或仓库、状态可入库 | 返回可入库包裹和阻断原因 |
| 正式入库 | 预查询结果可入库、仓库和库位有效 | 包裹进入 INBOUND，生成仓库存记录 |
| 仓内复核 | 包裹在当前仓、状态为 INBOUND 或可复核状态 |
包裹标记 reviewed = true，通常进入 STORED |
| 中转加包 | 包裹在起始仓、状态满足中转、无未完成任务占用 | 加入批次和分拣任务 |
| 中转出库 | 批次和车次已封 | 包裹进入 IN_TRANSIT |
| 派送加包 | 包裹在当前仓、已复核、目的地区和库位匹配 | 创建派送明细 |
| 完成分拣 | 分拣任务可完成且有有效包裹 | 包裹进入 DISPATCHED |
| 配送签收 | 当前用户是配送员、任务归属正确、明细可操作 | 包裹进入 SIGNED，运单段完成 |
| 失败退仓 | 明细失败且允许退仓 | 包裹回到 ARRIVED，可重新派送 |
通用物流接口
| 端别 | 接口名称 | 方法 | 路径 | 权限标识 | 主要用途 | 主要调用端 | 后端 Controller |
|---|---|---|---|---|---|---|---|
| shared | 物流公司 | GET /list、GET /page、GET /{companyId}、POST、PUT、DELETE |
/api/v1/system/logistics/company |
*:system:logistics:company:* |
物流公司基础资料 | admin、ops |
LogisticsCompanyController |
| shared | 区域城市映射 | GET /page、POST、PUT、DELETE |
/api/v1/system/logistics/region/city |
*:system:logistics:region:city:* |
城市归属和区域配置 | admin |
LogisticsRegionCityMappingController |
| shared | 运费规则 | GET /list、GET /page、POST、PUT、DELETE |
/api/v1/system/logistics/rule |
*:system:logistics:rule:* |
运费规则配置和查询 | admin、client |
LogisticsRegionShippingRuleController |
| shared | 物流仓库 | GET /list、GET /page、GET /{warehouseId}、POST、PUT、DELETE |
/api/v1/logistics/warehouse |
*:logistics:warehouse:* |
物流仓库资料 | admin、ops |
LogisticsWarehouseController |
| shared | 包裹类型 | GET /list、GET /page、GET /{packageTypeId}、POST、PUT、DELETE |
/api/v1/logistics/package-type |
*:logistics:package-type:* |
包裹类型维护 | admin |
LogisticsPackageTypeController |
| shared | 车次 | GET /list、GET /page、GET /{shipmentId}、POST、PUT、DELETE |
/api/v1/logistics/shipment |
*:logistics:shipment:* |
运输车次管理 | admin、ops |
LogisticsShipmentController |
| shared | 车次路线 | GET /list、GET /page、GET /{routeId}、POST、PUT、DELETE |
/api/v1/logistics/shipment-route |
*:logistics:shipment-route:* |
仓间路线维护 | admin |
LogisticsShipmentRouteController |
| shared | 车次批次 | GET /list、GET /page、GET /{batchId}、POST、PUT、DELETE |
/api/v1/logistics/shipment-batch |
*:logistics:shipment:batch:* |
批次管理 | admin、ops |
LogisticsShipmentBatchController |
| shared | 包裹基础 | POST、PUT /{packageId}、DELETE /{packageId}、POST /warehouse-inbound-waybill |
/api/v1/logistics/package |
*:logistics:package:* |
包裹创建、更新、删除和入库运单创建 | admin、ops |
LogisticsPackageController |
| shared | 包裹件级单元 | GET /list、GET /page、GET /{packageUnitId} |
/api/v1/logistics/package-unit |
*:logistics:package-unit:* |
件级包裹查询 | admin、client |
LogisticsPackageUnitController |
| shared | 件级轨迹 | GET /list、GET /page、GET /{packageUnitTrackId} |
/api/v1/logistics/package-unit-track |
*:logistics:package-unit-track:* |
件级轨迹查询 | admin、client |
LogisticsPackageUnitTrackController |
| shared | 运单 | GET /list、GET /page、GET /{waybillId}、GET /package-no/{packageNo}、GET /{waybillId}/tracks、POST /{waybillId}/tracks、PUT /{waybillId}/track-sync |
/api/v1/logistics/waybill |
*:logistics:waybill:* |
运单、轨迹和轨迹同步 | admin、client |
LogisticsWaybillController |
发货、退货和报关
| 端别 | 接口名称 | 方法 | 路径 | 权限标识 | 主要用途 | 主要调用端 | 后端 Controller |
|---|---|---|---|---|---|---|---|
| shared | 发货单 | GET /list、GET /page、GET /{deliveryOrderId}、POST、PUT、DELETE |
/api/v1/logistics/delivery-order |
*:logistics:delivery-order:* |
履约发货单查询和维护 | admin、ops |
LogisticsDeliveryOrderController |
| shared | 发货单明细 | GET /list、GET /page、GET /{itemId}、PUT /{itemId}/shipping |
/api/v1/logistics/delivery-order-item |
*:logistics:delivery-order-item:* |
按发货明细执行发货 | admin、ops |
LogisticsDeliveryOrderItemController |
| shared | 入库单 | GET /list、GET /page、GET /{inboundOrderId}、POST、PUT、DELETE |
/api/v1/logistics/inbound-order |
*:logistics:inbound-order:* |
入库单管理 | admin |
LogisticsInboundOrderController |
| shared | 入库单明细 | GET /list、GET /page、GET /{itemId} |
/api/v1/logistics/inbound-order/item |
*:logistics:inbound-order:item:* |
入库明细查询 | admin |
LogisticsInboundOrderItemController |
| shared | 退货物流单 | GET /list、GET /page、GET /{returnOrderId}、POST、PUT、DELETE |
/api/v1/logistics/return-order |
*:logistics:return-order:* |
退货物流管理 | admin、client |
LogisticsReturnOrderController |
| admin | 报关单 | GET /list、GET /page、GET /{declarationId}、POST、PUT、DELETE |
/api/v1/logistics/customs-declaration |
admin:logistics:customs-declaration:* |
报关资料和状态管理 | admin |
LogisticsCustomsDeclarationController |
仓作业接口
| 端别 | 接口名称 | 方法 | 路径 | 权限标识 | 主要用途 | 主要调用端 | 后端 Controller |
|---|---|---|---|---|---|---|---|
| admin | 国内快速流程 | POST /context、POST /shipment/{shipmentId}/batch、POST /batch/{batchId}/scan-inbound、POST /batch/{batchId}/seal、POST /batch/{batchId}/reopen、POST /batch/{batchId}/package/{packageId}/remove、POST /shipment/{shipmentId}/load-complete、POST /shipment/{shipmentId}/unload、POST /shipment/{shipmentId}/cancel、POST /shipment/{shipmentId}/outbound |
/api/v1/logistics/fast-process |
admin:logistics:fast:* |
国内快速入库出库 | admin、ops |
LogisticsFastInboundOutboundController |
| admin | 国内仓查询 | GET /context/page、GET /context/{contextId}、GET /warehouse/list |
/api/v1/logistics/domestic-warehouse |
admin:logistics:domestic-warehouse:* |
国内仓流程查询 | admin、ops |
LogisticsDomesticWarehouseQueryController |
| admin | 仓入库查询 | GET /shipment/page、GET /detail/{shipmentId} |
/api/v1/logistics/warehouse/inbound |
admin:logistics:warehouse:inbound:query |
到仓和入库查询 | ops |
LogisticsWarehouseInboundQueryController |
| admin | 仓入库操作 | PUT /shipment/{shipmentId}/arrive-confirm、POST /preview、POST /execute、PUT /package/{packageId}/rollback、PUT /batch/{batchId}/rollback |
/api/v1/logistics/warehouse/inbound |
admin:logistics:package:inbound |
到仓确认、入库预查询、正式入库和回退 | ops |
LogisticsWarehouseInboundController |
| admin | 仓库存查询 | GET /package/list、GET /package/page、GET /package/{packageId}、POST /package/inbound-preview、GET /{warehouseId}/stock-overview、GET /storage-history/page、GET /storage-history/{id} |
/api/v1/logistics/warehouse-inventory |
admin:logistics:warehouse-inventory:* |
仓内包裹、库位和库存流水查询 | ops |
LogisticsWarehouseInventoryQueryController |
| admin | 仓库存操作 | POST /package/inbound、POST /package/transfer、POST /package/review |
/api/v1/logistics/warehouse-inventory |
admin:logistics:warehouse-inventory:* |
仓内入库、移库和复核 | ops |
LogisticsWarehouseInventoryOperationController |
| admin | 仓中转查询 | GET /shipment/page、GET /shipment/detail/{shipmentId}、GET /batch/detail/{batchId}、GET /sorting-task/page、GET /sorting-task/detail/{sortingTaskId} |
/api/v1/logistics/warehouse/transfer |
admin:logistics:warehouse:transfer:query |
中转任务、批次和车次查询 | ops |
LogisticsWarehouseTransferQueryController |
| admin | 仓中转操作 | POST /context、POST /shipment/{shipmentId}/batch、POST /batch/{batchId}/package、PUT /batch/{batchId}/seal、PUT /shipment/{shipmentId}/seal、POST /shipment/{shipmentId}/outbound |
/api/v1/logistics/warehouse/transfer |
admin:logistics:warehouse:transfer:* |
创建中转上下文、加包、封批、封车、出库 | ops |
LogisticsWarehouseTransferController |
| admin | 仓派送查询 | GET /task/page、GET /task/detail/{dispatchTaskId}、GET /employee/list、GET /employee/{employeeAccountId}/task/page |
/api/v1/logistics/warehouse/dispatch |
admin:logistics:warehouse:dispatch:query |
派送任务和配送员查询 | ops |
LogisticsWarehouseDispatchQueryController |
| admin | 仓派送操作 | POST /context、POST /sorting-task/{sortingTaskId}/package、DELETE /sorting-task/{sortingTaskId}/package/{packageId}、PUT /sorting-task/{sortingTaskId}/cancel、PUT /sorting-task/{sortingTaskId}/complete、PUT /sorting-task/{sortingTaskId}/rollback-complete、PUT /dispatch-task/{dispatchTaskId}/assign-employee、PUT /dispatch-task-item/{dispatchTaskItemId}/complete、PUT /dispatch-task-item/{dispatchTaskItemId}/fail、PUT /dispatch-task-item/{dispatchTaskItemId}/return-warehouse |
/api/v1/logistics/warehouse/dispatch |
admin:logistics:warehouse:dispatch:* |
创建派送上下文、分拣加包、完成分拣、分配配送员和仓端代操作派送明细 | ops |
LogisticsWarehouseDispatchController |
| admin | 分拣任务 | GET /list、GET /page、GET /{sortingTaskId}、POST、PUT、DELETE |
/api/v1/logistics/sorting-task |
admin:logistics:sorting-task:* |
分拣任务基础管理 | admin |
LogisticsSortingTaskController |
| admin | 分拣明细 | GET /list、GET /page、GET /{itemId} |
/api/v1/logistics/sorting-task-item |
admin:logistics:sorting-task-item:* |
分拣明细查询 | admin |
LogisticsSortingTaskItemController |
| admin | 派送任务 | GET /list、GET /page、GET /{dispatchTaskId}、PUT /{dispatchTaskId}/dispatch、PUT /{dispatchTaskId}/complete、PUT /{dispatchTaskId}/fail |
/api/v1/logistics/dispatch-task |
admin:logistics:dispatch-task:* |
派送任务管理 | admin |
LogisticsDispatchTaskController |
| admin | 派送明细 | GET /list、GET /page、GET /{itemId}、PUT /{itemId}/sign、PUT /{itemId}/fail、PUT /{itemId}/return-to-warehouse |
/api/v1/logistics/dispatch-task-item |
admin:logistics:dispatch-task:item:* |
派送明细和平台代操作 | admin |
LogisticsDispatchTaskItemController |
| admin | 配送员查询 | GET /task/page、GET /task/{dispatchTaskId}/detail、GET /task-item/page |
/api/v1/logistics/dispatcher/query |
admin:logistics:dispatcher:task:query |
配送员本人任务查询 | ops |
LogisticsDispatcherQueryController |
| admin | 配送员操作 | PUT /item/{itemId}/sign、PUT /item/{itemId}/fail、PUT /item/{itemId}/return-to-warehouse |
/api/v1/logistics/dispatcher/task |
admin:logistics:dispatcher:task:* |
配送员签收、失败和退仓 | ops |
LogisticsDispatcherTaskController |
海外仓说明
- 当前没有
/api/v1/logistics/overseas-warehouse/...Controller。 - 海外仓页面使用
/api/v1/logistics/warehouse/...和/api/v1/logistics/warehouse-inventory/...。 - 后端场景组件会校验仓库
abroad = true。 - 仓派送加包当前允许同仓的
ARRIVED或STORED包裹，但要求reviewed = true，并校验库位和目的地区；INBOUND包裹必须先复核。
海外仓页面不要根据 waybillStatus = COMPLETED 判断流程结束。跨仓运输段完成只代表运输到仓，后续可能仍需要入库、复核和派送。
推荐调用顺序
海外仓入库：
GET /api/v1/logistics/warehouse/inbound/shipment/page查询待入库车次。GET /api/v1/logistics/warehouse/inbound/detail/{shipmentId}查看车次详情。PUT /api/v1/logistics/warehouse/inbound/shipment/{shipmentId}/arrive-confirm确认到仓。POST /api/v1/logistics/warehouse/inbound/preview按编号预查询。POST /api/v1/logistics/warehouse/inbound/execute执行正式入库。POST /api/v1/logistics/warehouse-inventory/package/review执行仓内复核。
仓中转：
POST /api/v1/logistics/warehouse/transfer/context创建中转上下文。POST /api/v1/logistics/warehouse/transfer/shipment/{shipmentId}/batch创建批次。POST /api/v1/logistics/warehouse/transfer/batch/{batchId}/package批次加包。PUT /api/v1/logistics/warehouse/transfer/batch/{batchId}/seal封批。PUT /api/v1/logistics/warehouse/transfer/shipment/{shipmentId}/seal封车。POST /api/v1/logistics/warehouse/transfer/shipment/{shipmentId}/outbound发运出库。
仓派送：
GET /api/v1/logistics/warehouse/dispatch/employee/list查询配送员。POST /api/v1/logistics/warehouse/dispatch/context创建派送上下文。POST /api/v1/logistics/warehouse/dispatch/sorting-task/{sortingTaskId}/package分拣加包。PUT /api/v1/logistics/warehouse/dispatch/sorting-task/{sortingTaskId}/complete完成分拣。PUT /api/v1/logistics/warehouse/dispatch/dispatch-task/{dispatchTaskId}/assign-employee分配或改派配送员。- 配送员使用
/api/v1/logistics/dispatcher/query和/api/v1/logistics/dispatcher/task处理本人任务。
关键字段
| 字段 | 说明 |
|---|---|
warehouseId |
当前操作仓库，海外仓场景必须对应 abroad = true |
warehouseStorageId |
仓内库位，入库、中转、派送可能需要 |
shipmentId |
车次 ID |
batchId |
批次 ID |
packageId |
包裹 ID |
packageNo |
包裹编号，常用于扫码 |
waybillNo |
内部运单号 |
externalWaybillNo |
第三方运单号 |
sortingTaskId |
分拣任务 ID |
dispatchTaskId |
派送任务 ID |
employeeAccountId |
配送员员工账户 ID |
编号识别口径
仓作业经常通过扫码或输入编号继续流程。前端传参前需要明确编号类型，后端会按不同字段查找。
| 编号 | 含义 | 常见用途 |
|---|---|---|
shipmentNo |
车次号 | 到仓确认、中转恢复、入库查询 |
batchNo |
批次号 | 入库预查询、批次详情 |
packageNo |
包裹号 | 包裹查询、入库、复核、派送加包 |
waybillNo |
内部运单号 | 运单查询、包裹物流链恢复 |
externalWaybillNo |
第三方运单号 | 商户或承运商侧扫码识别 |
dispatchTaskId |
派送任务 ID | 派送任务详情和配送员任务 |
如果接口支持多种编号，页面应把用户输入原样传给对应预查询接口，让后端决定识别结果，不在前端复制复杂查找逻辑。
前端封装
admin/src/api/logisticsApi.ts、logisticsRegionCityApi.ts、logisticsRuleApi.ts。client/api/index.js的personalOrder分组中包含订单物流详情展示。ops/api/logistics.js是运营小程序物流主入口。
维护注意事项
- 入库、复核、中转和派送均属于状态机动作，前端不应绕过后端状态校验。
- 扫码输入可能是批次号、包裹号、内部运单号或第三方运单号，接口需要明确可识别范围。
- 派送员只能操作本人任务，后端必须校验员工身份和任务归属。
- 物流轨迹展示应优先展示业务编号，不要把纯 ID 当作对外编号。
- 回退接口需要严格限制权限和状态，避免已签收或已结算包裹被误回退。
ops现场作业失败时，应直接展示后端返回的阻断原因，例如仓库不匹配、未复核、已有未完成任务。- 任意流程中断后，应通过车次、批次、包裹或运单重新查询后端状态恢复，不依赖本地缓存。
联调验收
| 场景 | 验收口径 |
|---|---|
| 商户发货 | 发货后能查到包裹、运单和发货明细状态 |
| 到仓入库 | 车次到仓、预查询、正式入库和回退状态正确 |
| 仓内复核 | INBOUND 包裹复核后变为可中转或可派送状态 |
| 中转出库 | 批次加包、封批、封车、出库后包裹进入运输中 |
| 海外仓恢复 | 输入 shipmentNo、waybillNo 或 packageNo 能恢复当前步骤 |
| 派送加包 | 未复核或仓库不匹配的包裹不能加入派送 |
| 配送员签收 | 只有本人任务可签收，签收后包裹和运单状态同步 |
| 派送失败退仓 | 失败件可退仓并重新进入派送准备 |