领星ERP OpenAPI 客户端 Skill

概述

提供领星ERP开放平台（https://openapi.lingxing.com）的完整 Python 接入能力：Token 管理、签名生成、统一请求封装。适用于订单查询、广告分析、采购/库存、财务利润等数据拉取场景。

前置条件（缺一不可）

AppID / AppSecret：超级管理员登录领星ERP →【设置】→【业务配置】→【全局】→【开放接口】获取
IP 白名单：同一页面配置调用方公网IP（查公网IP：https://toolbox.lingxing.com/api/getIp ）

环境变量：

export LINGXING_APP_ID="your_app_id"
export LINGXING_APP_SECRET="your_app_secret"
# 可选：token 缓存文件路径（默认 skill 目录下 runtime/token_cache.json）
export LINGXING_TOKEN_CACHE="/path/to/token_cache.json"

Python 依赖：requests；AES 加密优先用 pycryptodome（pip install pycryptodome），未安装时自动回退到系统 openssl 命令

工作流程

第 1 步：判断凭证状态

若用户未提供 AppID/AppSecret → 引导用户按上述「前置条件」第 1、2 步操作，此为硬性门槛，无法绕过
若用户 IP 不固定（家用网络/云函数）→ 提示需部署固定出口网关并加入白名单

第 2 步：调用客户端

import sys
sys.path.insert(0, "<skill目录>/scripts")
from lingxing_client import LingxingClient

client = LingxingClient()

# GET 示例：亚马逊店铺列表（几乎所有接口的前置，取 sid）
result = client.get("/erp/sc/data/seller/lists")

# POST 示例：订单列表（近7天）
result = client.post("/erp/sc/data/mws/orders", {
    "start_date": "2026-08-09 00:00:00",
    "end_date": "2026-08-16 23:59:59",
    "page": 1,
    "page_size": 50,
})

# 需要元数据（total、request_id）时用 request()
body = client.request("POST", "/erp/sc/data/mws/orders", data={...})

Token 的获取、缓存、过期续约（过期前5分钟自动刷新）均由客户端自动处理，无需手动管理。

第 3 步：按需查阅接口目录

调用具体接口前，读取 references/api_endpoints.md 查找对应模块的 Path、方法与令牌桶容量（路径已从官方文档核实）。若目标接口不在其中，读取 references/full_api_index.md（官方导航完整镜像，700+ 接口）找到文档页路径，然后直接抓取原始文档：

curl -s "https://apidoc.lingxing.com/docs/<文档页路径>.md"

广告报表类接口（prefix /pb/openapi/newad/）调用时需带请求头 X-API-VERSION: 2，分页用 offset/length；利润报表类接口 prefix 为 /bd/profit/...。

第 4 步：验证链路（可选）

export LINGXING_APP_ID="..." LINGXING_APP_SECRET="..."
python3 <skill目录>/scripts/smoke_check.py

烟测链路：Token 获取 → 店铺列表(GET) → 订单列表(POST)，输出 JSON 报告，exit 0 为全部通过。

关键规则（务必遵守）

签名有效期仅 2 分钟——客户端每次请求实时生成，绝不缓存签名或复用时间戳；sign 传输时必须 URL 编码
公共参数位置——4 个公共参数（access_token/app_key/timestamp/sign）始终放 URL query；POST 业务参数放 JSON body（Content-Type: application/json）
空值规则——value 为空字符串不参与签名拼接，value 为 null 参与（格式 key=）；body 内嵌套集合须转为 JSON 字符串参与签名（客户端已自动处理）
限流——令牌桶维度为 appId+接口URL；容量 1 的接口请求间隔 ≥ 1 秒；批量取数用分页逐页拉取，禁止并发轰炸；超限错误码 3001008，指数退避重试
先取 sid——业务接口大多需要店铺 sid，第一步先调店铺列表建立映射；广告接口 sid 与 profile_id 二选一
分页两套并存——page/page_size 与 offset/length，以各接口文档页为准
只读优先——本 skill 定位为数据拉取底座；调用写操作接口（如新增品牌、创建采购单）前必须向用户明确确认
凭证安全——AppSecret 不得写入代码、日志或输出给用户回显

排错指引

遇到错误时读取 references/authentication.md 第 7 节「常见错误排查」。要点：

| 现象 | 原因 | |------|------| | app not exist | appId 错误或 secret 已重置 | | 签名错误 | 时间戳超 2 分钟 / 排序拼接有误 | | IP 拒绝 | 调用方公网 IP 未加白名单 | | token 失效 | 已过期，客户端会自动续约；连续失败则重新获取 |

排查时把响应中的 request_id 保留，可提供给领星技术支持定位。

资源清单

lingxing-erp-openapi/
├── SKILL.md                       # 本文档
├── scripts/
│   ├── lingxing_client.py         # 核心客户端：Token/签名/请求封装（支持自定义header）
│   └── smoke_check.py             # 烟测脚本（Token→店铺→订单）
└── references/
    ├── authentication.md          # 认证、签名7步、官方错误码、错误排查
    ├── api_endpoints.md           # 四大模块接口速查表（官方文档核实）
    └── full_api_index.md          # 官方导航完整镜像（700+ 全量接口索引）

官方资源

API 文档主站：https://apidoc.lingxing.com
签名在线测试：https://apidoc.lingxing.com/docs/TestSign/signature.html
公网IP自查：https://toolbox.lingxing.com/api/getIp
官方 SDK 下载（Go/PHP/Java/Node/Python）：https://apidoc.lingxing.com/docs/Guidance/newInstructions 第6节