xian-guanjia

---

name: xian-guanjia description: 闲管家 API 集成，用于闲鱼自动化发货、订单管理、商品发布。支持通过 API 批量处理订单、自动发货、商品创建上下架。Use when: (1) 需要操作闲管家 API，(2) 帮用户处理闲鱼订单发货，(3) 查询订单列表和余额，(4) 商品创建上架下架，(5) 用户提到"闲管家"、"闲鱼自动发货"、"闲鱼自动化"。

闲管家

闲管家 API 客户端，用于闲鱼自动化发货、订单管理和商品发布。支持完整的商品管理、订单处理流程。

API 文档

完整的 API 签名规则和错误码参见 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() - 查询商户余额

使用方法

初始化客户端

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"
)

示例：查询待发货订单

# 获取订单列表（不指定status则返回全部）
result = client.get_order_list(page=1, page_size=20, status=1)
print(result)

示例：订单发货

result = client.ship_order(
    order_id=12345,
    logistics_no="7894561230",
    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)

响应格式

所有请求返回格式：

{
  "code": 0,
  "msg": "OK",
  "data": { ... }
}

• code = 0 表示成功
• 其他值表示失败，错误信息在 msg

错误码

详见 references/api-docs.md 中的全局错误码说明。

命令行使用

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：

pip install requests