# 云途物流 API 接口开发规范 OMS 摘要

来源：`doc/jykj/云途物流API接口开发规范OMS-20260717.pdf`

版本：OMS 1.4.6

日期：2026-07-17

## 一、接入信息

### 1.1 服务地址

| 环境 | 地址 |
| --- | --- |
| 测试 | `http://omsapi.uat.yunexpress.com` |
| 正式 | `http://oms.api.yunexpress.com` |

本系统默认连接测试环境。通过环境变量可快速切换：

```dotenv
# uat=测试环境，prod=正式环境
YUNTU_ENV=uat

# 非空时强制使用该地址，优先级高于 YUNTU_ENV
YUNTU_DOMAIN=

YUNTU_UAT_DOMAIN=http://omsapi.uat.yunexpress.com
YUNTU_PROD_DOMAIN=http://oms.api.yunexpress.com
```

### 1.2 认证方式

云途使用 HTTP Header Basic Token 认证。

Token 生成规则：

```text
base64(CustomerCode + '&' + ApiSecret)
```

请求头：

```text
Accept: application/json
Content-Type: application/json
Authorization: Basic {Token}
```

本系统账号配置建议：

| `express_account` 字段 | 云途含义 |
| --- | --- |
| `service` | 固定 `yuntu` |
| `token` | 云途客户编号 CustomerCode |
| `secret` | 云途 ApiSecret |
| `company_code` | 可选，默认运输方式代码 ShippingMethodCode |

## 二、核心接口

| 功能 | 方法 | 地址 | 说明 |
| --- | --- | --- | --- |
| 查询国家简码 | GET | `/api/Common/GetCountry` | 无请求参数 |
| 查询运输方式 | GET | `/api/Common/GetShippingMethods` | `CountryCode` 可选 |
| 查询货品类型 | GET | `/api/Common/GetGoodsType` | 无请求参数 |
| 查询价格 | GET | `/api/Freight/GetPriceTrial` | 运费试算 |
| 查询跟踪号 | GET | `/api/Waybill/GetTrackingNumber` | 通过客户订单号查询 |
| 运单申请 | POST | `/api/WayBill/CreateOrder` | 支持批量，一次最多 10 条 |
| 查询运单 | GET | `/api/WayBill/GetOrder` | 可用云途单号、客户订单号或跟踪号 |
| 修改预报重量 | POST | `/api/WayBill/UpdateWeight` | 仅支持已预报 |
| 订单删除 | POST | `/api/WayBill/Delete` | 仅支持草稿、已预报 |
| 订单拦截 | POST | `/api/WayBill/Intercept` | 支持已预报、已入仓 |
| 标签打印 | POST | `/api/Label/Print` | 每次最多 50 条 |
| 运费明细 | GET | `/api/Freight/GetShippingFeeDetail` | 按云途运单号查询 |
| 查询轨迹 | GET | `/api/Tracking/GetTrackInfo` | 按订阅轨迹查询 |
| 查询全程轨迹 | GET | `/api/Tracking/GetTrackAllInfo` | 全程轨迹 |
| 查询末端派送商 | POST | `/api/Waybill/GetCarrier` | 请求体为单号数组 |

## 三、运费试算

地址：

```text
GET /api/Freight/GetPriceTrial
```

关键请求字段：

| 字段 | 必填 | 说明 |
| --- | --- | --- |
| `CountryCode` | 是 | 目的国二字码 |
| `Weight` | 是 | 包裹重量，单位 kg，最多 3 位小数 |
| `Length` | 否 | 长，单位 cm，默认 1 |
| `Width` | 否 | 宽，单位 cm，默认 1 |
| `Height` | 否 | 高，单位 cm，默认 1 |
| `PostCode` | 否 | 邮编 |
| `PackageType` | 否 | 1 带电，0 普货，2 特货，默认 1 |
| `Origin` | 否 | 计费地点，云途默认 `YT-SZ` |
| `ExtraServicesList` | 否 | 额外服务列表 |

关键响应字段：

| 字段 | 说明 |
| --- | --- |
| `Items[].Code` | 运输方式代码 |
| `Items[].CName` | 中文名称 |
| `Items[].EName` | 英文名称 |
| `Items[].TotalFee` | 总费用 |
| `Items[].DeliveryDays` | 预计时效 |
| `Items[].Currency` | 币种 |
| `Items[].Weight` | 计费重 |
| `Items[].Track` | 轨迹 |
| `Code` | `0000` 表示提交成功 |
| `Message` | 结果描述 |

## 四、运单申请

地址：

```text
POST /api/WayBill/CreateOrder
```

请求体为订单数组，一次最多 10 条。

关键请求字段：

| 字段 | 必填 | 说明 |
| --- | --- | --- |
| `CustomerOrderNumber` | 是 | 客户订单号，不能重复 |
| `ShippingMethodCode` | 是 | 运输方式代码 |
| `TrackingNumber` | 否 | 外部跟踪号 |
| `WarehouseAddressCode` | 否 | 仓库代码 |
| `SizeUnits` | 否 | `cm` 或 `inch`，默认 `cm` |
| `Length` / `Width` / `Height` | 否 | 包裹尺寸 |
| `PackageCount` | 是 | 包裹件数 |
| `Weight` | 是 | 包裹总重量，单位 kg |
| `Receiver` | 是 | 收件人信息 |
| `Sender` | 否 | 发件人信息 |
| `ApplicationType` | 否 | 1 Gift，2 Sample，3 Documents，4 Others |
| `ReturnOption` | 否 | 是否退回 |
| `TariffPrepay` | 否 | 是否关税预付 |
| `InsuranceOption` | 否 | 保险类型 |
| `SensitiveTypeID` | 否 | 特殊货品类型 |
| `Parcels` | 是 | 申报信息 |
| `OrderExtra` | 否 | 附加服务 |
| `IossCode` | 否 | IOSS 备案识别码或 IOSS 号 |

