ShipBidding 打单平台 · 统一发货 API 接口文档（对外版）

适用对象：接入本平台统一发货能力的客户/第三方系统开发者
接口范围：运费试算、创建订单（下单）、获取面单、取消订单，共 4 个核心接口
文档版本：v1.0（2026-10-05）

1. 概述

ShipBidding 打单平台统一发货 API 提供一套承运商无关的物流发货能力：调用方只需按本规范组装标准报文并携带客户 Token，平台自动完成渠道解析、下单、面单获取与归档、订单取消等全链路操作。

4 个接口的典型调用关系：

① 运费试算 rates/calculate（不产生订单、不扣费，可反复调用）
        │ 确认价格
        ▼
② 创建订单 order/create（真实下单，产生费用；订单号唯一）
        │ 同步渠道立即返回跟踪号；异步渠道稍后获取
        ▼
③ 获取面单 label/get（返回跟踪号/费用/面单下载地址，未出单时自动等待重试）
        │
        │ （如需撤单）
        ▼
④ 取消订单 order/cancel（向上游发起真实取消，不可恢复）

2. 接入准备

2.1 获取客户 Token

联系平台运营（运营微信：api418017500）开通客户账号（管理端「客户管理」开户时自动分配 32 位接口 Token）；

复制 Token 妥善保管，所有接口调用均须携带；

Token 为长期接口凭证：可随时联系运营重置（重置后旧 Token 立即失效）；客户账号停用后其全部接口调用即刻被拒绝。

2.2 环境地址

环境	基础地址	说明
测试环境	`http://{测试环境地址}/api/shipping`	联调使用，由运营提供
生产环境	`https://{生产环境地址}/api/shipping`	由运营提供，接入时确认

下文所有示例中以 {BASE_URL} 代表基础地址（如 http://http://8.138.234.192:81 为本地联调地址）。

2.3 协议约定

项	约定
请求方式	全部业务接口为 `POST`，`Content-Type: application/json`，字符集 UTF-8
字段命名	请求/响应字段统一 camelCase（小驼峰）
日期格式	`yyyy-MM-dd HH:mm:ss`（如 `2026-10-05 14:30:00`）
币种	三字码（如 `USD`）
重量单位	业务报文固定为磅（lb）；SKU 明细可选单位制（见 6.2）
尺寸单位	业务报文固定为英寸（inch）；SKU 明细可选单位制（见 6.2）
容错	服务端忽略报文中未定义的未知字段，但请勿依赖该行为

公制换算参考：1 lb = 453.59237 g，1 inch = 2.54 cm。若系统内部使用公制，调用前请自行换算。

3. 通用说明

3.1 鉴权

全部接口强制客户 Token 鉴权，携带方式二选一：

推荐：HTTP Header —— token: <客户Token>

兜底：URL 参数 —— ?token=<客户Token>（仅浏览器直开面单下载地址等无法加 Header 的场景）

鉴权失败响应（HTTP 状态码仍为 200，以响应体 code 判断）：

code	msg	原因
10020	token不能为空	Header 与 URL 参数均未携带 Token
10030	token无效	Token 不存在或已被重置
10031	客户已停用，请联系管理员	客户账号已停用

安全提示：Token 等同于账户凭证，请勿硬编码进前端页面、日志或公开仓库；疑似泄露立即联系运营重置。

3.2 统一响应格式

所有业务接口返回统一信封：

{
  "code": 0,
  "msg": "success",
  "data": { ... }
}

字段	类型	说明
code	int	0 表示成功，其他值均为失败
msg	String	成功为 `success`；失败为具体错误原因（中文）
data	Object	业务数据，失败时为 `null`

注意：业务失败时 HTTP 状态码仍为 200，客户端务必以响应体 code 是否为 0 作为成败判据，不要依赖 HTTP 状态码。

3.3 错误码一览

