¶ 牛迈运单与轨迹回传操作指南
本文适用于需要把易抵达运单、每箱的子转单号以及物流轨迹同步到牛迈的用户。先配置“运单回传”，再配置“轨迹回传”，最后绑定实际使用的渠道。
本文截图来自测试界面；账号、密码已遮挡。映射行是未保存的填写示例，不代表已连接牛迈或回传成功。截图中的产品编号、渠道名称和时效不能直接作为正式业务配置。
¶ 一、先准备资料和单件箱号
向牛迈对接人确认以下资料：
- 牛迈接口域名、账号和密码。域名填写对方提供的基础地址（含协议，按需要带端口），不是某个完整业务接口路径。
- 牛迈客户编号：用于创建物流订单，不是易抵达客户代码。
- 牛迈销售产品编号，以及不同渠道对应的最短、最长运输天数和预计出发、到达日期规则。
- 双方一致的城市、起运港、目的港名称或代码。
运单应有收货时间、寄收件国家和城市，并已维护单件明细。单件的“箱号”必须符合：
FBA＋9位字母或数字＋U＋6位数字序号。例如：FBA000000001U000001。不能用客户单号代替箱号，也不能只填 FBA 主号。
系统按箱号提取 FBA 主号并分组。例如三个箱号：
FBA000000001U000001FBA000000001U000002FBA000000002U000001
会生成两个牛迈物流订单：主号 FBA000000001 对应2箱，主号 FBA000000002 对应1箱。创建、更新时的整票关联号使用易抵达“系统单号”；每箱的快递号码另通过子转单号绑定。
¶ 二、新建牛迈运单回传
¶ 1. 打开运单回传配置
在员工端进入“菜单 → 报价管理”，点击顶部“转单API”，切换到“运单回传”，点击“添加”。
图中①是运单回传，②是轨迹回传；两份配置需要分别建立。
¶ 2. 选择接口并填写账号资料
“API名称”选择“牛迈”，填写便于识别的模板名称、域名、账号、密码及客户编号。
客户编号必须使用牛迈确认的编号。即使同一账号也用于牛迈查价，也要在这份回传配置中填写，不会因为已经配过运费接口就自动完成回传设置。
¶ 3. 选择回传事件
展开“回传事件”，按业务需要选择：
- 确认收货、确认排货、确认发货、确认上网：首次成功时创建牛迈物流订单；之后再命中这些事件时，更新运输信息。
- 子转单号更新：逐箱同步“完整箱号＋该箱子转单号”。
- 手动回传：用于手动重传上述箱号与子转单号的绑定，不是重新创建物流订单。
页面当前规则是“全不选或全选都视为全部监听”。不选事件不能用于停用回传。建议明确选择实际需要的事件。
确认发货、确认上网的订单回传成功后，如果每箱子转单号都已齐全，系统还会补传箱号绑定；若有任一箱缺少子转单号，不会只绑定部分箱子。
¶ 三、配置城市、港口与渠道参数
两类映射的用途不同：城市及港口全局映射负责名称转换；参数条件映射负责按渠道选择产品和时效。
¶ 1. 城市及港口全局映射（图中①）
点击“添加全局映射”，选择目标字段，填写匹配条件和映射结果。
支持发件城市、收件城市、起运港、目的港。同一目标字段按页面顺序取第一条命中规则；没有命中就沿用原值。国家不在这张表中转换。
例如将发件城市 Shenzhen 转为 SHENZHEN：
匹配条件：
#root.getShipperInfo() != null && #root.getShipperInfo().getCity() == 'Shenzhen'
映射结果：
'SHENZHEN'
固定文字需要加单引号。名称、港口代码应先与牛迈核对，不能只因示例中这样写就直接套用。
¶ 2. 参数条件映射（图中②）
点击“添加条件映射”，每行同时填写以下6项：匹配条件、销售产品编号、最短天数、最长天数、预计出发日期ETD、预计到达日期ETA。
例如仅匹配“美国海派＋牛迈美西”：
#root.getShouHuoQuDaoMingCheng() == '美国海派' && #root.getFaHuoQuDaoMingCheng() == '牛迈美西'
该行其余字段的演示值：
- 销售产品编号：
1046 - 最短天数：
18 - 最长天数：
25 - 预计出发日期ETD：
T(org.apache.commons.lang3.time.DateUtils).addDays(#root.getShouHuoShiJian(), 2)
- 预计到达日期ETA：
T(org.apache.commons.lang3.time.DateUtils).addDays(#root.getShouHuoShiJian(), 22)
这些公式直接填入对应字段，不加 ${}。数值不加引号；ETD、ETA公式返回最终日期，系统不会再额外叠加最短或最长天数。以上示例分别为收货时间加2天、加22天，所以运单必须已有收货时间。
参数条件映射按顺序取第一条命中行。未命中、缺少任一结果或公式错误，都会阻止该票回传。 把范围更具体的规则放前面；产品编号必须替换为牛迈给你的真实编号。
¶ 3. 使用Excel批量维护
两张表分别有“导入全局映射”“导入条件映射”和各自的“下载导入示例”。先下载对应示例，再按原表头填写，不要混用。
也可下载本文重新制作的演示文件：
两个文件均为虚构业务配置示例。参数示例包含海派、空派两行，需替换渠道名称、产品编号、天数和日期规则后使用。全局映射列为“目标字段、匹配条件（公式）、映射结果（公式）”；条件映射列与上述6项一一对应。
导入会追加到当前列表，不会自动覆盖旧行。检查顺序、删除不再使用的重复规则，确认无误后点击“确定”保存整份配置。
¶ 四、新建牛迈轨迹回传
回到“报价对接设置”，切换“轨迹回传”，点击“添加”。
- 填写模板名称。
- “API名称”选择“牛迈”。
- 填写牛迈域名、账号和密码。
- 配置轨迹条件、轨迹时间和轨迹描述。
如果业务要求全部轨迹按原始时间和描述回传，可用下面这一行作为起点：
条件（公式）：
true
轨迹时间（公式）：
#root.getCaoZuoShiJian()
轨迹描述（公式）：
#root.getMiaoShu()
与运单参数公式不同，这里的公式针对当前这一条轨迹取值。需要筛选特定轨迹时，请按实际业务调整条件；不匹配的轨迹不会按该行发送。
“是否推送隐藏轨迹”按业务决定；不希望对方看到内部隐藏轨迹时，不要勾选。“同步立即推送”通常保持不选，避免给日常操作增加等待。
牛迈最终接收的轨迹关联号，仍从单件箱号中提取FBA主号，不是靠顶部通用的“回传单号类型”改成其他号码。同一运单有多个FBA主号时，命中的轨迹会分别发给各主号。轨迹时间或描述为空会失败。
检查后点击“确定”保存。
¶ 五、绑定实际使用的渠道
打开实际运单使用的报价／渠道，进入“基本”页：
- 在“轨迹回传”（图中①）选择刚建立的牛迈轨迹配置。
- 在“运单回传”（图中②）选择刚建立的牛迈运单配置。
- 保存报价。
截图仅展示字段位置，未替用户选择或保存配置。请核对运单实际引用的报价，不要仅凭同名渠道判断已绑定。只建立接口模板、没有绑定到实际渠道，不代表会自动回传。
“轨迹对接”用于抓取轨迹，“轨迹回传”用于把已有轨迹发给牛迈，两者不是同一字段。
¶ 六、怎样验证已生效
先使用双方约定的测试运单和合法箱号验证，不要直接对整批业务单重复操作。
- 核对测试运单已有收货时间，箱号格式正确，且能命中一条完整的参数条件映射。
- 正常业务操作命中已选事件后，查看该运单的操作日志与对接报文。
- 区分“牛迈创建物流订单”“牛迈修改物流订单”和“牛迈绑定快递单号”的结果，并让牛迈核对对应FBA主号、箱数与子转单号。
- 新增符合映射条件的轨迹后，查看“牛迈批量轨迹回传”结果，再到牛迈核对轨迹时间和描述。
接口有响应、任务已提交、HTTP成功，都不能单独当成业务成功。应以回传结果和牛迈接收数据共同确认；对方返回失败明细时，先处理失败原因。
配置完成不会自动证明历史运单、历史轨迹均已补传。补传前先核对对方是否已有记录；尤其不要把“手动回传”误用为建单补传。
¶ 七、常见问题
¶ 提示“箱号不符合FBA主号＋U＋6位序号格式”
检查每一个单件的箱号。FBA后有9位字母或数字，U后必须是6位数字；任一箱号不合法，该票相关回传就可能被拦截。只改整票客户单号不能解决。
¶ 提示“子转单号为空，整票未回传”
检查每一箱的子转单号，而不只是整票转单号。补齐后再处理箱号绑定；不要用一个整票号码代替全部单件号码。
¶ 提示“未匹配到牛迈参数条件映射”或某个表达式结果为空
检查实际收货、发货渠道名称是否匹配；再检查产品编号、天数、ETD、ETA五个结果，以及公式依赖的收货时间。城市映射未命中可以用原值，参数条件映射未命中则不能继续，两者规则不同。
¶ 配了轨迹回传但牛迈看不到轨迹
依次检查渠道绑定、单件箱号、轨迹是否存在、是否为隐藏轨迹、是否匹配条件，以及时间／描述是否有值。多条条件同时命中同一轨迹时，可能产生多条回传内容，应避免无意重复匹配。
¶ 能否直接把牛迈查价配置当作回传配置？
不能。查价、运单回传、轨迹回传用途不同，需要分别配置。该运单回传也不是费用或完整计重同步；当前创建牛迈订单时的进仓重量固定传1，不能用它核对实际重量或计费重。