---
name: kuaishou-ec
description: 快手电商开放平台 CLI 和 Skills - 封装快手电商 API，支持商品管理、订单管理、退款管理、物流管理、客服消息等。官方文档: https://open.kwaixiaodian.com/
version: 1.0.0
author: Hermes Agent
license: MIT
metadata:
  hermes:
    tags: [E-commerce, Kuaishou, Shop, CLI]
    related_skills: [kuaishou]
  language: zh
  platform: cli
---

# 快手电商开放平台 CLI

封装快手电商开放平台 API，使 Agent 能够通过 CLI 管理店铺商品、订单、退款、物流和客服消息。

## 快速开始

### 环境配置

```bash
# 设置环境变量（推荐写入 ~/.bashrc 或 ~/.zshrc）
export KUAISHOU_EC_APP_KEY=your_app_key
export KUAISHOU_EC_APP_SECRET=your_app_secret
export KUAISHOU_EC_ACCESS_TOKEN=your_access_token
```

### 首次认证

1. 在 [快手电商开放平台控制台](https://open.kwaixiaodian.com/) 创建应用
2. 获取授权码 code
3. 使用 code 换取 access_token

```bash
# 首次获取 access_token
python kuaishou_ec_client.py auth --code YOUR_AUTH_CODE

# 刷新 access_token（token 有效期 30 天）
python kuaishou_ec_client.py auth --refresh YOUR_REFRESH_TOKEN
```

## CLI 命令

### 商品管理

```bash
# 商品列表
python kuaishou_ec_client.py goods list
python kuaishou_ec_client.py goods list --status on_sale
python kuaishou_ec_client.py goods list --page 2 --page-size 50

# 商品详情
python kuaishou_ec_client.py goods detail GOODS_ID

# 创建商品
python kuaishou_ec_client.py goods create --name "商品名称" --price 99.9 --stock 100

# 更新商品
python kuaishou_ec_client.py goods update GOODS_ID --stock 200 --price 89.9

# 删除商品
python kuaishou_ec_client.py goods delete GOODS_ID

# 上架/下架
python kuaishou_ec_client.py goods onsale GOODS_ID
python kuaishou_ec_client.py goods warehouse GOODS_ID

# 自动审核设置
python kuaishou_ec_client.py goods autopass GOODS_ID --enable
python kuaishou_ec_client.py goods autopass GOODS_ID --disable
```

### 订单管理

```bash
# 订单列表
python kuaishou_ec_client.py orders list
python kuaishou_ec_client.py orders list --status pending
python kuaishou_ec_client.py orders list --status shipped --page 1 --page-size 50

# 订单详情
python kuaishou_ec_client.py orders detail ORDER_ID

# 发货
python kuaishou_ec_client.py orders ship ORDER_ID --company sf --no SF123456789

# 取消订单
python kuaishou_ec_client.py orders cancel ORDER_ID --reason "商品缺货"
```

### 退款管理

```bash
# 退款列表
python kuaishou_ec_client.py refunds list
python kuaishou_ec_client.py refunds list --status pending

# 退款详情
python kuaishou_ec_client.py refunds detail REFUND_ID

# 同意/拒绝退款
python kuaishou_ec_client.py refunds agree REFUND_ID
python kuaishou_ec_client.py refunds reject REFUND_ID --reason "不符合退款条件"
```

### 店铺信息

```bash
# 店铺信息
python kuaishou_ec_client.py shop info
python kuaishou_ec_client.py shop detail
```

### 物流管理

```bash
# 运费模板列表
python kuaishou_ec_client.py logistics template list
```

### 客服消息

```bash
# 发送文本消息
python kuaishou_ec_client.py customer send USER_ID --type text --content "您好，有什么可以帮您？"

# 发送商品卡片
python kuaishou_ec_client.py customer send USER_ID --type goods_card --content GOODS_ID

# 发送订单卡片
python kuaishou_ec_client.py customer send USER_ID --type order_card --content ORDER_ID
```

### 消息订阅

```bash
# 订阅列表
python kuaishou_ec_client.py subscription list

# 添加订阅
python kuaishou_ec_client.py subscription add --type order --callback "https://your-server.com/callback"

# 删除订阅
python kuaishou_ec_client.py subscription delete SUBSCRIPTION_ID
```

## API 端点总览

| 模块 | 方法 | 端点 | 说明 |
|-----|------|------|------|
| 认证 | POST | `/oauth/access_token` | 获取/刷新 token |
| 店铺 | GET | `/shop/info` | 店铺基本信息 |
| 店铺 | GET | `/shop/detail` | 店铺详情 |
| 商品 | GET | `/goods/list` | 商品列表 |
| 商品 | GET | `/goods/detail` | 商品详情 |
| 商品 | POST | `/goods/create` | 创建商品 |
| 商品 | POST | `/goods/update` | 更新商品 |
| 商品 | POST | `/goods/delete` | 删除商品 |
| 商品 | POST | `/goods/onsale` | 上架商品 |
| 商品 | POST | `/goods/warehouse` | 下架商品 |
| 商品 | POST | `/goods/stock/update` | 更新库存 |
| 商品 | POST | `/item/autopass/edit` | 自动审核设置 |
| 订单 | GET | `/order/list` | 订单列表 |
| 订单 | GET | `/order/detail` | 订单详情 |
| 订单 | POST | `/order/ship` | 发货 |
| 订单 | POST | `/order/cancel` | 取消订单 |
| 退款 | GET | `/refund/list` | 退款列表 |
| 退款 | GET | `/refund/detail` | 退款详情 |
| 退款 | POST | `/refund/agree` | 同意退款 |
| 退款 | POST | `/refund/reject` | 拒绝退款 |
| 物流 | GET | `/logistics/template/list` | 运费模板列表 |
| 客服 | POST | `/customer/message/send` | 发送消息 |
| 订阅 | GET | `/subscription/list` | 订阅列表 |
| 订阅 | POST | `/subscription/add` | 添加订阅 |
| 订阅 | DELETE | `/subscription/delete` | 删除订阅 |

## 常见问题

### Q: 如何获取 APP_KEY 和 APP_SECRET？
A: 登录 [快手电商开放平台控制台](https://open.kwaixiaodian.com/)，在「应用管理」中创建应用即可获取。

### Q: access_token 有效期是多久？
A: 默认有效期 30 天，需要使用 refresh_token 续期。

### Q: API 调用频率限制？
A: 具体限制请参考官方文档，一般每秒 10 次调用。

### Q: 支持哪些快递公司？
A: 常用快递：sf(顺丰)、yto(圆通)、zto(中通)、sto(申通)、ems、yunda(韵达)

## 错误码

| 错误码 | 说明 |
|-------|------|
| 0 | 成功 |
| 40001 | 参数错误 |
| 40003 | 认证失败 |
| 40004 | 权限不足 |
| 40005 | 资源不存在 |
| 50001 | 服务器内部错误 |

## Agent 使用示例

当用户询问快手店铺相关问题时，可以使用此 skill：

```
用户：查看我的快手店铺有哪些待发货的订单
→ 使用 kuaishou-ec skill
→ 执行: goods orders list --status pending
→ 返回订单列表给用户

用户：上架一个新商品"测试商品"，价格99元，库存50个
→ 使用 kuaishou-ec skill
→ 执行: goods create --name "测试商品" --price 99 --stock 50
→ 返回创建结果给用户

用户：有客户申请退款了，订单号是 REF123456
→ 使用 kuaishou-ec skill
→ 执行: refunds detail REF123456
→ 查看详情后再决定是否同意
```

## 相关链接

- 快手电商开放平台: https://open.kwaixiaodian.com/
- 官方文档: https://open.kwaixiaodian.com/zone/new/docs/dev
- 控制台: https://open.kwaixiaodian.com/console