code	含义	典型场景
0	成功	—
10020	Token 未携带	见 3.1
10030	Token 无效	见 3.1
10031	客户已停用	见 3.1
10002	数据已存在	重复创建相同订单号
500	业务/参数/上游错误	参数校验未通过、渠道配置错误、上游承运商返回失败等，具体原因见 `msg`

参数校验失败时 msg 为具体的中文校验提示（一次返回一条），如 产品代码不能为空、收件人不能为空、保险服务不能为空 等，可直接用于排查报文问题。

3.4 通用业务校验（先于上游调用）

以下校验在调用上游承运商之前执行，失败不产生任何费用：

场景	错误提示（msg）
产品代码不存在或未配置渠道	`产品代码[xxx]不存在或未配置渠道`
渠道已停用	`产品代码[xxx]对应渠道已停用`
必填字段缺失	中文校验提示，如 `订单号不能为空`
收件人缺邮编（传入收件人时）	`收件人邮编(zipCode)不能为空`
试算长宽高/重量非正数	`长、宽、高、重量必须大于0`
需要保险但未传保险价格	`需要保险服务时保险价格(insurancePrice)必填`
签名服务类型越界	`签名服务类型(signType)必填且仅支持 0~3(0 不需要/1 直接/2 间接/3 成人)`

4. 接口列表

#	接口	方法	路径	作用
1	运费试算	POST	`/api/shipping/rates/calculate`	按原始重量尺寸试算运费（对客应收价），不产生订单、不扣费
2	创建订单	POST	`/api/shipping/order/create`	真实下单（产生费用），订单号唯一
3	获取面单	POST	`/api/shipping/label/get`	获取跟踪号/费用/面单下载地址；未出单时自动等待重试
4	取消订单	POST	`/api/shipping/order/cancel`	向上游发起真实取消，不可恢复

附属能力：面单下载地址（labelUrl）由接口 3 返回，可直接在浏览器/下载工具中打开，无需单独调接口（见 5.3.3）。

5. 接口详情

5.1 运费试算

POST {BASE_URL}/api/shipping/rates/calculate

按客户原始申报的重量与尺寸试算运费，返回对客应收价格。不产生订单、不产生任何费用，orderNo 可传可不传、可重复调用。

请求参数

字段	类型	必填	说明
productCode	String	是	物流产品代码（由平台运营分配，如 `20133800`）
orderNo	String	否	订单号（仅用于日志追踪，可重复，不真正下单）
length	BigDecimal	是	包裹长（inch，须 > 0）
width	BigDecimal	是	包裹宽（inch，须 > 0）
height	BigDecimal	是	包裹高（inch，须 > 0）
weight	BigDecimal	是	包裹重量（lb，须 > 0）
recipientAddressQo	Object	否	收件人地址（字段见 6.1；非必填——部分承运商试算不使用收件人，不传时可能被上游拒绝，建议传入以保证报价准确；传入时收件人 zipCode 必填）
sendAddressQo	Object	否	寄件人地址（部分渠道试算不使用，建议传入以保证报价准确）
skuList	Array	否	SKU 明细（字段见 6.2；部分渠道计费会参考申报明细）
orderExtra	Object	否	订单附加信息（保险/签名/申报/发货日期/备注，字段同 5.2 的 orderExtra 子对象）。试算时整体可选：传入则保险/签名/申报/发货日期参与报价（其中 `insuranceService`/`signType` 必填）；不传时按渠道配置试算，与历史行为完全一致

响应参数（data）

字段	类型	说明
provider	String	承运商
quotes	Array	报价列表（部分承运商返回单条总费用报价，部分返回多产品报价）

quotes 数组元素：

字段	类型	说明
productId	String	产品 ID
productName	String	产品名称
totalWeight	BigDecimal	计费总重量
totalCharge	BigDecimal	总费用（对客应收价）
currency	String	币种（如 USD）
zone	Integer	分区
message	String	提示信息（如超大件提示等）
details	Array	费用明细，元素含 `code`（费用代码）/`name`（费用名称）/`currency`/`zoneCode`/`amount`

