[{"data":1,"prerenderedAt":19},["ShallowReactive",2],{"docs-tree":3,"docs-detail-doc-api":16},[4],{"articles":5,"id":14,"name":15},[6,10],{"id":7,"slug":8,"title":9},"2113637381121822721","doc-api","ShipBidding打单平台 · 统一发货 API 接口文档（对外版）",{"id":11,"slug":12,"title":13},"2117458315372990466","sync-order","ShipBest → 领星OMS 订单同步（Chrome 扩展）· 安装与使用手册","2113637017345642498","接口文档",{"categoryId":14,"categoryName":15,"content":17,"id":7,"slug":8,"title":9,"updateDate":18},"> **适用对象**：接入本平台统一发货能力的客户\u002F第三方系统开发者\n> **接口范围**：运费试算、创建订单（下单）、获取面单、取消订单，共 4 个核心接口\n> **文档版本**：v1.6（2026-10-11）\n\n---\n\n## 1. 概述\n\nShipBidding 打单平台统一发货 API 提供一套**承运商无关**的物流发货能力：调用方只需按本规范组装标准报文并携带客户 Token，平台自动完成物流产品解析、候选渠道自动比价、上游承运商下单、面单获取与归档、订单取消等全链路操作。\n\n4 个接口的典型调用关系：\n\n```\n① 运费试算 rates\u002Fcalculate（不产生订单、不扣费，可反复调用）\n        │ 确认价格\n        ▼\n② 创建订单 order\u002Fcreate（真实下单，产生费用；订单号唯一）\n        │ 同步渠道立即返回跟踪号；异步渠道稍后获取\n        ▼\n③ 获取面单 label\u002Fget（返回跟踪号\u002F费用\u002F面单下载地址，未出单时自动等待重试）\n        │\n        │ （如需撤单）\n        ▼\n④ 取消订单 order\u002Fcancel（受理式：上游取消无论成败均受理，受理成功即退还该订单扣费）\n```\n\n---\n\n## 2. 接入准备\n\n### 2.1 获取客户 Token\n\n1. 联系平台运营开通客户账号（管理端「客户管理」开户时自动分配 32 位接口 Token）；\n2. 复制 Token 妥善保管，所有接口调用均须携带；\n3. Token 为长期接口凭证：可随时联系运营重置（重置后旧 Token **立即失效**）；客户账号停用后其全部接口调用即刻被拒绝。\n\n### 2.2 环境地址\n\n| 环境 | 基础地址 | 说明 |\n|------|----------|------|\n| 生产环境（正式域名） | `https:\u002F\u002Fapi.shipbidding.com\u002Fapi\u002Fshipping` | 正式接入地址（推荐） |\n| 直连备用地址 | `http:\u002F\u002F8.138.234.192:81\u002Fapi\u002Fshipping` | 域名不可用时的直连入口，接口行为与正式域名完全一致 |\n\n> 下文所有示例中以 `{BASE_URL}` 代表基础地址的域名部分（生产为 `https:\u002F\u002Fapi.shipbidding.com`）。\n\n### 2.3 协议约定\n\n| 项 | 约定 |\n|----|------|\n| 请求方式 | 全部业务接口为 `POST`，`Content-Type: application\u002Fjson`，字符集 UTF-8 |\n| 字段命名 | 请求\u002F响应字段统一 **camelCase**（小驼峰） |\n| 日期格式 | `yyyy-MM-dd HH:mm:ss`（如 `2026-10-05 14:30:00`） |\n| 币种 | 三字码（如 `USD`） |\n| 重量单位 | 业务报文固定为 **磅（lb）**；SKU 明细可选单位制（见 6.2） |\n| 尺寸单位 | 业务报文固定为 **英寸（inch）**；SKU 明细可选单位制（见 6.2） |\n| 容错 | 服务端忽略报文中未定义的未知字段，但请勿依赖该行为 |\n\n> 公制换算参考：1 lb = 453.59237 g，1 inch = 2.54 cm。若系统内部使用公制，调用前请自行换算。\n\n---\n\n## 3. 通用说明\n\n### 3.1 鉴权\n\n**全部接口强制客户 Token 鉴权**，携带方式二选一：\n\n- 推荐：HTTP Header —— `token: \u003C客户Token>`\n- 兜底：URL 参数 —— `?token=\u003C客户Token>`（仅浏览器直开面单下载地址等无法加 Header 的场景）\n\n鉴权失败响应（HTTP 状态码仍为 200，以响应体 `code` 判断）：\n\n| code | msg | 原因 |\n|------|-----|------|\n| 10020 | token不能为空 | Header 与 URL 参数均未携带 Token |\n| 10030 | token无效 | Token 不存在或已被重置 |\n| 10031 | 客户已停用，请联系管理员 | 客户账号已停用 |\n\n> 安全提示：Token 等同于账户凭证，请勿硬编码进前端页面、日志或公开仓库；疑似泄露立即联系运营重置。\n\n### 3.2 统一响应格式\n\n所有业务接口返回统一信封：\n\n```json\n{\n  \"code\": 0,\n  \"msg\": \"success\",\n  \"data\": { ... }\n}\n```\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| code | int | **0 表示成功**，其他值均为失败 |\n| msg | String | 成功为 `success`；失败为具体错误原因（中文） |\n| data | Object | 业务数据，失败时为 `null` |\n\n> 注意：**业务失败时 HTTP 状态码仍为 200**，客户端务必以响应体 `code` 是否为 0 作为成败判据，不要依赖 HTTP 状态码。\n\n### 3.3 错误码一览\n\n| code | 含义 | 典型场景 |\n|------|------|----------|\n| 0 | 成功 | — |\n| 10020 | Token 未携带 | 见 3.1 |\n| 10030 | Token 无效 | 见 3.1 |\n| 10031 | 客户已停用 | 见 3.1 |\n| 10002 | 数据已存在 | 重复创建相同订单号 |\n| 500 | 业务\u002F参数\u002F上游错误 | 参数校验未通过、渠道配置错误、上游承运商返回失败等，具体原因见 `msg` |\n\n参数校验失败时 `msg` 为具体的中文校验提示（一次返回一条），如 `产品代码不能为空`、`收件人不能为空`、`保险服务不能为空` 等，可直接用于排查报文问题。\n\n### 3.4 通用业务校验（先于上游调用）\n\n以下校验在调用上游承运商**之前**执行，失败不产生任何费用：\n\n| 场景 | 错误提示（msg） |\n|------|-----------------|\n| 物流产品不存在 | `产品代码[xxx]不存在` |\n| 物流产品已停用 | `产品代码[xxx]已停用` |\n| 产品未关联可用渠道 | `产品[xxx]未关联可用物流渠道，请联系管理员` |\n| 候选渠道试算全部失败 | 试算：返回首个渠道错误或 `产品[xxx]下所有可用渠道试算失败，请稍后重试`；下单：`产品[xxx]下所有可用渠道试算失败，暂不能打单，请稍后重试`（订单落库异常，未产生上游费用） |\n| 必填字段缺失 | 中文校验提示，如 `订单号不能为空` |\n| 收件人缺邮编（传入收件人时） | `收件人邮编(zipCode)不能为空` |\n| 试算长宽高\u002F重量非正数 | `长、宽、高、重量必须大于0` |\n| 需要保险但未传保险价格 | `需要保险服务时保险价格(insurancePrice)必填` |\n| 签名服务类型越界 | `签名服务类型(signType)必填且仅支持 0~3(0 不需要\u002F1 直接\u002F2 间接\u002F3 成人)` |\n\n---\n\n## 4. 接口列表\n\n| # | 接口 | 方法 | 路径 | 作用 |\n|---|------|------|------|------|\n| 1 | 运费试算 | POST | `\u002Fapi\u002Fshipping\u002Frates\u002Fcalculate` | 按原始重量尺寸试算运费（对客应收价）；多渠道产品自动比价返回最低报价渠道，不产生订单、不扣费 |\n| 2 | 创建订单 | POST | `\u002Fapi\u002Fshipping\u002Forder\u002Fcreate` | 真实下单（产生费用），订单号唯一 |\n| 3 | 获取面单 | POST | `\u002Fapi\u002Fshipping\u002Flabel\u002Fget` | 获取跟踪号\u002F费用\u002F面单下载地址；未出单时自动等待重试 |\n| 4 | 取消订单 | POST | `\u002Fapi\u002Fshipping\u002Forder\u002Fcancel` | 受理式：上游取消无论成败均返回受理结果（成功\u002F失败），受理成功即自动退还该订单扣费 |\n\n> 附属能力：面单下载地址（`labelUrl`）由接口 3 返回，可直接在浏览器\u002F下载工具中打开，无需单独调接口（见 5.3.3）。\n\n---\n\n## 5. 接口详情\n\n### 5.1 运费试算\n\n`POST {BASE_URL}\u002Fapi\u002Fshipping\u002Frates\u002Fcalculate`\n\n按**客户原始申报的重量与尺寸**试算运费，返回对客应收价格。**不产生订单、不产生任何费用**，`orderNo` 可传可不传、可重复调用。\n\n> **多渠道自动比价**：一个物流产品可关联多个物流渠道。单渠道产品直接按该渠道试算；**多渠道产品对全部启用渠道逐一试算，返回报价最低渠道的完整结果**（响应 `provider` 即选中渠道的承运商），试算失败\u002F无报价的渠道自动跳过；全部失败时返回错误（见 3.4）。\n\n#### 请求参数\n\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| productCode | String | 是 | 物流产品代码（由平台运营分配，8 位数字，如 `20133800`）；产品关联多渠道时自动比价，返回最低报价渠道结果 |\n| orderNo | String | 否 | 订单号（仅用于日志追踪，可重复，不真正下单） |\n| length | BigDecimal | 是 | 包裹长（inch，须 > 0） |\n| width | BigDecimal | 是 | 包裹宽（inch，须 > 0） |\n| height | BigDecimal | 是 | 包裹高（inch，须 > 0） |\n| weight | BigDecimal | 是 | 包裹重量（lb，须 > 0） |\n| recipientAddressQo | Object | 否 | 收件人地址（字段见 6.1；非必填——部分承运商试算不使用收件人，不传时可能被上游拒绝，建议传入以保证报价准确；**传入时收件人 zipCode 必填**） |\n| sendAddressQo | Object | 否 | 寄件人地址（部分渠道试算不使用，建议传入以保证报价准确） |\n| skuList | Array | 否 | SKU 明细（字段见 6.2；**全部明细转发承运商**，支持多明细的渠道逐条参与计费\u002F清关；部分渠道计费会参考申报明细） |\n| orderExtra | Object | 否 | 订单附加信息（保险\u002F签名\u002F申报\u002F发货日期\u002F备注，字段同 5.2 的 orderExtra 子对象）。**试算时整体可选**：传入则保险\u002F签名\u002F申报\u002F发货日期参与报价（其中 `insuranceService`\u002F`signType` 必填）；不传时按渠道配置试算，与历史行为完全一致 |\n\n#### 响应参数（data）\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| provider | String | 承运商（多渠道产品为比价选中渠道的承运商） |\n| quotes | Array | 报价列表（部分承运商返回单条总费用报价，部分返回多产品报价） |\n\n**quotes 数组元素**：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| productId | String | 产品 ID |\n| productName | String | 产品名称 |\n| totalWeight | BigDecimal | 计费总重量 |\n| totalCharge | BigDecimal | **总费用（对客应收价）** |\n| currency | String | 币种（如 USD） |\n| zone | Integer | 分区 |\n| message | String | 提示信息（如超大件提示等） |\n| details | Array | 费用明细，元素含 `code`（费用代码）\u002F`name`（费用名称）\u002F`currency`\u002F`zoneCode`\u002F`amount` |\n\n#### 请求示例\n\n```bash\ncurl -X POST {BASE_URL}\u002Fapi\u002Fshipping\u002Frates\u002Fcalculate \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -H \"token: $CUSTOMER_TOKEN\" \\\n  -d '{\n        \"productCode\": \"20133800\",\n        \"orderNo\": \"RATE-20261005-001\",\n        \"length\": 10, \"width\": 8, \"height\": 6, \"weight\": 1,\n        \"sendAddressQo\": {\n          \"nameFirst\": \"San\", \"nameLast\": \"Zhang\", \"phone\": \"13800000000\",\n          \"country\": \"CN\", \"province\": \"Guangdong\", \"city\": \"Shenzhen\",\n          \"address1\": \"1 Sender Rd\", \"zipCode\": \"518000\"\n        },\n        \"recipientAddressQo\": {\n          \"nameFirst\": \"Jane\", \"nameLast\": \"Doe\", \"phone\": \"2135551234\",\n          \"country\": \"US\", \"province\": \"CA\", \"city\": \"Los Angeles\",\n          \"address1\": \"1234 S Main St\", \"zipCode\": \"90015\"\n        },\n        \"skuList\": [{\n          \"sku\": \"SKU-1\", \"productNameCn\": \"手提包\", \"productNameEn\": \"Handbag\",\n          \"quantity\": 1, \"declaredUnitPrice\": 19.99, \"declaredCurrency\": \"USD\",\n          \"weight\": 453.6, \"length\": 25.4, \"width\": 20.3, \"height\": 15.2,\n          \"hsCode\": \"4202.21\", \"productNature\": \"2,4\", \"unit\": 1\n        }],\n        \"orderExtra\": {\n          \"insuranceService\": 1,\n          \"insurancePrice\": 100,\n          \"insuranceFeeCurrency\": \"USD\",\n          \"signType\": 1,\n          \"declaredAmount\": 19.99,\n          \"declaredCurrencyType\": \"USD\",\n          \"shipDate\": \"2026-10-06 14:30:00\"\n        }\n      }'\n```\n\n> **`orderExtra` 为可选段**：删除该段即回到历史试算行为（按渠道默认配置报价）；传入时保险费\u002F签名附加费会体现在 `details` 明细中，`totalCharge` 相应增加（实测：SHIPBEST 渠道不传 `orderExtra` 总费 5.68，传保险 100 + 直接签名后总费 9.63，附加费 +3.95）。\n\n#### 响应示例\n\n```json\n{\n  \"code\": 0,\n  \"msg\": \"success\",\n  \"data\": {\n    \"provider\": \"USPS\",\n    \"quotes\": [\n      {\n        \"productName\": \"Handbag\",\n        \"totalWeight\": 1,\n        \"totalCharge\": 8.05,\n        \"currency\": \"USD\",\n        \"zone\": 4\n      }\n    ]\n  }\n}\n```\n\n> **价格口径说明**：试算返回的 `totalCharge` 为**客户应收价格**（按原始申报重量\u002F尺寸计算），可直接用于对客报价。实际出单后接口 3 返回的 `totalFee` 为渠道侧费用，两者口径不同，请勿混用。\n\n---\n\n### 5.2 创建订单（下单）\n\n`POST {BASE_URL}\u002Fapi\u002Fshipping\u002Forder\u002Fcreate`\n\n向渠道真实下单。**下单成功即产生实际费用且订单不可删除**，请务必在调用前通过试算确认价格、通过业务流程确认发货意向。\n\n#### 请求参数\n\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| orderNo | String | 是 | 订单号，**必须唯一**（建议携带日期与业务前缀，如 `ORDER-20261005-0001`，长度不超过 64 字符）；重复创建将返回错误 |\n| productCode | String | 是 | 物流产品代码（由平台运营分配）；产品关联多渠道时按上游应付价最低自动比价选渠道下单 |\n| orderExtra | Object | 是 | 订单附加信息（保险\u002F签名\u002F申报\u002F发货日期\u002F备注，字段见下表） |\n| length | BigDecimal | 是 | 包裹长（inch） |\n| width | BigDecimal | 是 | 包裹宽（inch） |\n| height | BigDecimal | 是 | 包裹高（inch） |\n| weight | BigDecimal | 是 | 包裹重量（lb） |\n| sendAddressQo | Object | 是 | 寄件人地址（字段见 6.1） |\n| recipientAddressQo | Object | 是 | 收件人地址（字段见 6.1；**收件人 zipCode 必填**） |\n| skuList | Array | 否 | SKU 申报明细（字段见 6.2，**每行全部字段选填**，缺失字段按兜底链取值、其余原样转发；**全部明细转发承运商**——支持多明细的渠道逐条上送；建议尽量填写完整以保证清关信息完整） |\n\n**orderExtra 子对象**：\n\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| insuranceService | Integer | 是 | 保险服务：1 需要 \u002F 0 不需要 |\n| insurancePrice | BigDecimal | 条件 | 保险价格，`insuranceService=1` 时必填 |\n| insuranceFeeCurrency | String | 否 | 保险价格币种（默认 USD） |\n| signType | Integer | 是 | 签名服务：0 不需要 \u002F 1 直接签名 \u002F 2 间接签名 \u002F 3 成人签名 |\n| shipDate | String | 否 | 发货日期（`yyyy-MM-dd HH:mm:ss`；部分渠道限定为当天起 7 日内，不传按当天处理） |\n| declaredAmount | BigDecimal | 否 | 申报总金额 |\n| declaredCurrencyType | String | 否 | 申报金额币种（默认 USD） |\n| declareQuantity | Integer | 否 | 申报总数量（不传时取 SKU 明细数量合计） |\n| remark | String | 否 | 备注 |\n\n#### 响应参数（data）\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| provider | String | 承运商 |\n| orderNumber | String | 订单号（回显） |\n| trackingNumber | String | 跟踪号：**同步出单渠道**下单即返回；**异步出单渠道**为空，需调用「获取面单」获取 |\n| masterTrackingNumber | String | 主运单号（部分承运商返回，可空） |\n| carrier | String | 实际承运商（如 USPS \u002F SF \u002F UPS，可空） |\n| estimatedSeconds | Integer | 异步出单渠道的预估可获取面单时间（秒，可空） |\n| extra | Object | 承运商专有扩展返回（如发票地址、标签地址等，可空，按需向运营确认字段含义） |\n\n#### 请求示例\n\n```bash\ncurl -X POST {BASE_URL}\u002Fapi\u002Fshipping\u002Forder\u002Fcreate \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -H \"token: $CUSTOMER_TOKEN\" \\\n  -d '{\n        \"orderNo\": \"ORDER-20261005-001\",\n        \"productCode\": \"20133800\",\n        \"orderExtra\": {\n          \"insuranceService\": 0,\n          \"signType\": 0,\n          \"declaredAmount\": 19.99,\n          \"declaredCurrencyType\": \"USD\",\n          \"shipDate\": \"2026-10-05 14:30:00\"\n        },\n        \"length\": 10, \"width\": 8, \"height\": 6, \"weight\": 1.1,\n        \"sendAddressQo\": {\n          \"nameFirst\": \"San\", \"nameLast\": \"Zhang\", \"phone\": \"13800000000\",\n          \"country\": \"CN\", \"province\": \"Guangdong\", \"city\": \"Shenzhen\",\n          \"address1\": \"1 Sender Rd\", \"zipCode\": \"518000\"\n        },\n        \"recipientAddressQo\": {\n          \"nameFirst\": \"Jane\", \"nameLast\": \"Doe\", \"phone\": \"2135551234\",\n          \"country\": \"US\", \"province\": \"CA\", \"city\": \"Los Angeles\",\n          \"address1\": \"1234 S Main St\", \"zipCode\": \"90015\"\n        },\n        \"skuList\": [{\n          \"sku\": \"SKU-1\", \"productNameCn\": \"手提包\", \"productNameEn\": \"Handbag\",\n          \"quantity\": 1, \"declaredUnitPrice\": 19.99, \"declaredCurrency\": \"USD\",\n          \"weight\": 453.6, \"length\": 25.4, \"width\": 20.3, \"height\": 15.2,\n          \"hsCode\": \"4202.21\", \"productNature\": \"2,4\", \"unit\": 1\n        }]\n      }'\n```\n\n#### 响应示例\n\n```json\n{\n  \"code\": 0,\n  \"msg\": \"success\",\n  \"data\": {\n    \"provider\": \"USPS\",\n    \"orderNumber\": \"ORDER-20261005-001\",\n    \"trackingNumber\": \"\",\n    \"masterTrackingNumber\": null,\n    \"carrier\": null,\n    \"estimatedSeconds\": 60,\n    \"extra\": null\n  }\n}\n```\n\n#### 典型错误\n\n| 场景 | 返回 |\n|------|------|\n| 产品不存在\u002F已停用\u002F未关联可用渠道 | 见 3.4 通用业务校验 |\n| 全部候选渠道试算失败 | `产品[xxx]下所有可用渠道试算失败，暂不能打单，请稍后重试`（订单落库异常，未产生上游费用） |\n| 订单号重复创建 | code 10002（数据已存在）或上游「订单号已存在」类错误 |\n| 需要保险但缺 insurancePrice | `需要保险服务时保险价格(insurancePrice)必填` |\n| signType 传 4 | `签名服务类型(signType)必填且仅支持 0~3(0 不需要\u002F1 直接\u002F2 间接\u002F3 成人)` |\n| 收件人缺邮编 | `收件人邮编(zipCode)不能为空` |\n\n---\n\n### 5.3 获取面单\n\n`POST {BASE_URL}\u002Fapi\u002Fshipping\u002Flabel\u002Fget`\n\n按订单号获取面单结果：返回跟踪号、渠道侧费用、面单文件信息与**面单下载地址**（不返回 Base64 面单内容）。服务端**按下单归档记录自动路由**——以该订单实际选中的物流商拉取面单，与产品\u002F渠道当前配置无关。\n\n- 同步出单渠道：下单后即可调用；\n- **异步出单渠道**：面单未就绪时服务端会**自动等待并重试**（视渠道配置约 1~5 分钟）；若仍未出单将返回错误，请间隔数十秒后重新调用，勿高频轮询。\n\n#### 请求参数\n\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| orderNo | String | 是 | 订单号（下单时使用的订单号） |\n| productCode | String | 否 | 兼容保留字段（服务端按下单归档记录路由，不参与解析，可省略） |\n| waybillFormat | String | 否 | 面单格式：`PDF` \u002F `PNG` \u002F `ZPL`（部分渠道由上游决定，不保证生效） |\n\n#### 响应参数（data）\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| provider | String | 承运商 |\n| orderNumber | String | 订单号 |\n| trackingNumber | String | 跟踪号 |\n| carrier | String | 实际承运商（可空） |\n| labelUrl | String | **面单下载地址**（后端代理下载，地址稳定不过期；已自动附带 Token 参数，可直接打开，见 5.3.3） |\n| fileType | String | 面单文件格式：pdf \u002F png \u002F zpl |\n| totalFee | BigDecimal | 渠道侧费用（注意与试算的应收价 `totalCharge` 口径不同） |\n| zone | Integer | 分区 |\n\n#### 请求示例\n\n```bash\ncurl -X POST {BASE_URL}\u002Fapi\u002Fshipping\u002Flabel\u002Fget \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -H \"token: $CUSTOMER_TOKEN\" \\\n  -d '{ \"orderNo\": \"ORDER-20261005-001\" }'\n```\n\n#### 响应示例\n\n```json\n{\n  \"code\": 0,\n  \"msg\": \"success\",\n  \"data\": {\n    \"provider\": \"USPS\",\n    \"orderNumber\": \"ORDER-20261005-001\",\n    \"trackingNumber\": \"9235990363079551107022\",\n    \"carrier\": \"USPS\",\n    \"labelUrl\": \"{BASE_URL}\u002Fapi\u002Fshipping\u002Flabel\u002Fdownload?orderNo=ORDER-20261005-001&token=\u003C客户Token>\",\n    \"fileType\": \"pdf\",\n    \"totalFee\": 8.05,\n    \"zone\": 4\n  }\n}\n```\n\n#### 典型错误\n\n| 场景 | 返回 |\n|------|------|\n| 订单尚未出单（异步渠道未就绪） | 上游「任务未完成」类错误，请稍后重试 |\n| 订单号不存在（无下单归档记录） | `订单[xxx]不存在，无法定位物流渠道` |\n\n#### 5.3.3 面单下载地址（labelUrl）说明\n\n`labelUrl` 指向平台代理下载接口，特点：\n\n- 已附带本次请求的客户 Token 参数，浏览器、下载工具、`\u003Ca>`\u002F`\u003Ciframe>` 嵌入均可直接打开；\n- 地址**长期稳定不过期**，可持久化保存；\n- 响应为文件流：`Content-Disposition: attachment`，文件名为 `{跟踪号或订单号}.{pdf|png|zpl}`；\n- **Token 重置后旧 labelUrl 失效**，需重新调用「获取面单」获取新地址。\n\n```bash\n# 直接下载面单文件\ncurl -OJ \"{BASE_URL}\u002Fapi\u002Fshipping\u002Flabel\u002Fdownload?orderNo=ORDER-20261005-001&token=$CUSTOMER_TOKEN\"\n```\n\n---\n\n### 5.4 取消订单\n\n`POST {BASE_URL}\u002Fapi\u002Fshipping\u002Forder\u002Fcancel`\n\n按订单号向渠道上游发起**真实取消**（受理式，2026-10-05 起）。服务端**按下单归档记录自动路由**——以该订单实际选中的物流商发起取消；只要订单号匹配到归档记录即返回 `code=0` 与受理结果：`cancelStatus=SUCCESS`（上游取消成功，订单不可恢复）\u002F `cancelStatus=FAILED`（上游取消失败，`cancelMsg` 为失败原因，可稍后重试）；已 `SUCCESS` 的订单重复调用幂等返回。\n\n> **退费说明**：只要受理成功（`code=0`），**无论上游取消成败，平台均自动退还该订单扣费**（下单时按客户应收价扣减的可用额度）；未扣费订单跳过；重复取消不重复退款。上游成败不影响退费，无需等待重试成功。\n\n#### 请求参数\n\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| orderNo | String | 是 | 订单号（下单时使用的订单号） |\n| productCode | String | 否 | 兼容保留字段（服务端按下单归档记录路由，不参与解析，可省略） |\n\n#### 响应参数（data）\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| cancelStatus | String | 受理结果：`SUCCESS`=上游取消成功 \u002F `FAILED`=上游取消失败 |\n| cancelMsg | String | 失败原因（`cancelStatus=FAILED` 时非空；`SUCCESS` 时为 `null`） |\n\n> 仅归档记录路由类错误（`订单[xxx]不存在，无法定位物流渠道`、`订单[xxx]物流商[yyy]未接入发货链路`）仍返回非 0 错误码；上游取消成败一律以 `code=0` 受理并体现在 `data.cancelStatus` 中。\n\n#### 请求示例\n\n```bash\ncurl -X POST {BASE_URL}\u002Fapi\u002Fshipping\u002Forder\u002Fcancel \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -H \"token: $CUSTOMER_TOKEN\" \\\n  -d '{ \"orderNo\": \"ORDER-20261005-001\" }'\n```\n\n#### 响应示例\n\n```json\n{ \"code\": 0, \"msg\": \"success\", \"data\": { \"cancelStatus\": \"SUCCESS\", \"cancelMsg\": null } }\n```\n\n上游取消失败时（同样受理成功）：\n\n```json\n{ \"code\": 0, \"msg\": \"success\", \"data\": { \"cancelStatus\": \"FAILED\", \"cancelMsg\": \"错误状态：Processing\" } }\n```\n\n---\n\n## 6. 公共数据对象\n\n### 6.1 地址对象（寄件人 sendAddressQo \u002F 收件人 recipientAddressQo）\n\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| nameFirst | String | 是 | 联系人姓（或名称前段） |\n| nameLast | String | 是 | 联系人名（或名称后段） |\n| country | String | 是 | 国家\u002F地区二字码（如 US \u002F CN） |\n| city | String | 是 | 城市 |\n| address1 | String | 是 | 地址 1 |\n| zipCode | String | 条件 | 邮编：**收件人必填**，寄件人选填（建议传入） |\n| province | String | 否 | 省\u002F州（美国建议传二字简码，如 CA） |\n| area | String | 否 | 区\u002F县 |\n| street | String | 否 | 街道 |\n| houseNumber | String | 否 | 门牌号 |\n| address2 | String | 否 | 地址 2 |\n| phone | String | 否 | 电话 |\n| email | String | 否 | 邮箱 |\n| corporateName | String | 否 | 公司名称 |\n| taxIdValue | String | 否 | 税号（发往欧洲等目的地时建议填写） |\n| portCode | String | 否 | 注入口岸代码（特殊渠道需要，由运营告知；仅寄件人侧生效） |\n\n> `area`（区\u002F县）\u002F`street`（街道）\u002F`houseNumber`（门牌号）为地址细分字段：支持细粒度地址的渠道（如 ShipBest）会原样上送上游，建议传入以提高派送地址精度。\n\n### 6.2 SKU 明细对象（skuList 数组元素）\n\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| sku | String | 否 | SKU 编码 |\n| productNameCn | String | 否 | 品名（中文） |\n| productNameEn | String | 否 | 品名（英文） |\n| quantity | Integer | 否 | 数量（缺省 1） |\n| declaredUnitPrice | BigDecimal | 否 | 申报单价 |\n| declaredCurrency | String | 否 | 申报币种三字码（如 USD；缺省取请求级申报币种） |\n| weight | BigDecimal | 否 | **单件**重量（单位由 unit 决定；缺失\u002F非正数时取首件包裹重量） |\n| length | BigDecimal | 否 | **单件**长（单位由 unit 决定；缺失\u002F非正数时取首件包裹长） |\n| width | BigDecimal | 否 | **单件**宽（单位由 unit 决定；缺失\u002F非正数时取首件包裹宽） |\n| height | BigDecimal | 否 | **单件**高（单位由 unit 决定；缺失\u002F非正数时取首件包裹高） |\n| hsCode | String | 否 | 海关编码（HS Code） |\n| productNature | String | 否 | 商品性质：1 带磁 \u002F 2 不带磁 \u002F 3 带电 \u002F 4 不带电 \u002F 5 液体，多选逗号分隔（如 `\"2,4\"` = 不带磁不带电；缺省取渠道参数或默认 `2,4`） |\n| unit | Integer | 否 | SKU 单位制：1 = g\u002Fcm，2 = kg\u002Fcm，3 = lb\u002Fin（缺省按 lb\u002Fin 处理） |\n\n> 注意：SKU 明细的单件尺寸\u002F重量单位由其自身 `unit` 声明，与包裹级（顶层 `length`\u002F`weight`，固定 inch\u002Flb）相互独立；**每行全部字段选填（v1.6 起）**——缺失字段按兜底链取值（品名英→中→SKU、数量缺省 1、币种取请求级、商品性质取渠道参数\u002F默认 `2,4`、重量\u002F尺寸取首件包裹），`sku`\u002F`hsCode` 等无兜底的字段原样透传，由承运商\u002F下游校验驱动报错。\n> **全量转发（v1.5 起）**：`skuList` 的**全部行**会转发给承运商（此前仅首行生效）——支持多明细的渠道（如 ShipBest）逐条上送参与清关申报，首行同时用于单件模型的包裹字段回填；明细的申报单价\u002F币种\u002F商品性质（`productNature`）均按传入值转发，不再被渠道默认值覆盖。\n\n---\n\n## 7. 调用时序与最佳实践\n\n### 7.1 推荐接入流程\n\n```\n1. 获取 Token（运营开户）→ 环境连通性验证（调用试算）\n2. 业务下单页：先调「运费试算」展示对客价格 → 用户确认\n3. 调「创建订单」→ 记录 orderNumber（异步渠道 trackingNumber 为空属正常）\n4. 轮询\u002F延迟调用「获取面单」：\n   - 建议首次在下单后 10~30 秒调用；服务端未就绪会自动等待重试（视渠道配置约 1~5 分钟）\n   - 若返回「未出单」错误，间隔 30~60 秒重试，无需（也不要）秒级高频轮询\n5. 拿到 labelUrl 后按需下载\u002F打印面单\n6. 异常流程：调「取消订单」撤单（越早成功率越高；已交运后可能失败 `cancelStatus=FAILED`，可稍后重试）；**受理成功即退还该订单扣费**（上游成败不影响退费）\n```\n\n### 7.2 注意事项\n\n| # | 事项 |\n|---|------|\n| 1 | **费用安全**：创建订单、获取面单、取消订单均会触达上游并可能产生费用；务必先试算、再下单，避免误操作 |\n| 2 | **订单号唯一**：由调用方生成并保证唯一；重复创建同一订单号会被拒绝。建议格式：业务前缀 + 日期 + 序号 |\n| 3 | **试算可重复**：试算不产生订单与费用，可放心反复调用（如购物车实时报价） |\n| 4 | **成败判据**：以响应体 `code == 0` 判断成功，不要依赖 HTTP 状态码 |\n| 5 | **重试策略**：网络超时可重试「试算」「获取面单」；**「创建订单」不可盲目重试**（可能造成重复下单），超时后建议先按订单号查询面单确认是否已创建成功，再决定是否重新下单（换新订单号） |\n| 6 | **取消时效**：取消请求宜在出单前后尽快发起；已揽收\u002F交运的订单上游可能取消失败（`cancelStatus=FAILED`，可稍后重试）。**只要受理成功即退还该订单扣费**，上游成败不影响退费 |\n| 7 | **Token 保密**：labelUrl 内含 Token 参数，请勿将完整地址展示给无关人员或写入公开页面 |\n| 8 | **单位换算**：包裹级固定 lb\u002Finch；内部系统为公制时请先换算再上送（1 lb=453.59237 g，1 inch=2.54 cm），或利用 SKU 的 `unit` 字段按 g\u002Fcm 传明细 |\n\n---\n\n## 8. 常见问题（FAQ）\n\n**Q1：试算价格和出单后的 totalFee 为什么不一致？**\n试算返回的 `totalCharge` 为**对客应收价**（按原始申报重量尺寸计价）；`totalFee` 为**渠道侧费用**。两者口径不同，对客收款请以试算价为准。\n\n**Q2：下单成功但 trackingNumber 为空？**\n该渠道为异步出单：下单仅完成创建，跟踪号需在「获取面单」阶段获取。可参考返回的 `estimatedSeconds` 安排首次查询时间。\n\n**Q3：获取面单报「任务未完成」？**\n异步渠道上游尚未出单。服务端已自动等待重试（视渠道配置约 1~5 分钟），仍失败请间隔 30~60 秒再调；持续失败请联系运营排查。\n\n**Q4：订单号重复了怎么办？**\n重复创建会被拒绝（错误码 10002 或上游订单号已存在）。请为每次下单生成新订单号；如需查询已存在的订单，走「获取面单」按订单号查询。\n\n**Q5：Token 失效了怎么办？**\n联系平台运营重置，用新 Token 替换。注意重置后旧的 labelUrl 也会失效，需重新调用「获取面单」。\n\n**Q6：可以取消已出单的订单吗？**\n可随时调用；视渠道与物流状态而定，出单后未交运前通常取消成功（`cancelStatus=SUCCESS`），已揽收\u002F交运后上游可能失败（`cancelStatus=FAILED`，可稍后重试）。无论上游成败，只要受理成功即退还该订单扣费。\n\n**Q7：报文里传了文档没有的字段会怎样？**\n服务端忽略未知字段不会报错，但也不要依赖该行为，字段请严格按本文档传递。\n\n**Q8：productCode（物流产品代码）从哪里获取？**\n由平台运营在管理端创建「物流产品」时由系统自动分配（8 位数字、全局唯一），并配置该产品关联的物流渠道（可多选）；产品关联多个渠道时，试算\u002F下单自动比价。另：`label\u002Fget`、`order\u002Fcancel` 不必传 productCode（兼容保留，传了也不参与路由），服务端按订单号的下单归档记录自动路由。\n\n---\n\n## 9. 变更记录\n\n| 版本 | 日期 | 变更内容 |\n|------|------|----------|\n| v1.0 | 2026-10-05 | 首版：试算、创建订单、获取面单、取消订单 4 个对外接口 |\n| v1.1 | 2026-10-05 | 运费试算支持可选 `orderExtra`（保险\u002F签名\u002F申报\u002F发货日期参与报价，不传时与历史行为一致） |\n| v1.2 | 2026-10-05 | 运费试算 `recipientAddressQo` 改为非必填（传入时 zipCode 仍必填） |\n| v1.3 | 2026-10-05 | 取消订单改为受理式：返回 `{cancelStatus, cancelMsg}`；上游取消失败亦受理（可重试），受理成功即退还该订单扣费 |\n| v1.4 | 2026-10-05 | 引入**物流产品模型**：产品代码改由「物流产品」统一管理（系统自动分配 8 位数字、全局唯一，可关联多个物流渠道）；`rates\u002Fcalculate`、`order\u002Fcreate` 按产品解析候选渠道——单渠道直用、多渠道自动比价（下单按上游应付价最低选渠道、试算返回最低报价渠道结果）；`label\u002Fget`、`order\u002Fcancel` 改按**下单归档记录**的物流商路由，`productCode` 兼容保留、非必填 |\n| v1.5 | 2026-10-11 | SKU 申报明细**全量转发**：`skuList` 全部行转发承运商（此前仅首行生效），申报明细的商品性质\u002F币种\u002F单价按传入值转发、不再被渠道默认值覆盖；地址细分字段 `area`\u002F`street`\u002F`houseNumber` 支持的渠道原样上送上游 |\n| v1.6 | 2026-10-11 | SKU 申报明细字段全部改为**选填**：下游物流商对申报字段必填口径持续变化且逐字段报错，平台层不再拦截；缺失字段按兜底链取值（品名英→中→SKU、数量缺省 1、币种取请求级、商品性质取渠道参数\u002F默认 `2,4`、重量\u002F尺寸取首件包裹），其余透传由承运商\u002F下游校验驱动 |\n","2026-10-30 11:39:48",1794166823845]