🚀 CrossBorder 物流 API 文档

提供高效、稳定、国际化的跨境物流服务接口。

所有接口均需通过 X-API-Key 进行身份认证。

测试环境 Host: https://apitest.cbasvs.com

正式环境 Host: https://api.cbasvs.com

📦 接口概览

创建运单
轨迹查询
获取面单

📦 创建运单

POST /v2/orders/create

提交完整的发件人、收件人及商品信息，系统将返回运单号和面单下载链接。

请求参数

字段名	类型	必填	描述
`referenceNo`	string	是	客户订单号，唯一标识
`productCode`	string	是	产品编码 / 渠道代码（如 SCCHD）
`weight`	number	是	包裹总重量 (kg) 支持小数点，如 0.9
`length`	number	是	包裹长度 (cm)
`width`	number	是	包裹宽度 (cm)
`height`	number	是	包裹高度 (cm)
`remark`	string	否	订单备注，例如投递特殊要求（"Please leave at front desk"）
`receiver`	object	是	收件人信息对象
`receiver.company`	string	否	收件公司名称
`receiver.fullname`	string	是	收件人全名（姓+名）
`receiver.phone`	string	是	收件人电话（包含区号）
`receiver.email`	string	是	电子邮箱（用于通知）
`receiver.country`	string	是	国家名称（如 Armenia）
`receiver.province`	string	是	州/省
`receiver.city`	string	是	城市
`receiver.address`	string	是	详细街道地址
`receiver.postCode`	string	是	邮政编码
`receiver.vat`	string	否	增值税号 / 税号（部分国家清关需要）
`sender`	object	是	发件人信息对象
`sender.company`	string	否	发件公司名称
`sender.fullname`	string	是	发件人姓名
`sender.phone`	string	是	联系电话（区号+号码）
`sender.email`	string	是	电子邮箱（用于接收通知）
`sender.country`	string	是	发件人国家
`sender.province`	string	是	省份
`sender.city`	string	是	城市
`sender.address`	string	是	详细地址
`sender.postCode`	string	是	邮政编码
`itemList`	array	是	商品/物品清单数组，至少包含1项
`itemList[].sku`	string	是	商品SKU（唯一标识）
`itemList[].goodsName`	string	是	商品名称
`itemList[].goodsNameCN`	string	是	商品名称(中文)
`itemList[].composition`	string	否	商品材质成分（用于海关申报）
`itemList[].hsCode`	string	是	HS编码（海关编码）
`itemList[].quantity`	string/number	是	商品数量
`itemList[].itemWeight`	string/number	是	单个商品重量（kg）
`itemList[].itemValue`	string/number	是	商品货值
`itemList[].currency`	string	是	商品货值币种（ISO代码，如 USD）
`itemList[].exportDeclaredValue`	string/number	是	商品出口申报价值
`itemList[].exportDeclaredCurrency`	string	是	商品出口申报币种（ISO代码，如 USD）
`itemList[].importDeclaredValue`	string/number	是	商品进口申报价值
`itemList[].importDeclaredCurrency`	string	是	商品进口申报币种（ISO代码，如 USD）
`itemList[].sellingUrl`	string(URL)	否	商品销售链接
`itemList[].imageUrl`	string(URL)	否	商品图片链接

请求示例

成功响应示例

失败响应示例

📍 轨迹查询

POST /v2/tracking/query

支持一次查询最多 100 个运单号，返回每个包裹的最新状态和完整物流事件。

请求参数

字段名	类型	必填	描述
`trackingNos`	string[]	是	运单号数组，最多 100 个

请求示例

{
  "trackingNos": [
    "791829381364",
    "163395270345"
  ]
}

成功响应示例

失败响应示例

响应字段说明

字段名	类型	描述
`success`	boolean	请求是否成功
`code`	integer	HTTP/业务状态码
`message`	string	返回消息
`requestId`	string	请求唯一标识，用于排查问题
`data`	array	轨迹数据列表
`data[].trackingNo`	string	运单号
`data[].referenceNo`	string	客户订单号
`data[].latestEventCode`	integer	最新轨迹状态码（参见轨迹状态码表）
`data[].latestStatus`	string	最新状态描述（根据收件人国家语言返回）
`data[].latestStatusEn`	string	最新状态描述（英文）
`data[].latestLocation`	string	最新发生地点（本地语言）
`data[].latestLocationEn`	string	最新发生地点（英文）
`data[].latestStatusTime`	string	最新状态时间
`data[].timezone`	string	时区（IANA格式，如 Asia/Yerevan）
`data[].events`	array	全量轨迹事件列表
`events[].eventCode`	integer	事件状态码
`events[].status`	string	状态描述（本地语言）
`events[].statusEn`	string	状态描述（英文）
`events[].location`	string	发生地点（本地语言）
`events[].locationEn`	string	发生地点（英文）
`events[].statusTime`	string	事件时间
`events[].timezone`	string	事件时区
`data[].podUrls`	array	签收证明图片/PDF链接列表

📄 获取物流面单

GET /v2/labels/{trackingNo}

通过运单号获取 PDF 面单的下载链接。

请求参数