请求示例

orderExtra 为可选段：删除该段即回到历史试算行为（按渠道默认配置报价）；传入时保险费/签名附加费会体现在 details 明细中，totalCharge 相应增加（实测：SHIPBEST 渠道不传 orderExtra 总费 5.68，传保险 100 + 直接签名后总费 9.63，附加费 +3.95）。

响应示例

{
  "code": 0,
  "msg": "success",
  "data": {
    "provider": "USPS",
    "quotes": [
      {
        "productName": "Handbag",
        "totalWeight": 1,
        "totalCharge": 8.05,
        "currency": "USD",
        "zone": 4
      }
    ]
  }
}

价格口径说明：试算返回的 totalCharge 为客户应收价格（按原始申报重量/尺寸计算），可直接用于对客报价。实际出单后接口 3 返回的 totalFee 为渠道侧费用，两者口径不同，请勿混用。

5.2 创建订单（下单）

POST {BASE_URL}/api/shipping/order/create

向渠道真实下单。下单成功即产生实际费用且订单不可删除，请务必在调用前通过试算确认价格、通过业务流程确认发货意向。

请求参数

字段	类型	必填	说明
orderNo	String	是	订单号，必须唯一（建议携带日期与业务前缀，如 `ORDER-20261005-0001`，长度不超过 64 字符）；重复创建将返回错误
productCode	String	是	物流产品代码
orderExtra	Object	是	订单附加信息（保险/签名/申报/发货日期/备注，字段见下表）
length	BigDecimal	是	包裹长（inch）
width	BigDecimal	是	包裹宽（inch）
height	BigDecimal	是	包裹高（inch）
weight	BigDecimal	是	包裹重量（lb）
sendAddressQo	Object	是	寄件人地址（字段见 6.1）
recipientAddressQo	Object	是	收件人地址（字段见 6.1；收件人 zipCode 必填）
skuList	Array	否	SKU 申报明细（字段见 6.2；传入时每行所有字段必填，建议传入以保证清关信息完整）

orderExtra 子对象：

字段	类型	必填	说明
insuranceService	Integer	是	保险服务：1 需要 / 0 不需要
insurancePrice	BigDecimal	条件	保险价格，`insuranceService=1` 时必填
insuranceFeeCurrency	String	否	保险价格币种（默认 USD）
signType	Integer	是	签名服务：0 不需要 / 1 直接签名 / 2 间接签名 / 3 成人签名
shipDate	String	否	发货日期（`yyyy-MM-dd HH:mm:ss`；部分渠道限定为当天起 7 日内，不传按当天处理）
declaredAmount	BigDecimal	否	申报总金额
declaredCurrencyType	String	否	申报金额币种（默认 USD）
declareQuantity	Integer	否	申报总数量（不传时取 SKU 明细数量合计）
remark	String	否	备注

响应参数（data）

字段	类型	说明
provider	String	承运商
orderNumber	String	订单号（回显）
trackingNumber	String	跟踪号：同步出单渠道下单即返回；异步出单渠道为空，需调用「获取面单」获取
masterTrackingNumber	String	主运单号（部分承运商返回，可空）
carrier	String	实际承运商（如 USPS / SF / UPS，可空）
estimatedSeconds	Integer	异步出单渠道的预估可获取面单时间（秒，可空）
extra	Object	承运商专有扩展返回（如发票地址、标签地址等，可空，按需向运营确认字段含义）

请求示例

响应示例

{
  "code": 0,
  "msg": "success",
  "data": {
    "provider": "USPS",
    "orderNumber": "ORDER-20261005-001",
    "trackingNumber": "",
    "masterTrackingNumber": null,
    "carrier": null,
    "estimatedSeconds": 60,
    "extra": null
  }
}

