1. ISV仓库对接SDK

1.1. 概述

QLink SDK 提供了调用 GlobalWarehouseController 所有方法的客户端SDK，支持仓库管理的各种操作。该SDK采用现代化的设计模式，支持两种调用方式：自动生成请求头和自定义请求头。

1.2. 主要功能

1.2.1. QlinkWarehouseClient

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

  1. 仓库初始化

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

  2. 订单管理

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

  3. 库存管理

    • 库存同步

  4. 入库单管理

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

  5. 商品管理

    • 商品下发仓库

1.3. 核心特性

1.3.1. 双重调用方式

每个API方法都支持两种调用方式：

  1. 方式1: 自动生成请求头

    // 自动从请求对象中提取warehouseType，并生成appKey和sign
client.methodName(request);

  2. 方式2: 自定义请求头

    // 完全自定义请求头
Map<String, String> customHeaders = new HashMap<>();
customHeaders.put("warehouseType", "LINGXING");
customHeaders.put("appKey", "1");
customHeaders.put("Content-Type", "application/json");
client.methodName(request, customHeaders);

1.3.2. 智能请求头管理

  • 自动从请求对象中提取 warehouseType 字段
  • 自动生成 appKey 和 sign 签名
  • 支持完全自定义请求头覆盖

1.4. 快速开始

1.4.1. 添加依赖

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

1.4.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.4.3. 使用示例

初始化仓库列表

// 构建请求对象
WarehouseInitRequest request = new WarehouseInitRequest();
List<String> warehouseKeys = new ArrayList<>();
warehouseKeys.add("afd1dd995b9e432c907d3f8237b3f69b");
request.setWarehouseType("LINGXING");

// 方式1: 使用默认请求头（自动生成appKey和sign）
QlinkWarehouseResponse<WarehouseInitResponse> response = client.initWarehouses(request);

// 方式2: 自定义请求头
Map<String, String> customHeaders = new HashMap<>();
customHeaders.put("warehouseType", "LINGXING");
customHeaders.put("appKey", "1");
customHeaders.put("Content-Type", "application/json");

QlinkWarehouseResponse<WarehouseInitResponse> response = client.initWarehouses(request, customHeaders);

创建仓库订单

WarehouseCreateOrderRequest request = new WarehouseCreateOrderRequest();
request.setWarehouseKey("afd1dd995b9e432c907d3f8237b3f69b");
request.setWarehouseCode("TU02");
request.setOrderNumber("UNU250822163403");
request.setOnlineOrderId("UNU250822163403");
request.setShopName("测试店铺");
request.setLogisticsCode("UPS-1");
request.setPlatform("SHEIN");
request.setFreight(new BigDecimal("0.0"));
request.setCodEnabled(1);
request.setCodPayAmount(new BigDecimal("1"));
request.setCodCurrency("USD");
request.setWarehouseType("LINGXING");

// 设置收件人信息
WarehouseCreateOrderRequest.Receiver receiver = new WarehouseCreateOrderRequest.Receiver();
receiver.setName("测试");
receiver.setPhone("13131313131");
receiver.setCountry("CN");
receiver.setState("黑龙江省");
receiver.setCity("双鸭山市");
receiver.setAddress1("测试街道地址");
receiver.setPostalCode("211300");
request.setReceiver(receiver);

// 设置商品信息
List<WarehouseCreateOrderRequest.SkuInfo> skuList = new ArrayList<>();
WarehouseCreateOrderRequest.SkuInfo skuInfo = new WarehouseCreateOrderRequest.SkuInfo();
skuInfo.setSku("SKU1");
skuInfo.setName("soges Side Table Moving Unite Laptop Desk Small Computer Table with Caster, Black KH02-BK");
skuInfo.setQuantity("1");
skuInfo.setAmount(new BigDecimal("0.0"));
skuList.add(skuInfo);
request.setSkuList(skuList);

// 方式1: 使用默认请求头
QlinkWarehouseResponse<WarehouseCreateOrderResponse> response = client.createOrder(request);

