xianyu-api-client

# 闲鱼API客户端技能 ## 技能概述 这是一个专为闲鱼管家开放平台设计的基础API客户端技能，为所有闲鱼相关操作提供安全、可靠的底层通信能力。本技能处理了所有复杂的认证、签名、错误处理等技术细节，让您能够专注于业务逻辑开发，而无需关心底层API实现。 ## 核心价值 - **安全可靠**：严格按照闲鱼管家官方签名算法实现，确保每次请求都能成功认证 - **开箱即用**：预置所有常用API端点，支持商品管理、订单处理、用户查询等完整功能 - **智能容错**：内置完善的错误处理机制，自动识别并处理各种异常情况 - **企业级稳定**：经过严格测试，适用于高频率、大批量的生产环境使用 ## 使用前准备 ### 必需配置项 在使用本技能之前，您必须完成以下配置： #### 1. 获取闲鱼管家开发者账号 - 访问 [闲鱼管家开放平台](https://www.goofish.pro) - 注册并登录您的开发者账号 - 创建新的应用，获取以下关键信息： - **应用KEY (appKey)**：一串数字，如 `203413189371893` - **应用密钥 (appSecret)**：一串字母数字组合，如 `o9wl81dncmvby3ijpq7eur456zhgtaxs` #### 2. 配置环境变量（推荐方式） 将获取到的密钥信息配置为环境变量，这是最安全的方式： ```bash # 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. 或者程序化配置 如果您不想使用环境变量，也可以在代码中直接传入密钥： ```python from xianyu_api_client_skill import XianYuAPIClient client = XianYuAPIClient( app_key="您的应用KEY", app_secret="您的应用密钥" ) ``` ### 权限要求 - 您的闲鱼管家应用必须具有相应的API调用权限 - 确保您的闲鱼店铺已经通过相关认证 - 某些高级功能可能需要额外的权限申请 ## 支持的功能范围 ### 商品管理 **创建商品完整参数说明（基于实际成功经验）：** ```json { "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 - 查询商品详情和列表 - 编辑商品信息 - 商品上下架操作 - 库存管理 - 商品删除 ### 用户与店铺 - 查询闲鱼店铺信息 - 获取店铺统计数据 ### 订单处理 - 查询订单列表和详情 - 订单物流发货 - 订单价格修改 ### 辅助功能 - 查询商品类目和属性 - 查询快递公司信息 - 省市区数据标准化 ## 用户交互流程 ### 自动确认机制 本技能采用智能确认机制，确保操作的安全性和准确性： #### 1. 敏感操作确认 对于可能产生费用或不可逆影响的操作（如批量创建商品、删除商品），系统会自动暂停并等待用户确认： ``` 检测到批量商品创建操作（预计创建12个商品） 预计费用：¥8388 是否继续执行？[Y/N] ``` #### 2. 配置验证确认 首次使用时，系统会自动验证您的API配置是否正确： ``` 正在验证闲鱼管家API配置... ✓ 应用KEY格式正确 ✓ 应用密钥格式正确 ✓ API连接测试成功 配置验证通过，可以开始使用！ ``` #### 3. 错误恢复确认 当遇到可恢复的错误时，系统会提供修复建议并等待用户选择： ``` 错误：商品类目ID无效 建议解决方案： 1. 自动查询最新类目列表并重试 2. 手动指定正确的类目ID 3. 取消当前操作 请选择处理方式 [1/2/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. **检查配置**：确认appKey和appSecret正确无误 2. **验证权限**：确认您的应用具有相应API权限 3. **查看日志**：启用详细日志模式获取更多信息 4. **联系支持**：如果问题持续存在，请联系闲鱼管家技术支持 ## 开始使用 配置完成后，您就可以在其他闲鱼技能中无缝使用本技能，或者直接调用其提供的API方法进行自定义开发。