典型错误

场景	返回
订单号重复创建	code 10002（数据已存在）或上游「订单号已存在」类错误
需要保险但缺 insurancePrice	`需要保险服务时保险价格(insurancePrice)必填`
signType 传 4	`签名服务类型(signType)必填且仅支持 0~3(0 不需要/1 直接/2 间接/3 成人)`
收件人缺邮编	`收件人邮编(zipCode)不能为空`

5.3 获取面单

POST {BASE_URL}/api/shipping/label/get

按订单号获取面单结果：返回跟踪号、渠道侧费用、面单文件信息与面单下载地址（不返回 Base64 面单内容）。

同步出单渠道：下单后即可调用；

异步出单渠道：面单未就绪时服务端会自动等待并重试（视渠道配置约 1~5 分钟）；若仍未出单将返回错误，请间隔数十秒后重新调用，勿高频轮询。

请求参数

字段	类型	必填	说明
orderNo	String	是	订单号（下单时使用的订单号）
productCode	String	是	物流产品代码
waybillFormat	String	否	面单格式：`PDF` / `PNG` / `ZPL`（部分渠道由上游决定，不保证生效）

响应参数（data）

字段	类型	说明
provider	String	承运商
orderNumber	String	订单号
trackingNumber	String	跟踪号
carrier	String	实际承运商（可空）
labelUrl	String	面单下载地址（后端代理下载，地址稳定不过期；已自动附带 Token 参数，可直接打开，见 5.3.3）
fileType	String	面单文件格式：pdf / png / zpl
totalFee	BigDecimal	渠道侧费用（注意与试算的应收价 `totalCharge` 口径不同）
zone	Integer	分区

请求示例

响应示例

{
  "code": 0,
  "msg": "success",
  "data": {
    "provider": "USPS",
    "orderNumber": "ORDER-20261005-001",
    "trackingNumber": "9235990363079551107022",
    "carrier": "USPS",
    "labelUrl": "{BASE_URL}/api/shipping/label/download?orderNo=ORDER-20261005-001&token=<客户Token>",
    "fileType": "pdf",
    "totalFee": 8.05,
    "zone": 4
  }
}

典型错误

场景	返回
订单尚未出单（异步渠道未就绪）	上游「任务未完成」类错误，请稍后重试
订单号不存在	上游/平台「订单不存在」类错误

5.3.3 面单下载地址（labelUrl）说明

labelUrl 指向平台代理下载接口，特点：

已附带本次请求的客户 Token 参数，浏览器、下载工具、<a>/<iframe> 嵌入均可直接打开；

地址长期稳定不过期，可持久化保存；

响应为文件流：Content-Disposition: attachment，文件名为 {跟踪号或订单号}.{pdf|png|zpl}；

Token 重置后旧 labelUrl 失效，需重新调用「获取面单」获取新地址。

5.4 取消订单

POST {BASE_URL}/api/shipping/order/cancel

按订单号向上游承运商发起真实取消。成功后订单状态置为已取消、不可恢复；已交运/已揽收的订单可能被上游拒绝，以返回的 msg 为准。

请求参数

字段	类型	必填	说明
orderNo	String	是	订单号（下单时使用的订单号）
productCode	String	是	物流产品代码

响应参数（data）

成功时 data 为 null（code=0 即取消成功）。

请求示例

响应示例

{ "code": 0, "msg": "success", "data": null }

6. 公共数据对象

6.1 地址对象（寄件人 sendAddressQo / 收件人 recipientAddressQo）

