接口文档
ShipBest → 领星OMS 订单同步（Chrome 扩展）· 安装与使用手册
2026-11-03
ShipBest → 领星OMS 订单同步（Chrome 扩展）· 安装与使用手册
把 ShipBest（https://oms.shipbest.com/orders/list）里已打单的订单，同步到领星 OMS（https://oms.xlwms.com）的「一件代发 · 新建出库单」页面（https://oms.xlwms.com/warehouse/packet/create），自动填表并上传面单文件。
插件只填不提交：填完后由你人工核对，再自己点领星的保存/提交。
| 项目 | 内容 |
|---|---|
| 扩展名 | ShipBest → 领星OMS 订单同步 |
| 当前版本 | 0.1.11 |
| 适用浏览器 | Chrome / Edge 111 及以上（其他新版 Chromium 内核浏览器同样可用） |
| 安装方式 | 开发者模式「加载已解压的扩展程序」 |
一、它做了什么
① ShipBest 订单列表页 /orders/list
页内弹框自动采集：收件人 / 运单号 / 承运商 / 面单 / SKU
│
├─ 勾选订单 →「同步到领星OMS (n)」
│ ├─ 订单写入待填充队列
│ └─ 自动打开领星「新建出库单」页
│
② 领星建单页 /warehouse/packet/create
右下角面板列出待填充订单
├─ 进页自动预设：仓库、物流渠道
└─ 点某单的「填充」→ 填字段 + 自动上传面单 → 行状态变「已填充」
│
③ 人工核对（收件人 / 承运商 / 渠道 / SKU / 面单是否本单）
└─ 你自己点领星的保存 / 提交建单
整条链路上，插件不会点任何「保存」「提交」「确认下单」按钮。
下载插件
ShipBest → 领星OMS 订单同步 Chrome插件下载
二、安装
1. 准备扩展目录
以下任一目录都可用（内容一致）：
- 仓库内：
browser-extension/shipbest-lingxing - 桌面副本：
~/Desktop/shipbest-lingxing
扩展目录里必须直接有
manifest.json这一层。不要双击manifest.json，也不要打包成 zip 安装——必须用下面的「加载已解压」方式。
2. 在 Chrome 里加载
-
地址栏打开
chrome://extensions -
右上角打开 开发者模式
-
点 加载已解压的扩展程序
-
选择扩展目录（例如
~/Desktop/shipbest-lingxing） -
点浏览器工具栏的拼图图标，把「ShipBest → 领星OMS」固定到工具栏（图标上的数字 = 待填充单数）
Edge 同理：edge://extensions → 打开「开发人员模式」→「加载解压缩的扩展」。
3. 登录两个站点
插件不做登录、不保存账号密码，只复用你浏览器里已有的登录状态：
- 打开并登录 ShipBest 订单列表
https://oms.shipbest.com/orders/list - 打开并登录领星 OMS
https://oms.xlwms.com
插件会在你正常使用 ShipBest 时，从页面自身的请求里读取登录令牌（JWT），仅存本机浏览器，用于后续同源取单。
4. 升级 / 重装
- 用新版本文件覆盖扩展目录
chrome://extensions→ 本扩展卡片 → 重新加载- 刷新已经打开的 ShipBest / 领星页面
第 3 步很关键：扩展重载前打开的标签页里没有新脚本，表现为「采集不到」「面板不更新」「Receiving end does not exist」。
5. 权限说明
| 权限 | 用途 |
|---|---|
storage |
存订单队列、设置、最近一次订单缓存（全部仅本机浏览器） |
tabs |
找到 / 打开 ShipBest 与领星标签页，同步后自动打开建单页 |
clipboardWrite |
「复制诊断」「复制面单链接」 |
https://*.shipbest.com/* |
读取 ShipBest 订单接口（同源，带你自己的登录态） |
https://oms.xlwms.com/* |
在领星建单页注入填充面板 |
| 可选：任意域名（默认不申请） | 仅用于下载面单文件（面单常放在对象存储域名上）。需要时在设置页点「授权面单下载域名」，或点面板上的「授权并重试」 |
三、首次配置
入口：右键工具栏上的扩展图标 → 选项；或 chrome://extensions → 本扩展「扩展程序选项」。（工具栏弹窗里不再放「设置」按钮。）
建议只确认这几项，其余保持默认：
| 设置项 | 默认值 | 说明 |
|---|---|---|
| 新建出库单地址 | https://oms.xlwms.com/warehouse/packet/create |
同步完成后自动打开的页面（一件代发建单页）。旧版本默认的 /warehouse/create 会在升级后首次读取设置时自动换成新地址（自己填过的地址不动） |
| 物流渠道 | 上传物流面单 |
建单页「物流渠道」固定选这一项（卖家使用 ShipBest 面单） |
| 固定仓库名 | 留空 | 留空 = 自动：优先用你上次选过的仓库，否则选第一个 |
| 填物流承运商 | 开启 | 关闭后承运商留空，由你手选 |
设置页底部工具按钮：授权面单下载域名 / 清空待填充队列 / 清空订单缓存 / 恢复默认（只重置设置，不动队列和登录态）。
完整设置项见 第六节 设置项全表。
四、使用
第 1 步：在 ShipBest 采集订单
- 打开
https://oms.shipbest.com/orders/list - 页面右下角自动弹出「ShipBest → 领星OMS」面板，并自动采集一次
- 面板副标题显示采集概况，例如
38/1200 单 · 面单 36 · 已同步 12 · 缺 2面单= 有面单地址的单数已同步= 已推送进领星队列的单数缺= 缺收件人 / 承运商 / SKU / 运单号中任意一项的单数
- 面板为空或列表有单但采不到：
- 点底栏 「采集本页」 再试
- 点工具条 「复制诊断」，把内容发我，可据此校准字段
- 出现「缺 N」时点工具条 「补齐详情」：插件逐单调详情接口补全字段（承运商、收件人、SKU、面单多在详情里）；失败原因会直接写在面板上（
详情失败：…）
面板工具条：全选复选框、已选 n 单、补齐详情、（有缺字段时）复制诊断。
面板底栏只有两个按钮：采集本页、同步到领星OMS (n)。
第 2 步：勾选并同步到领星
- 勾选要处理的订单（点整行即勾选；工具条复选框是全选）
- 点底栏 「同步到领星OMS (n)」
- 插件把订单写入待填充队列，并自动打开领星「新建出库单」页（地址取设置里的「新建出库单地址」）
同一单重复同步不会产生重复条目，只会更新数据；已填充过的单保持「已填充」状态，避免重复填。
第 3 步：在领星逐单填充
进入建单页后，右下角出现面板「打单同步 · 领星OMS」，副标题是 队列 N 单 · 待填充 M。
进页会自动预设（可在设置里关）：仓库（上次选过的仓库，否则第一个）、物流渠道（上传物流面单）。承运商不预选，跟着字段填充走。
对每一单：
- 点该行的 「填充」（已填过的显示「重新填充」）
- 插件按顺序执行：
- 清掉上一单留下的面单文件（防止旧面单跟着新单提交）
- 预设仓库、物流渠道
- 逐字段填充：收件人、地址、电话、州/市/邮编、重量尺寸、SKU、客户订单号、运单号、物流承运商、备注等
- 填充后自动上传面单（可在设置里关）
- 行状态变化：
待填充→填充中→已填充，并留在列表原位 - 行上出现结果摘要：
上次结果：填充 18 · 无值 0 · 未找到控件 0 · 失败 1 - 有失败字段时，行内直接显示红字原因，例如：
· 物流承运商：下拉里没有匹配的选项，页面可选：GOFO / GOFO Ground（订单值：GOFO Express） - 面板「填充中」时不要切单
行内按钮与标签
| 元素 | 含义 |
|---|---|
| 填充 / 重新填充 | 填这一单；已填过的可重填（换单前会清空上一单面单） |
| 传面单 / 重传面单 | 只重传这一单的面单，不重填字段 |
待填充 |
还在队列里，没填过 |
填充中 |
正在填（此时不要切单） |
已填充 |
填过了，可核对提交 |
面单已传 |
面单文件已写入领星上传控件 |
有面单 |
订单有面单地址，但还没上传 |
无SKU |
这一单没有商品明细，需先回 ShipBest 补齐 |
GOFO Express 这类紫底标签 |
订单的物流承运商 |
面单上传失败时
面板顶部出现红色提示块，写明具体原因（未授权 / 存储异常 / 签名过期等），并给出按钮：
- 授权并重试（域名未授权时）：授予该面单域名权限后自动重试上传
- 复制面单链接：手工下载面单
- 关闭提示：收起提示块
第 4 步：人工核对并提交
插件只填表单字段与面单文件，最终提交由你完成。建议核对：收件人 / 电话 / 邮编、承运商、物流渠道、SKU 与数量、面单是否为本单。
五、三处界面说明
1. 工具栏弹窗（点扩展图标）
显示 ShipBest 登录态与队列概况（队列 N 单：待填充 M，已填充 K。），只保留三个按钮：
- 打开 ShipBest 订单列表
- 打开领星新建一件代发页面
- 清空队列（二次确认：只清待填充项，已填充记录保留，避免同一单被重复填）
设置入口不在弹窗里：右键工具栏图标选「选项」，或 chrome://extensions → 本扩展「扩展程序选项」。
2. ShipBest 页内弹框（右下角，宽 470）
- 底栏：采集本页、同步到领星OMS (n)
- 工具条：全选、已选计数、补齐详情、（有缺字段时）复制诊断
- 每行显示：订单号、运单号、承运商、收件人摘要，以及标签
有面单 / 无面单、SKU n、已同步 - 头部：
−折叠、×隐藏（隐藏后刷新页面恢复）；面板可拖动，位置会记住 - 空态会给出 复制诊断 与 重新采集 按钮
3. 领星页内面板（右下角，宽 400）
- 没有底栏按钮，所有操作都在订单行上（填充 / 传面单）
- 面单下载失败时的红色提示块见上文
- 队列为空时显示提示与 打开订单中心 按钮
- 同样支持拖动、折叠、隐藏
4. 订单中心（全页）
扩展内的完整订单页，适合批量处理。弹窗里不再放入口，需要时直接访问：
chrome-extension://<扩展ID>/app/index.html
扩展 ID 在 chrome://extensions 的本扩展卡片上可以看到。页面内提供：打开 ShipBest、设置、拉取订单、推送到领星队列、打开领星出库单、原始报文；点行可看详情抽屉（推送到队列 / 复制面单链接）。
注意：「每页条数」「最多拉取页数」「拉列表同时拉详情」这三项只对订单中心页生效。页内弹框的「采集本页」只采当前页，缺字段用「补齐详情」。
六、设置项全表
领星 OMS
| 设置项 | 默认 | 说明 |
|---|---|---|
| 新建出库单地址 | https://oms.xlwms.com/warehouse/packet/create |
同步完成后自动打开；留空则用内置地址。旧版本默认的 /warehouse/create 会在升级后首次读取设置时自动改成新地址（自己改过的地址不动） |
拉取
| 设置项 | 默认 | 说明 |
|---|---|---|
| 订单状态 | 4 |
4 = 已打单。多个用逗号分隔，如 4,5 |
| 每页条数 | 50 |
10–100；页内弹框也用这个值 |
| 最多拉取页数 | 20 |
1–100；仅订单中心页批量拉取时生效 |
| 拉列表同时拉详情 | 是 | 仅订单中心页生效；字段更全但更慢 |
填充
| 设置项 | 默认 | 说明 |
|---|---|---|
| 固定仓库名 | 空 | 空 = 自动：上次选过的仓库，否则第一个。你在页面上手动换仓也会被记住（记录在 lastWarehouse，无独立开关） |
| 物流渠道 | 上传物流面单 |
建单页「物流渠道」选这一项 |
| 填物流承运商 | 开启 | 建单时拿订单承运商去「物流承运商」下拉匹配填进去（详见第七节）。关闭则留空由你手选 |
| 进入建单页自动预设 | 开启 | 进页 / 切路由时先选好仓库与物流渠道（承运商不预选） |
| 填充后自动上传面单 | 开启 | 填完自动把面单文件写入上传控件 |
| 重量目标单位 | 不换算 | 可选 lb / oz / g / kg |
| 尺寸目标单位 | 不换算 | 可选 in / cm |
| 数值小数位 | 3 |
0–4 |
| 字段填充间隔(ms) | 120 |
页面控件多、填充不稳时调大（如 200–300） |
高级
| 设置项 | 默认 | 说明 |
|---|---|---|
| 字段映射覆盖(JSON) | 空 | 数组格式，元素含 id/label/path/include/exclude 等。只有领星页面结构与内置映射差太多时才需要改 |
设置页工具按钮
| 按钮 | 作用 |
|---|---|
| 保存设置 | 写入 sblxSettings（表单里没有的键如 lastWarehouse 会原样保留） |
| 授权面单下载域名 | 申请任意域名下载权限，用于面单在对象存储域名时 |
| 清空待填充队列 | 只删待填充项，已填充记录保留（与弹窗一致，避免重复填） |
| 清空订单缓存 | 清空上次拉到的订单，下次重新拉 |
| 恢复默认 | 只重置设置，不动队列和登录态 |
七、会填哪些字段 / 承运商怎么匹配
字段映射表在 content/fieldmap.js，定位方式是「标签 + placeholder + name + id + 邻近文案」打分，兼容原生 input/select 与 Element UI / Ant Design / iView 等组件库（含自研组件下拉）。
1. 字段清单
| 分组 | 字段 |
|---|---|
| 收件人 | 姓名、公司、电话、邮箱、国家、州/省、城市、邮编、地址1、地址2、完整地址 |
| 寄件人 | 姓名、公司、电话、国家、州/省、城市、邮编、地址1（页面没有则记为「未找到控件」，属正常） |
| 包裹 | 重量、长、宽、高、尺寸（合并文本） |
| 商品 | 首条明细的 SKU、中文品名、英文品名、数量、申报单价、申报币种、海关编码 |
| 单据 | 客户订单号、运单号、面单链接、备注 |
| 预设 | 仓库、物流渠道（进页自动选） |
2. 承运商匹配规则
候选值顺序 = 订单承运商原值 → 产品名 → 各自首段短名（GOFO Express 会额外试 GOFO）。下拉选项按四档打分：完全相同 > 以候选开头 > 包含候选 > 被候选包含。
同分时按两级收敛，不是一上来就报歧义：
- 候选权威性：优先命中更靠前的候选。订单
SpeedX、产品名SPX，下拉里两者都有时选SpeedX（订单原值才是客户下的那个），不会报「候选项有歧义」。 - 互为包含取最短：
GOFO与GOFO Ground都能吃GOFO候选时取GOFO。
两级都收敛不了（两个互不相干的品牌/线路）才放弃，并把页面实际可选值写进行内红字，由你手选——宁可不选，也不把单入错渠道。
3. 不会做的事
- 不点保存 / 提交 / 确认下单
- 不登录、不填账号密码
- 不伪造面单：ShipBest 侧还没打印面单的单，插件只会显示「无面单」
八、常见问题
先按症状查表，再看下面展开的几条。
| 症状 | 处理 |
|---|---|
| 弹框一直空 / 采集不到 | 确认在 /orders/list；刷新页面；点「采集本页」；仍为空点「复制诊断」发我 |
Receiving end does not exist |
该 ShipBest 标签页是扩展重载之前打开的：刷新它，或直接重试（插件会自愈开新标签页） |
| 补齐后仍显示「无面单」 | 该单在 ShipBest 侧未获取 ScanForm / 未打印面单，属数据状态 |
| 承运商没自动选上 | 看行内红字里的「页面可选」；两个品牌/线路确实冲突时需手选 |
| 面单上传失败 | 面板顶部红块看原因；域名未授权点「授权并重试」，或「复制面单链接」手工下载 |
| 仓库 / 物流渠道选错 | 确认「进入建单页自动预设」开启；页面手动换一次仓库会被记住 |
| 图标角标数字对不上 | 角标 = 待填充数；已填充的单不再计数 |
| 想全部重来 | 设置页「清空待填充队列」，再回 ShipBest 重新同步 |
1. 为什么面板采集不到订单？
按顺序排查：
- 是否在
https://oms.shipbest.com/orders/list（/orders也认） - 该标签页是否在扩展重载前打开的 → 刷新
- 页面本身能看到订单表格吗（登录态是否失效）
- 点「复制诊断」，看是接口没通、还是报文解析不出订单（面板会把原因直接写出来）
2. 「候选项有歧义」到底算不算错误？
同一家承运商的两种写法（SpeedX / SPX）不算歧义，会按订单原值选。真正会报歧义的是两个互不相干的选项（两个不同品牌或线路），此时插件不猜，等你手选，避免入错物流渠道。
3. 为什么「面单上传」会失败？
面单文件在对象存储域名上（如 download.shipbest.com），扩展需要该域名的下载权限：
- 默认已覆盖
*.shipbest.com - 面单在其它域名 → 面板红块点 授权并重试，或设置页点 授权面单下载域名
其它失败原因（签名过期、网络异常）会原样显示在红块里，可直接「复制面单链接」手工下载。
4. 升级后要做什么？
chrome://extensions → 重新加载扩展 → 刷新已打开的 ShipBest 和领星页面。建单页地址会自动迁移成 packet/create，你自定义过的地址不会被覆盖。
九、数据与隐私
- 全部数据只存在本机浏览器的
chrome.storage.local，不上传任何服务器：sblxShipbestAuth：从页面请求里读到的 ShipBest 登录令牌（含时间戳）sblxQueue：待填充队列sblxOrders：最近一次拉到的订单sblxSynced：已推送标记sblxSettings：设置sblxRawSample/sblxDebug：最近一次原始报文样本与接口摘要（仅用于排查）
- 插件不外发任何数据；面单文件由后台代下载后直接写入页面控件，不落第三方
- 队列与缓存都可在设置页清空；卸载扩展会一并清掉
十、已知限制
- 只填不提交：提交动作始终由人完成
- 领星「商品」是选择器时，可能只填上 SKU 文本，需要你在商品行里补选具体商品
- 建单页按页面特征判定（可填控件 ≥ 6 且出现「收件人」字样），不看 URL；页面大改版可能需要更新字段映射
- 单条填充是串行的：队列里一次只填一单，填充中切换页面会中断该次填充
- 面单必须先在 ShipBest 侧打印出来才有地址
- 极少数自研组件下拉需要更长的等待，可把「字段填充间隔」调到 200–300ms
十一、给维护者
目录结构
shipbest-lingxing/
├── manifest.json
├── background.js # 消息路由、面单下载、角标、开页、地址迁移
├── content/
│ ├── common.js # 存储 / 设置 / 面板 UI 公共层（SBLX.LX_CREATE_URL 在此单源声明）
│ ├── dict.js # 单位换算、国家州省份字典
│ ├── normalize.js # ShipBest 报文归一化（含未知包法兜底）
│ ├── fieldmap.js # 领星字段映射表
│ ├── fill.js # 填充引擎（控件定位 / 下拉匹配 / 面单上传）
│ ├── shipbest.js # ShipBest 侧同源取数 + 登录态捕获
│ ├── sb-hook.js # MAIN world 钩子（抓 authorization 头）
│ ├── sb-panel.js # ShipBest 页内弹框
│ └── lingxing.js # 领星页内面板
├── app/ # 订单中心（全页）
├── popup/ # 工具栏弹窗（3 个按钮）
├── options/ # 设置页
└── dev/verify.mjs # 静态一致性 + 纯函数行为断言
本地验证
# 1) 静态一致性 + matchOptions/设置迁移等行为断言（无需浏览器）
node browser-extension/shipbest-lingxing/dev/verify.mjs
# 2) 后台 service worker（chrome.* 桩驱动真实 background.js）
cd .tmp-smoke && node sblx-bg-test.mjs
# 3) 端到端：真实 Chrome + 静态托管扩展 + 假 ShipBest / 假领星页面（场景 A–O）
cd .tmp-smoke && node sblx-e2e.mjs
# 4) 弹窗渲染与按钮宽度检查（可选，出图 .tmp-smoke/sblx-popup.png）
cd .tmp-smoke && node sblx-popup-shots.mjs
.tmp-smoke/ 是本地临时验证目录（不在扩展内），依赖根目录的 playwright-core。
发布流程
- 改代码
manifest.json与本文「当前版本」同步递增- 上述 1–3 全部通过
- 同步桌面副本并校验：
rsync -a --delete browser-extension/shipbest-lingxing/ ~/Desktop/shipbest-lingxing/
diff -r browser-extension/shipbest-lingxing ~/Desktop/shipbest-lingxing && echo SYNC_OK
- 提示使用者到
chrome://extensions重新加载并刷新已打开页面
十二、版本变更（近期）
| 版本 | 变更 |
|---|---|
| 0.1.11 | 修正「清空队列」行为：只删待填充项，已填充记录保留（此前会把整条队列含已填充记录一起清掉，与确认文案不符）；重写安装与使用文档 |
| 0.1.10 | 工具栏弹窗收敛为三个按钮（打开 ShipBest 订单列表 / 打开领星新建一件代发页面 / 清空队列），移除「订单中心」「设置」入口 |
| 0.1.9 | 领星面板删除「当前页面看起来不是建单页」提示块与「打开新建出库单」按钮，不再占用队列版面 |
| 0.1.8 | 承运商同分按候选权威性收敛：SpeedX / SPX 并存时取订单原值，不再误报歧义；修复下拉选中时元素引用错误（下拉展开但不选值） |
| 0.1.7 | 建单页默认地址改为「一件代发」/warehouse/packet/create，老用户旧默认值自动迁移（自定义地址不覆盖） |
| 0.1.6 | 承运商改走字段填充（不再进页预选）；失败原因直接写在队列行上 |