闲鱼API客户端技能

技能概述

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

核心价值

• - 安全可靠：严格按照闲鱼管家官方签名算法实现，确保每次请求都能成功认证
• 开箱即用：预置所有常用API端点，支持商品管理、订单处理、用户查询等完整功能
• 智能容错：内置完善的错误处理机制，自动识别并处理各种异常情况
• 企业级稳定：经过严格测试，适用于高频率、大批量的生产环境使用

使用前准备

必需配置项

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

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

• - 访问 闲鱼管家开放平台
• 注册并登录您的开发者账号
• 创建新的应用，获取以下关键信息：

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

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

bash

Linux/Mac系统

Windows系统（命令提示符）

3. 或者程序化配置

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

python
from xianyuapiclient_skill import XianYuAPIClient

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

权限要求

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

支持的功能范围

商品管理

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

json
{
itembiztype: 2,
spbiztype: 1,
channelcatid: e11455b218c06e7ae10cfa39bf43dc0f,
price: 29900,
original_price: 39900,
express_fee: 0,
stock: 1,
outerid: YOURUNIQUE_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

• - 查询商品详情和列表

• - 编辑商品信息

• - 商品上下架操作

• - 库存管理

• - 商品删除

用户与店铺

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

订单处理

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

辅助功能

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

用户交互流程

自动确认机制

本技能采用智能确认机制，确保操作的安全性和准确性：

1. 敏感操作确认

对于可能产生费用或不可逆影响的操作（如批量创建商品、删除商品），系统会自动暂停并等待用户确认：

检测到批量商品创建操作（预计创建12个商品）
预计费用：¥8388
是否继续执行？[Y/N]

2. 配置验证确认

首次使用时，系统会自动验证您的API配置是否正确：

正在验证闲鱼管家API配置...
✓ 应用KEY格式正确
✓ 应用密钥格式正确
✓ API连接测试成功
配置验证通过，可以开始使用！

3. 错误恢复确认

当遇到可恢复的错误时，系统会提供修复建议并等待用户选择：

错误：商品类目ID无效
建议解决方案：

1. 1. 自动查询最新类目列表并重试
2. 手动指定正确的类目ID
3. 取消当前操作

交互控制选项

您可以通过以下方式控制交互行为：

• - 静默模式：设置 silent=True 参数跳过所有确认提示（适用于自动化脚本）
• 详细模式：设置 verbose=True 参数获取更详细的执行日志
• 调试模式：设置 debug=True 参数启用完整的调试信息输出

安全最佳实践

密钥管理

• - 绝不提交密钥到代码仓库：始终使用环境变量或安全的密钥管理系统
• 定期轮换密钥：建议每3-6个月更换一次应用密钥
• 最小权限原则：只申请必要的API权限，避免过度授权

请求限制

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

依赖关系

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

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

版本兼容性

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

故障排除

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

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

开始使用

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