1. Qlink Warehouse SDK

1.1. 概述

Qlink Warehouse SDK 提供了调用 GlobalWarehouseController 所有方法的客户端SDK，支持仓库管理的各种操作。

1.2. 主要功能

1.2.1. QlinkWarehouseClient

QlinkWarehouseClient 是仓库管理的主要SDK客户端，提供以下功能：

  1. 仓库初始化

    • 初始化仓库列表
    • 初始化仓库物流渠道列表

  2. 订单管理

    • 创建仓库订单
    • 查询仓库订单
    • 取消仓库订单

  3. 库存管理

    • 库存同步

  4. 入库单管理

    • 创建入库单
    • 查询入库单列表
    • 取消入库单

  5. 商品管理

    • 商品下发仓库

1.3. 快速开始

1.3.1. 添加依赖

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

1.3.2. 初始化客户端

方式1: 直接创建

String baseUrl = "http://localhost:8080"; // API服务地址
String appKey = "your-app-key"; // 应用密钥
String appSecret = "your-app-secret"; // 应用密钥

QlinkWarehouseClient client = new QlinkWarehouseClient(baseUrl, appKey, appSecret);

方式2: 使用工厂类

// 开发环境
QlinkWarehouseClient client = QlinkWarehouseClientFactory.createDevClient(appKey, appSecret);

// 测试环境
QlinkWarehouseClient client = QlinkWarehouseClientFactory.createTestClient(appKey, appSecret);

// 生产环境
QlinkWarehouseClient client = QlinkWarehouseClientFactory.createProdClient(appKey, appSecret);

// 自定义环境
QlinkWarehouseClient client = QlinkWarehouseClientFactory.createClientByEnvironment("dev", appKey, appSecret);

方式3: 使用配置类

// 创建配置
QlinkWarehouseConfig config = QlinkWarehouseConfig.createDevConfig(appKey, appSecret);
QlinkWarehouseClient client = new QlinkWarehouseClient(config);

// 或者使用工厂类
QlinkWarehouseClient client = QlinkWarehouseClientFactory.createClient(config);

方式4: 自定义配置

// 创建自定义配置客户端
QlinkWarehouseClient client = QlinkWarehouseClientFactory.createCustomClient(
    baseUrl, appKey, appSecret, 5000, 30000, true);

1.3.3. 使用示例

初始化仓库列表

List<String> warehouseKeys = Arrays.asList("WH001", "WH002");
QlinkWarehouseResponse<WarehouseInitResponse> response = client.initWarehouses(warehouseKeys);

if (response.isSuccess()) {
    System.out.println("初始化成功: " + response.getResult());
} else {
    System.err.println("初始化失败: " + response.getErrorMsg());
}

创建仓库订单

WarehouseCreateOrderRequest request = new WarehouseCreateOrderRequest();
request.setWarehouseKey("WH001");
request.setOrderNumber("ORD123456");
request.setOnlineOrderId("ONLINE123456");
request.setShopName("测试店铺");
request.setWarehouseCode("WH001");
request.setLogisticsCode("LOG001");
request.setPlatform("TEMU");
request.setFreight(new BigDecimal("10.00"));

// 设置收件人信息
WarehouseCreateOrderRequest.Receiver receiver = new WarehouseCreateOrderRequest.Receiver();
receiver.setName("张三");
receiver.setPhone("13800138000");
receiver.setEmail("zhangsan@example.com");
receiver.setCountry("CN");
receiver.setState("北京");
receiver.setCity("北京");
receiver.setDistrict("朝阳区");
receiver.setAddress1("测试地址1");
receiver.setPostalCode("100000");
request.setReceiver(receiver);

// 设置商品信息
List<WarehouseCreateOrderRequest.SkuInfo> skuList = new ArrayList<>();
WarehouseCreateOrderRequest.SkuInfo skuInfo = new WarehouseCreateOrderRequest.SkuInfo();
skuInfo.setSku("SKU001");
skuInfo.setErpSku("ERP001");
skuInfo.setName("测试商品");
skuInfo.setQuantity("2");
skuInfo.setAmount(new BigDecimal("99.99"));
skuList.add(skuInfo);
request.setSkuList(skuList);

QlinkWarehouseResponse<WarehouseCreateOrderResponse> response = client.createOrder(request);

查询仓库订单

