¶ 已预报运单按箱号连续电子秤收货操作与对接指南
这篇文档用于帮助仓库操作员、系统管理员和电子秤设备方一起完成一种“少扫码、少点击”的收货方式。使用本流程前，运单必须已经预报完成，并且每个单件都已经有箱号。仓库把包裹逐件放上电子秤，系统自动接收箱号、重量、尺寸和照片；第一件自动加载整票并打印单件标签，后续逐件回填，最后一件完成后自动保存。
本功能是机构专项功能，需要先联系易抵达客服或实施人员开通。未开通的机构仍使用原来的电子秤和收货流程。
¶ 一、适用场景
¶ 适合使用
- 客户已经在员工端或客户端完成快递或专线运单预报。
- 一票货有多个箱号，每个箱号唯一代表一件包裹。
- 仓库希望第一件到秤后自动加载运单、自动打印标签，后续不再反复扫码加载。
- 电子秤能够读取或接收箱号，并能通过 HTTPS 接口上传重量、尺寸和照片。
- 操作员不想在最后手工点击“保存”，希望整票完成后自动保存。
¶ 不适合使用
- 货物没有提前预报，需要在现场新建运单。
- 电子秤无法提供箱号，或者箱号与预报内容不一致。
- 已预报运单的单件明细中没有箱号，或者现场箱号与预报箱号不一致。
没有预报的现场收货，请继续使用收货录入和电子秤 API 常见场景中介绍的原流程，不要使用本文的 mode=4 专项方式。
¶ 二、开通前提（由客服/运维完成）
用户和设备方开始对接前，请向易抵达客服提供机构域名，并确认客服后台已经完成以下事项：
| 项目 | 需要确认的内容 |
|---|---|
| 机构专项功能 | 开通“按箱号连续电子秤收货”和“全部单件完成后自动保存” |
| 预报数据 | 运单已经预报完成，每个单件都有唯一、正确的箱号 |
| 电子秤权限 | 机构已开通电子秤上传功能，设备调用账号可以修改并收货对应的快递或专线运单 |
| 专用员工账号 | 建议创建一个电子秤专用员工账号；收货页面与设备接口必须使用同一个账号 |
| 标签模板 | 已配置可用的单件标签模板，并在收货页面勾选“打印单件标签” |
| 打印环境 | 普通浏览器准备好打印机和打印预览；需要直接出纸时安装并配置易连浏览器 |
客户不需要了解或修改服务器内部配置。若其中任何一项未完成，直接把机构域名和本页链接发给易抵达客服处理。
¶ 三、仓库操作流程
¶ 1. 打开收货页面
使用电子秤专用员工账号登录机构域名，按当前运单类型进入“快递 → 收货”或“专线 → 收货”。页面需要保持打开并保持网络连接。
检查页面上的“打印单件标签”已经勾选。建议同一账号只保留一个正在操作的收货页面，避免现场人员看错窗口。
¶ 2. 第一件包裹过秤
扫描第一件箱号，把包裹放到电子秤上。设备取得稳定的重量和尺寸后，调用本文后面的电子秤接口；照片为可选资料，设备支持拍照时可以一并上传。
页面会自动完成：
- 根据箱号找到已经预报的运单。
- 自动加载整票运单和全部单件明细。
- 把本件重量、尺寸，以及设备选择上传的照片放入对应箱号的单件明细。
- 触发一次整票单件标签打印。
下图是测试环境实测效果：第一件 D47100-2227-A1 到秤后，页面一次加载 3 件预报明细，并只在第一行回填 1.280kg、32×24×18cm。普通浏览器的打印预览已在截图前关闭，因此截图重点展示运单加载和单件回填结果。
¶ 3. 第二件及后续包裹过秤
继续逐件扫描箱号并过秤。页面只更新对应单件，不会重新加载运单，也不会再次打印标签。
下图继续提交第 2 件后，原运单和第 1 件数据保持不变，只在第 2 行回填 2.350kg、36×26×20cm；页面没有重新加载运单，也没有再次触发打印。
¶ 4. 最后一件完成后自动保存
系统确认所有预报单件都已经收到有效重量后，会自动保存整票收货数据，操作员不需要点击“保存”。尺寸允许为 0，但重量必须大于 0；照片不是必填项，不上传或上传失败都不会阻止自动保存。
自动保存完成后，左侧录入区会恢复为空白待收货状态，右侧“全部”数量增加并出现本次操作记录。若页面仍停留在当前运单，请先查看是否存在重量无效、缺件或既有业务校验提示。
¶ 四、串票时系统怎样处理
如果第二件或后续包裹的箱号不属于当前页面已经加载的运单：
- 电子秤接口仍会确认已经接收请求，避免设备方因为业务提示丢失测量信息。
- 收货页面会持续显示“电子秤连续收货串票”提示。
- 错票的重量、尺寸和照片不会写入当前运单。
- 当前运单不会被替换，也不会重复打印。
操作员看到提示后，应把错误包裹移开，核对箱号，再继续处理当前票。不要因为设备接口返回成功就忽略电脑屏幕上的提示。
下图是实测提交另一票箱号后的页面提示。当前页面仍保留原票的第 1、2 件数据，错误包裹没有覆盖当前运单。
¶ 五、打印标签说明
| 使用方式 | 第一件触发打印时的表现 |
|---|---|
| Chrome、Edge 等普通浏览器 | 系统弹出打印预览框，操作员确认打印后出纸 |
| 易连浏览器 | 正确配置静默打印后，可以不弹预览框，直接从指定打印机出纸 |
本流程只在第一件加载整票时打印一次。第二件、第三件以及自动保存时都不会重复打印。
需要直接出纸时，请参考易连浏览器中的“静默打印”说明。首次使用前应先用测试标签确认打印机、纸张尺寸、标签模板和默认打印机都正确。
¶ 六、电子秤设备方对接
¶ 6.1 对接原则
- 使用 HTTPS，不要把真实账号、密码或 Token 写入日志、截图或群消息。
- 建议使用独立的电子秤员工账号，设备 Token 与收货页面登录账号必须一致。
- 每件包裹取得稳定读数后提交一次；
orderNo必须传本件箱号。 - 本场景固定传
mode=4，表示按单件箱号称重。 - 建议显式传
weightUnit=kg、lengthUnit=cm，避免设备与系统单位理解不同。 - 图片为可选参数；需要上传时建议使用 JPEG Base64，每张图片压缩后不得超过 100KB。图片过大会增加设备上传时间、现场网络压力和长期存储占用，不要直接上传相机原图。
- 设备收到 HTTP 成功响应表示平台已接收请求；是否写入当前运单，应同时观察收货页面提示。
¶ 6.2 获取 Token
如果客服直接提供了 API Token，可跳过本步骤。需要由设备程序登录获取 Token 时，使用电子秤专用员工账号调用：
curl -X POST 'https://<机构域名>/itdida-api/login' \
--data-urlencode 'username=<电子秤员工账号>' \
--data-urlencode 'password=<账号密码>'
成功响应的 data 字段是后续请求使用的 Token。Token 自获取成功起有效期为 48 小时（172800 秒）。设备程序应记录 Token 的获取时间，并在到期前重新登录获取；不要把同一个 Token 长期写死在程序中。若接口返回 401，应立即重新登录获取 Token，并使用新 Token 重试当前请求一次。
¶ 6.3 提交一件包裹：cURL 示例
curl -X POST 'https://<机构域名>/itdida-api/dws/weigh' \
-H 'Authorization: Bearer <API_TOKEN>' \
--data-urlencode 'orderNo=BOX-2026-0001' \
--data-urlencode 'mode=4' \
--data-urlencode 'weight=2.35' \
--data-urlencode 'weightUnit=kg' \
--data-urlencode 'length=42' \
--data-urlencode 'width=31' \
--data-urlencode 'height=28' \
--data-urlencode 'lengthUnit=cm' \
--data-urlencode 'pic=<JPEG图片的BASE64内容>'
参数说明：
| 参数 | 是否必需 | 说明 |
|---|---|---|
| orderNo | 是 | 当前包裹箱号，必须存在于已预报单件中 |
| mode | 是 | 本场景固定为 4 |
| weight | 是 | 本件实重，必须大于 0 |
| weightUnit | 建议 | 推荐固定传 kg；不传时设备方容易与默认单位混淆 |
| length / width / height | 否 | 长、宽、高；没有测量时可以不传或传 0 |
| lengthUnit | 建议 | 推荐固定传 cm |
| pic | 否 | 可选的本件照片 Base64；需要上传时压缩后不得超过 100KB。缺少图片不影响自动保存 |
¶ 6.4 Postman 示例
- 新建一个
POST请求，地址填写https://<机构域名>/itdida-api/dws/weigh。 - 在 Authorization 中选择 Bearer Token，填写 API Token。
- 在 Body 中选择 x-www-form-urlencoded。
- 按上表添加
orderNo、mode、重量、尺寸、单位和pic。 - 保持收货页面打开，先发送第一件，确认页面加载和打印；再发送第二件，确认页面只更新第二件且不重复打印。
设备方还可以查看机构域名下的 Swagger：
https://<机构域名>/itdida-api/swagger-ui.html
¶ 七、建议的联调验收清单
- 运单已预报，预报单件数量正确，每件都有唯一箱号。
- 第一件过秤后，页面自动加载正确运单。
- 第一件只触发一次整票标签打印。
- 第二件及后续件正确回填，且不重复打印。
- 每件重量、尺寸都对应正确箱号；若上传照片，照片也应对应正确箱号。
- 最后一件完成后自动保存，无需点击“保存”。
- 保存后，运单档案中可以查看每个箱号对应的 DWS 图片。
- 故意提交另一票箱号时，页面显示串票提示，当前运单不被污染。
- 普通浏览器出现打印预览；易连浏览器启用静默打印后直接出纸。
- 没有预报的现场收货仍能按原流程正常使用。
¶ 八、常见问题与排查
¶ 1. 电子秤请求成功，但收货页面没有反应
依次检查：
- 收货页面是否保持打开，网络是否正常。
- 页面登录账号是否与 API Token 所属账号完全一致。
- 是否打开了多个收货页面；请保留当前正在操作的一个页面并刷新。
- 客服后台是否已为正确的机构域名开通专项功能和电子秤权限。
- 浏览器是否断线；重新登录并打开收货页面后再测一件。
¶ 2. 页面提示“未找到已预报运单单件”
- 核对
orderNo是否为已预报单件箱号，而不是整票运单号码。 - 打开预报运单的单件明细，确认该箱号已经存在且没有重复。
- 核对箱号前后是否夹带空格、换行或扫描枪控制字符。
- 核对运单是否仍处于已预报状态；已经收货的运单不能再次按本流程加载。
¶ 3. 页面提示“串票”
当前包裹属于另一票。系统已经接收设备请求，但不会把它写入当前运单。移开错误包裹、核对箱号后继续当前票即可。
¶ 4. 第一件没有打印标签
- 确认收货页面已经勾选“打印单件标签”。
- 普通浏览器请查看是否出现打印预览框，或被其他窗口遮挡。
- 检查标签模板、默认打印机、纸张规格和打印机连接。
- 易连浏览器请检查静默打印是否开启、指定打印机是否在线。
- 确认这是本票第一件；后续件按设计不会再次打印。
¶ 5. 每一件都重复打印
正常情况只在第一件加载整票时打印一次。请检查是否反复刷新页面、打开多个收货窗口，或设备每次提交时使用了不同账号。仍能复现时，把机构域名、发生时间、箱号和浏览器类型提供给客服。
¶ 6. 最后一件完成后没有自动保存
- 检查所有单件重量是否都大于 0。
- 检查预报单件数是否与现场包裹数一致。
- 查看页面是否有串票、权限不足、运单状态变化或其他录单校验提示。
- 尺寸可以为 0，照片可以不传，但每一件重量都必须大于 0。
¶ 7. 图片上传失败
- 图片是可选资料；上传失败不会阻止整票自动保存。需要上传时，推荐使用 JPEG，去掉不必要的高分辨率和元数据，确保每张图片压缩后不超过 100KB。图片只需能够清楚辨认包裹和标签，不需要使用相机原始分辨率。
- 确认
pic是完整 Base64 内容，不是本地文件路径或设备内网 URL。 - 确认请求使用
x-www-form-urlencoded或正确进行 URL 编码。 - 不要把一张图片误传给多个箱号。
¶ 8. 返回 401 或鉴权失败
Token 的有效期为 48 小时。返回 401 时，可能是 Token 已过期、账号密码已修改，或调用了错误的机构域名。请重新使用该机构的电子秤员工账号登录获取 Token，换用新 Token 重试当前请求一次，并确认收货页面也使用同一个员工账号。
¶ 九、联系设备方时可以直接发送的信息
可以把下面这段话连同本文链接发给电子秤厂家：
我们使用易抵达“已预报运单按箱号连续电子秤收货”。请按 HTTPS 表单方式调用
/itdida-api/dws/weigh，每件提交箱号、重量和尺寸；Base64 照片为可选参数，需要上传时请使用 JPEG 并确保每张压缩后不超过 100KB。mode固定为4，重量单位传kg、尺寸单位传cm。API Token 必须属于现场收货页面登录的同一个员工账号，有效期为 48 小时；设备程序应在到期前重新获取，收到 401 时换用新 Token 重试当前请求一次。第一件会加载整票并打印一次标签，后续件只回填，最后一件有效重量完成后自动保存。接口收到请求后会正常确认，串票等业务问题在现场收货页面提示，请设备程序保留请求日志，但不要记录账号密码、Token 和图片原文。