🚀 CrossBorder 物流 API 文档
提供高效、稳定、国际化的跨境物流服务接口。
所有接口均需通过 Bearer Token 进行身份认证。
测试环境 Host: https://apitest.cbasvs.com
正式环境 Host: https://api.cbasvs.com
📦 接口概览
- 创建运单：提交包裹信息，生成运单号和面单。
- 轨迹查询：批量查询最多 100 个运单的物流状态。
- 获取面单：通过运单号下载 PDF 面单文件。
📦 创建运单
POST /api/v1/orders/create
提交完整的发件人、收件人及商品信息，系统将返回运单号和面单下载链接。
请求参数
| 字段名 | 类型 | 必填 | 描述 |
|---|---|---|---|
referenceNo | string | 是 | 客户订单号，唯一标识 |
productCode | string | 是 | 产品编码（如 ARMEXP） |
weight | number | 是 | 包裹总重量（kg） |
length | number | 是 | 长度（cm） |
width | number | 是 | 宽度（cm） |
height | number | 是 | 高度（cm） |
remark | string | 否 | 备注信息（如 "Leave at gate"） |
receiver | object | 是 | 收件人信息 |
sender | object | 是 | 寄件人信息 |
itemList | array | 是 | 物品清单列表 |
请求示例
响应示例
📍 轨迹查询
POST /api/v1/tracking/query
支持一次查询最多 100 个运单号，返回每个包裹的最新状态和完整物流事件。
请求参数
| 字段名 | 类型 | 必填 | 描述 |
|---|---|---|---|
trackingNos | string[] | 是 | 运单号数组，最多 100 个 |
请求示例
响应示例
📄 获取物流面单
GET /api/v1/labels/{trackingNo}
通过运单号获取 PDF 面单的下载链接。
请求参数
| 字段名 | 类型 | 必填 | 描述 |
|---|---|---|---|
trackingNo | string | 是 | 运单号 |
请求示例
GET /api/v1/labels/163395270345
响应示例
❌ 错误代码说明
| 错误码 | 中文描述 | 英文描述 | 解决方案 |
|---|---|---|---|
| 400 | 请求参数错误 | Invalid Request Parameters | 检查请求体格式和必填字段 |
| 401 | 未授权访问 | Unauthorized Access | 请确保 Bearer Token 正确且有效 |
| 403 | 权限不足 | Forbidden | 联系管理员确认账号权限 |
| 404 | 资源未找到 | Resource Not Found | 检查 URL 是否正确 |
| 409 | 冲突（如重复订单） | Conflict | 检查 referenceNo 是否已存在 |
| 1001 | 运单号已存在 | Tracking Number Already Exists | 使用新的 referenceNo 或修改原有订单 |
| 1002 | 商品信息不完整 | Incomplete Item Information | 确保 itemList 中每个 item 都有 sku 和 goodsName |