物流接口与发货物流
物流接口是快递发货的可选增强能力。启用后，系统可以订阅并展示包裹物流轨迹；未启用或第三方接口暂时不可用时，商家仍可选择物流公司、填写运单号并正常发货。
当前一期接入快递100，支持物流轨迹订阅、回调更新和低频查询补偿。电子面单暂不在本期范围内。
页面标题与底部操作区保持可见，服务状态和配置内容在中间区域滚动。加载失败时点击【重试】，加载成功前无法修改或提交；标题栏的【使用文档】可以打开本章节。保存、测试、启停及恢复配置期间，相关操作会暂时锁定，避免重复提交。
已有服务商配置未修改或已恢复原值时，【保存配置】不可点击；修改客户编号或填写新密钥后可保存。首次配置仍需填写必要的账号与密钥。保存失败保留输入，成功后清空密钥输入并再次禁用保存；测试及启停按各自条件操作。
先区分三个概念
| 概念 | 作用 | 由谁维护 |
|---|---|---|
| 物流配置来源 | 决定应用使用平台公共配置，还是允许租户维护自定义配置 | 平台管理员 |
| 物流接口配置 | 保存快递100账号、验证结果和启用状态 | 当前配置所属工作空间的管理员 |
| 物流公司目录 | 发货和测试查询时可选择的承运商及标准编码 | 系统统一提供 |
物流接口与运费模板相互独立：运费模板用于计算下单运费，物流接口用于发货后的轨迹更新。只配置其中一项不会自动完成另一项。
平台设置应用的配置来源
新应用默认使用“租户自定义配置”。平台管理员可以在【应用管理】中打开应用的【编辑应用能力配置】，在“物流配置”区域调整配置来源：
- 租户自定义配置：应用及其商户、门店、供应商可以在各自工作空间维护物流接口配置；
- 使用平台配置：该应用统一使用平台公共物流配置，租户工作空间中的物流接口页面只展示服务状态，不显示自定义配置表单。
配置来源只决定“从哪里取配置”，不代表物流接口已经启用。平台公共配置或租户自定义配置仍需分别完成保存、测试和启用。
NOTE
应用使用平台配置时，租户仍能按菜单和权限规则看到【物流接口】页面。页面只读是正常现象，不需要重复填写平台账号。
工作空间与配置继承
使用租户自定义配置时，应用、商户、门店和供应商工作空间可以维护自己的配置。
- 当前工作空间已有并启用配置时，使用当前配置；
- 当前工作空间没有配置时，商户、门店和供应商可能使用页面显示的上级有效配置；
- 当前工作空间已有配置但未启用时，表示当前层级明确停用，不再继续使用上级配置；
- 应用是租户配置的根节点。应用没有自身配置时显示“当前应用尚未配置”，不会显示为使用上级配置；
- 商户、门店或供应商需要重新使用上级配置时，使用页面上的【恢复使用上级配置】；应用工作空间对应的操作为【删除当前配置】。
请根据页面显示的“当前配置”“实际配置来源”和“实际服务状态”判断当前生效情况，不要只根据配置表单是否有内容判断。
配置快递100
使用前准备
准备以下信息：
- 已开通所需产品能力的快递100账号；
- 快递100客户编号和授权 Key；
- 一个真实、物流公司明确且已经产生轨迹的测试运单；
- 部分物流公司查询所需的收件人或寄件人手机号；
- 当前账号具备物流接口配置和验证权限。
回调地址和数据库凭据加密能力由技术人员在部署环境中统一配置，不需要运营人员在物流接口页面填写。页面提示“物流凭据安全配置尚未完成”时，请联系平台技术人员；在修复前人工发货仍可正常使用。
保存服务商配置
- 切换到需要维护配置的工作空间；
- 进入【设置 → 交易履约 → 物流接口】；
- 选择【快递100】；
- 填写客户编号和授权 Key；
- 点击【保存配置】。
保存成功只表示配置已经安全保存，不代表账号、产品权限和查询能力已经验证。授权 Key 保存后不会回显原文，再次编辑时留空表示继续使用原值；只有填写新值才会替换原 Key。
如果客户编号或授权 Key 确实发生变化，系统会将该服务商恢复为未验证状态；当前正在使用该服务商时，物流接口也会停用，完成重新测试并再次启用后才恢复第三方调用。未修改任何配置时，【保存配置】不可点击，也不会重置验证状态。
测试物流查询
- 保存配置后点击【测试物流查询】；
- 从选择组件中选择真实物流公司，不要手工猜测承运商编码；
- 填写与物流公司匹配、已经产生轨迹的测试运单号；
- 对需要手机号的物流公司填写正确手机号；
- 点击【开始测试】并阅读测试结果。
该操作会真实调用快递100查询接口，可能计入第三方账号调用量。随机单号、尚未揽收的单号或错误的物流公司不能用于判断账号配置是否有效。
测试结果分为两类：
- 快递100明确返回客户编号、授权 Key 或签名错误时，说明服务商配置无效，需要修正配置并重新测试；
- 运单不存在、物流公司不匹配、手机号缺失、网络异常或第三方临时故障，只说明本次测试未通过，不会把此前已验证并启用的配置自动置为失效。
首次测试成功后，系统会自动把该服务商选为当前生效服务商，但不会自动启用物流接口。
启用物流接口
完成测试后，打开页面“服务状态”区域中的【启用物流接口】开关。启用必须同时满足：
- 已保存服务商配置；
- 已完成测试并显示“已验证”；
- 已有当前生效服务商；
- 系统凭据安全配置正常；
- 当前账号具备更新权限。
【设为生效服务商】用于系统接入多个服务商后，在已经验证的服务商之间切换。当前一期只有快递100时，首次验证成功会自动完成选择，通常不需要单独操作。
关闭物流接口只停止当前工作空间使用第三方物流能力，不会影响人工发货，也不会删除历史订单、包裹和已经保存的物流轨迹。
物流公司目录
【设置 → 交易履约 → 物流公司】用于查询系统提供的物流公司名称、编码和服务商编码映射，支持按名称搜索。该目录只读，运营人员不需要新增、编辑或删除物流公司；发货和测试物流查询时，从选择组件中选取对应公司即可。页面顶部的【使用文档】可打开本节说明。
发货和查看物流
商家发货
- 进入【订单管理】，打开待发货订单；
- 点击【发货】；
- 选择本次发货的商品和数量；
- 从系统目录中选择物流公司，填写真实运单号；
- 确认发货并核对发货记录。
物流公司目录由系统统一提供，运营人员不需要新增、编辑或删除公司名称和编码。发货不会等待第三方物流接口：即使配置未启用、订阅提交失败或第三方暂时不可用，发货结果也不会因此回滚。
一个订单可以分多次发货并产生多个包裹。每个包裹分别保存物流公司、运单号、发货商品和物流轨迹，不能把多个包裹的轨迹合并判断。用户端包裹标签使用运单尾号，缺少运单号时使用发货时间，不使用会随列表排序变化的包裹序号。
更完整的订单操作参见快递发货。
查看物流
后台订单详情的【发货记录】会按包裹展示物流状态和最新一条轨迹。点击当前包裹的【查看物流】，可以在抽屉中查看完整轨迹。
用户端订单详情同样按包裹展示物流摘要，并提供独立的物流详情页。一个订单存在多个包裹时，用户可以按稳定的运单尾号标签切换包裹查看；切换期间页面会显示加载提示，系统不会混合不同运单的数据。
页面刷新只重新读取系统已经保存的轨迹，不会因为用户或运营人员刷新页面就再次调用第三方接口。发货后暂时没有轨迹时，页面显示“物流信息暂未更新”；这通常表示快递公司尚未揽收，或系统仍在等待首次推送，可以稍后再查看。
“订阅已提交”只表示快递100接受了监控请求，不表示运单号已经验证为真实有效。系统不会在发货前强制实时查询，以免尚未揽收的真实运单或第三方临时异常阻断发货。经过两次低频查询仍没有有效轨迹时，后台订单详情会提示核对物流公司和运单号。
物流轨迹如何更新
日常轨迹以订阅推送为主：
商家发货
→ 系统创建物流轨迹订阅任务
→ 快递100接受订阅
→ 快递100推送物流变化
→ 系统异步处理回调
→ 更新对应包裹的轨迹
→ 后台和用户端展示当首次回调长时间未到达、轨迹长时间没有更新，或服务商结束监控但包裹仍未到达终态时，系统会按低频策略创建查询补偿任务：
系统健康检查发现异常
→ 创建物流轨迹查询补偿任务
→ 在频率和次数限制内查询快递100
→ 更新同一个包裹的轨迹缓存订阅是主要更新通道，实时查询只用于受控补偿。不要通过反复刷新页面、重复订阅或反复重置任务来尝试更新物流，这些操作可能增加第三方调用量，也不会绕过系统的查询间隔和次数限制。
在任务中心排查
任务中心当前位于应用工作空间。有相应权限的应用管理员可以进入【设置 → 任务中心】，按任务名称、状态或业务主体 ID 查询。物流链路主要涉及：
| 页面任务名称 | 任务标识 | 用途 |
|---|---|---|
| 物流轨迹订阅 | logistics.subscribe_tracking | 发货后向快递100提交轨迹订阅 |
| 物流轨迹回调处理 | logistics.process_webhook | 异步处理快递100推送并更新包裹 |
| 物流轨迹查询补偿 | logistics.query_tracking_fallback | 回调缺失或轨迹长时间未更新时低频查询 |
任务状态表示调度执行情况，执行结果说明本次业务处理结果：
| 状态或结果 | 含义 | 建议操作 |
|---|---|---|
| 待执行 | 已创建但尚未处理 | 等待系统调度，必要时由有权限人员立即执行 |
| 处理中 | 当前正在执行 | 先等待完成，不要重复触发 |
| 等待重试 | 临时异常，系统将在计划时间重试 | 查看最后异常，通常先等待自动重试 |
| 已完成 | 任务流程正常结束 | 继续阅读“执行结果”，确认是否实际提交、更新或正常跳过 |
| 已完成，结果显示跳过 | 当前无需或不能执行该物流动作，例如接口未启用 | 这不是调度失败；按结果提示判断是否需要配置物流接口 |
| 待人工处理 | 自动重试已经停止 | 修复配置或业务数据后再重置任务 |
| 已取消 | 后续不会自动执行 | 确认取消原因和业务是否仍需处理 |
“已完成”不等同于一定获得了新轨迹。例如接口未启用、包裹已经签收或尚未达到查询间隔时，任务可以正常完成并在执行结果中说明跳过原因。
排查时优先查看“执行结果”“最后异常”和“诊断详情”。诊断详情中的第三方信息已经脱敏，可用于区分凭据、产品权限、额度、物流公司、运单和网络问题。不要仅凭任务状态修改订单或包裹数据。
常见问题
发货成功，但物流信息一直没有更新
先确认物流公司和运单号正确，并到承运商渠道确认已经产生揽收轨迹。然后在任务中心依次查看物流轨迹订阅和物流轨迹回调处理任务。首次推送可能有延迟，系统也会在达到健康检查条件后安排低频查询补偿。
发货后没有创建订阅，或者订阅任务显示跳过
查看任务执行结果中的具体原因。常见原因包括物流接口未启用、配置未验证、当前物流公司不支持订阅，或部署环境回调地址尚未就绪。上述情况不会影响人工发货，但需要先修复相应配置才能自动更新轨迹。
测试物流查询失败，是否说明授权 Key 错误
不一定。错误物流公司、错误或无轨迹运单、缺少手机号、产品权限、额度、网络和第三方临时故障都可能导致失败。只有页面明确提示客户编号、授权 Key 或签名无效时，才应修改服务商配置。
为什么测试失败后，物流接口仍然显示已启用
如果失败原因只是测试运单或临时网络问题，系统会保留之前已经验证的配置和启用状态。这样可以避免一次无效测试影响正在运行的真实物流服务。
为什么保存后的授权 Key 变成非必填
系统不会回显敏感凭据。页面显示授权 Key 已配置时，留空保存表示保留原值；需要轮换 Key 时再填写新值。
页面显示“当前应用由平台统一提供物流接口服务”
平台管理员已经把当前应用的配置来源设为“使用平台配置”。租户无需也不能维护自己的快递100账号；如果实际服务状态显示不可用，请联系平台管理员检查平台公共配置。
页面显示使用上级配置
这表示当前商户、门店或供应商没有覆盖配置，系统实际解析到了页面所示的上级有效配置。若希望当前工作空间使用独立账号，请保存、测试并启用自身配置；若页面显示当前工作空间已有但未启用配置，则当前层级已经明确停用，不会继续继承上级配置。
任务进入待人工处理后怎么办
先根据最后异常和诊断详情修复配置、权限、物流公司或运单数据。确认原因已经消除后再使用【重置重试】。不要在原因未修复时反复重置，以免重复消耗第三方调用额度。
操作安全
- 只允许获得授权的管理员维护第三方物流账号；
- 不要在文档、聊天、工单或截图中公开授权 Key；
- 客户编号虽然不是授权密钥，也不应在无关渠道公开；
- 不要公开包含手机号、签名参数或完整第三方报文的诊断信息；
- 不要直接修改数据库中的订阅状态、回调时间、轨迹、查询次数或任务状态；
- 测试时使用专门准备的真实测试运单，不要反复查询无关的生产订单；
- 凭据疑似泄露时，应先在快递100侧轮换，再到物流接口页面更新并重新测试、启用。