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

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

1. 概述

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

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

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

2. 接入准备

2.1 获取客户 Token

联系平台运营开通客户账号（管理端「客户管理」开户时自动分配 32 位接口 Token）；
复制 Token 妥善保管，所有接口调用均须携带；
Token 为长期接口凭证：可随时联系运营重置（重置后旧 Token 立即失效）；客户账号停用后其全部接口调用即刻被拒绝。

2.2 环境地址

环境	基础地址	说明
生产环境（正式域名）	`https://api.shipbidding.com/api/shipping`	正式接入地址（推荐）
直连备用地址	`http://8.138.234.192:81/api/shipping`	域名不可用时的直连入口，接口行为与正式域名完全一致

下文所有示例中以 {BASE_URL} 代表基础地址的域名部分（生产为 https://api.shipbidding.com）。

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]已停用`
产品未关联可用渠道	`产品[xxx]未关联可用物流渠道，请联系管理员`
候选渠道试算全部失败	试算：返回首个渠道错误或 `产品[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 可传可不传、可重复调用。

多渠道自动比价：一个物流产品可关联多个物流渠道。单渠道产品直接按该渠道试算；多渠道产品对全部启用渠道逐一试算，返回报价最低渠道的完整结果（响应 provider 即选中渠道的承运商），试算失败/无报价的渠道自动跳过；全部失败时返回错误（见 3.4）。

请求参数

字段	类型	必填	说明
productCode	String	是	物流产品代码（由平台运营分配，8 位数字，如 `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`

请求示例

curl -X POST {BASE_URL}/api/shipping/rates/calculate \
  -H "Content-Type: application/json" \
  -H "token: $CUSTOMER_TOKEN" \
  -d '{
        "productCode": "20133800",
        "orderNo": "RATE-20261005-001",
        "length": 10, "width": 8, "height": 6, "weight": 1,
        "sendAddressQo": {
          "nameFirst": "San", "nameLast": "Zhang", "phone": "13800000000",
          "country": "CN", "province": "Guangdong", "city": "Shenzhen",
          "address1": "1 Sender Rd", "zipCode": "518000"
        },
        "recipientAddressQo": {
          "nameFirst": "Jane", "nameLast": "Doe", "phone": "2135551234",
          "country": "US", "province": "CA", "city": "Los Angeles",
          "address1": "1234 S Main St", "zipCode": "90015"
        },
        "skuList": [{
          "sku": "SKU-1", "productNameCn": "手提包", "productNameEn": "Handbag",
          "quantity": 1, "declaredUnitPrice": 19.99, "declaredCurrency": "USD",
          "weight": 453.6, "length": 25.4, "width": 20.3, "height": 15.2,
          "hsCode": "4202.21", "productNature": "2,4", "unit": 1
        }],
        "orderExtra": {
          "insuranceService": 1,
          "insurancePrice": 100,
          "insuranceFeeCurrency": "USD",
          "signType": 1,
          "declaredAmount": 19.99,
          "declaredCurrencyType": "USD",
          "shipDate": "2026-10-06 14:30:00"
        }
      }'

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	承运商专有扩展返回（如发票地址、标签地址等，可空，按需向运营确认字段含义）

请求示例

curl -X POST {BASE_URL}/api/shipping/order/create \
  -H "Content-Type: application/json" \
  -H "token: $CUSTOMER_TOKEN" \
  -d '{
        "orderNo": "ORDER-20261005-001",
        "productCode": "20133800",
        "orderExtra": {
          "insuranceService": 0,
          "signType": 0,
          "declaredAmount": 19.99,
          "declaredCurrencyType": "USD",
          "shipDate": "2026-10-05 14:30:00"
        },
        "length": 10, "width": 8, "height": 6, "weight": 1.1,
        "sendAddressQo": {
          "nameFirst": "San", "nameLast": "Zhang", "phone": "13800000000",
          "country": "CN", "province": "Guangdong", "city": "Shenzhen",
          "address1": "1 Sender Rd", "zipCode": "518000"
        },
        "recipientAddressQo": {
          "nameFirst": "Jane", "nameLast": "Doe", "phone": "2135551234",
          "country": "US", "province": "CA", "city": "Los Angeles",
          "address1": "1234 S Main St", "zipCode": "90015"
        },
        "skuList": [{
          "sku": "SKU-1", "productNameCn": "手提包", "productNameEn": "Handbag",
          "quantity": 1, "declaredUnitPrice": 19.99, "declaredCurrency": "USD",
          "weight": 453.6, "length": 25.4, "width": 20.3, "height": 15.2,
          "hsCode": "4202.21", "productNature": "2,4", "unit": 1
        }]
      }'