字段名	类型	必填	描述
`trackingNo`	string	是	运单号

请求示例

GET /v2/labels/163395270345

成功响应示例

失败响应示例

📋 接口状态码（完整列表）

状态码	中文描述	英文描述	解决方案
200	请求成功	Success	操作成功完成
400	请求参数错误	Bad Request	检查请求体格式、必填字段及字段类型
4001	缺少必填字段	Missing Required Field	请补充缺失的必填字段（如 referenceNo, productCode 等）
4002	字段格式无效	Invalid Field Format	检查邮箱、电话、邮编等格式是否正确
4003	重量或尺寸超限	Weight/Dimension Exceeded	单件包裹重量或尺寸超过物流渠道限制
4004	HS编码无效	Invalid HS Code	请提供有效的海关编码（6-10位数字）
4005	国家/地区不支持	Country Not Supported	当前物流线路不支持该国家或地区
4006	商品清单为空或数量为零	Empty Item List	itemList 至少包含一个有效商品且 quantity>0
4007	币种代码无效	Invalid Currency Code	使用 ISO 4217 标准币种（如 USD, EUR, CNY）
4008	产品代码无效	Invalid Product Code	productCode 不存在或已停用
401	未授权访问	Unauthorized	请确保 X-API-Key 正确且未过期
403	权限不足	Forbidden	当前账号无权限调用该接口，联系管理员
404	资源未找到	Not Found	请求的 URL 或运单号不存在
409	订单号冲突	Conflict	referenceNo 已存在，请使用新的订单号
429	请求频率超限	Too Many Requests	请降低调用频率，稍后重试
500	服务器内部错误	Internal Server Error	系统异常，请联系技术支持
503	服务暂不可用	Service Unavailable	服务维护中，请稍后重试
1001	运单号已存在	Tracking Number Exists	使用新的 referenceNo 或修改原有订单
1002	商品信息不完整	Incomplete Item Info	每个 item 至少提供 sku、goodsName、hsCode
1003	收件人地址无效	Invalid Receiver Address	地址解析失败，请填写详细正确的地址
1004	申报价值超出限制	Declared Value Exceeds Limit	申报价值超出目的国免税额度或物流限制
1005	面单生成失败	Label Generation Failed	暂时无法生成面单，请稍后重试或联系客服

📌 轨迹状态码说明

轨迹简码	轨迹描述EN	轨迹描述
ORCD	Shipment Information Received	包裹信息传输
PRCD01	CN Processing Center Received	揽收入库
PRCD03	Shipment Added in Transit Bag	货物装包
PRCD05	Added into Batch	分配批次
PRCD07	Outbound From CN Processing Center	出库交头程
DORG	Departure From Origin Airport	头程发出
TSTD	Transshipment to Destination Airport	头程转运中
ADST	Arrived at Destination Airport	到达目的地机场
ICCC	In Customs Clearance	清关中
INSP01	Customs inspection in progress	海关查验
INSP02	Held by customs – Awaiting additional documentation	海关扣留 – 等待补充文件
INSP03	Held by customs – Incorrect or missing declaration	海关扣留 – 申报信息不完整或错误
INSP04	Held by customs – Restricted or prohibited item	海关扣留 – 涉及限制/禁运商品
INSP05	Held by customs – Value verification required	海关扣留 – 需要核实申报价值
INSP06	Held by customs – Incomplete consignee information	海关扣留 – 收件人信息不完整
INSP07	Held by customs – Pending customs clearance	海关扣留 – 等待清关处理
ICCF	Import Customs Clearance Finished	清关完成
DRCD	Received at Sorting Center	尾程揽收
LMIT	In Transit	尾程转运中
ADB	Arrived Delivery Branch	到达派送站点
DOFD	Out For Delivery	外出派送
RFCC	Ready for Customer Collection	待自提
RDR	Report Damaged - Repacked	包裹破损并重新包装
RBSC	Rejected by Security Check	安检不通过
REDR	Redirection requested	更改地址
TETD	Transit Delay	转运延误
UDLV01	Unsuccessful delivery – Consignee not available	收件人不在
UDLV02	Unsuccessful delivery – Incorrect or incomplete address	地址问题
UDLV03	Unsuccessful delivery – Unable to access delivery location	地址无法进入
UDLV04	Unsuccessful delivery – Wrong Number	错误的联系方式
UDLV05	Unsuccessful delivery – Delivery refused by consignee	收件人拒收
UDLV06	Unsuccessful delivery – Delivery rescheduled by carrier	改日派送
UDLV07	Unsuccessful delivery – Bad weather conditions	天气原因
UDLV08	Unsuccessful delivery – RTO as per Sender Instruction	发件方要求退件
CSD01	Shipment Delivered	签收
CBC01	Collected by Customer	已自提
CSL	Shipment Lost	包裹丢失
CSD	Shipment Damanged	包裹破损
CSC	Shipment Cancelled	包裹取消
RTOCF	RTO Confirmed	确认拒收
RTOHW	Held in Warehouse - RTO area	包裹退件暂存
RTOC	Return Completed	退件完成
RTOD	Shipment Disposed	弃件销毁