领星ERP OpenAPI 客户端

要解决的问题

领星 ERP 开放平台（https://openapi.lingxing.com）开放了订单、广告、采购、库存、财务利润等数据的接口，但直接对接有几个实际痛点：签名有效期仅 2 分钟，必须每个请求实时生成且传输时 URL 编码；access_token 的获取、缓存与过期续约要自己维护；限流按 appId+接口URL 维度的令牌桶控制；公共参数必须放 URL query，POST 业务参数放 JSON body。这个 skill 把这些协议细节封装成 Python 客户端，让你专注取数，而不是反复处理签名和 Token。

核心能力

• 凭证与签名自动化：Token 的获取、缓存、过期前 5 分钟自动续约全部由客户端处理；签名每次请求实时生成，绝不复用时间戳。
• 统一请求封装：4 个公共参数（access_token/app_key/timestamp/sign）固定放 URL query，业务参数走 JSON body。
• 接口目录：references/api_endpoints.md 给出常用接口的 Path、方法与令牌桶容量；references/full_api_index.md 是 700+ 接口的官方导航镜像，找不到目标时先定位文档页再抓原始文档。
• AES 加密：优先用 pycryptodome，未安装时自动回退到系统 openssl 命令。

工作流程

1. 判断凭证状态：未提供 AppID/AppSecret 时，引导用户在领星后台【设置】→【业务配置】→【全局】→【开放接口】获取，并把调用方公网 IP 加入白名单；IP 不固定（家用网络/云函数）时提示部署固定出口网关。
2. 调用客户端发起请求，Token 管理无需手动干预。
3. 按需查阅接口目录：广告报表类接口（prefix /pb/openapi/newad/）需带请求头 X-API-VERSION: 2，分页用 offset/length；利润报表类接口 prefix 为 /bd/profit/...。
4. 可选烟测链路：Token 获取 → 店铺列表 → 订单列表，输出 JSON 报告，exit 0 为全部通过。

适用边界与注意点

• 签名只活 2 分钟：客户端已实时生成，不要自行缓存签名或复用时间戳。
• 限流：容量为 1 的接口请求间隔 ≥ 1 秒；批量取数用分页逐页拉取，禁止并发轰炸；遇到错误码 3001008 做指数退避重试。
• 先取 sid：业务接口大多需要店铺 sid，第一步先调店铺列表建立映射；广告接口 sid 与 profile_id 二选一。
• 只读优先：定位为数据拉取底座，调用写操作接口（如创建采购单）前必须向用户明确确认。
• 凭证安全：AppSecret 不得写入代码、日志，也不要回显给用户。