137 lines
3.5 KiB
Markdown
137 lines
3.5 KiB
Markdown
---
|
||
name: xian-guanjia
|
||
description: 闲管家 API 集成，用于闲鱼自动化发货、订单管理、商品发布。支持通过 API 批量处理订单、自动发货、商品创建上下架。Use when: (1) 需要操作闲管家 API，(2) 帮用户处理闲鱼订单发货，(3) 查询订单列表和余额，(4) 商品创建上架下架，(5) 用户提到"闲管家"、"闲鱼自动发货"、"闲鱼自动化"。
|
||
---
|
||
|
||
# 闲管家
|
||
|
||
闲管家 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()` - 查询商户余额
|
||
|
||
## 使用方法
|
||
|
||
### 初始化客户端
|
||
|
||
```python
|
||
from scripts.xian_guanjia import XianGuanjiaClient
|
||
|
||
client = XianGuanjiaClient(
|
||
app_id="your_app_id",
|
||
app_secret="your_app_secret",
|
||
mch_id="your_mch_id",
|
||
mch_secret="your_mch_secret"
|
||
)
|
||
```
|
||
|
||
### 示例：查询待发货订单
|
||
|
||
```python
|
||
# 获取订单列表（不指定status则返回全部）
|
||
result = client.get_order_list(page=1, page_size=20, status=1)
|
||
print(result)
|
||
```
|
||
|
||
### 示例：订单发货
|
||
|
||
```python
|
||
result = client.ship_order(
|
||
order_id=12345,
|
||
logistics_no="7894561230",
|
||
logistics_company="顺丰速运"
|
||
)
|
||
```
|
||
|
||
### 示例：创建并上架商品
|
||
|
||
```python
|
||
# 创建商品
|
||
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)
|
||
```
|
||
|
||
## 响应格式
|
||
|
||
所有请求返回格式：
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"msg": "OK",
|
||
"data": { ... }
|
||
}
|
||
```
|
||
|
||
- `code = 0` 表示成功
|
||
- 其他值表示失败，错误信息在 `msg`
|
||
|
||
## 错误码
|
||
|
||
详见 [references/api-docs.md](references/api-docs.md) 中的全局错误码说明。
|
||
|
||
## 命令行使用
|
||
|
||
```bash
|
||
python scripts/xian_guanjia.py \
|
||
--app-id YOUR_APP_ID \
|
||
--app-secret YOUR_APP_SECRET \
|
||
--mch-id YOUR_MCH_ID \
|
||
--mch-secret YOUR_MCH_SECRET
|
||
```
|
||
|
||
## 依赖
|
||
|
||
需要安装 requests：
|
||
```bash
|
||
pip install requests
|
||
```
|