`Receiver` 关键字段：

| 字段 | 必填 | 说明 |
| --- | --- | --- |
| `CountryCode` | 是 | 国家二字码 |
| `FirstName` | 是 | 收件人姓/姓名 |
| `LastName` | 否 | 收件人名字 |
| `Company` | 否 | 公司 |
| `Street` | 是 | 详细地址 |
| `StreetAddress1` / `StreetAddress2` | 否 | 地址补充 |
| `City` | 是 | 城市 |
| `State` | 否 | 省/州 |
| `Zip` | 否 | 邮编 |
| `Phone` | 否 | 电话 |
| `Email` | 否 | 邮箱 |
| `MobileNumber` | 否 | 手机号 |

`Parcels` 关键字段：

| 字段 | 必填 | 说明 |
| --- | --- | --- |
| `EName` | 是 | 英文申报名 |
| `CName` | 否 | 中文申报名 |
| `HSCode` | 否 | 海关编码 |
| `Quantity` | 是 | 数量 |
| `UnitPrice` | 是 | FOB 申报价 |
| `UnitWeight` | 是 | 单重 kg |
| `SKU` | 否 | SKU |
| `CurrencyCode` | 是 | 申报币种，默认 `USD` |
| `InvoicePart` | 否 | 材质 |
| `InvoiceUsage` | 否 | 用途 |

关键响应字段：

| 字段 | 说明 |
| --- | --- |
| `Item[].CustomerOrderNumber` | 客户订单号 |
| `Item[].Success` | 1 成功，0 失败 |
| `Item[].TrackType` | 1 已产生跟踪号，2 等待更新跟踪号，3 不需要跟踪号 |
| `Item[].WayBillNumber` | 云途运单号 |
| `Item[].TrackingNumber` | 跟踪号 |
| `Item[].RemoteArea` | 是否偏远地址 |
| `Code` | `0000` 表示提交成功 |

## 五、订单操作

### 5.1 查询跟踪号

```text
GET /api/Waybill/GetTrackingNumber?CustomerOrderNumber={customer_order_number}
```

可多个客户订单号逗号分隔。

### 5.2 查询运单

```text
GET /api/WayBill/GetOrder?OrderNumber={order_number}
```

`OrderNumber` 可传云途运单号、客户订单号或跟踪号。

订单状态：

| 状态 | 说明 |
| --- | --- |
| 0 | 草稿 |
| 3 | 已提交 |
| 4 | 已收货 |
| 5 | 已发货 |
| 6 | 已删除 |
| 7 | 已退回 |
| 10 | 已理赔 |
| 11 | 已签收 |

### 5.3 删除订单

```text
POST /api/WayBill/Delete
```

请求：

```json
{
  "OrderType": 1,
  "OrderNumber": "YT1908621203000037"
}
```

`OrderType`：1 云途单号，2 客户订单号，3 跟踪号。

### 5.4 标签打印

```text
POST /api/Label/Print
```

请求体：

```json
["YT1907911202000015"]
```

响应中的 `Item[].Url` 是标签 PDF 地址。

## 六、轨迹

### 6.1 查询轨迹

```text
GET /api/Tracking/GetTrackInfo?OrderNumber={order_number}
GET /api/Tracking/GetTrackAllInfo?OrderNumber={order_number}
```

关键响应字段：

| 字段 | 说明 |
| --- | --- |
| `Item.WaybillNumber` | 云途运单号 |
| `Item.TrackingNumber` | 跟踪号 |
| `Item.ProviderName` | 末端服务商 |
| `Item.PackageState` | 包裹状态 |
| `Item.TrackingStatus` | 轨迹状态 |
| `Item.OrderTrackingDetails[]` | 轨迹明细 |

包裹状态：

| 状态 | 说明 |
| --- | --- |
| 0 | 未知 |
| 1 | 已提交 |
| 2 | 运输中 |
| 3 | 已签收 |
| 4 | 已收货 |
| 5 | 订单取消 |
| 6 | 投递失败 |
| 7 | 已退回 |

轨迹状态：

| 状态 | 说明 |
| --- | --- |
| 0 | 未找到 |
| 10 | 电子预报信息已接收 |
| 20 | 运输途中 |
| 30 | 到达待取 |
| 40 | 投递失败 |
| 50 | 已签收 |
| 60 | 异常 |
| 80 | 未知 |
| 90 | 已退回 |
| 100 | 已取消 |

### 6.2 查询末端派送商

```text
POST /api/Waybill/GetCarrier
```

请求体：

```json
["YT1907911202000015"]
```

响应字段包括 `CarrierCode`、`CarrierCName`、`CarrierEName`、`CarrierPhone`、`CarrierWebsite`。

## 七、系统实现约定

本系统新增 `App\Service\Third\Express\Realize\Yuntu`：

1. `ExpressAccount.token` 存云途客户编号。
2. `ExpressAccount.secret` 存云途 ApiSecret。
3. `ExpressTask.express_com` 存运输方式代码。
4. `ExpressTask.order_id` 存客户订单号。
5. `ExpressTask.task_id` 优先存跟踪号，没有跟踪号时存云途运单号。
6. `ExpressTask.label_url` 存云途标签 PDF URL。
7. 运费试算返回结构对齐现有 `imputedExpress()` 列表格式。
8. 云途环境配置在 `config/autoload/yuntu.php`：默认 `YUNTU_ENV=uat` 连接测试环境；切正式环境只需改为 `YUNTU_ENV=prod`；临时联调其他网关可填写 `YUNTU_DOMAIN` 覆盖。