xiaohongshu-ecommerce

🚀 小红书电商开放API的Python SDK

✨ 特性

• 🔄 全自动Token管理 - 自动获取、刷新、注入access_token，完全无感知
• 🏗️ 完整API覆盖 - 支持商品、订单、库存、物流、财务等全部电商API
• 💾 灵活Token存储 - 支持内存、文件、数据库等多种存储方式
• 🔒 线程安全设计 - 支持多线程并发，内置锁机制保证安全
• 🎯 类型安全 - 完整的类型注解，支持IDE智能提示
• 📚 详细文档 - 丰富的示例和API文档
• 🧪 完整测试 - 高测试覆盖率，保证代码质量

📦 安装

pip install xiaohongshu-ecommerce

🚀 快速开始

1. 基础配置

from xiaohongshu_ecommerce import XhsClient, ClientConfig, FileTokenStorage

# 创建客户端配置
config = ClientConfig(
    base_url="https://openapi.xiaohongshu.com",
    app_id="your_app_id",
    app_secret="your_app_secret",
    token_storage=FileTokenStorage("tokens.json")  # 持久化存储token
)

# 创建客户端
client = XhsClient.create(config)

2. 设置Token（仅需一次）

# 方式一：使用授权码（推荐）
tokens = client.set_tokens_from_auth_code("your_authorization_code")
print(f"授权成功，商家：{tokens.seller_name}")

# 方式二：手动设置（如果已有token信息）
client.set_tokens_manually(
    access_token="your_access_token",
    refresh_token="your_refresh_token",
    access_token_expires_at=1640995200000,
    refresh_token_expires_at=1641081600000,
    seller_id="your_seller_id",
    seller_name="your_seller_name"
)

3. 使用API（完全无需传递Token！）

# 🎉 所有API调用都无需access_token参数
# SDK会自动处理token的获取、刷新和注入

# 获取商品列表
products = client.product.get_detail_sku_list(
    page_no=1,
    page_size=20,
    buyable=True
)

if products.success:
    print(f"获取到 {len(products.data.get('data', []))} 个商品")
    for product in products.data.get('data', []):
        print(f"商品：{product.get('title')}")

# 获取订单列表
orders = client.order.get_order_list(
    page_no=1,
    page_size=20
)

if orders.success:
    order_list = orders.data.get('order_list', [])
    print(f"获取到 {len(order_list)} 个订单")

# 查询库存
inventory = client.inventory.get_sku_stock_list(
    page_no=1,
    page_size=50
)

# SDK自动处理：
# ✅ 检查token是否过期
# ✅ 自动刷新即将过期的token
# ✅ 在每个请求中自动注入有效token
# ✅ 处理token获取失败等异常情况

📋 支持的API模块

模块	说明	主要功能
client.oauth	OAuth认证	获取/刷新access_token
client.product	商品管理	商品创建、更新、查询、上下架
client.order	订单管理	订单查询、发货、退款处理
client.inventory	库存管理	库存查询、更新、预警设置
client.finance	财务管理	账单查询、结算、提现
client.express	物流管理	快递单号、物流轨迹查询
client.after_sale	售后服务	退货退款、售后处理
client.data	数据分析	销售数据、流量分析
client.material	素材管理	图片、视频素材上传管理

🛠️ 高级用法

多商家支持

def create_seller_client(seller_id: str) -> XhsClient:
    """为不同商家创建独立的客户端"""
    config = ClientConfig(
        base_url="https://openapi.xiaohongshu.com",
        app_id="your_app_id",
        app_secret="your_app_secret",
        token_storage=FileTokenStorage(f"./tokens/seller_{seller_id}.json")
    )
    return XhsClient.create(config)

# 使用独立客户端管理不同商家
seller1_client = create_seller_client("seller_001")
seller2_client = create_seller_client("seller_002")

# 独立设置各自的token
seller1_client.set_tokens_from_auth_code("seller1_auth_code")
seller2_client.set_tokens_from_auth_code("seller2_auth_code")

自定义Token存储

from xiaohongshu_ecommerce.token_manager import TokenStorage, TokenInfo
from typing import Optional

