okooooooo/xian-guanjia
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add full API support - user, product, order, logistics interfaces

Browse Source
This commit is contained in:
kingofmarketing committed 2026-04-10 04:51:41 +08:00
1 parent 3891554e79
commit 571da18dbd
4 files changed
+402 -55
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

README.md
+75 -16
View File
@@ -1,28 +1,55 @@
# xian-guanjia
闲管家 API Python 客户端 - 闲鱼自动化发货、订单管理工具
闲管家 API Python 客户端 - 闲鱼自动化发货、商品管理工具
[![GitHub](https://img.shields.io/github/stars/thefreelight/xian-guanjia?style=social)](https://github.com/thefreelight/xian-guanjia)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
## 简介
这是一个闲管家开放平台的 Python API 客户端，支持通过 API 进行：
这是一个闲管家开放平台的 Python API 客户端，支持完整的闲鱼自动化操作：
- 订单查询和管理
- 自动发货
- 商品管理
- 余额查询
- 货源对接下单
- 🔐 **自动签名** - 按照闲管家规则自动生成 MD5 签名
- 📦 **商品管理** - 创建、编辑、上架、下架、删除商品，批量创建
- 📦 **订单管理** - 查询订单、发货、改价、获取卡密
- 🔍 **查询功能** - 类目查询、属性查询、快递公司查询、余额查询
- 🪝 **Webhook 支持** - 支持商品和订单推送回调
## 安装
```bash
git clone https://github.com/kingofmarketing/xian-guanjia.git
git clone https://github.com/thefreelight/xian-guanjia.git
cd xian-guanjia
pip install requests
```
## 使用方法
## 功能列表
### Python 代码调用
| 模块 | 方法 | 功能 |
|------|------|------|
| 用户 | `get_xianyu_shops()` | 查询闲鱼店铺列表 |
| 商品 | `get_categories()` | 查询商品类目 |
| 商品 | `get_product_attributes(category_id)` | 查询商品属性 |
| 商品 | `get_product_list(page, page_size, status)` | 查询商品列表 |
| 商品 | `get_product_detail(product_id)` | 查询商品详情 |
| 商品 | `get_product_skus(product_id)` | 查询商品规格（多规格） |
| 商品 | `create_product(data)` | 创建单个商品 |
| 商品 | `create_products_batch(products)` | 批量创建商品 |
| 商品 | `publish_product(product_id)` | 上架商品 |
| 商品 | `unpublish_product(product_id)` | 下架商品 |
| 商品 | `update_product(product_id, data)` | 编辑商品 |
| 商品 | `update_stock(product_id, stock, sku_id)` | 编辑库存 |
| 商品 | `delete_product(product_id)` | 删除商品 |
| 订单 | `get_order_list(page, page_size, status)` | 获取订单列表 |
| 订单 | `get_order_detail(order_id)` | 获取订单详情 |
| 订单 | `get_order_cards(order_id)` | 获取卡密列表（虚拟商品） |
| 订单 | `ship_order(order_id, logistics_no, logistics_company)` | 订单发货 |
| 订单 | `update_order_price(order_id, price)` | 修改订单价格 |
| 订单 | `place_order(...)` | 下单（货源对接） |
| 其他 | `get_logistics_companies()` | 查询快递公司列表 |
| 其他 | `query_balance()` | 查询商户余额 |
## 使用方法
```python
from xian_guanjia import XianGuanjiaClient
@@ -35,7 +62,7 @@ client = XianGuanjiaClient(
)
# 查询订单列表
result = client.get_order_list(page=1, page_size=20)
result = client.get_order_list(page=1, page_size=20, status=1) # status=1 待发货
print(result)
# 订单发货
@@ -45,12 +72,26 @@ result = client.ship_order(
logistics_company="顺丰速运"
)
# 创建商品
product_data = {
"title": "商品标题",
"price": 29.90,
"category_id": 123,
# 更多字段请参考官方 API 文档
}
result = client.create_product(product_data)
# 上架商品
if result['code'] == 0:
product_id = result['data']['product_id']
client.publish_product(product_id)
# 查询余额
result = client.query_balance()
print(result)
```
### 命令行使用
## 命令行使用
```bash
python scripts/xian_guanjia.py \
@@ -64,26 +105,44 @@ python scripts/xian_guanjia.py \
闲管家使用 MD5 签名认证，本客户端已经自动处理签名，无需手动计算。
详细的签名规则参见 [SKILL.md](SKILL.md) 或 [references/api-docs.md](references/api-docs.md)
**签名流程：**
1. 将请求体 JSON 序列化得到 `body_str`
2. 计算 `body_md5 = md5(body_str)`
3. 拼接签名字符串：`app_id,app_secret,body_md5,timestamp,mch_id,mch_secret`
4. 计算最终签名：`sign = md5(sign_str)`
详细的签名规则参见 [references/api-docs.md](references/api-docs.md)
## 错误码
| 错误码 | 错误描述 |
| --- | --- |
| 0 | 请求成功 |
| 1 | 请求错误（不在定义范围内的错误） |
| 401 | 签名错误 |
| 403 | IP不在白名单 |
| 408 | 时间戳过期 |
| 500 | 系统异常，请重试 |
| 1000 | 商户不存在 |
| 1002 | 余额不足 |
| 1001 | 商户不可用 |
| 1002 | 商户余额不足 |
| 1100 | 商品不存在 |
| 1101 | 商品不可用 |
| 1102 | 商品库存不足 |
| 1200 | 订单不存在 |
完整错误码参见 [references/api-docs.md](references/api-docs.md)
## 官方文档
- 闲管家开放平台：https://open.goofish.pro
- 完整 API 文档：https://s.apifox.cn/3ac13d69-5a38-4536-ae9b-a54001854ef8/llms.txt
## 许可证
MIT License
MIT License - see [LICENSE](LICENSE) for details
## 相关链接
- 闲管家官网：https://goofish.pro
- API 文档：https://apifox.com/apidoc/shared-cf4d53fd-8bb2-41c5-8da3-371ba9a38956/doc-4985015
SKILL.md
+58 -22
View File
@@ -1,16 +1,47 @@
---
name: xian-guanjia
description: 闲管家 API 集成，用于闲鱼自动化发货、订单管理、商品发布。支持通过 API 批量处理订单、自动发货。Use when: (1) 需要操作闲管家 API，(2) 帮用户处理闲鱼订单发货，(3) 查询订单列表和余额，(4) 用户提到"闲管家"、"闲鱼自动发货"。
description: 闲管家 API 集成，用于闲鱼自动化发货、订单管理、商品发布。支持通过 API 批量处理订单、自动发货、商品创建上下架。Use when: (1) 需要操作闲管家 API，(2) 帮用户处理闲鱼订单发货，(3) 查询订单列表和余额，(4) 商品创建上架下架，(5) 用户提到"闲管家"、"闲鱼自动发货"、"闲鱼自动化"。
---
# 闲管家
闲管家 API 客户端，用于闲鱼自动化发货、订单管理和商品发布。
闲管家 API 客户端，用于闲鱼自动化发货、订单管理和商品发布。支持完整的商品管理、订单处理流程。
## API 文档
完整的 API 签名规则和错误码参见 [references/api-docs.md](references/api-docs.md)
## 功能列表
### 用户接口
- `get_xianyu_shops()` - 查询闲鱼店铺列表
### 商品接口
- `get_categories()` - 查询商品类目
- `get_product_attributes(category_id)` - 查询商品属性
- `get_product_list(page, page_size, status)` - 查询商品列表
- `get_product_detail(product_id)` - 查询商品详情
- `get_product_skus(product_id)` - 查询商品规格（仅多规格）
- `create_product(data)` - 创建单个商品
- `create_products_batch(products)` - 批量创建商品
- `publish_product(product_id)` - 上架商品
- `unpublish_product(product_id)` - 下架商品
- `update_product(product_id, data)` - 编辑商品
- `update_stock(product_id, stock, sku_id)` - 编辑库存
- `delete_product(product_id)` - 删除商品
### 订单接口
- `get_order_list(page, page_size, status)` - 获取订单列表
- `get_order_detail(order_id)` - 获取订单详情
- `get_order_cards(order_id)` - 获取订单卡密列表（虚拟商品）
- `ship_order(order_id, logistics_no, logistics_company)` - 订单发货
- `update_order_price(order_id, price)` - 修改订单价格
- `place_order(...)` - 下单（货源对接）
### 其他接口
- `get_logistics_companies()` - 查询快递公司列表
- `query_balance()` - 查询商户余额
## 使用方法
### 初始化客户端
@@ -26,42 +57,47 @@ client = XianGuanjiaClient(
)
```
### 常用操作
### 示例：查询待发货订单
**查询订单列表**
```python
result = client.get_order_list(page=1, page_size=20)
# 获取订单列表（不指定status则返回全部）
result = client.get_order_list(page=1, page_size=20, status=1)
print(result)
```
**查询订单详情**
```python
result = client.get_order_detail(order_id=12345)
```
### 示例：订单发货
**订单发货**
```python
result = client.ship_order(
order_id=12345,
logistics_no="物流单号",
logistics_company="快递公司"
logistics_no="7894561230",
logistics_company="顺丰速运"
)
```
**下单（货源对接）**
### 示例：创建并上架商品
```python
result = client.place_order(
goods_no="商品编号",
goods_type=1, # 1-普通 2-虚拟
buyer_nick="买家昵称",
buyer_id="买家ID",
order_no="管家订单号",
price=29.90
)
# 创建商品
product_data = {
"title": "商品标题",
"price": 29.90,
"category_id": 123,
# ... 其他必填字段见API文档
}
result = client.create_product(product_data)
if result['code'] == 0:
product_id = result['data']['product_id']
# 上架商品
client.publish_product(product_id)
```
**查询余额**
### 示例：查询余额
```python
result = client.query_balance()
print(result)
```
## 响应格式
references/api-docs.md
+36 -3
View File
@@ -4,6 +4,42 @@
生产环境地址：https://open.goofish.pro
## 相关文档
完整的 API 列表：
### 用户接口
- [查询闲鱼店铺](https://s.apifox.cn/3ac13d69-5a38-4536-ae9b-a54001854ef8/api-93586388.md)
### 商品接口
- [查询商品类目](https://s.apifox.cn/3ac13d69-5a38-4536-ae9b-a54001854ef8/api-97448687.md)
- [查询商品属性](https://s.apifox.cn/3ac13d69-5a38-4536-ae9b-a54001854ef8/api-95804125.md)
- [查询商品列表](https://s.apifox.cn/3ac13d69-5a38-4536-ae9b-a54001854ef8/api-93586381.md)
- [查询商品详情](https://s.apifox.cn/3ac13d69-5a38-4536-ae9b-a54001854ef8/api-93586380.md)
- [查询商品规格](https://s.apifox.cn/3ac13d69-5a38-4536-ae9b-a54001854ef8/api-165788779.md) - 仅多规格商品才能查询
- [创建商品（单个）](https://s.apifox.cn/3ac13d69-5a38-4536-ae9b-a54001854ef8/api-93586377.md)
- [创建商品（批量）](https://s.apifox.cn/3ac13d69-5a38-4536-ae9b-a54001854ef8/api-93586378.md)
- [上架商品](https://s.apifox.cn/3ac13d69-5a38-4536-ae9b-a54001854ef8/api-95038267.md)
- [下架商品](https://s.apifox.cn/3ac13d69-5a38-4536-ae9b-a54001854ef8/api-93586382.md)
- [编辑商品](https://s.apifox.cn/3ac13d69-5a38-4536-ae9b-a54001854ef8/api-93586379.md)
- [编辑库存](https://s.apifox.cn/3ac13d69-5a38-4536-ae9b-a54001854ef8/api-93586384.md)
- [删除商品](https://s.apifox.cn/3ac13d69-5a38-4536-ae9b-a54001854ef8/api-93586383.md)
### 订单接口
- [查询订单列表](https://s.apifox.cn/3ac13d69-5a38-4536-ae9b-a54001854ef8/api-95074856.md)
- [查询订单详情](https://s.apifox.cn/3ac13d69-5a38-4536-ae9b-a54001854ef8/api-93586385.md)
- [订单卡密列表](https://s.apifox.cn/3ac13d69-5a38-4536-ae9b-a54001854ef8/api-97142794.md)
- [订单物流发货](https://s.apifox.cn/3ac13d69-5a38-4536-ae9b-a54001854ef8/api-93586386.md)
- [订单修改价格](https://s.apifox.cn/3ac13d69-5a38-4536-ae9b-a54001854ef8/api-333703388.md)
### 推送回调接口
- [商品回调通知](https://s.apifox.cn/3ac13d69-5a38-4536-ae9b-a54001854ef8/api-98676477.md) - 请商家自行在上架商品和编辑商品接口填写真实的推送地址
- [商品推送通知](https://s.apifox.cn/3ac13d69-5a38-4536-ae9b-a54001854ef8/api-108700789.md) - 请商家自行在闲管家的开放平台填写真实的推送地址
- [订单推送通知](https://s.apifox.cn/3ac13d69-5a38-4536-ae9b-a54001854ef8/api-93586387.md) - 请商家自行在闲管家的开放平台填写真实的推送地址
### 其他接口
- [查询快递公司](https://s.apifox.cn/3ac13d69-5a38-4536-ae9b-a54001854ef8/api-97431955.md) - 如列表内没有需要的快递公司，可以联系闲管家技术支持补充
## 相关下载
- 闲管家省市区：
@@ -14,9 +50,6 @@
- https://file.goofish.pro/doc/商品异常状态码.xlsx
- https://file.goofish.pro/doc/商品异常状态码.sql
- 闲管家虚拟货源标准接口：
- https://apifox.com/apidoc/shared-cf4d53fd-8bb2-41c5-8da3-371ba9a38956/doc-4985015
## 注意事项
1. 闲管家所有参数都是强校验，需要严格按照文档的字段类型传参+返回
scripts/xian_guanjia.py
+233 -14
View File
@@ -8,7 +8,7 @@ import hashlib
import time
import json
import requests
from typing import Dict, Any, Optional
from typing import Dict, Any, Optional, List
class XianGuanjiaClient:
@@ -92,21 +92,214 @@ class XianGuanjiaClient:
return response.json()
def get_order_list(self, page: int = 1, page_size: int = 20) -> Dict[str, Any]:
# ==================== 用户接口 ====================
def get_xianyu_shops(self) -> Dict[str, Any]:
"""
查询闲鱼店铺列表
Returns:
店铺列表响应
"""
return self.request('POST', '/api/user/shops', {})
# ==================== 商品接口 ====================
def get_categories(self) -> Dict[str, Any]:
"""
查询商品类目
Returns:
类目列表响应
"""
return self.request('POST', '/api/product/categories', {})
def get_product_attributes(self, category_id: int) -> Dict[str, Any]:
"""
查询商品属性
Args:
category_id: 类目ID
Returns:
属性列表响应
"""
return self.request('POST', '/api/product/attributes', {
'category_id': category_id
})
def get_product_list(self, page: int = 1, page_size: int = 20, status: Optional[int] = None) -> Dict[str, Any]:
"""
查询商品列表
Args:
page: 页码
page_size: 每页数量
status: 商品状态 (可选) 1-上架 2-下架
Returns:
商品列表响应
"""
body = {
'page': page,
'page_size': page_size
}
if status is not None:
body['status'] = status
return self.request('POST', '/api/product/list', body)
def get_product_detail(self, product_id: int) -> Dict[str, Any]:
"""
查询商品详情
Args:
product_id: 商品ID
Returns:
商品详情响应
"""
return self.request('POST', '/api/product/detail', {
'product_id': product_id
})
def get_product_skus(self, product_id: int) -> Dict[str, Any]:
"""
查询商品规格（仅多规格商品）
Args:
product_id: 商品ID
Returns:
规格列表响应
"""
return self.request('POST', '/api/product/skus', {
'product_id': product_id
})
def create_product(self, data: Dict[str, Any]) -> Dict[str, Any]:
"""
创建单个商品
Args:
data: 商品数据（包含标题、图片、价格等完整信息）
Returns:
创建响应
"""
return self.request('POST', '/api/product/create', data)
def create_products_batch(self, products: List[Dict[str, Any]]) -> Dict[str, Any]:
"""
批量创建商品
Args:
products: 商品数据列表
Returns:
创建响应
"""
return self.request('POST', '/api/product/create_batch', {
'products': products
})
def publish_product(self, product_id: int) -> Dict[str, Any]:
"""
上架商品
Args:
product_id: 商品ID
Returns:
上架响应
"""
return self.request('POST', '/api/product/publish', {
'product_id': product_id
})
def unpublish_product(self, product_id: int) -> Dict[str, Any]:
"""
下架商品
Args:
product_id: 商品ID
Returns:
下架响应
"""
return self.request('POST', '/api/product/unpublish', {
'product_id': product_id
})
def update_product(self, product_id: int, data: Dict[str, Any]) -> Dict[str, Any]:
"""
编辑商品
Args:
product_id: 商品ID
data: 更新的商品数据
Returns:
更新响应
"""
body = {'product_id': product_id}
body.update(data)
return self.request('POST', '/api/product/update', body)
def update_stock(self, product_id: int, stock: int, sku_id: Optional[int] = None) -> Dict[str, Any]:
"""
编辑库存
Args:
product_id: 商品ID
stock: 库存数量
sku_id: SKU ID（多规格商品需要）
Returns:
更新响应
"""
body = {
'product_id': product_id,
'stock': stock
}
if sku_id is not None:
body['sku_id'] = sku_id
return self.request('POST', '/api/product/update_stock', body)
def delete_product(self, product_id: int) -> Dict[str, Any]:
"""
删除商品
Args:
product_id: 商品ID
Returns:
删除响应
"""
return self.request('POST', '/api/product/delete', {
'product_id': product_id
})
# ==================== 订单接口 ====================
def get_order_list(self, page: int = 1, page_size: int = 20, status: Optional[int] = None) -> Dict[str, Any]:
"""
获取订单列表
Args:
page: 页码
page_size: 每页数量
status: 订单状态 (可选)
Returns:
订单列表响应
"""
return self.request('POST', '/api/order/list', {
body = {
'page': page,
'page_size': page_size
})
}
if status is not None:
body['status'] = status
return self.request('POST', '/api/order/list', body)
def get_order_detail(self, order_id: int) -> Dict[str, Any]:
"""
@@ -122,14 +315,28 @@ class XianGuanjiaClient:
'order_id': order_id
})
def get_order_cards(self, order_id: int) -> Dict[str, Any]:
"""
获取订单卡密列表（虚拟商品）
Args:
order_id: 订单ID
Returns:
卡密列表响应
"""
return self.request('POST', '/api/order/cards', {
'order_id': order_id
})
def ship_order(self, order_id: int, logistics_no: str, logistics_company: str) -> Dict[str, Any]:
"""
订单发货
订单物流发货
Args:
order_id: 订单ID
logistics_no: 物流单号
logistics_company: 物流公司
logistics_company: 物流公司代码/名称
Returns:
发货响应
@@ -140,20 +347,20 @@ class XianGuanjiaClient:
'logistics_company': logistics_company
})
def get_product_list(self, page: int = 1, page_size: int = 20) -> Dict[str, Any]:
def update_order_price(self, order_id: int, price: float) -> Dict[str, Any]:
"""
获取商品列表
修改订单价格
Args:
page: 页码
page_size: 每页数量
order_id: 订单ID
price: 新价格
Returns:
商品列表响应
修改响应
"""
return self.request('POST', '/api/product/list', {
'page': page,
'page_size': page_size
return self.request('POST', '/api/order/update_price', {
'order_id': order_id,
'price': price
})
def place_order(self, goods_no: str, goods_type: int, buyer_nick: str,
@@ -181,6 +388,18 @@ class XianGuanjiaClient:
'price': price
})
# ==================== 其他接口 ====================
def get_logistics_companies(self) -> Dict[str, Any]:
"""
查询快递公司列表
Returns:
快递公司列表响应
如果列表内没有需要的快递公司，可以联系闲管家技术支持补充
"""
return self.request('POST', '/api/logistics/companies', {})
def query_balance(self) -> Dict[str, Any]:
"""
查询商户余额