cmroubao/erp-connector/README.md

顺运宝 ERP Connector

内部只读适配器：保持顺运宝验证码/Cookie 会话，按完整单号或最多 7 个自然日的 创建日期闭区间查询货运列表和详情，再输出不含收件人、电话、地址、Cookie、JWT 或原始响应的规范化 JSON。

协议客户端基于同一开发机上已经用本地 HAR 验证的 shunyunbaoerp 0.1.0 代码收敛； 本目录不包含 HAR、真实响应、账号、密码或订单号。

安装和测试

Set-Location erp-connector
python -m pip install -e ".[api,dev]"
pytest

测试只使用伪响应，不访问线上 ERP。

启动

$env:SHUNYUNBAO_USERNAME = "your_username"
$env:SHUNYUNBAO_PASSWORD = "your_password"
$env:SHUNYUNBAO_SERVICE_API_KEY = "at-least-32-utf8-bytes"
..\scripts\start-erp-connector.bat

服务固定监听 127.0.0.1:8091 并关闭访问日志。不要把环境变量写入脚本、Git 或命令行 参数；生产前应改用受控秘密注入。

受控会话

1. GET /v1/session/captcha，请求头携带 X-API-Key。

2. 人员查看验证码后调用 POST /v1/session/login：

   {"captcha_code":"abcd"}
   

3. 调用 POST /v1/freight/query：

   {"mode":"ORDER_NUMBER","order_number":"完整单号"}
   

   日期查询严格使用 Asia/Shanghai 的 YYYY-MM-DD：

   {
     "mode":"CREATED_RANGE",
     "created_from":"2026-07-22",
     "created_to":"2026-07-28"
   }
   

Connector 不自动 OCR 绕过验证码。服务重启或 ERP 会话过期后需重新执行前两步。

输出边界

响应只包含：

• external_stock_id、受控来源单号、店铺、ERP 时间和原始状态。
• 全部商品的 external_item_id、标题、规格、SKU、数量、productThumb 引用和状态。

productThumb 当前可能是数字引用，不是公开图片 URL。下游必须保持 NEEDS_IMAGE， 不能拼接 URL 或抓取未知主机。