# Xianyu API Client Skill

> 闲鱼API客户端技能

- Skill: `cogine-ai/xianyu-api-client-skill` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add cogine-ai/xianyu-api-client-skill`
- Raw SKILL.md: https://api.skillmd.com/api/skills/cogine-ai/xianyu-api-client-skill/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: cogine-ai (https://skillmd.com/u/cogine-ai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/cogine-ai/xianyu-api-client-skill

---

# 闲鱼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调用权限
- 确保您的闲鱼店铺已经通过相关认证
- 某些高级功能可能需要额外的权限申请

## 支持的功能范围

### 商品管理

- 创建商品（单个/批量）
- 查询商品详情和列表
- 编辑商品信息
- 商品上下架操作
- 库存管理
- 商品删除

### 用户与店铺

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

### 订单处理

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

### 辅助功能

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

## 用户交互流程

### 自动确认机制

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

#### 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.2
- **API兼容性**：闲鱼管家开放平台 v1
- **Python版本**：3.7+

## 故障排除

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

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

## 开始使用

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