并不是所有团队都应该直接做 API 接入。对很多仓库、卖家运营团队和 3PL 来说，Excel 批量上传是从手工流程过渡到系统化物流操作的关键一步：它既能显著提升批量效率，也能在门户与 API 之间形成一个更低风险的中间层。
本页跟着文件本身走：从订单数据离开上游系统开始，到这一批文件的最后一行进入终态为止，讲清楚模板契约、电子表格会悄悄改坏哪些字段、上传前的预检、行状态与幂等、错误分类与重试、批次收尾、权限与保留，以及一个把常见失败量化出来的假设算例。渠道选择见 门户与 API 上线顺序；包裹打包完成之后的产线控制点见 仓库物流操作。
| 观察到的信号 | 更合适的路径 | 原因 |
|---|---|---|
| 订单数据能从一个系统稳定导出，但字段和异常规则还在变 | 文件批量上传 | 改表头比改接口便宜，先把字段契约固定下来 |
| 文件的等待、人工生成和上传本身已经成为截单风险 | 平台侧自动生成或 API | 瓶颈已经从人少变成链路长 |
| 需要实时库存、承诺、取消或客户状态同步 | API | 文件天生是快照，表达不了实时状态 |
| 每天一到几批，每批几百到几千行 | 文件批量上传 | 现有通道够用，而且人还能看到整张文件 |
在这些场景下，Excel 批量上传不是落后方案，而是更适合现阶段团队结构的选择。关键在于：上传字段必须与门户和后续 API 字段保持一致，这样未来扩展时不需要重做流程。
将文件导入流程与Shipping API 技术总览中的相同步骤对照；以后增加 API 入口时，按发货数据模型指南保持标识关系一致。
可靠的批量上传不是把表格填满，而是让文件生产方和物流系统对每个字段达成同一解释。模板必须写明版本、字段名、数据类型、单位、必填条件、允许枚举、默认值、最大长度、示例、错误代码和负责人。
| 字段组 | 最低要求 | 常见失败 |
|---|---|---|
| 身份 | 批次号、客户或仓库、唯一行键、外部订单号 | 同一订单被重复上传，或结果关不回来源表 |
| 地址与联系人 | 结构化地址、国家或地区、邮编、姓名和必要联系方式 | 列错位、数字格式变化或地址被截断 |
| 包裹 | 件数、实测重、尺寸、单位、包装和内容属性 | 单位混淆、尺寸缺失，或用商品重量替代包装后重量 |
| 服务与控制 | 服务代码、签名或保险等选项、参考号与授权字段 | 自由文本无法映射，或账户无权使用该服务 |
| 单位与代码 | 显式单位列、ISO 国家与州省代码、系统枚举里的服务代码 | 下游把 1.5 读成 15，或服务代码是自由文本，资格无法校验 |
| 结果与账单 | 运单号、标签、费用、币种、错误、冲销和终态回到唯一行键 | 成功出单却在导出或财务里定位不到 |
有四样东西不该出现在自由文本里：服务代码、地址字段之间的边界、计量单位、异常原因。它们必须是枚举或结构化字段，否则统计、重试和分配责任都无从下手。
批量上传的事故多数不是系统宕机，而是文件在被人打开、排序、另存为 CSV 的过程中被默默改写。下表是最常见的几种，以及它们在下游的表现。
| 陷阱 | 下游表现 | 规则 |
|---|---|---|
| 前导零被去掉（邮编、库位、客户号） | 五位邮编变成四位，地址校验和分区判断跟着出错 | 该列必须以文本写入，并在生成端补齐前导零；事后修改单元格格式不会把已经丢掉的零找回来（Microsoft 说明） |
| 超过 15 位有效数字的编号被改尾数 | 订单号或参考号尾数变成 0，和上游再也对不上 | 长数字一律按文本处理，电子表格只保留 15 位有效数字（Microsoft 说明） |
| 长数字显示成科学计数法 | 表格里显示 1.23457E+11，导出后无法还原 | 列类型固定为文本，并在导出后校验位数 |
| 同一列混存文本与数字 | 01234 与 1234 关不上，重复判断随之失效 | 唯一键整列统一类型，比较前去掉空白与不可见字符 |
| 日期被本地格式重排或存成序列号 | 2026-10-04 变成 04/10/2026，或者干脆变成 46242 | 生成端输出 ISO 8601 文本，禁止在表格里手填日期 |
| 小数点与千分位随区域设置变化 | 1.5 kg 被读成 15 kg，重量与分区随之偏离 | 显式单位列加固定小数分隔符，必要时以最小单位整数写入 |
| 单元格里留着公式和查找结果 | 粘贴时带出不可见字符，换环境后值变成错误值 | 上传前一律粘贴为值，不保留公式引用 |
| 合并单元格、多行表头、隐藏行 | 列错位、行数对不上、隐藏行被漏传 | 表头固定一行，禁止合并单元格，不要用筛选后复制来生成文件 |
| 全角空格、不间断空格、弯引号 | 枚举匹配失败，两个看起来一样的值关不上 | 生成端统一做去空白与 ASCII 归一化 |
| 编码不一致 | 非拉丁姓名或地址变成问号或被截断 | 统一使用 UTF-8，并在接收端校验编码与字段字节长度 |
一次导入能吃下多少行，由接收方决定，而不是由你手上有多少订单决定。例如 UPS 的批量文件上传一次最多接受 250 票，用 CSV 或 SSV 导入（UPS 批量文件上传说明）；平台侧通道和自建接口也各有上限，先查清楚再排班。超过上限时按同一个批次号拆成多个文件，并保证行键在整个批次内唯一，拆分就不会制造重复。另外要分清文件和凭证：USPS 对高量包裹寄件使用电子清单来申报和支付邮资（USPS 电子核验系统说明），清单由系统生成并由系统校验，人工维护的表格不在其中。
这些约定看起来琐碎，但它们决定了两个系统能不能对上一行。把下面这张表写进模板说明，比在每个批次里靠人眼挑错便宜得多。
| 字段类 | 统一写法 | 为什么 |
|---|---|---|
| 国家与地区 | ISO 3166-1 两位字母代码 | 自由文本的各种写法会让分区和服务资格判断失效 |
| 州与省 | 系统枚举里的短码，不用全称 | 全称有拼写和缩写两套写法，短码只有一种 |
| 日期与时间 | ISO 8601 文本，带时区偏移 | 否则截单前这几个字在不同系统里指的是不同时刻 |
| 重量与尺寸 | 数值加显式单位列，固定小数位数 | 单位靠约定而不靠字段，是合并文件时最先出错的地方 |
| 金额 | 最小货币单位整数，或数值加币种列 | 浮点小数在求和后会自己产生差异 |
| 服务代码 | 系统枚举值，不用日常叫法 | 日常叫法会变、会产生别名，枚举不会 |
| 电话与联系方式 | 只留数字并显式写国家码 | 括号和连字符在解析时会被当成字段分隔 |
| 布尔与标记 | 整批统一用 Y/N 或 1/0，只选一种 | 混用会让未填写和否无法区分 |
如果上游系统只能给出别的格式，就在生成环节做映射，不要让操作员在表格里手工改写。手工改写的部分，恰恰是没法被校验、也没法被统计的部分。
预检的目标不是文件看起来没问题，而是让每一行在离开生成环节之前就知道自己是合格、待修，还是必然失败。清单不必很长，但每一项都要有明确的负责人。
| 检查 | 怎么查 | 谁负责修 |
|---|---|---|
| 表头与锁定版本一致 | 比对表头指纹，而不是比对人眼看到的列名 | 模板负责人 |
| 行数与本批订单数一致 | 生成端同时输出源单数、导出数和去重后行数 | 生成端 |
| 必填与条件必填 | 按服务、目的地和包裹类型分别校验 | 生成端 |
| 枚举与服务资格 | 服务代码必须在枚举内，且该账户和目的地可用 | 账户负责人 |
| 文件内重复 | 按行键分组，任何一组多于一行都要报出 | 生成端 |
| 与在途订单重复 | 与已经购标且未作废的行键比对 | 上传操作者 |
| 地址完整性 | 街道、城市、州省、邮编、国家齐全，且邮编与州省互相一致 | 订单来源方 |
| 包裹数据合理性 | 单位列非空，重量和尺寸在合理区间，件数与包裹行一致 | 仓库数据负责人 |
| 文本长度与非法字符 | 按每个字段的最大长度和允许字符集校验 | 生成端 |
| 单文件行数与通道上限 | 与接收方上限比较，超过就按批次号拆分 | 上传操作者 |
预检没有通过的批次不要交到仓库手里。把一个坏批次送进产线，真正的代价不是错误本身，而是产线停下来等有人修表。
六个阶段各自要留下什么，决定了出错之后能不能只修坏掉的那一行，而不是整批重来。
| 阶段 | 控制点 | 输出 |
|---|---|---|
| 1. 生成 | 模板版本、批次号、创建人和生成时间锁定 | 不可歧义的待上传文件 |
| 2. 本地或系统预检 | 列、类型、单位、必填、枚举、重复和明显业务规则 | 可上传的文件，或带行号的错误清单 |
| 3. 接收与验证 | 文件校验值、版本、账户权限、服务资格和地址包裹规则 | 每行的接受、拒绝或待判断状态 |
| 4. 执行 | 唯一行键防重，购标结果与请求输入绑定 | 成功运单或稳定的错误码 |
| 5. 修正与重试 | 只修正失败行，保留原行键、尝试次数和原因 | 不重复成功行的重试批次 |
| 6. 导出与关账 | 结果、费用、标签、错误、冲销和操作者可追溯到行键 | 操作、客服和财务共享的批次事实 |
每一行只能有一个终态：已出单、已作废或明确拒绝。一个批次在最后一行进入终态之前都不算关账。把部分成功当成完成，是后续对账和客服查询里最贵的一种习惯。
批次号只能识别文件，不能单独防止订单重复。再次上传同一键时，系统应该返回已有结果、明确拒绝，或者要求授权的替换与冲销动作。修正地址后重新购标，也要把原标签、冲销和新标签连在一起。
批量上传的关键不只是导入成功，而是失败记录能否被快速识别和修复。每次尝试都要留下时间、操作者、输入版本和错误码；修正后的重试只能追加记录，不能改写历史。同一行第三次失败时应该转人工，而不是继续自动重试。
| 类别 | 典型例子 | 影响范围 | 重试规则 | 谁负责修 |
|---|---|---|---|---|
| 结构错误 | 版本未知、列缺失、文件损坏、编码不符 | 整批 | 不重试，重新生成后作为新批次上传 | 生成端 |
| 授权与资格错误 | 账户未开通该服务、目的地不可达、缺少必要选项 | 整批或按账户分组 | 不重试，先解决权限或策略问题再决定是否重发 | 账户负责人 |
| 行级业务错误 | 地址不完整、包裹超限、单位缺失、枚举不匹配 | 单行 | 修正后只重试这些行，保留原行键 | 订单来源方 |
| 瞬时系统错误 | 超时、限流、下游短暂不可用 | 单行或整批 | 同一行按退避策略重试，设次数上限 | 上传操作者 |
| 数据质量警告 | 地址能出单但可以标准化、房号与街道混写 | 单行 | 不重试，记录并回喂清洗规则 | 订单来源方 |
错误码要稳定、可归因，并且跨批次含义一致。用自由文本当错误信息，等于放弃统计，也等于放弃把某一类错误直接分配给责任方。
以下数字是用于说明口径的假设算例，不是行业平均值，也不代表任何客户的实际表现。
假设周一早班生成 5,000 行。预检在文件离开生成环节之前拦下 180 行：地址缺房号或州省 90 行、邮编前导零丢失 40 行、服务代码不在枚举内 30 行、重量单位列为空 20 行，修表平均每行 1.5 分钟，合计 270 分钟。剩下 4,820 行上传，其中 4,780 行首次即出单，首票通过率 95.6%；40 行被行级拒绝（服务不覆盖 22 行、包裹尺寸超限 11 行、账户未开通 7 行），复核与重试平均每行 4 分钟，合计 160 分钟，其中 2 行最终转人工，另耗 40 分钟。这一批的返工总量约 470 分钟，接近 8 人时，几乎全部集中在地址完整性和单位两类问题上。修生成端的两条规则，比在产线上加人更快见效。
| 指标 | 分子除以分母 | 变差时先看什么 |
|---|---|---|
| 首票通过率 | 首次上传即出单的行 ÷ 上传总行数 | 生成端的地址与单位规则 |
| 预检拦截率 | 预检拦下的行 ÷ 生成总行数 | 上游数据质量，不一定是模板问题 |
| 重试成功率 | 重试后成功行 ÷ 重试行数 | 错误分类是否分对了 |
| 每批返工人时 | 修正与重试总耗时 ÷ 已关账批次数 | 排在返工榜首的那一类原因 |
| 批次关账时长 | 文件生成到全部行进入终态的时间 ÷ 批次数 | 收尾导出是否缺字段 |
| 重复行率 | 幂等拦下的重复行 ÷ 上传总行数 | 文件生成频率或人工补单流程 |
| 每千行人工干预次数 | 人工干预次数 ÷ 上传行数 ×1000 | 是否有一类错误本该被预检拦住 |
这七个指标全部写成分子除以分母的形式是有原因的：只报百分比而不写分母，两个部门的数字会在同一周里互相矛盾，而没有人能说清谁对。分母写清楚，争议就变成了一个可以查证的事实。
| 角色 | 允许的动作 | 文件存放 |
|---|---|---|
| 生成者 | 生成、校验、按模板导出 | 受控的共享位置 |
| 上传操作者 | 上传、查看行状态、按规则重试 | 只读打开，不另存副本 |
| 修正负责人 | 修正被拒绝的行并保留原行键 | 修正版与原始版并存 |
| 客服只读 | 按行键或运单号查询 | 不下载全量文件 |
| 财务 | 读取费用、币种与冲销字段 | 按账期取数 |
| 3PL 场景的外部客户 | 上传自己的订单，只看到自己的行 | 按客户隔离的位置 |
具体要求：通过受控位置传递文件，不要用聊天工具或个人邮箱制造无主副本；文件名里不放收件人姓名、电话或完整地址；测试批次用假地址；导出应用与上传同等的权限和审计；保留期与业务、客服和财务的实际需要一致，到期删除并留下删除记录。
如果字段本身还不稳定，批量上传只会把错误放大。更合理的做法是先确认订单号、收件信息、服务字段和账单追溯字段都保持统一，再开始批量化。
试单批次要故意包含这几类行：目的地不可达的邮编、多件包裹的订单、超长地址、需要额外选项的包裹（签名、保险），以及一笔退货或换货冲销。能出单不算通过，能被拒绝并被修好才算。
先按 10% 的订单量跑一周，比较首票通过率和每批返工人时；数字稳定后再到 50%，最后全量。一次性全量切换的问题在于，出问题时你手里没有任何可比基线。
当字段稳定、批量执行顺畅、异常闭环清楚时，才值得进入更深的 API 集成。否则 Excel 往往已经是更合适的长期过渡层。
| 观察到的摩擦 | 先做的动作 | 示例阈值 |
|---|---|---|
| 早上生成与上传占用了截单前的缓冲 | 把生成移到班次前，或让平台侧定时拉取 | 示例：截单前可用缓冲不足 30 分钟 |
| 因为等文件而错过截单 | 换成接口或平台侧自动生成 | 示例：每周超过两次 |
| 重复或版本冲突成为主要错误来源 | 先修行键与幂等规则，再谈接口 | 示例：重复行率超过 1% |
| 字段和异常规则已经稳定 | 可以开始评估迁移 | 示例：连续四周首票通过率高于 99% |
如果主要问题只是模板不清楚或错误不能修复，API 会把同样的问题更快地放大。先完成文件契约和异常闭环，再使用 API 接入准备清单 评估迁移。