1. Open Platform SDK - 物流客户端使用文档（QlinkLogisticsClient）

1.1. 概述

QlinkLogisticsClient 对接网关 GlobalLogisticsController，提供：

• 创建物流订单（create-order）
• 取消物流订单（cancelOrder）
• 获取面单数据（getLabelData）
• 获取轨迹信息（getTrackingInfo）
• 初始化物流渠道（initLogisticsChannels）

两种调用方式：

• 默认请求头：自动从 request.content.logisticsType 提取 logisticsType，自动填充 appKey、sign
• 自定义请求头：可传入 logisticsType、secret、accessToken、refreshToken、authInfo、apiUrl 等透传

统一返回：com.best.open.platform.common.vo.res.openapi.temu.OpenApiResponse<T>

1.2. 依赖

<dependency>
    <groupId>com.800best</groupId>
    <artifactId>open-platform-sdk</artifactId>
    <version>1.0.6-SNAPSHOT</version>
</dependency>

1.3. 初始化

import com.best.open.platform.sdk.client.QlinkLogisticsClient;
import com.best.open.platform.sdk.config.QlinkWarehouseConfig;

String appKey = "your-app-key";
String appSecret = "your-app-secret";

// 预设环境
QlinkWarehouseConfig config = QlinkWarehouseConfig.createDevConfig(appKey, appSecret);
QlinkLogisticsClient client = new QlinkLogisticsClient(config);

// 自定义基础地址
QlinkLogisticsClient custom = new QlinkLogisticsClient("http://localhost:8080", appKey, appSecret);

1.4. 请求与响应

• 请求：com.best.open.platform.common.vo.req.openapi.qlink.logistics.QlinkLogisticsRequest<T>
  • 关键：method、appKey、sign、content
• 响应：com.best.open.platform.common.vo.res.openapi.temu.OpenApiResponse<T>
  • 常用：success、code、errorMsg、result

1.5. 调用方式

1.5.1. 默认请求头

QlinkLogisticsRequest<CreateLogisticsOrderRequest> req = new QlinkLogisticsRequest<>();
req.setMethod("createOrder");
req.setAppKey(config.getAppKey());

CreateLogisticsOrderRequest content = new CreateLogisticsOrderRequest();
content.setLogisticsType("QLINK");
// TODO: 设置其它必填字段
req.setContent(content);

OpenApiResponse<CreateLogisticsOrderResponse> res = client.createOrder(req);

1.5.2. 自定义请求头

Map<String, String> headers = new HashMap<>();
headers.put("logisticsType", "QLINK");
headers.put("appKey", config.getAppKey());
headers.put("sign", "custom-sign-or-use-sdk");
headers.put("secret", "xxx");
headers.put("accessToken", "xxx");
headers.put("refreshToken", "xxx");
headers.put("authInfo", "xxx");
headers.put("apiUrl", "https://provider.example");

QlinkLogisticsRequest<GetLabelRequest> req = new QlinkLogisticsRequest<>();
req.setMethod("getLabelData");
GetLabelRequest content = new GetLabelRequest();
content.setLogisticsType("QLINK");
req.setContent(content);

OpenApiResponse<GetLabelResponse> res = client.getLabelData(req, headers);

1.6. 方法示例（默认请求头）

// 1) create-order
QlinkLogisticsRequest<CreateLogisticsOrderRequest> r1 = new QlinkLogisticsRequest<>();
r1.setMethod("createOrder");
CreateLogisticsOrderRequest c1 = new CreateLogisticsOrderRequest();
c1.setLogisticsType("QLINK");
r1.setContent(c1);
OpenApiResponse<CreateLogisticsOrderResponse> a1 = client.createOrder(r1);

// 2) cancelOrder
QlinkLogisticsRequest<CancelLogisticsOrderRequest> r2 = new QlinkLogisticsRequest<>();
r2.setMethod("cancelOrder");
CancelLogisticsOrderRequest c2 = new CancelLogisticsOrderRequest();
c2.setLogisticsType("QLINK");
r2.setContent(c2);
OpenApiResponse<String> a2 = client.cancelOrder(r2);

// 3) getLabelData
QlinkLogisticsRequest<GetLabelRequest> r3 = new QlinkLogisticsRequest<>();
r3.setMethod("getLabelData");
GetLabelRequest c3 = new GetLabelRequest();
c3.setLogisticsType("QLINK");
r3.setContent(c3);
OpenApiResponse<GetLabelResponse> a3 = client.getLabelData(r3);

// 4) getTrackingInfo
QlinkLogisticsRequest<GetTrackingInfoRequest> r4 = new QlinkLogisticsRequest<>();
r4.setMethod("getTrackingInfo");
GetTrackingInfoRequest c4 = new GetTrackingInfoRequest();
c4.setLogisticsType("QLINK");
r4.setContent(c4);
OpenApiResponse<GetTrackingResponse> a4 = client.getTrackingInfo(r4);

// 5) initLogisticsChannels
QlinkLogisticsRequest<InitLogisticsChannelsRequest> r5 = new QlinkLogisticsRequest<>();
r5.setMethod("initLogisticsChannels");
InitLogisticsChannelsRequest c5 = new InitLogisticsChannelsRequest();
c5.setLogisticsType("QLINK");
r5.setContent(c5);
OpenApiResponse<InitLogisticsChannelsResponse> a5 = client.initLogisticsChannels(r5);

1.7. 错误处理

if (res != null && Boolean.TRUE.equals(res.getSuccess())) {
    // 使用 res.getResult()
} else {
    String code = res != null ? res.getCode() : "UNKNOWN";
    String msg = res != null ? res.getErrorMsg() : "empty response";
}

1.8. 网关路径对齐

• /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

1.9. 版本与支持

• 模块：open-platform-sdk
• 建议版本：1.0.6-SNAPSHOT 或以上