ZTK Rust SDK

折淘客 (ZheTaoKe/ZTK) Rust SDK - 多平台电商 API 客户端库

特性

• 类型安全 - 利用 Rust 类型系统在编译时捕获错误
• 模块化 - 各平台独立，支持按需编译
• 易用性 - 链式调用，Builder 模式，清晰的 API
• 异步优先 - 基于 async/await 的异步 API
• 完善文档 - 中文注释，示例代码

支持平台

安装

在 Cargo.toml 中添加依赖：

[dependencies]
ztk-rust-sdk = "0.1"
tokio = { version = "1.0", features = ["rt-multi-thread", "macros"] }

按需启用平台

默认启用 taobao、jd、pdd 三个平台。如需其他平台：

# 启用特定平台
[dependencies]
ztk-rust-sdk = { version = "0.1", features = ["taobao", "jd", "douyin"] }

# 启用所有平台
[dependencies]
ztk-rust-sdk = { version = "0.1", features = ["full"] }

# 只启用淘宝
[dependencies]
ztk-rust-sdk = { version = "0.1", default-features = false, features = ["taobao"] }

快速开始

use ztk_rust_sdk::{ZtkClient, ZtkResult};

#[tokio::main]
async fn main() -> ZtkResult<()> {
    // 创建客户端
    let client = ZtkClient::new("your_appkey")
        .build()?;
    
    println!("客户端创建成功！");
    Ok(())
}

使用示例

淘宝平台

高佣转链 (商品ID)

use ztk_rust_sdk::{ZtkClient, ZtkResult, ConvertByItemIdRequest, TaobaoSignUrlType};

#[tokio::main]
async fn main() -> ZtkResult<()> {
    let client = ZtkClient::new("your_appkey").build()?;
    
    // 方式一：使用结构体
    let request = ConvertByItemIdRequest {
        sid: "your_sid".to_string(),
        pid: "mm_xxx_xxx_xxx".to_string(),
        num_iid: "123456789".to_string(),
        relation_id: Some("your_relation_id".to_string()),
        special_id: None,
        signurl: Some(TaobaoSignUrlType::WithFullDetail),
    };
    
    // 方式二：使用 Builder 模式
    let request = ConvertByItemIdRequest::new("your_sid", "mm_xxx_xxx_xxx", "123456789")
        .relation_id("your_relation_id")
        .signurl(TaobaoSignUrlType::WithFullDetail);
    
    let result = client.taobao().convert_by_item_id(request).await?;
    println!("转链结果: {:?}", result);
    
    Ok(())
}

高佣转链 (淘口令)

use ztk_rust_sdk::{ZtkClient, ZtkResult, ConvertByTklRequest};

#[tokio::main]
async fn main() -> ZtkResult<()> {
    let client = ZtkClient::new("your_appkey").build()?;
    
    let request = ConvertByTklRequest::new(
        "your_sid",
        "mm_xxx_xxx_xxx",
        "【淘口令内容】"
    );
    
    let result = client.taobao().convert_by_tkl(request).await?;
    println!("转链结果: {:?}", result);
    
    Ok(())
}

订单查询

use ztk_rust_sdk::{ZtkClient, ZtkResult, QueryOrdersRequest};

#[tokio::main]
async fn main() -> ZtkResult<()> {
    let client = ZtkClient::new("your_appkey").build()?;
    
    let request = QueryOrdersRequest::new("your_sid", "2024-01-01 00:00:00")
        .page(1)
        .page_size(50);
    
    let result = client.taobao().query_orders(request).await?;
    println!("订单列表: {:?}", result);
    
    Ok(())
}

京东平台

商品转链

use ztk_rust_sdk::{ZtkClient, ZtkResult, JdConvertRequest, JdChainType};

#[tokio::main]
async fn main() -> ZtkResult<()> {
    let client = ZtkClient::new("your_appkey").build()?;
    
    let request = JdConvertRequest::new(
        "https://item.jd.com/123456.html",
        "your_union_id"
    )
    .position_id("12345")
    .chain_type(JdChainType::Short);
    
    let result = client.jd().convert(request).await?;
    println!("转链结果: {:?}", result);
    
    Ok(())
}

京粉精选商品

use ztk_rust_sdk::{ZtkClient, ZtkResult, JingfenGoodsRequest, JdEliteId, JdSortField, SortDirection};