class DatabaseTokenStorage:
    """数据库Token存储示例"""

    def __init__(self, user_id: str):
        self.user_id = user_id

    def load_tokens(self) -> Optional[TokenInfo]:
        # 从数据库加载token
        data = db.get_user_tokens(self.user_id)
        return TokenInfo(**data) if data else None

    def save_tokens(self, tokens: TokenInfo) -> None:
        # 保存token到数据库
        from dataclasses import asdict
        db.save_user_tokens(self.user_id, asdict(tokens))

    def clear_tokens(self) -> None:
        # 清除token
        db.delete_user_tokens(self.user_id)

# 使用自定义存储
config = ClientConfig(
    # ... 其他配置
    token_storage=DatabaseTokenStorage(user_id="user123")
)

错误处理

from xiaohongshu_ecommerce import TokenManagerError

try:
    products = client.product.get_detail_sku_list(page_no=1, page_size=20)

    if products.success:
        print("获取商品成功")
    else:
        print(f"API错误：{products.error_message}")

except TokenManagerError as e:
    print(f"Token管理错误：{e}")
    # 需要重新授权
    client.set_tokens_from_auth_code(input("请输入新的授权码："))

except Exception as e:
    print(f"其他错误：{e}")

并发使用

import threading
from concurrent.futures import ThreadPoolExecutor

def fetch_products(page_no):
    """获取指定页的商品"""
    return client.product.get_detail_sku_list(page_no=page_no, page_size=50)

# 并发获取多页数据（完全线程安全）
with ThreadPoolExecutor(max_workers=5) as executor:
    futures = [executor.submit(fetch_products, page) for page in range(1, 11)]

    all_products = []
    for future in futures:
        result = future.result()
        if result.success:
            all_products.extend(result.data.get("data", []))

print(f"总共获取 {len(all_products)} 个商品")

🔐 OAuth授权流程

Web端授权

1. 引导用户访问授权页面：

   https://ark.xiaohongshu.com/ark/authorization?appId={your_app_id}&redirectUri={your_redirect_uri}&state=12345
   

2. 用户授权后获取code：

   https://your-callback-url/?code=xxx&state=12345
   

3. 使用code设置token：

   tokens = client.set_tokens_from_auth_code(code)
   

移动端授权

1. 生成二维码：

   https://ark.xiaohongshu.com/thor/open/authorization?fullscreen=true&appId={your_app_id}&sellerId={seller_id}&redirectUri={your_redirect_uri}
   

2. 小红书千帆APP扫码授权

3. 获取code并设置token

📊 Token管理

# 检查token状态
if client.is_token_valid():
    print("Token有效")

    # 获取token详细信息
    tokens = client.get_current_tokens()
    print(f"商家：{tokens.seller_name}")
    print(f"访问token剩余：{tokens.access_token_expires_in_seconds}秒")
    print(f"刷新token剩余：{tokens.refresh_token_expires_in_seconds}秒")

    # 检查是否需要刷新
    if tokens.should_refresh(buffer_seconds=3600):  # 1小时内过期
        print("建议刷新token")
else:
    print("Token无效，需要重新设置")

# 清除token（如用户退出登录）
client.clear_tokens()

🧪 开发和测试

环境要求

• Python 3.12+
• httpx >= 0.28.1

本地开发

# 克隆项目
git clone https://github.com/AndersonBY/xiaohongshu-ecommerce-python-sdk.git
cd xiaohongshu-ecommerce-python-sdk

# 安装依赖
pdm install

# 运行测试
pdm run pytest

# 代码检查
pdm run lint

# 类型检查
pdm run typecheck

# 代码格式化
pdm run format

运行示例

# 运行自动token管理示例
python examples/auto_token_management_demo.py

📝 更新日志

v2.0.0

• 🎉 重大重构：采用纯自动token管理模式
• ❌ 移除所有手动access_token参数
• ✨ 新增灵活的token存储接口
• 🔒 增强线程安全性
• 📦 重命名包为 xiaohongshu-ecommerce

v1.x.x

• 🏗️ 基础API客户端实现
• 🔧 手动token管理模式

🤝 贡献

欢迎提交Issue和Pull Request！

1. Fork 本项目
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 打开 Pull Request

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

🔗 相关链接

• 小红书开放平台
• 官方API文档
• 问题反馈

⭐ 支持项目

如果这个项目对你有帮助，请给一个 ⭐️ Star 支持一下！

---

Made with ❤️ by AndersonBY