跳到主要内容

2. 运单 CRUD

运单(waybill)是系统里的核心单据,代表一票货。一张运单下挂若干包裹(parcel/package)。

操作接口
建单POST /api/waybills
列表GET /api/waybills
详情GET /api/waybills/{waybillNo}
改单PATCH /api/waybills/{waybillNo}
取消DELETE /api/waybills/{waybillNo}
查轨迹GET /api/waybills/{waybillNo}/events
预分配单号POST /api/waybills/allocate-number
面单 PDFGET /api/waybills/{waybillNo}/label

以上均需 waybills 套餐功能。

建单​

POST /api/waybills

:::caution 字段命名 建单接口使用 camelCase 字段名(outTradeNo、parcelList、receiverName……),这是为兼容早期集成保留的格式。不要用 recipient / packages 这类命名,会直接返回 422。 :::

必填字段​

字段类型说明
outTradeNostring你自己系统的单号,作为幂等键。重复推送同一个值的行为由 overwrite 参数决定
parcelListarray包裹列表,至少 1 个

寄件人 / 收件人​

不传 route_id 时,以下字段必填:

字段类型说明
senderPhonestring寄件人电话。系统据此匹配你已登记的发货地址
receiverNamestring收件人姓名
receiverPhonestring收件人电话
receiverProvinceNamestring省
receiverCityNamestring市
receiverPostCodestring邮编
receiverAddressstring详细地址

receiverDistrictName(区/县)可选但强烈建议传。其余可选:senderName、senderAddress、senderCityName、senderDistrictName、senderPostCode、receiverPhone2。

传了 route_id 时,收发双方从线路的首尾节点推导,上述字段全部变为可选。

提示

收件地址建议先用地址解析接口规范化,拿到标准的省/市/区/邮编再填进来,能显著降低分拣异常率。

parcelList 每一项​

字段类型必填说明
outParcelNostring是你自己的包裹号
itemDescstring是品名描述
itemValuenumber是货值,不能为负
weightnumber否重量(kg)
length / width / heightnumber否尺寸(cm)
piece_countnumber否件数(正整数)
productListarray否商品明细
photosarray否图片 URL

productList 每项:sku、name 必填,quantity、weight、length、width、height 可选。

productList 每项还可以带一个可选的 metadata 对象,存放这件产品的自定义信息,比如报关用的生产资料:

{
"sku": "SKU-001",
"name": "Wireless Mouse",
"quantity": 2,
"metadata": { "hsCode": "8471.60", "origin": "CN", "manufacturer": "Example Electronics Ltd" }
}
  • 任意 JSON 对象,按 UTF-8 编码的 JSON 计不超过 8 KB。超过 8 KB 或不是对象(比如字符串),返回 422 参数校验失败。
  • 详情接口在 packages[].products[].metadata 里原样返回;没传的产品返回 null。
  • 用 overwrite=overwrite 重新推送同一张单时,同一包裹里 sku 相同的产品如果没传 metadata,保留原来的值;传 null 则清空。
  • 新增包裹接口(POST /api/waybills/{waybillNo}/packages)的 parcel.productList 同样接受 metadata。
  • TMS 后台的运单详情页会把它按“名称 / 值”逐行显示出来,只读,不能在页面上改。

常用可选字段​

字段类型说明
service_iduuid指定服务
route_iduuid指定线路,收发双方从线路推导
sender_accountobject{ code?, id? },关联到某个客户账号
additional_service_idsuuid[]增值服务
insuranceobject{ declaredValue },保价金额(组织结算币种)
autoSplitboolean默认 true,每件商品拆成独立包裹;批量同款货请传 false 并用 piece_count
estimatedWeight / estimatedVolume / volumetricWeightnumber整票计费总量
reference_nostring内部参考号
remarkstring备注

route_id 必须是你自己组织的线路。传了别的组织的线路或不存在的线路,返回 400(错误码 1000,"Route not found"),运单不会创建。查询运单时返回的线路,也是你自己组织在这票运单上的线路:别的组织分配给你的运单,返回你的线路,没有就为空。

重复推送的处理​

用 query 参数 overwrite 控制同一个 outTradeNo 再次推送时的行为:

值行为
overwrite默认,覆盖原运单(原地更新,运单 ID 不变)
reject返回 409 重复运单
return_existing原样返回已有运单,不做修改
return_if_accepted已接单则原样返回,否则返回 422(未分配承运商)
警告

不传 overwrite 时,重复推送会直接覆盖已有运单。如果你需要防止重复建单,请显式传 overwrite=reject。