// 方式2: 自定义请求头
Map<String, String> customHeaders = new HashMap<>();
customHeaders.put("warehouseType", "LINGXING");
customHeaders.put("appKey", "1");
customHeaders.put("Content-Type", "application/json");

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

查询仓库订单

WarehouseGetOrderRequest request = new WarehouseGetOrderRequest();
request.setWarehouseCode("TU02");
request.setWarehouseKey("afd1dd995b9e432c907d3f8237b3f69b");

// 设置订单信息列表
List<WarehouseGetOrderRequest.GetOrderInfo> orderInfoList = new ArrayList<>();
WarehouseGetOrderRequest.GetOrderInfo orderInfo = new WarehouseGetOrderRequest.GetOrderInfo();
orderInfo.setOrderNumber("UNU250822163403");
orderInfo.setWarehouseOrderNumber("UNU250822163403");
orderInfoList.add(orderInfo);
request.setGetOrderInfoList(orderInfoList);

// 方式1: 使用默认请求头
QlinkWarehouseResponse<WarehouseGetOrderResponse> response = client.getOrder(request);

// 方式2: 自定义请求头
Map<String, String> customHeaders = new HashMap<>();
customHeaders.put("warehouseType", "LINGXING");
customHeaders.put("appKey", "1");
customHeaders.put("Content-Type", "application/json");

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

创建入库单

WarehouseCreateAsnOrderRequest request = new WarehouseCreateAsnOrderRequest();
request.setWarehouseKey("afd1dd995b9e432c907d3f8237b3f69b");
request.setAsnNumber("A250828163429");
request.setWarehouseCode("TU02");
request.setCustomNumber("");
request.setEstimatedArrivalDate(1692086400000L);
request.setTrackNumber("");
request.setType("MANUAL");
request.setWarehouseType("LINGXING");

// 设置商品信息
List<WarehouseCreateAsnOrderRequest.SkuInfo> skuList = new ArrayList<>();
WarehouseCreateAsnOrderRequest.SkuInfo skuInfo = new WarehouseCreateAsnOrderRequest.SkuInfo();
skuInfo.setSku("SKU1");
skuInfo.setName("soges Side Table Moving Unite Laptop Desk Small Computer Table with Caster, Black KH02-BK");
skuInfo.setQuantity(1L);
skuList.add(skuInfo);
request.setSkuList(skuList);

// 设置装箱信息
List<WarehouseCreateAsnOrderRequest.AsnMarkSku> asnMarkSkuList = new ArrayList<>();
WarehouseCreateAsnOrderRequest.AsnMarkSku asnMarkSku = new WarehouseCreateAsnOrderRequest.AsnMarkSku();
asnMarkSku.setBoxNumber(1L);
asnMarkSku.setMarkCode("BOX001-1-1");
asnMarkSku.setQuantity(1L);
asnMarkSku.setSku("SKU1");
asnMarkSku.setName("soges Side Table Moving Unite Laptop Desk Small Computer Table with Caster, Black KH02-BK");
asnMarkSku.setLength(new BigDecimal("20.0"));
asnMarkSku.setWidth(new BigDecimal("19.1"));
asnMarkSku.setHeight(new BigDecimal("20.1"));
asnMarkSkuList.add(asnMarkSku);
request.setAsnMarkSku(asnMarkSkuList);

// 方式1: 使用默认请求头
QlinkWarehouseResponse<WarehouseCreateAsnOrderResponse> response = client.createAsnOrder(request);

// 方式2: 自定义请求头
Map<String, String> customHeaders = new HashMap<>();
customHeaders.put("warehouseType", "LINGXING");
customHeaders.put("appKey", "1");
customHeaders.put("Content-Type", "application/json");

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

1.5. API 接口说明

1.5.1. 初始化仓库列表

方法: initWarehouses(WarehouseInitRequest request, Map<String, String> headers)

参数:

  • request: 初始化仓库请求对象
  • headers: 自定义请求头（可选）

返回: QlinkWarehouseResponse<WarehouseInitResponse>

