1. ISV物流对接SDK使用文档
1.1. 目录
1.2. 概述
QlinkLogisticsClient 是千易开放平台的物流SDK客户端，提供统一的接口调用服务商的物流服务。
1.2.1. 主要功能
- 创建物流订单
- 取消物流订单
- 获取面单数据
- 获取物流轨迹
- 初始化物流渠道
- 授权与取消授权
1.2.2. 支持两种调用方式
- 默认请求头：自动填充认证信息（推荐）
- 自定义请求头：灵活控制请求参数
1.3. 快速开始
// 1. 创建配置
QlinkBaseConfig config = new QlinkBaseConfig(
"https://api.example.com", // 网关地址
"your-app-key", // 应用Key
"your-app-secret" // 应用密钥
);
// 2. 创建客户端
QlinkLogisticsClient client = new QlinkLogisticsClient(config);
// 3. 调用接口
QlinkLogisticsRequest<CreateLogisticsOrderRequest> request = new QlinkLogisticsRequest<>();
request.setMethod("createOrder");
CreateLogisticsOrderRequest content = new CreateLogisticsOrderRequest();
// 设置其他业务参数...
request.setContent(content);
OpenApiResponse<CreateLogisticsOrderResponse> response = client.createOrder(request);
1.4. 依赖配置
1.4.1. Maven依赖
在项目的 pom.xml 文件中添加以下依赖：
<dependency>
<groupId>com.800best</groupId>
<artifactId>open-platform-sdk</artifactId>
<version>1.0.6-SNAPSHOT</version>
</dependency>
1.4.2. 依赖说明
SDK底层依赖：
fastjson：JSON序列化lombok：代码简化apache httpclient：HTTP请求slf4j：日志框架
1.5. 初始化SDK
1.5.1. 方式一：使用配置类（推荐）
import com.best.open.platform.sdk.config.QlinkBaseConfig;
import com.best.open.platform.sdk.client.QlinkBaseConfig;
// 构造配置
QlinkBaseConfig config = new QlinkBaseConfig(
"https://api.example.com",
"your-app-key",
"your-app-secret"
);
// 创建客户端
QlinkLogisticsClient client = new QlinkLogisticsClient(config);
1.5.2. 方式二：直接构造函数
QlinkLogisticsClient client = new QlinkLogisticsClient(
"https://api.example.com",
"your-app-key",
"your-app-secret"
);
1.5.3. 方式三：环境预设
// 开发环境
QlinkBaseConfig devConfig = QlinkBaseConfig.createDevConfig("your-app-key", "your-app-secret");
QlinkLogisticsClient devClient = new QlinkLogisticsClient(devConfig);
// 测试环境
QlinkBaseConfig testConfig = QlinkBaseConfig.createTestConfig("your-app-key", "your-app-secret");
QlinkLogisticsClient testClient = new QlinkLogisticsClient(testConfig);
// 生产环境
QlinkBaseConfig prodConfig = QlinkBaseConfig.createProdConfig("your-app-key", "your-app-secret");
QlinkLogisticsClient prodClient = new QlinkLogisticsClient(prodConfig);
1.5.4. 配置参数说明
QlinkBaseConfig config = new QlinkBaseConfig();
config.setBaseUrl("https://api.example.com"); // API服务基础URL
config.setAppKey("your-app-key"); // 应用Key
config.setAppSecret("your-app-secret"); // 应用密钥
config.setConnectTimeout(5000); // 连接超时时间（毫秒）
config.setReadTimeout(30000); // 读取超时时间（毫秒）
config.setEnableLog(true); // 是否启用日志
config.setRetryCount(3); // 重试次数
config.setRetryInterval(1000); // 重试间隔（毫秒）
1.6. 核心功能
1.6.1. 请求对象结构
所有请求都使用统一的 QlinkLogisticsRequest<T> 结构：
public class QlinkLogisticsRequest<T> {
private String appKey; // 应用Key（SDK自动填充）
private String method; // 请求方法（必填）
private String sign; // 签名（SDK自动生成）
private T content; // 请求内容（业务参数）
}
1.6.2. 响应对象结构
统一返回 OpenApiResponse<T>：
public class OpenApiResponse<T> {
private String state; // 状态：success/fail
private String code; // 错误码
private String errorMsg; // 错误信息
private T result; // 业务数据
private Boolean success; // 是否成功
private String requestId; // 请求ID
}
1.7. API详解
1.7.1. 1. 创建物流订单
接口说明
创建物流运单，获取物流跟踪号。
请求参数
QlinkLogisticsRequest<CreateLogisticsOrderRequest> request = new QlinkLogisticsRequest<>();
request.setMethod("createOrder");
CreateLogisticsOrderRequest content = new CreateLogisticsOrderRequest();
content.setLogisticsKey("QLINK"); // 物流类型（必填）
content.setChannelCode("YANWEN"); // 物流渠道编码
content.setCustomerNumber("CUST001"); // 客户编码
content.setOnlineOrderId("ORDER123"); // 线上订单号
content.setRecipientAddress(recipientAddress); // 收件人地址
content.setSenderAddress(senderAddress); // 发件人地址
content.setItemList(itemList); // 商品列表
content.setPackageWeight(new BigDecimal("1.5")); // 包裹重量
content.setRemarks("特殊说明"); // 备注
// ... 设置其他字段
request.setContent(content);
调用方式
// 默认请求头（推荐）
OpenApiResponse<CreateLogisticsOrderResponse> response = client.createOrder(request);
// 自定义请求头
Map<String, String> headers = new HashMap<>();
headers.put("logisticsType", "QLINK");
headers.put("appKey", "your-app-key");
headers.put("sign", "custom-sign");
OpenApiResponse<CreateLogisticsOrderResponse> response = client.createOrder(request, headers);
响应数据
CreateLogisticsOrderResponse result = response.getResult();
// result.getTrackingNumber() // 物流跟踪号
// result.getCustomerNumber() // 客户编码
// result.getPackageInfoList() // 包裹信息列表
响应类结构
public class CreateLogisticsOrderResponse {
private String trackingNumber; // 物流跟踪号
private String customerNumber; // 客户编码
private String addressType; // 地址类型
private String feedBackId; // 反馈ID
private List<PackageInfo> packageInfoList; // 包裹信息列表
public static class PackageInfo {
private String packageNumber; // 包裹号
private String trackingNumber; // 跟踪号
private String customerNumber; // 客户编码
}
}
1.7.2. 2. 取消物流订单
接口说明
取消已创建的物流订单。
请求参数
QlinkLogisticsRequest<CancelLogisticsOrderRequest> request = new QlinkLogisticsRequest<>();
request.setMethod("cancelOrder");
CancelLogisticsOrderRequest content = new CancelLogisticsOrderRequest();
content.setLogisticsKey("LOG_KEY_123"); // 物流Key
content.setTrackingNumber("TRACK123"); // 物流跟踪号
content.setCustomerNumber("CUST001"); // 客户编码
request.setContent(content);
调用方式
OpenApiResponse<String> response = client.cancelOrder(request);
1.7.3. 3. 获取面单数据
接口说明
获取物流面单的PDF或图片数据。
请求参数
QlinkLogisticsRequest<GetLabelRequest> request = new QlinkLogisticsRequest<>();
request.setMethod("getLabelData");
GetLabelRequest content = new GetLabelRequest();
content.setLogisticsKey("QLINK");
content.setTrackingNumber("TRACK123"); // 物流跟踪号
content.setCustomerNumber("CUST001"); // 客户编码
content.setLabelType("PDF"); // 面单类型：PDF/PNG
content.setChannelCode("YANWEN"); // 渠道编码
request.setContent(content);
调用方式
OpenApiResponse<GetLabelResponse> response = client.getLabelData(request);
响应数据
GetLabelResponse result = response.getResult();
// result.getTrackingNumber() // 物流跟踪号
// result.getCustomerNumber() // 客户编码
// result.getLabelData() // 面单数据（Base64编码）
1.7.4. 4. 获取物流轨迹
接口说明
查询物流包裹的运输轨迹信息。
请求参数
QlinkLogisticsRequest<GetTrackingInfoRequest> request = new QlinkLogisticsRequest<>();
request.setMethod("getTrackingInfo");
GetTrackingInfoRequest content = new GetTrackingInfoRequest();
content.setLogisticsKey("QLINK");
content.setTrackingNumber("TRACK123"); // 物流跟踪号
content.setCustomerNumber("CUST001"); // 客户编码
request.setContent(content);
调用方式
OpenApiResponse<GetTrackingResponse> response = client.getTrackingInfo(request);
响应数据
GetTrackingResponse result = response.getResult();
// result.getCarrierName() // 承运商名称
// result.getTrackingNumber() // 物流跟踪号
// result.getStatus() // 物流状态
// result.getStageList() // 物流阶段列表
响应类结构
public class GetTrackingResponse {
private String orderNumber; // 订单号
private String carrierName; // 承运商名称
private String trackingNumber; // 物流跟踪号
private String status; // 状态
private List<StageInfo> stageList; // 物流阶段列表
public static class StageInfo {
private String status; // 阶段状态
private Integer number; // 阶段编号
private List<TrackingEvent> trackingEvents; // 物流事件列表
}
public static class TrackingEvent {
private String eventDate; // 事件日期
private String eventPlace; // 事件地点
private String eventDesc; // 事件描述
}
}
1.7.5. 5. 初始化物流渠道
接口说明
初始化可用的物流渠道列表。
请求参数
QlinkLogisticsRequest<InitLogisticsChannelsRequest> request = new QlinkLogisticsRequest<>();
request.setMethod("initLogisticsChannels");
InitLogisticsChannelsRequest content = new InitLogisticsChannelsRequest();
content.setLogisticsKey("LOG_KEY_123");
request.setContent(content);
调用方式
OpenApiResponse<InitLogisticsChannelsResponse> response = client.initLogisticsChannels(request);
响应数据
InitLogisticsChannelsResponse result = response.getResult();
// result.getChannelList() // 可用的物流渠道列表
1.7.6. 6. 授权接口
接口说明
获取访问令牌。
请求参数
QlinkLogisticsRequest<AuthorizeRequest> request = new QlinkLogisticsRequest<>();
request.setMethod("authorize");
AuthorizeRequest content = new AuthorizeRequest();
content.setAppKey("your-app-key");
content.setAppSecret("your-app-secret");
// 设置其他授权参数...
request.setContent(content);
调用方式
OpenApiResponse<AuthorizeResponse> response = client.authorize(request);
1.7.7. 7. 取消授权接口
接口说明
取消授权访问。
请求参数
QlinkLogisticsRequest<UnauthorizeRequest> request = new QlinkLogisticsRequest<>();
request.setMethod("unauthorize");
UnauthorizeRequest content = new UnauthorizeRequest();
// 设置取消授权参数...
request.setContent(content);
调用方式
OpenApiResponse<UnauthorizeResponse> response = client.unauthorize(request);
1.8. 错误处理
1.8.1. 统一错误处理
OpenApiResponse<CreateLogisticsOrderResponse> response = client.createOrder(request);
// 方式一：检查success字段
if (Boolean.TRUE.equals(response.getSuccess())) {
// 成功处理
CreateLogisticsOrderResponse result = response.getResult();
// 使用result数据...
} else {
// 失败处理
String errorCode = response.getCode();
String errorMsg = response.getErrorMsg();
System.err.println("请求失败，错误码：" + errorCode + "，错误信息：" + errorMsg);
}
// 方式二：检查state字段
if ("success".equals(response.getState())) {
// 成功处理
} else {
// 失败处理
String errorMsg = response.getErrorMsg();
System.err.println("请求失败：" + errorMsg);
}
// 方式三：调用isSuccess()方法
if (response.isSuccess()) {
// 成功处理
} else {
// 失败处理
}
1.8.2. 异常处理
try {
OpenApiResponse<CreateLogisticsOrderResponse> response = client.createOrder(request);
// 处理响应...
} catch (IllegalArgumentException e) {
// 配置错误
System.err.println("配置错误：" + e.getMessage());
} catch (RuntimeException e) {
// 网络或其他错误
System.err.println("请求失败：" + e.getMessage());
e.printStackTrace();
} catch (Exception e) {
// 其他异常
System.err.println("未知错误：" + e.getMessage());
e.printStackTrace();
}
1.9. 完整示例
1.9.1. 示例1：完整的创建物流订单流程
import com.best.open.platform.sdk.client.QlinkLogisticsClient;
import com.best.open.platform.sdk.config.QlinkBaseConfig;
import com.best.open.platform.common.vo.req.openapi.qlink.logistics.QlinkLogisticsRequest;
import com.best.open.platform.common.vo.qlink.request.CreateLogisticsOrderRequest;
import com.best.open.platform.common.vo.qlink.response.CreateLogisticsOrderResponse;
import com.best.open.platform.common.vo.res.openapi.temu.OpenApiResponse;
public class LogisticsSDKExample {
public static void main(String[] args) {
// 1. 初始化配置
QlinkBaseConfig config = new QlinkBaseConfig(
"https://api.example.com",
"your-app-key",
"your-app-secret"
);
config.setEnableLog(true); // 开启日志
// 2. 创建客户端
QlinkLogisticsClient client = new QlinkLogisticsClient(config);
// 3. 构建请求
QlinkLogisticsRequest<CreateLogisticsOrderRequest> request =
new QlinkLogisticsRequest<>();
request.setMethod("createOrder");
CreateLogisticsOrderRequest content = new CreateLogisticsOrderRequest();
content.setLogisticsType("QLINK");
content.setCustomerNumber("CUST001");
content.setOnlineOrderId("ORDER_20231201_001");
content.setChannelCode("YANWEN");
// 设置收件人地址
AddressVO recipientAddress = new AddressVO();
recipientAddress.setName("张三");
recipientAddress.setPhone("13800138000");
recipientAddress.setCountry("中国");
recipientAddress.setProvince("广东省");
recipientAddress.setCity("深圳市");
recipientAddress.setDistrict("南山区");
recipientAddress.setAddress("科技园");
content.setRecipientAddress(recipientAddress);
// 设置其他参数...
request.setContent(content);
// 4. 发送请求
try {
OpenApiResponse<CreateLogisticsOrderResponse> response =
client.createOrder(request);
// 5. 处理响应
if (Boolean.TRUE.equals(response.getSuccess())) {
CreateLogisticsOrderResponse result = response.getResult();
System.out.println("创建成功！");
System.out.println("物流跟踪号：" + result.getTrackingNumber());
} else {
System.err.println("创建失败：" + response.getErrorMsg());
}
} catch (Exception e) {
System.err.println("请求异常：" + e.getMessage());
e.printStackTrace();
}
}
}
1.9.2. 示例2：自定义请求头
Map<String, String> headers = new HashMap<>();
headers.put("logisticsType", "QLINK");
headers.put("appKey", "your-app-key");
headers.put("sign", "custom-signature");
headers.put("accessToken", "token-value");
headers.put("refreshToken", "refresh-value");
headers.put("authInfo", "{\"key\":\"value\"}");
headers.put("apiUrl", "https://provider.example.com");
QlinkLogisticsRequest<CreateLogisticsOrderRequest> request =
new QlinkLogisticsRequest<>();
request.setMethod("createOrder");
CreateLogisticsOrderRequest content = new CreateLogisticsOrderRequest();
// 设置业务参数...
request.setContent(content);
// 使用自定义请求头调用
OpenApiResponse<CreateLogisticsOrderResponse> response =
client.createOrder(request, headers);
1.10. 网关路径说明
SDK自动调用以下网关路径：
| 功能 | 网关路径 |
|---|---|
| 创建物流订单 | /global-api/v1/logistics/create-order |
| 取消物流订单 | /global-api/v1/logistics/cancelOrder |
| 获取面单数据 | /global-api/v1/logistics/getLabelData |
| 获取物流轨迹 | /global-api/v1/logistics/getTrackingInfo |
| 初始化物流渠道 | /global-api/v1/logistics/initLogisticsChannels |
| 授权 | /global-api/v1/auth/authorize |
| 取消授权 | /global-api/v1/auth/unauthorize |
1.11. 签名机制
SDK自动生成请求签名，签名算法如下：
// 签名内容 = SHA1(JSON.stringify({appKey: xxx, content: xxx}) + appSecret)
String signContent = JSON.toJSONString(signMap) + appSecret;
String sign = DigestUtils.sha1Hex(signContent);
签名过程由SDK自动完成，无需手动处理。
1.12. 版本与依赖
- SDK版本：1.0.6-SNAPSHOT
- 最低JDK版本：JDK 8+
- 推荐JDK版本：JDK 11+
1.13. 常见问题
1.13.1. 1. 如何处理配置错误？
try {
QlinkLogisticsClient client = new QlinkLogisticsClient(config);
} catch (IllegalArgumentException e) {
// 配置无效，检查baseUrl、appKey和appSecret是否正确
System.err.println("配置错误：" + e.getMessage());
}
1.13.2. 2. 如何启用日志？
QlinkBaseConfig config = new QlinkBaseConfig(...);
config.setEnableLog(true); // 启用日志
// 确保项目中有slf4j实现（如logback）
1.13.3. 3. 如何自定义超时时间？
QlinkBaseConfig config = new QlinkBaseConfig(...);
config.setConnectTimeout(10000); // 连接超时10秒
config.setReadTimeout(60000); // 读取超时60秒
1.13.4. 4. 如何实现重试机制？
SDK默认支持重试机制（可配置）：
QlinkBaseConfig config = new QlinkBaseConfig(...);
config.setRetryCount(3); // 重试3次
config.setRetryInterval(1000); // 重试间隔1秒
1.13.5. 5. 是否需要手动设置sign？
不需要。SDK会自动生成sign，无需手动设置。
1.13.6. 6. 如何处理网络异常？
try {
OpenApiResponse<CreateLogisticsOrderResponse> response = client.createOrder(request);
} catch (RuntimeException e) {
if (e.getMessage().contains("Connection")) {
System.err.println("网络连接失败，请检查网络");
} else if (e.getMessage().contains("Timeout")) {
System.err.println("请求超时，请重试");
} else {
System.err.println("请求失败：" + e.getMessage());
}
}
1.14. 技术支持
如有问题，请联系：
- 文档中心：https://open.qianyierp.com
- 更新日期：2025-01-27