POST /api/waybills?overwrite=return_existing

请求示例​

{
"api_key": "ak_example000000",
"nonceStr": "1771545600000",
"sign": "(按鉴权章节算出的 64 位大写十六进制)",
"outTradeNo": "ORDER-2026-001",
"senderPhone": "0212345678",
"senderName": "Acme 仓库",
"senderAddress": "123 Sukhumvit Road",
"senderCityName": "Bangkok",
"senderPostCode": "10110",
"receiverName": "张三",
"receiverPhone": "0812345678",
"receiverProvinceName": "Bangkok",
"receiverCityName": "Bangkok",
"receiverDistrictName": "Chatuchak",
"receiverPostCode": "10900",
"receiverAddress": "456 Phaholyothin Road",
"parcelList": [
{
"outParcelNo": "PKG-001",
"itemDesc": "电子产品",
"itemValue": 1200,
"weight": 1.5,
"length": 30,
"width": 20,
"height": 15
}
],
"remark": "易碎,轻拿轻放"
}

成功返回 201 和运单详情,其中包含系统生成的 waybill_no。

建单错误​

HTTP错误码含义
4221000参数校验失败,error 里会指出具体字段
4091003运单已存在(overwrite=reject 时)
4031000该单号属于别的组织
4001000寄件人地址匹配不到,或缺少寄件人电话

route_id 不是你自己组织的线路时,也返回 400、错误码 1000,见常用可选字段。

查询运单​

列表​

GET /api/waybills?page=1&pageSize=20

返回 { data, total, page, pageSize, totalPages }。

警告

这是 GET 请求,签名字段要放在 query string 里,并且所有参数值签名前都要转成字符串。详见鉴权章节。

详情​

GET /api/waybills/{waybillNo}

{waybillNo} 既可以传系统运单号,也可以传你自己的 outTradeNo,系统会自动识别。

修改运单​

PATCH /api/waybills/{waybillNo}

只接受以下 7 个字段,传其他字段会被忽略:

reference_no、notes、tags、priority、requires_signature、sender_account_id、product_category_id

传空对象会返回 400 "No valid fields to update"。

需要改地址、包裹或重量?用 overwrite=overwrite 重新推送整张单。

取消运单​

DELETE /api/waybills/{waybillNo}

只有处于可取消状态的运单才能取消,否则返回 400。运单不存在返回 404。

备注

DELETE 的签名字段放在 JSON body 里,和 POST 一样。

面单 PDF​

GET /api/waybills/{waybillNo}/label

直接返回 application/pdf 二进制流,不是 JSON。可选 query 参数 packageId 用于只打某一个包裹的面单。

批量打印:

POST /api/waybills/batch-label
{ "waybill_nos": ["WB001", "WB002"] }

单次最多 100 张,返回合并后的 PDF。

预分配单号​

需要先拿到单号再建单(比如要先印面单)时:

POST /api/waybills/allocate-number

请求体除签名字段外可以为空,返回 { "number": "ABC1A748213905" }。该功能需要组织启用自定义单号。

响应格式​

系统有两种响应信封,同一个接口返回哪种取决于请求方,不影响请求体格式。

默认格式​

成功直接返回数据本身,失败返回 {"error":"..."},并且 HTTP 状态码是真实的:

{ "error": "运单不存在" }

兼容信封​

带上 X-Legacy-Response: true 时,或你的组织被配置为兼容模式时,返回统一信封,且 HTTP 状态码永远是 200,靠 code 判断成败:

{
"code": 1006,
"success": false,
"message": "运单不存在",
"data": null,
"extra": null
}
警告

包裹相关接口(新增包裹、拆分包裹)强制使用兼容信封,永远返回 HTTP 200。接入这两个接口时务必检查 code 而不是 HTTP 状态码。

错误码​

code含义
0成功
-1系统错误
1000参数校验失败
1001组织不存在
1002签名验证失败
1003运单重复
1004发货地址未匹配到
1005收货地址未匹配到
1006运单不存在
1007未分配承运方
1008包裹重复

运单状态​

运单状态与轨迹事件类型是同一套枚举:

draft、created、picked_up、accepted、delivering、delivered、failed、exception、canceled、rescheduled、returning、returned、in_transit_sorted、in_transit_hub_inbound、in_transit_hub_outbound

其中 in_transit_sorted、in_transit_hub_inbound、in_transit_hub_outbound 是可重复发生的(货物会多次经过中转场)。

查询轨迹见配送规划与跟踪。