1.5.2. 初始化仓库物流渠道

方法: initChannels(ChannelInitRequest request, Map<String, String> headers)

参数:

  • request: 渠道初始化请求对象
  • headers: 自定义请求头（可选）

返回: QlinkWarehouseResponse<WarehouseInitChannelsResponse>

1.5.3. 创建仓库订单

方法: createOrder(WarehouseCreateOrderRequest request, Map<String, String> headers)

参数:

  • request: 创建订单请求对象
  • headers: 自定义请求头（可选）

返回: QlinkWarehouseResponse<WarehouseCreateOrderResponse>

1.5.4. 查询仓库订单

方法: getOrder(WarehouseGetOrderRequest request, Map<String, String> headers)

参数:

  • request: 查询订单请求对象
  • headers: 自定义请求头（可选）

返回: QlinkWarehouseResponse<WarehouseGetOrderResponse>

1.5.5. 取消仓库订单

方法: cancelOrder(WarehouseCancelOrderRequest request, Map<String, String> headers)

参数:

  • request: 取消订单请求对象
  • headers: 自定义请求头（可选）

返回: QlinkWarehouseResponse<WarehouseCancelOrderResponse>

1.5.6. 库存同步

方法: syncInventory(WarehouseSyncInventoryRequest request, Map<String, String> headers)

参数:

  • request: 库存同步请求对象
  • headers: 自定义请求头（可选）

返回: QlinkWarehouseResponse<WarehouseSyncInventoryResponse>

1.5.7. 创建入库单

方法: createAsnOrder(WarehouseCreateAsnOrderRequest request, Map<String, String> headers)

参数:

  • request: 创建入库单请求对象
  • headers: 自定义请求头（可选）

返回: QlinkWarehouseResponse<WarehouseCreateAsnOrderResponse>

1.5.8. 查询入库单列表

方法: getAsnList(WarehouseGetAsnListRequest request, Map<String, String> headers)

参数:

  • request: 查询入库单请求对象
  • headers: 自定义请求头（可选）

返回: QlinkWarehouseResponse<WarehouseGetAsnListResponse>

1.5.9. 取消入库单

方法: cancelAsnOrder(WarehouseCancelAsnOrderRequest request, Map<String, String> headers)

参数:

  • request: 取消入库单请求对象
  • headers: 自定义请求头（可选）

返回: QlinkWarehouseResponse<WarehouseCancelAsnOrderResponse>

1.5.10. 商品下发仓库

方法: insertSkuInfo(WarehouseInsertSkuInfoRequest request, Map<String, String> headers)

参数:

  • request: 商品信息请求对象
  • headers: 自定义请求头（可选）

返回: QlinkWarehouseResponse<WarehouseInsertSkuInfoResponse>

1.6. 配置说明

1.6.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.6.2. 环境配置

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

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

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

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

1.7. 错误处理

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

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

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

1.8. 技术特性

1.8.1. 签名算法

SDK 使用SHA1签名算法，自动生成 sign 请求头：

private String generateSign(Object request) {
    // 构建待签名的JSON字符串
    Map<String, Object> signMap = new HashMap<>();
    signMap.put("appKey", config.getAppKey());
    if (request != null) {
        signMap.put("content", JSON.toJSONString(request));
    }
    String jsonStr = JSON.toJSONString(signMap);

    // 添加appSecret到末尾
    String signContent = jsonStr + config.getAppSecret();

    // 使用SHA1加密生成签名
    return org.apache.commons.codec.digest.DigestUtils.sha1Hex(signContent);
}

1.8.2. HTTP 配置

SDK 使用 Apache HttpClient 发送请求，支持配置超时时间等参数。

1.8.3. 日志配置

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

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

1.9. 注意事项

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

1.10. 完整示例

参考 QlinkWarehouseClientExample.java 文件，其中包含了所有API的完整使用示例，演示了两种调用方式的使用方法。

1.11. 技术支持

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

© Copyright QianYi Team 2025 All Rights Reserved            Updated 2025-09-29 04:26:14

results matching ""

    No results matching ""