WarehouseGetOrderRequest request = new WarehouseGetOrderRequest();
request.setOrderNumber("ORD123456");
request.setWarehouseCode("WH001");

QlinkWarehouseResponse<WarehouseGetOrderResponse> response = client.getOrder(request);

取消仓库订单

WarehouseCancelOrderRequest request = new WarehouseCancelOrderRequest();
request.setOrderNumber("ORD123456");
request.setWarehouseCode("WH001");
request.setCancelReason("用户取消");

QlinkWarehouseResponse<WarehouseCancelOrderResponse> response = client.cancelOrder(request);

创建入库单

WarehouseCreateAsnOrderRequest request = new WarehouseCreateAsnOrderRequest();
request.setWarehouseKey("WH001");
request.setAsnNumber("ASN123456");
request.setWarehouseCode("WH001");
request.setCustomNumber("REF123456");
request.setEstimatedArrivalDate(System.currentTimeMillis());
request.setTrackNumber("TRACK123456");
request.setType("NORMAL");

// 设置商品信息
List<WarehouseCreateAsnOrderRequest.SkuInfo> skuList = new ArrayList<>();
WarehouseCreateAsnOrderRequest.SkuInfo skuInfo = new WarehouseCreateAsnOrderRequest.SkuInfo();
skuInfo.setSku("SKU001");
skuInfo.setName("测试商品");
skuInfo.setQuantity(100L);
skuList.add(skuInfo);
request.setSkuList(skuList);

QlinkWarehouseResponse<WarehouseCreateAsnOrderResponse> response = client.createAsnOrder(request);

商品下发仓库

WarehouseInsertSkuInfoRequest request = new WarehouseInsertSkuInfoRequest();
request.setWarehouseKey("WH001");
request.setWarehouseCode("WH001");
request.setSku("SKU001");
request.setErpSku("ERP001");
request.setTitle("测试商品");
request.setBarcode("123456789");
request.setSpecifications("规格信息");
request.setImageUrl("http://example.com/image.jpg");
request.setWeight(new BigDecimal("0.5"));
request.setNetWeight(new BigDecimal("0.4"));
request.setWeightUnit("KG");
request.setLength(new BigDecimal("10"));
request.setWidth(new BigDecimal("5"));
request.setHeight(new BigDecimal("3"));
request.setDimensionUnit("CM");
request.setItemPackage(1);

QlinkWarehouseResponse<WarehouseInsertSkuInfoResponse> response = client.insertSkuInfo(request);

1.4. 配置说明

1.4.1. QlinkWarehouseConfig

配置类提供了灵活的配置选项：

QlinkWarehouseConfig config = new QlinkWarehouseConfig();
config.setBaseUrl("http://localhost:8080");
config.setAppKey("your-app-key");
config.setAppSecret("your-app-secret");
config.setConnectTimeout(5000);        // 连接超时时间（毫秒）
config.setReadTimeout(30000);          // 读取超时时间（毫秒）
config.setEnableLog(true);             // 是否启用日志
config.setRetryCount(3);              // 重试次数
config.setRetryInterval(1000);        // 重试间隔（毫秒）

QlinkWarehouseClient client = new QlinkWarehouseClient(config);

1.4.2. 环境配置

SDK提供了预定义的环境配置：

// 开发环境配置
QlinkWarehouseConfig devConfig = QlinkWarehouseConfig.createDevConfig(appKey, appSecret);

// 测试环境配置
QlinkWarehouseConfig testConfig = QlinkWarehouseConfig.createTestConfig(appKey, appSecret);

// 生产环境配置
QlinkWarehouseConfig prodConfig = QlinkWarehouseConfig.createProdConfig(appKey, appSecret);

1.5. API 接口说明

1.5.1. 初始化仓库列表

方法: initWarehouses(List<String> warehouseKeys)

参数:

  • warehouseKeys: 仓库key数组

返回: QlinkWarehouseResponse<WarehouseInitResponse>

1.5.2. 初始化仓库物流渠道

方法: initChannels(List<String> warehouseKeys, String warehouseCode)

参数:

  • warehouseKeys: 仓库key数组
  • warehouseCode: 仓库编码

返回: QlinkWarehouseResponse<WarehouseInitChannelsResponse>

1.5.3. 创建仓库订单

方法: createOrder(WarehouseCreateOrderRequest createOrderRequest)

