Infilake OpenAPI Java SDK - README

完整的Java SDK，融合了HMAC-SHA256认证和API调用功能

📦 版本信息

最新版本: 1.5.2 推荐
JDK要求: Java 8+
依赖: Jackson 2.16.1 (JSON处理)
JAR包大小: 78KB

✨ 主要特性

1. 认证功能 (AuthSDK)

✅ HMAC-SHA256签名生成
✅ 自动时间戳生成（UTC格式）
✅ 支持所有HTTP方法（GET, POST, PUT, DELETE等）
✅ Base64编码的签名输出

2. API客户端 (ApiClient)

✅ 内置认证支持
✅ 自动添加认证头（X-Access-Key, X-Timestamp, X-Authorization）
✅ 支持GET/POST/PUT/DELETE请求
✅ 查询参数自动编码
✅ JSON请求体支持
✅ 可配置超时设置

3. 采购平台API客户端 (BiddingApiClient)

✅ 订单API - 9个方法（分页查询、详情、履约、物流、退货、客户端申请单号查询等）
✅ 项目API - 2个方法（分页查询、详情）
✅ 采购申请API - 4个方法（导入、更新、对象参数支持）
✅ 物料API - 6个方法（创建、更新、删除、对象参数支持）
✅ 类别API - 6个方法（分页查询、创建、更新、删除）
✅ 结算单API - 3个方法（分页查询、下载发票、查询发票）
✅ 仓库API - 1个方法（仓库列表查询）
✅ 用户档案API - 1个方法（获取用户档案）
✅ 总计: 33个API方法全部封装

4. 异常处理体系 (v1.5.2新增)

✅ BiddingApiException - 所有API异常的基类
✅ UnauthorizedException (20401) - 认证失败
✅ ParamErrorException (20402) - 参数错误
✅ InternalErrorException (20500) - 服务器内部错误
✅ DataConflictException (20501) - 数据冲突
✅ DataNotFoundException (20502) - 数据不存在

🚀 快速开始

安装SDK

方式一：直接引用JAR包

# 编译时引用
javac -cp infilake-openapi-sdk-1.5.2.jar YourApp.java

# 运行时引用 (Windows)
java -cp "infilake-openapi-sdk-1.5.2.jar;." YourApp

# 运行时引用 (macOS/Linux)
java -cp "infilake-openapi-sdk-1.5.2.jar:." YourApp

基础使用示例

import com.infilake.openapi.BiddingApiClient;

public class Example {
    public static void main(String[] args) throws Exception {
        // 创建采购平台API客户端
        BiddingApiClient client = new BiddingApiClient(
            "https://api.example.com",
            "your-access-key",
            "your-secret-key"
        );

        // 查询订单
        String orders = client.getOrderPage(1, 10, "approved", null, null, null, null);
        System.out.println(orders);

        // 查询项目列表
        String projects = client.getProjectPage(1, 10, null, null, null);
        System.out.println(projects);
    }
}

📖 API方法列表

订单API（6个方法）

getOrderPage() - 订单分页查询
getOrderDetail(orderNo) - 订单详情
getOrderFulfillment(fulfillmentNo) - 订单履约详情
getOrderExpress(fulfillmentNo) - 物流信息查询
getOrderReturnPage() - 退货分页查询
getOrderReturnDetail(returnNo) - 退货详情

项目API（2个方法）

getProjectPage() - 项目分页查询
getProjectDetail(projectId) - 项目详情

采购申请API（2个方法）

importPurchaseApplication(jsonBody) - 导入采购申请
updatePurchaseApplication(clientApplicationNo, jsonBody) - 更新采购申请

物料API（3个方法）

createProduct(jsonBody) - 创建物料
updateProduct(productCode, jsonBody) - 更新物料
deleteProduct(productCode) - 删除物料

结算单API（3个方法）

getSettlementPage() - 结算单分页查询
downloadInvoice(settlementNo) - 下载发票
queryInvoice(settlementNo) - 查询发票

仓库API（1个方法）

getWarehousePage() - 仓库列表查询

🔐 签名算法说明

SDK使用HMAC-SHA256算法生成签名，流程如下：

生成时间戳: 格式为 YYYYMMDDTHHMMSSZ（UTC时间）
构建待签名字符串: {HTTP方法}\n{请求路径}\n{时间戳}\n
计算HMAC-SHA256签名: 使用Secret Key对字符串签名
Base64编码: 将签名结果进行Base64编码

⚙️ 高级配置

自定义超时设置

ApiClient client = new ApiClient(baseUrl, accessKey, secretKey);

// 设置连接超时（毫秒）
client.setConnectTimeout(15000);  // 15秒

// 设置读取超时（毫秒）
client.setReadTimeout(20000);     // 20秒

⚠️ 注意事项

时间同步: 确保客户端时间准确，时间戳偏差过大会导致认证失败
密钥安全: 妥善保管Secret Key，不要提交到代码仓库
URL路径: 签名时使用的路径必须与实际请求路径完全一致
HTTP方法: 方法必须大写（GET, POST, PUT, DELETE等）
字符编码: SDK统一使用UTF-8编码

📞 支持与反馈

如有问题或建议，请联系技术支持团队。