SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场linkfox-shopee-store-returns

linkfox-shopee-store-returns

营销与增长

查看项目

更新于 10-16 09:21

技能介绍

用途

本技能用于操作 Shopee（虾皮）开放平台 Returns（退货）模块，覆盖该模块的 15 个 API，针对店铺的退货、退款与争议场景。它属于 linkfox-shopee-store-auth 同系列，需先完成选店授权后使用。

主要能力

技能内提供 15 个 Shopee Returns API，均为店铺级接口，通常需要传入 shopId：

  • get_return_list：获取退货列表（支持 page_no、page_size）
  • get_return_detail：获取退货详情（传入 return_sn）
  • get_available_solutions：获取可用处理方案（传入 return_sn）
  • confirm：确认退货
  • offer：提出方案
  • accept_offer：接受方案
  • dispute：发起争议
  • cancel_dispute：取消争议
  • get_return_dispute_reason：获取退货争议原因
  • convert_image：图片转换
  • upload_proof：上传凭证
  • query_proof：查询凭证
  • get_shipping_carrier：获取物流承运商
  • upload_shipping_proof：上传发货凭证
  • get_reverse_tracking_info：获取逆向物流跟踪信息

另提供通用入口 returns_api.py（JSON 中包含 api 字段即可调用），以及共享模块 _shopee_returns_common.py、_returns_endpoints.py、_returns_api_runner.py。

各 API 的入参与响应细节收录在 references/apis/ 目录下，SKILL 正文仅保留索引。

使用方式

  1. 前置条件：先运行 python scripts/check_auth_dependency.py，若退出码为 42，需先安装并授权 linkfox-shopee-store-auth。授权与令牌逻辑不在本技能内实现。
  2. 调用链路：developerProxy（通过 shopId/merchantId 选店，服务端注入令牌）→ 紫鸟 shopee-proxy → Shopee API。请求 path 须以 api/v2/returns/... 形式传入。
  3. API 端点方式：POST /shopee/developerProxy，不同操作通过请求体区分。
  4. Python 脚本方式：python scripts/<脚本名>.py '<JSON 参数>' [--inline]。
  5. 参数放置约定：GET 请求将业务参数放在 JSON 顶层；POST 复杂接口传入 body。
  6. 调用后先看 developerProxy.httpStatus，再读取 *Response 字段。
  7. 每个脚本的 docstring 内含官方文档 URL（module=102）。

输出与数据读取

脚本默认将完整响应写入 <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/<skill-name>-<timestamp>.json。其中 <cwd> 为脚本执行时的工作目录，<session> 取自环境变量 SESSION_ID；禁止写入 /tmp，当前目录不可写则报错。

  • 响应体 ≤ 8 KB：落盘后将完整 JSON 打印到 stdout。
  • 响应体 > 8 KB：落盘后 stdout 只输出摘要（顶层字段、常见计数如 total/costToken、最大列表字段长度加前 3 条样本）。
  • 加 --inline 可强制全量打印到 stdout，同时仍会落盘。

读数据建议先看摘要判断是否足够，需要具体字段时优先用 jq 或 ConvertFrom-Json 从保存的 json 文件按需抽取，避免整份 JSON 进入上下文。

成本与异常约束

本工具会消耗算力；失败或空结果不得自动更换关键词、翻页或连续试探；需要继续检索时，应先向用户说明会产生额外消耗。

出现以下情况时，按 references/onboarding.md 引导解决：未配置 LINKFOX_AGENT_API_KEY 或 LINKFOXAGENT_API_KEY；响应 401 或 402 状态码；响应提示算力或余额不足（含“算力余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值”或类似含义）。

适用场景

  • 查询店铺退货列表与详情
  • 处理退货：获取可用方案后确认或提出方案，必要时发起或取消争议
  • 凭证管理：上传凭证、查询凭证、图片转换
  • 逆向物流：获取退货物流承运商、上传发货凭证、查询逆向物流跟踪信息

典型流程为 get_return_list → get_return_detail → confirm / offer / dispute。

限制与边界

  • 店铺授权请使用 linkfox-shopee-store-auth。
  • 订单查询与取消请使用 linkfox-shopee-store-orders。
  • 正向物流发货请使用 linkfox-shopee-store-logistics。
  • 商品 listing 请使用 linkfox-shopee-store-product。
  • 本技能不消耗算力。

官方参考：Returns 模块索引为 v2.returns.get_return_list；模块总览与 Feedback 见 references/api.md。