跨境物流系统怎么对接：别一上来就写代码，先把四段流程拆开
客服每天在货代后台查轨迹，财务月底拿 Excel 对运费，仓库贴错面单被客户催。很多公司以为跨境物流系统对接就是接一个 API，结果做完发现：单能下，轨迹回不来；面单能打，取消改址没人管；月底对账还是手工。
先别谈接口，先把主数据统一
要统一的包括：包裹、SKU、仓库、渠道、国家、计费重规则。
- 渠道编码做映射表。货代 A 叫“美国专线”，系统里是“US-STD-01”，别让业务在订单里手选自由文本。
- 海关申报字段提前收齐：品名、HS 编码、材质、用途、申报价、币种。缺字段，货代直接退单。
- 仓库和发货人信息固定下来。多仓发货时，别让订单跑到错误的仓库。
四段对接，一段一段验收
1. 下单/预报
订单从 ERP/OMS 到物流中台，再下发到货代或海外仓。API 优先；老货代只有表格，就 SFTP/CSV 定时收。必须有幂等键，重复推送不能重复下单。失败进队列，能重试，能人工改。
2. 面单和揽收
货代返回运单号、面单 PDF/ZPL、渠道单号。别只存 URL，文件要落到对象存储。打印前校验尺寸、热敏纸、条码清晰度。地址校验失败、偏远、超重、带电这些异常要提前拦。
3. 轨迹回传
货代推送 webhook 为主，定时轮询兜底。状态码要统一：已下单、已揽收、运输中、清关中、派送中、签收、异常。每个状态保留原始报文和时间。客服页面直接看，别让他们来回切后台。
4. 费用与对账
报价表要版本化，按渠道、国家、重量段、时效。计费重取实重和体积重较大者。燃油、偏远、关税、退件费分开列。对账差异标红，能追到具体包裹。
| 对接方式 | 适合场景 | 注意点 |
|---|---|---|
| API | 主流货代、海外仓、快递 | 限流、重试、幂等，沙箱和真实小单都测 |
| EDI | 传统空运、船司、报关行 | 报文版本、字段长度、字符集 |
| SFTP/CSV | 小货代、批量出货 | 定时任务、文件校验、重复文件 |
| Webhook | 轨迹推送、状态变更 | 验签、防重、失败补拉 |
常见的坑
- 只做下单，不做取消、改址、退件。
- 轨迹状态不统一，客服看不懂。
- 面单文件过期或丢失，仓库重复打印。
- 报价表没版本，财务对不上。
- 没做失败重试，货代一抖动就丢单。
- 测试只跑沙箱，没跑真实小单。
- 多时区、编码、地址字段长度，都是小问题变大问题。
怎么落地
先画一张图：订单从哪来，经过谁，到哪里去；每个节点谁改状态；异常谁处理。再列货代接口清单：有没有 API、文档、沙箱、联系人、限流、支持哪些国家。用一个小渠道跑通，再复制到其他渠道。别一口气全接。
如果你们正准备做跨境物流系统对接，先把现在用的货代、仓库、ERP 和 Excel 流程列出来。鼎汇通科技（深圳）做这类定制系统时，通常先帮客户把接口清单和异常流程理清，再谈开发，能省掉不少返工。