#[tokio::main]
async fn main() -> ZtkResult<()> {
    let client = ZtkClient::new("your_appkey").build()?;
    
    let request = JingfenGoodsRequest::new(JdEliteId::HotSale)
        .page_index(1)
        .page_size(20)
        .sort_name(JdSortField::CommissionShare)
        .sort(SortDirection::Desc);
    
    let result = client.jd().jingfen_goods(request).await?;
    println!("商品列表: {:?}", result);
    
    Ok(())
}

拼多多平台

商品转链

use ztk_rust_sdk::{ZtkClient, ZtkResult, PddConvertRequest};

#[tokio::main]
async fn main() -> ZtkResult<()> {
    let client = ZtkClient::new("your_appkey").build()?;
    
    let request = PddConvertRequest::new(
        "pdd_app_key",
        "pdd_app_secret",
        "your_pid",
        "453581732819"  // 商品 ID
    )
    .custom_parameters(r#"{"uid":"user123"}"#);  // 用于返利场景
    
    let result = client.pdd().convert(request).await?;
    println!("转链结果: {:?}", result);
    
    Ok(())
}

抖音平台

商品转链

use ztk_rust_sdk::{ZtkClient, ZtkResult, DouyinGoodsConvertRequest};

#[tokio::main]
async fn main() -> ZtkResult<()> {
    let client = ZtkClient::new("your_appkey").build()?;
    
    let request = DouyinGoodsConvertRequest::new("product_url_or_id");
    
    let result = client.douyin().convert_goods(request).await?;
    println!("转链结果: {:?}", result);
    
    Ok(())
}

直播间转链

use ztk_rust_sdk::{ZtkClient, ZtkResult, DouyinLiveConvertRequest};

#[tokio::main]
async fn main() -> ZtkResult<()> {
    let client = ZtkClient::new("your_appkey").build()?;
    
    let request = DouyinLiveConvertRequest::new_with_buyin_id("buyin_id");
    
    let result = client.douyin().convert_live(request).await?;
    println!("直播间转链结果: {:?}", result);
    
    Ok(())
}

客户端配置

基础配置

use ztk_rust_sdk::ZtkClient;
use std::time::Duration;

let client = ZtkClient::new("your_appkey")
    .base_url("https://api.zhetaoke.com:10001")  // 主接口地址 (默认)
    .timeout(Duration::from_secs(60))             // 请求超时时间
    .build()?;

使用备用接口

let client = ZtkClient::new("your_appkey")
    .base_url("http://api.zhetaoke.cn:10000")  // 备用接口地址
    .build()?;

错误处理

SDK 定义了统一的错误类型 ZtkError：

use ztk_rust_sdk::{ZtkClient, ZtkError, ZtkResult};

async fn example() -> ZtkResult<()> {
    let client = ZtkClient::new("your_appkey").build()?;
    
    match client.taobao().convert_by_item_id(request).await {
        Ok(result) => {
            println!("成功: {:?}", result);
        }
        Err(ZtkError::Network(e)) => {
            eprintln!("网络错误: {}", e);
        }
        Err(ZtkError::Api { code, message, .. }) => {
            eprintln!("API 错误 [{}]: {}", code, message);
        }
        Err(ZtkError::Parse(e)) => {
            eprintln!("解析错误: {}", e);
        }
        Err(ZtkError::Validation(msg)) => {
            eprintln!("参数验证错误: {}", msg);
        }
        Err(e) => {
            eprintln!("其他错误: {}", e);
        }
    }
    
    Ok(())
}

枚举类型

SDK 提供了丰富的枚举类型，确保参数值的正确性：

通用枚举

• SignUrlType - 返回结果类型
• SortDirection - 排序方向 (Asc/Desc)

京东枚举

• JdEliteId - 京粉频道 ID (好券商品、精选卖场、9.9包邮、实时热销榜等)
• JdChainType - 转链类型 (长链/短链)
• JdSortField - 排序字段 (价格、佣金比例、销量等)
• JdOrderQueryType - 订单查询类型 (下单时间/完成时间/更新时间)

淘宝枚举

• TaobaoSignUrlType - 淘宝返回结果类型
• TaobaoOrderQueryType - 订单查询类型
• TaobaoOrderStatus - 订单状态

抖音枚举

• DouyinSearchType - 搜索类型
• DouyinSortType - 排序类型
• DouyinOrderQueryType - 订单查询类型

API 参考

ZtkClient 方法

TaobaoApi 方法

JdApi 方法

PddApi 方法

DouyinApi 方法

依赖项

• reqwest - HTTP 客户端
• serde / serde_json - JSON 序列化
• thiserror - 错误处理
• tokio - 异步运行时
• url - URL 处理

License

MIT License

相关链接

• 折淘客官网
• 折淘客 API 文档