2. 系统架构概览
本章从全局视角阐述承运商集成接口在企业级系统中的位置、交互关系与数据流转路径。理解整体架构是后续进行接口参数配置与测试验证的基础，避免在局部细节中迷失方向。
2.1 整体集成架构图
下图展示了以企业核心业务中台（OMS/TMS）为枢纽，连接上游电商平台/ERP、下游多家承运商系统的标准集成拓扑。该架构遵循“统一接入、协议适配、异步解耦”的设计原则。
2.2 承运商系统与内部系统的交互关系
交互关系可归纳为三个核心层次，每个层次对应不同的系统角色与接口类型：
| 交互层次 | 源系统 | 目标系统 | 接口类型 | 典型数据 |
|---|---|---|---|---|
| 订单下发 | OMS / 中台 | 承运商 API | HTTP POST / JSON | 订单号、收件人、物品、时效要求 |
| 运单回传 | 承运商 API | 中台 / TMS | HTTP POST / 回调 | 运单号、揽收状态、预计到达 |
| 轨迹同步 | 承运商 API | 中台 / 数据仓库 | SFTP / MQ 推送 | 节点时间、位置、异常代码 |
| 电子面单 | 中台 | 承运商面单服务 | HTTP POST / XML | 面单号、打印模板、加密数据 |
| 费用结算 | 计费系统 | 承运商对账接口 | SFTP / 文件 | 重量、费用、折扣、账单 |
关键交互原则： 所有从承运商到内部系统的数据回传，必须经过中台统一校验、去重、转换后再分发，禁止上游系统直连承运商接口，避免安全漏洞与数据孤岛。
2.3 数据流向说明
以一次完整的“订单发货-轨迹回传-签收结算”流程为例，数据流向分为以下 7 个步骤：
- 订单生成： 上游电商平台或 ERP 将待发货订单推送至中台 OMS。
- 路由匹配： 中台根据收货地址、商品类型、时效要求匹配最优承运商与运力。
- 运单推送： 中台调用承运商标准下单接口，传入订单信息与电子面单参数。
- 承运商响应： 承运商返回运单号、面单 URL 或 PDF 数据，中台存储并回告上游。
- 轨迹回传： 承运商在揽收、中转、派送等节点通过回调或 MQ 推送轨迹数据。
- 状态更新： 中台解析轨迹，更新订单状态，并同步至上游 ERP/电商平台。
- 签收结算： 签收后，计费系统根据重量/费用生成账单，与承运商对账文件比对。
数据流向避坑提示： 步骤⑥轨迹回传是高频失败点。承运商回调地址必须配置为公网可访问的中台网关，且中台需在 5 秒内返回 HTTP 200 确认，否则承运商会触发重试导致重复数据。建议中台对运单号+轨迹节点做幂等去重。
2.4 集成架构关键设计决策
| 决策项 | 推荐方案 | 备选方案 | 选择理由 |
|---|---|---|---|
| 协议类型 | HTTP REST + JSON | SOAP / XML | 轻量、易调试、生态成熟 |
| 数据同步方式 | 异步 MQ + 回调 | 定时轮询 | 实时性高、系统解耦 |
| 安全认证 | HMAC-SHA256 签名 | + Secret | 防篡改、防重放 |
| 异常处理 | 指数退避重试 + 死信队列 | 固定间隔重试 | 避免雪崩、保护下游 |
| 配置管理 | 配置中心（Nacos/Apollo） | 本地配置文件 | 动态生效、灰度发布 |