字段	类型	必填	说明
nameFirst	String	是	联系人姓（或名称前段）
nameLast	String	是	联系人名（或名称后段）
country	String	是	国家/地区二字码（如 US / CN）
city	String	是	城市
address1	String	是	地址 1
zipCode	String	条件	邮编：收件人必填，寄件人选填（建议传入）
province	String	否	省/州（美国建议传二字简码，如 CA）
area	String	否	区/县
street	String	否	街道
houseNumber	String	否	门牌号
address2	String	否	地址 2
phone	String	否	电话
email	String	否	邮箱
corporateName	String	否	公司名称
taxIdValue	String	否	税号（发往欧洲等目的地时建议填写）
portCode	String	否	注入口岸代码（特殊渠道需要，由运营告知；仅寄件人侧生效）

6.2 SKU 明细对象（skuList 数组元素）

字段	类型	必填	说明
sku	String	是	SKU 编码
productNameCn	String	是	品名（中文）
productNameEn	String	是	品名（英文）
quantity	Integer	是	数量
declaredUnitPrice	BigDecimal	是	申报单价
declaredCurrency	String	是	申报币种三字码（如 USD）
weight	BigDecimal	是	单件重量（单位由 unit 决定）
length	BigDecimal	是	单件长（单位由 unit 决定）
width	BigDecimal	是	单件宽（单位由 unit 决定）
height	BigDecimal	是	单件高（单位由 unit 决定）
hsCode	String	是	海关编码（HS Code）
productNature	String	是	商品性质：1 带磁 / 2 不带磁 / 3 带电 / 4 不带电 / 5 液体，多选逗号分隔（如 `"2,4"` = 不带磁不带电）
unit	Integer	是	SKU 单位制：1 = g/cm，2 = kg/cm，3 = lb/in

注意：SKU 明细的单件尺寸/重量单位由其自身 unit 声明，与包裹级（顶层 length/weight，固定 inch/lb）相互独立；传入 skuList 时每行全部字段必填。

7. 调用时序与最佳实践

7.1 推荐接入流程

1. 获取 Token（运营开户）→ 环境连通性验证（调用试算）
2. 业务下单页：先调「运费试算」展示对客价格 → 用户确认
3. 调「创建订单」→ 记录 orderNumber（异步渠道 trackingNumber 为空属正常）
4. 轮询/延迟调用「获取面单」：
   - 建议首次在下单后 10~30 秒调用；服务端未就绪会自动等待重试（视渠道配置约 1~5 分钟）
   - 若返回「未出单」错误，间隔 30~60 秒重试，无需（也不要）秒级高频轮询
5. 拿到 labelUrl 后按需下载/打印面单
6. 异常流程：调「取消订单」撤单（越早成功率越高；已交运后可能被拒绝）

7.2 注意事项

#	事项
1	费用安全：创建订单、获取面单、取消订单均会触达上游并可能产生费用；务必先试算、再下单，避免误操作
2	订单号唯一：由调用方生成并保证唯一；重复创建同一订单号会被拒绝。建议格式：业务前缀 + 日期 + 序号
3	试算可重复：试算不产生订单与费用，可放心反复调用（如购物车实时报价）
4	成败判据：以响应体 `code == 0` 判断成功，不要依赖 HTTP 状态码
5	重试策略：网络超时可重试「试算」「获取面单」；「创建订单」不可盲目重试（可能造成重复下单），超时后建议先按订单号查询面单确认是否已创建成功，再决定是否重新下单（换新订单号）
6	取消时效：取消请求宜在出单前后尽快发起；上游已揽收/交运的订单取消会被拒绝
7	Token 保密：labelUrl 内含 Token 参数，请勿将完整地址展示给无关人员或写入公开页面
8	单位换算：包裹级固定 lb/inch；内部系统为公制时请先换算再上送（1 lb=453.59237 g，1 inch=2.54 cm），或利用 SKU 的 `unit` 字段按 g/cm 传明细

8. 常见问题（FAQ）

Q1：试算价格和出单后的 totalFee 为什么不一致？
试算返回的 totalCharge 为对客应收价（按原始申报重量尺寸计价）；totalFee 为渠道侧费用。两者口径不同，对客收款请以试算价为准。

