skills/kuaishou-ec/SKILL.md

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 管理店铺商品、订单、退款、物流和客服消息。

快速开始

环境配置

# 设置环境变量（推荐写入 ~/.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. 在 快手电商开放平台控制台 创建应用
2. 获取授权码 code
3. 使用 code 换取 access_token

# 首次获取 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 命令

商品管理

# 商品列表
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

订单管理

# 订单列表
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 "商品缺货"

退款管理

# 退款列表
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 "不符合退款条件"

店铺信息

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

物流管理

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

客服消息

# 发送文本消息
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

消息订阅

# 订阅列表
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: 登录 快手电商开放平台控制台，在「应用管理」中创建应用即可获取。

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