响应示例

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

典型错误

场景	返回
产品不存在/已停用/未关联可用渠道	见 3.4 通用业务校验
全部候选渠道试算失败	`产品[xxx]下所有可用渠道试算失败，暂不能打单，请稍后重试`（订单落库异常，未产生上游费用）
订单号重复创建	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	分区

请求示例

curl -X POST {BASE_URL}/api/shipping/label/get \
  -H "Content-Type: application/json" \
  -H "token: $CUSTOMER_TOKEN" \
  -d '{ "orderNo": "ORDER-20261005-001" }'

响应示例

{
  "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
  }
}

典型错误

场景	返回
订单尚未出单（异步渠道未就绪）	上游「任务未完成」类错误，请稍后重试
订单号不存在（无下单归档记录）	`订单[xxx]不存在，无法定位物流渠道`

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

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

已附带本次请求的客户 Token 参数，浏览器、下载工具、<a>/<iframe> 嵌入均可直接打开；
地址长期稳定不过期，可持久化保存；
响应为文件流：Content-Disposition: attachment，文件名为 {跟踪号或订单号}.{pdf|png|zpl}；
Token 重置后旧 labelUrl 失效，需重新调用「获取面单」获取新地址。

# 直接下载面单文件
curl -OJ "{BASE_URL}/api/shipping/label/download?orderNo=ORDER-20261005-001&token=$CUSTOMER_TOKEN"

5.4 取消订单

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

按订单号向渠道上游发起真实取消（受理式，2026-10-05 起）。服务端按下单归档记录自动路由——以该订单实际选中的物流商发起取消；只要订单号匹配到归档记录即返回 code=0 与受理结果：cancelStatus=SUCCESS（上游取消成功，订单不可恢复）/ cancelStatus=FAILED（上游取消失败，cancelMsg 为失败原因，可稍后重试）；已 SUCCESS 的订单重复调用幂等返回。

退费说明：只要受理成功（code=0），无论上游取消成败，平台均自动退还该订单扣费（下单时按客户应收价扣减的可用额度）；未扣费订单跳过；重复取消不重复退款。上游成败不影响退费，无需等待重试成功。

请求参数

字段	类型	必填	说明
orderNo	String	是	订单号（下单时使用的订单号）
productCode	String	否	兼容保留字段（服务端按下单归档记录路由，不参与解析，可省略）

响应参数（data）

字段	类型	说明
cancelStatus	String	受理结果：`SUCCESS`=上游取消成功 / `FAILED`=上游取消失败
cancelMsg	String	失败原因（`cancelStatus=FAILED` 时非空；`SUCCESS` 时为 `null`）

仅归档记录路由类错误（订单[xxx]不存在，无法定位物流渠道、订单[xxx]物流商[yyy]未接入发货链路）仍返回非 0 错误码；上游取消成败一律以 code=0 受理并体现在 data.cancelStatus 中。

请求示例

curl -X POST {BASE_URL}/api/shipping/order/cancel \
  -H "Content-Type: application/json" \
  -H "token: $CUSTOMER_TOKEN" \
  -d '{ "orderNo": "ORDER-20261005-001" }'

响应示例

{ "code": 0, "msg": "success", "data": { "cancelStatus": "SUCCESS", "cancelMsg": null } }

上游取消失败时（同样受理成功）：

{ "code": 0, "msg": "success", "data": { "cancelStatus": "FAILED", "cancelMsg": "错误状态：Processing" } }

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	否	注入口岸代码（特殊渠道需要，由运营告知；仅寄件人侧生效）

area（区/县）/street（街道）/houseNumber（门牌号）为地址细分字段：支持细粒度地址的渠道（如 ShipBest）会原样上送上游，建议传入以提高派送地址精度。

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

字段	类型	必填	说明
sku	String	否	SKU 编码
productNameCn	String	否	品名（中文）
productNameEn	String	否	品名（英文）
quantity	Integer	否	数量（缺省 1）
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"` = 不带磁不带电；缺省取渠道参数或默认 `2,4`）
unit	Integer	否	SKU 单位制：1 = g/cm，2 = kg/cm，3 = lb/in（缺省按 lb/in 处理）