Q2：下单成功但 trackingNumber 为空？
该渠道为异步出单：下单仅完成创建，跟踪号需在「获取面单」阶段获取。可参考返回的 estimatedSeconds 安排首次查询时间。

Q3：获取面单报「任务未完成」？
异步渠道上游尚未出单。服务端已自动等待重试（视渠道配置约 1~~5 分钟），仍失败请间隔 30~~60 秒再调；持续失败请联系运营排查。

Q4：订单号重复了怎么办？
重复创建会被拒绝（错误码 10002 或上游订单号已存在）。请为每次下单生成新订单号；如需查询已存在的订单，走「获取面单」按订单号查询。

Q5：Token 失效了怎么办？
联系平台运营重置，用新 Token 替换。注意重置后旧的 labelUrl 也会失效，需重新调用「获取面单」。

Q6：可以取消已出单的订单吗？
视渠道与物流状态而定：出单后未交运前通常可取消；已揽收/交运后上游会拒绝。取消结果以接口返回为准。

Q7：报文里传了文档没有的字段会怎样？
服务端忽略未知字段不会报错，但也不要依赖该行为，字段请严格按本文档传递。

9. 变更记录

版本	日期	变更内容
v1.0	2026-10-05	首版：试算、创建订单、获取面单、取消订单 4 个对外接口
v1.1	2026-10-05	运费试算支持可选 `orderExtra`（保险/签名/申报/发货日期参与报价，不传时与历史行为一致）
v1.2	2026-10-05	运费试算 `recipientAddressQo` 改为非必填（传入时 zipCode 仍必填）

ShipBidding接口文档

ShipBidding 打单平台 · 统一发货 API 接口文档（对外版）#

1. 概述#

2. 接入准备#

2.1 获取客户 Token#

2.2 环境地址#

2.3 协议约定#

3. 通用说明#

3.1 鉴权#

3.2 统一响应格式#

3.3 错误码一览#

3.4 通用业务校验（先于上游调用）#

4. 接口列表#

5. 接口详情#

5.1 运费试算#

请求参数#

响应参数（data）#

请求示例#

响应示例#

5.2 创建订单（下单）#

请求参数#

响应参数（data）#

请求示例#

响应示例#

典型错误#

5.3 获取面单#

请求参数#

响应参数（data）#

请求示例#

响应示例#

典型错误#

5.3.3 面单下载地址（labelUrl）说明#

5.4 取消订单#

请求参数#

响应参数（data）#

请求示例#

响应示例#

6. 公共数据对象#

6.1 地址对象（寄件人 sendAddressQo / 收件人 recipientAddressQo）#

6.2 SKU 明细对象（skuList 数组元素）#

7. 调用时序与最佳实践#

7.1 推荐接入流程#

7.2 注意事项#

8. 常见问题（FAQ）#

9. 变更记录#

ShipBidding 打单平台 · 统一发货 API 接口文档（对外版）

1. 概述

2. 接入准备

2.1 获取客户 Token

2.2 环境地址

2.3 协议约定

3. 通用说明

3.1 鉴权

3.2 统一响应格式

3.3 错误码一览

3.4 通用业务校验（先于上游调用）

4. 接口列表

5. 接口详情

5.1 运费试算

请求参数

响应参数（data）

请求示例

响应示例

5.2 创建订单（下单）

请求参数

响应参数（data）

请求示例

响应示例

典型错误

5.3 获取面单

请求参数

响应参数（data）

请求示例

响应示例

典型错误

5.3.3 面单下载地址（labelUrl）说明

5.4 取消订单

请求参数

响应参数（data）

请求示例

响应示例

6. 公共数据对象

6.1 地址对象（寄件人 sendAddressQo / 收件人 recipientAddressQo）

6.2 SKU 明细对象（skuList 数组元素）

7. 调用时序与最佳实践

7.1 推荐接入流程

7.2 注意事项

8. 常见问题（FAQ）

9. 变更记录