闲鱼API客户端技能

技能概述

这是一个专为闲鱼管家开放平台设计的基础API客户端技能，为所有闲鱼相关操作提供安全、可靠的底层通信能力。本技能处理了所有复杂的认证、签名、错误处理等技术细节，让您能够专注于业务逻辑开发，而无需关心底层API实现。

核心价值

• 安全可靠：严格按照闲鱼管家官方签名算法实现，端点白名单防止未授权调用
• 安全确认：高风险操作（创建/删除商品、改价）自动暂停并等待用户确认
• 开箱即用：预置所有常用API端点，支持商品管理、订单处理、用户查询等完整功能
• 智能容错：内置完善的错误处理机制，自动识别并处理各种异常情况
• Dry Run支持：支持预览模式，先检查请求数据再实际执行

使用前准备

必需配置项

在使用本技能之前，您必须完成以下配置：

1. 获取闲鱼管家开发者账号

• 访问 [闲鱼管家开放平台](https://www.goofish.pro)
• 注册并登录您的开发者账号
• 创建新的应用，获取以下关键信息：

- 应用KEY (appKey)：一串数字，如 203413189371893

- 应用密钥 (appSecret)：一串字母数字组合，如 o9wl81dncmvby3ijpq7eur456zhgtaxs

2. 配置环境变量（推荐方式）

将获取到的密钥信息配置为环境变量，这是最安全的方式：

# Linux/Mac系统
export XIAN_YU_APP_KEY=您的应用KEY
export XIAN_YU_APP_SECRET=您的应用密钥

# Windows系统（命令提示符）
set XIAN_YU_APP_KEY=您的应用KEY
set XIAN_YU_APP_SECRET=您的应用密钥

3. 或者程序化配置

如果您不想使用环境变量，也可以在代码中直接传入密钥：

from xianyu_api_client_skill import XianYuAPIClient

client = XianYuAPIClient(
    app_key="您的应用KEY",
    app_secret="您的应用密钥"
)

权限要求

• 您的闲鱼管家应用必须具有相应的API调用权限
• 确保您的闲鱼店铺已经通过相关认证
• 某些高级功能可能需要额外的权限申请

支持的功能范围

商品管理

创建商品完整参数说明（基于实际成功经验）：

{
  "item_biz_type": 2,
  "sp_biz_type": 1,
  "channel_cat_id": "e11455b218c06e7ae10cfa39bf43dc0f",
  "price": 29900,
  "original_price": 39900,
  "express_fee": 0,
  "stock": 1,
  "outer_id": "YOUR_UNIQUE_ID",
  "stuff_status": 100,
  "publish_shop": [{
    "user_name": "您的闲鱼号",           // 必需！如：xy137114666612
    "images": ["https://example.com/image.jpg"],  // 必需！至少1张图片URL
    "title": "商品标题",              // ≤60字符，不能包含表情符号
    "content": "详细商品描述",
    "service_support": "SDR",         // 固定值
    "province": 110000,              // 省代码
    "city": 110100,                  // 市代码
    "district": 110101               // 区代码
  }]
}

关键注意事项：

• ✅ user_name必需：必须填写您的真实闲鱼号

• ✅ images必需：必须提供有效的图片URL数组

• ✅ 标题限制：不超过60字符，不能包含表情符号（🎯❌）

• ✅ 价格单位：以分为单位（29900 = ¥299）

• ✅ 成功响应：code=0 表示成功，不是200

• 查询商品详情和列表

• 编辑商品信息

• 商品上下架操作

• 库存管理

• 商品删除

用户与店铺

• 查询闲鱼店铺信息
• 获取店铺统计数据

订单处理

• 查询订单列表和详情
• 订单物流发货
• 订单价格修改

辅助功能

• 查询商品类目和属性
• 查询快递公司信息
• 省市区数据标准化

安全确认机制

本技能采用强制确认机制，确保所有高风险操作都是安全且可控的：

默认安全模式（推荐）

所有写操作默认需要用户确认，无法跳过。以下操作会暂停并等待用户确认：

• 创建商品 (/api/open/product/create)
• 编辑商品 (/api/open/product/edit)
• 删除商品 (/api/open/product/del)
• 上架/下架商品 (/api/open/product/onshelf, /api/open/product/offshelf)
• 修改订单价格 (/api/open/order/modifyprice)
• 订单发货 (/api/open/order/logistics)

# 默认安全模式：高风险操作会暂停等待确认
client.request("/api/open/product/create", product_data)
client.create_product(product_data)
client.delete_product(product_data)
client.modify_order_price(order_data)

Dry Run 预览模式

在实际执行前，先用 dry_run=True 预览请求数据：

# 预览请求，不实际发送
result = client.request("/api/open/product/create", product_data, dry_run=True)

自动化模式（Unsafe 方法）

对于确认需要自动化脚本使用的场景，提供了 _unsafe 后缀的方法。这些方法跳过所有确认，请务必先用 dry_run=True 预览：

# 1. 先预览确认数据正确
client.request_unsafe("/api/open/product/create", product_data, dry_run=True)

# 2. 预览无误后执行（跳过确认）
result = client.request_unsafe("/api/open/product/create", product_data)

# 或者使用便捷方法
client.create_product_unsafe(product_data)
client.delete_product_unsafe(product_data)
client.modify_order_price_unsafe(order_data)

警告：_unsafe 方法跳过所有安全确认，仅适用于：

• 已验证过的自动化脚本
• 经过 dry_run 预览的请求
• 使用低权限凭证的自动化账户

Security Model

此技能通过API凭证与闲鱼管家开放平台进行交互。以下安全控制在代码层面强制执行。

访问范围

该技能仅应在需要闲鱼店铺自动化时安装。它专用于管理闲鱼市场上的商品、订单和店铺信息。不会访问闲鱼开放平台以外的任何平台、服务或本地资源。

端点白名单（代码强制）

所有API调用均受限于 __init__.py 中硬编码的白名单。任何对白名单外端点的请求都会在发起网络调用前被拒绝，并抛出 ValueError。允许的端点如下：

写操作确认机制（代码强制）

所有写操作（创建、编辑、删除、上/下架、价格修改、物流）均定义在 HIGH_RISK_ENDPOINTS 中，默认需要交互式用户确认。默认 request() 方法调用 _do_request(endpoint, data, confirm=True)，会打印完整的请求负载，并等待用户输入 y 才继续。

# 默认路径：写操作始终提示确认
client.request("/api/open/product/create", product_data)   # 提示 [y/N]
client.create_product(product_data)                         # 提示 [y/N]
client.delete_product(product_data)                         # 提示 [y/N]
client.modify_order_price(order_data)                       # 提示 [y/N]

默认 request() 方法无法通过任何方式禁用确认。

Dry-Run 模式

所有方法均支持 dry_run=True，该模式会打印完整的请求负载但不发起任何网络请求。请在执行写操作前始终使用 dry-run 进行预览。

result = client.request("/api/open/product/create", product_data, dry_run=True)
# 输出: [模拟运行] 完整的JSON请求体 —— 未实际发起API调用

不安全方法（自动化场景需显式启用）

在受控的自动化场景中，本技能提供了独立命名的 _unsafe 方法（如 request_unsafe、create_product_unsafe、delete_product_unsafe、modify_order_price_unsafe），这些方法会跳过交互式确认提示。

这些方法与默认的安全路径明确分离，旨在防止误用。仅在以下情况下使用：

1. 调用方已通过设置 dry_run=True 审查过请求内容
2. 自动化流程受到严格控制并具备审计能力
3. 使用的凭证权限最小化，仅包含必要操作权限
4. 调用方明确选择以 _unsafe 命名的方法

_unsafe 方法不会通过默认的 request() 路径暴露。代理或脚本必须显式调用 request_unsafe() 或 create_product_unsafe() 等方法。

凭证安全

本技能从环境变量或构造函数参数读取闲鱼API凭证（XIAN_YU_APP_KEY、XIAN_YU_APP_SECRET），仅用于对闲鱼开放平台API请求进行签名。

建议遵循以下实践：

• 使用专用的低权限闲鱼应用密钥。不要复用其他应用的凭证。
• 将敏感信息存储于环境变量或密钥管理服务中。切勿在源码中硬编码，也禁止提交到版本控制系统。
• 定期更换凭证（建议每3至6个月一次），一旦怀疑泄露应立即更换。
• 不与其他技能或代理共享凭证。每个技能应使用独立的应用密钥，并仅授予最小必要权限。
• 若技能卸载或不再可信，立即撤销相关凭证。

请求限制

• 遵守API频率限制：闲鱼管家有严格的请求频率限制，请合理安排请求间隔
• 批量操作优化：优先使用批量接口，避免多次单次调用
• 错误重试策略：实现合理的重试机制，防止因临时网络问题导致失败

依赖关系

本技能是其他闲鱼相关技能的基础依赖项：

• xianyu-product-manager-skill：商品管理技能依赖本技能完成API通信
• xianyu-automation-skill：自动化技能依赖本技能执行所有底层操作

版本兼容性

• 当前版本：1.0.6
• API兼容性：闲鱼管家开放平台 v1
• Python版本要求：3.7+

故障排除

如遇问题，请按以下步骤排查：

1. 检查配置：确认 appKey 和 appSecret 配置正确无误
2. 验证权限：确认应用已开通对应API权限
3. 查看日志：启用详细日志模式以获取更多信息
4. 联系支持：若问题持续存在，请联系闲鱼管家技术支持

开始使用

配置完成后，您可在其他闲鱼相关技能中无缝调用本技能，或直接使用其提供的API方法进行自定义开发。