参数:

  • createOrderRequest: 创建订单请求对象

返回: QlinkWarehouseResponse<WarehouseCreateOrderResponse>

1.5.4. 查询仓库订单

方法: getOrder(WarehouseGetOrderRequest getOrderRequest)

参数:

  • getOrderRequest: 查询订单请求对象

返回: QlinkWarehouseResponse<WarehouseGetOrderResponse>

1.5.5. 取消仓库订单

方法: cancelOrder(WarehouseCancelOrderRequest cancelOrderRequest)

参数:

  • cancelOrderRequest: 取消订单请求对象

返回: QlinkWarehouseResponse<WarehouseCancelOrderResponse>

1.5.6. 库存同步

方法: syncInventory(WarehouseSyncInventoryRequest syncInventoryRequest)

参数:

  • syncInventoryRequest: 库存同步请求对象

返回: QlinkWarehouseResponse<WarehouseSyncInventoryResponse>

1.5.7. 创建入库单

方法: createAsnOrder(WarehouseCreateAsnOrderRequest createAsnOrderRequest)

参数:

  • createAsnOrderRequest: 创建入库单请求对象

返回: QlinkWarehouseResponse<WarehouseCreateAsnOrderResponse>

1.5.8. 查询入库单列表

方法: getAsnList(WarehouseGetAsnListRequest getAsnListRequest)

参数:

  • getAsnListRequest: 查询入库单请求对象

返回: QlinkWarehouseResponse<WarehouseGetAsnListResponse>

1.5.9. 取消入库单

方法: cancelAsnOrder(WarehouseCancelAsnOrderRequest cancelAsnOrderRequest)

参数:

  • cancelAsnOrderRequest: 取消入库单请求对象

返回: QlinkWarehouseResponse<WarehouseCancelAsnOrderResponse>

1.5.10. 商品下发仓库

方法: insertSkuInfo(WarehouseInsertSkuInfoRequest insertSkuInfoRequest)

参数:

  • insertSkuInfoRequest: 商品信息请求对象

返回: QlinkWarehouseResponse<WarehouseInsertSkuInfoResponse>

1.6. 错误处理

所有方法都会返回 QlinkWarehouseResponse<T> 对象，包含以下字段：

  • success: 是否成功
  • code: 响应代码
  • errorMsg: 错误信息
  • result: 响应结果
QlinkWarehouseResponse<WarehouseInitResponse> response = client.initWarehouses(warehouseKeys);

if (response.isSuccess()) {
    // 处理成功响应
    WarehouseInitResponse result = response.getResult();
    // ...
} else {
    // 处理错误
    String errorMsg = response.getErrorMsg();
    String code = response.getCode();
    // ...
}

1.7. 配置说明

1.7.1. 签名算法

SDK 使用简单的签名算法，可以根据实际需求修改 generateSign 方法：

private String generateSign(QlinkWarehouseRequest<?> request) {
    // 自定义签名算法
    String signContent = request.getAppKey() + request.getMethod() + 
                        JSON.toJSONString(request.getContent()) + appSecret;
    return java.util.Base64.getEncoder().encodeToString(signContent.getBytes());
}

1.7.2. HTTP 配置

SDK 使用 Apache HttpClient 发送请求，可以通过修改 HttpUtil 来调整超时时间等配置。

1.7.3. 日志配置

可以通过配置类控制日志输出：

QlinkWarehouseConfig config = new QlinkWarehouseConfig();
config.setEnableLog(true);  // 启用详细日志
config.setEnableLog(false); // 关闭详细日志

1.8. 注意事项

  1. 安全性: 请妥善保管 appKey 和 appSecret，不要泄露给第三方
  2. 网络: 确保网络连接正常，SDK 会处理网络异常
  3. 日志: SDK 会记录详细的请求和响应日志，便于调试
  4. 版本: 请使用与服务器端匹配的SDK版本
  5. 配置: 建议使用配置类来管理SDK的配置参数
  6. 工厂类: 推荐使用工厂类来创建客户端，更加便捷和安全

1.9. 完整示例

参考 QlinkWarehouseClientExample.java 文件，其中包含了所有API的完整使用示例。

1.10. 技术支持

如有问题，请联系开发团队或查看项目文档。

© Copyright QianYi Team 2025 All Rights Reserved            Updated 2025-08-13 07:32:45

results matching ""

    No results matching ""