注意：SKU 明细的单件尺寸/重量单位由其自身 unit 声明，与包裹级（顶层 length/weight，固定 inch/lb）相互独立；每行全部字段选填（v1.6 起）——缺失字段按兜底链取值（品名英→中→SKU、数量缺省 1、币种取请求级、商品性质取渠道参数/默认 2,4、重量/尺寸取首件包裹），sku/hsCode 等无兜底的字段原样透传，由承运商/下游校验驱动报错。 全量转发（v1.5 起）：skuList 的全部行会转发给承运商（此前仅首行生效）——支持多明细的渠道（如 ShipBest）逐条上送参与清关申报，首行同时用于单件模型的包裹字段回填；明细的申报单价/币种/商品性质（productNature）均按传入值转发，不再被渠道默认值覆盖。

7. 调用时序与最佳实践

7.1 推荐接入流程

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

7.2 注意事项

#	事项
1	费用安全：创建订单、获取面单、取消订单均会触达上游并可能产生费用；务必先试算、再下单，避免误操作
2	订单号唯一：由调用方生成并保证唯一；重复创建同一订单号会被拒绝。建议格式：业务前缀 + 日期 + 序号
3	试算可重复：试算不产生订单与费用，可放心反复调用（如购物车实时报价）
4	成败判据：以响应体 `code == 0` 判断成功，不要依赖 HTTP 状态码
5	重试策略：网络超时可重试「试算」「获取面单」；「创建订单」不可盲目重试（可能造成重复下单），超时后建议先按订单号查询面单确认是否已创建成功，再决定是否重新下单（换新订单号）
6	取消时效：取消请求宜在出单前后尽快发起；已揽收/交运的订单上游可能取消失败（`cancelStatus=FAILED`，可稍后重试）。只要受理成功即退还该订单扣费，上游成败不影响退费
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：可以取消已出单的订单吗？ 可随时调用；视渠道与物流状态而定，出单后未交运前通常取消成功（cancelStatus=SUCCESS），已揽收/交运后上游可能失败（cancelStatus=FAILED，可稍后重试）。无论上游成败，只要受理成功即退还该订单扣费。

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

Q8：productCode（物流产品代码）从哪里获取？ 由平台运营在管理端创建「物流产品」时由系统自动分配（8 位数字、全局唯一），并配置该产品关联的物流渠道（可多选）；产品关联多个渠道时，试算/下单自动比价。另：label/get、order/cancel 不必传 productCode（兼容保留，传了也不参与路由），服务端按订单号的下单归档记录自动路由。

9. 变更记录

版本	日期	变更内容
v1.0	2026-10-05	首版：试算、创建订单、获取面单、取消订单 4 个对外接口
v1.1	2026-10-05	运费试算支持可选 `orderExtra`（保险/签名/申报/发货日期参与报价，不传时与历史行为一致）
v1.2	2026-10-05	运费试算 `recipientAddressQo` 改为非必填（传入时 zipCode 仍必填）
v1.3	2026-10-05	取消订单改为受理式：返回 `{cancelStatus, cancelMsg}`；上游取消失败亦受理（可重试），受理成功即退还该订单扣费
v1.4	2026-10-05	引入物流产品模型：产品代码改由「物流产品」统一管理（系统自动分配 8 位数字、全局唯一，可关联多个物流渠道）；`rates/calculate`、`order/create` 按产品解析候选渠道——单渠道直用、多渠道自动比价（下单按上游应付价最低选渠道、试算返回最低报价渠道结果）；`label/get`、`order/cancel` 改按下单归档记录的物流商路由，`productCode` 兼容保留、非必填
v1.5	2026-10-11	SKU 申报明细全量转发：`skuList` 全部行转发承运商（此前仅首行生效），申报明细的商品性质/币种/单价按传入值转发、不再被渠道默认值覆盖；地址细分字段 `area`/`street`/`houseNumber` 支持的渠道原样上送上游
v1.6	2026-10-11	SKU 申报明细字段全部改为选填：下游物流商对申报字段必填口径持续变化且逐字段报错，平台层不再拦截；缺失字段按兜底链取值（品名英→中→SKU、数量缺省 1、币种取请求级、商品性质取渠道参数/默认 `2,4`、重量/尺寸取首件包裹），其余透传由承运商/下游校验驱动