海运货物追踪 API：集装箱事件、预计到达时间（ETA）数据和选择标准
海运货运跟踪 API 应将集装箱移动、运输里程碑和 ETA 更新关联到贵团队管理的货运。对于货运代理、进口商和集成团队而言，选择标准在于：它能否可靠识别正确的集装箱运输过程，区分实际事件与预测，并提供足够的上下文来支持运营决策。对于海运货运管理而言，通用的货件状态或无法解释的到达日期是不够的。
本指南将说明应请求哪些数据、如何解读集装箱事件和到达预估，以及如何在投入生产流量或采购预算之前评估集成方案。
从货件模型开始，而不是从跟踪界面开始
海运货运跟踪涉及多个相关对象：商业货件、运输单据、一个或多个集装箱，以及承运这些集装箱的运输段。这些关系很重要，因为一次订舱可能涉及多个集装箱，而一个集装箱可能经过多艘船舶、多个码头和多个内陆运输段。
实用的集成必须保留这些关系，而不是将所有内容压缩成一个状态。如果同一货件下的两个集装箱移动情况不同，系统应允许操作人员看到这种差异，而不是显示一个看似完整的货件级里程碑。
在评估 API 之前，请确定贵企业实际接收的引用信息：
- 集装箱编号：用于识别设备，但应与相关货件或运输过程关联，因为集装箱会被重复使用。
- 承运商订舱编号：可将跟踪请求关联到某次订舱，但需符合源系统的查询要求。
- 运输单据编号：可能用于在海运承运商层面识别货件。请确认 API 是否接受团队持有的单据编号。
- 内部货件 ID：将外部跟踪记录关联到运输管理系统、ERP 或货运代理软件。
不要假设货运代理签发的分单编号可以在所有需要海运承运商单据编号的场景中使用。请测试订舱和单据流程中实际可用的确切标识符。
API 应公开哪些集装箱事件？
数字集装箱航运协会（DCSA）的跟踪与追踪标准，为讨论海运货件数据提供了有用参考。DCSA 区分货件事件、运输事件和设备事件。这些类别有助于区分行政进度、运输工具的移动以及实体集装箱的处理情况。
供应商不必使用您偏好的字段名称才能发挥作用，但应说明其事件模型如何映射到您所需的运营里程碑。
设备事件：集装箱发生了什么
相关设备里程碑可能包括进闸、装船、卸船、出闸和空箱移动。数据可用性取决于运输过程、数据来源和产品。请要求提供示例记录，不要假设每个码头都能提供每种事件。
这些区别具有实际影响。船舶到港并不能证明某个特定集装箱已经卸船。卸船也不能证明集装箱已经放行或可以提取。出闸记录同样需要位置和上下文：转运设施的出闸与从最终进口码头提货，在业务结果上并不相同。
运输事件：船舶或运输段处于什么状态
到达和离开事件描述运输活动。要解读这些事件，系统需要关联的位置、运输方式和运输段。在可用的情况下，船舶和航次标识符有助于区分计划中的航程与服务相同港口的其他移动。
对于转运货物，请保留中间停靠点。将路线压缩为起点和终点，可能掩盖错过衔接或路线变更。运营时间线应能够显示哪个运输段已经完成，哪个仍为预估状态。
货件事件：行政进度不等于实体移动
单据和货件处理事件对于货运代理流程可能很有用，但应与集装箱移动保持可区分。单据里程碑不能证明货物已经实际移动，移动事件也不能证明所有商业或监管要求都已满足。
对于每个事件，请请求事件类型、相关对象、位置、事件时间戳、时区信息、来源，以及事件属于计划、预估还是实际状态的标识。同时询问稳定的事件标识符和更正行为，避免重复更新产生重复里程碑。
ETA 数据需要目的地、含义和历史记录
ETA 是在指定地点的预计到达时间。它本身并不意味着货物一定可以提取。海运货运跟踪 API 应明确目的地里程碑，而不是只返回一个含义模糊的 eta 字段。
例如，到达预估可能指港口挂靠、码头、内陆设施或其他已定义的目的地。在使用该时间戳安排卡车或承诺库存可用性之前，应明确该时间戳具体代表什么。
将预估来源与其状态分开
承运商提供的预估和供应商生成的预测是不同的数据产品。两者都不应被呈现为实际到达。请确认响应是否标明预估来源、计算或发布时间，以及它预测的位置或事件。
如果供应商提供预测性 ETA，请要求其方法和验证方式。可询问的问题包括：预测的是哪个里程碑、在到达前多久评估准确性，以及不同航线之间的结果是否存在差异。当目标事件和测量窗口未明确时，笼统的准确率声明很难应用。
保留 ETA 修订记录，而不是覆盖旧值
最新 ETA 支持当日规划；修订历史则解释发生了什么变化。请存储之前的预估、新预估、相关里程碑、来源，以及系统接收到变更的时间。
这段历史能够帮助运营团队区分重大延误、格式更正和无关港口挂靠的变更。它还支持事后评估，同时避免假装在运输早期就已经知道最终预估。
应明确测试时区。保留源时间戳及其提供的偏移量，统一时间戳用于计算，并在适当情况下显示当地运营时间。如果来源只提供日期，不要默默将其转换为精确到午夜的到达承诺。
在事件层面评估覆盖范围
承运商出现在覆盖列表中，本身并不能证明每个集装箱里程碑都可用。覆盖范围应针对对贵企业重要的承运商、航线、货件引用和运营事件进行测试。
根据实际要求建立评估矩阵。对于每个代表性货件，检查 API 是否能够解析引用信息、返回正确路线、公开所需里程碑，并在贵团队负责的运输阶段持续提供更新。
- 直达海运：能否识别起运地离港、目的地到达以及相关集装箱处理事件？
- 转运：中间运输段是否可见？分别移动的集装箱能否保持可区分？
- 内陆运输段：如果服务包含内陆运输，API 是否提供相关铁路、驳船或卡车里程碑，还是可见性在港口处结束？
- 异常：缺失事件、路线变更、无法匹配的引用和数据源中断如何表示？
- 已完成货件：团队能否获取足够的历史数据，以调查客户争议或核对运营记录？
请将不可用数据与否定事件分开。没有卸船记录，并不能证明尚未卸船。实用的集成应区分明确的运营状态和可见性缺口。
API 行为与事件列表同样重要
即使事件流内容丰富，如果交付行为不明确，也可能难以运营。请评估应用如何接收更新、处理更正，以及在服务中断后恢复。
轮询、Webhook 和恢复
轮询允许应用按照自己的计划请求更新。Webhook 允许供应商向您运营的端点发送更新。单独使用任何一种机制都不能保证数据新鲜度：即时交付的 Webhook 仍可能包含延迟接收的源事件。
在可用的情况下，请分别要求定义源事件时间、供应商接收时间和通知时间。对于 Webhook，请确认身份验证或签名验证、重试机制、重复交付行为，以及失败通知是否可以重新播放。对于轮询，请检查分页、速率限制、增量获取以及历史更正的处理方式。
标准化，但不要丢失证据
标准化状态可以简化跨承运商工作流，但过度简化会删除有用的上下文。应优先选择能够在保留原始来源描述或代码（如果可用）的同时保留标准化事件的模型。
将原始传入记录与把它们转换为仪表板状态的业务规则分开存储。这样可以在不丢失原始证据的情况下修订映射。当面向客户的状态与运营团队的解读不一致时，也更容易进行调查。
商业和治理检查
请要求供应商书面说明计费单位。订阅、跟踪货件、集装箱、API 请求和通知不是可以相互替换的计量单位。应明确重试、重复注册、历史查询和重新激活的货件如何影响费用，而不要假设某种定价模式。
还应审查数据保留、访问控制、凭据轮换、允许的下游使用方式、支持升级机制和服务承诺。应将合同保障与产品演示及营销声明分开对待。
不要假设通用跟踪 API 能满足海运货运要求
选择跟踪 API 应依据经过验证的数据模型，而不是类别标签。包裹配送更新和海运集装箱可见性可能服务于不同工作流，即使两者都被描述为货件跟踪。
如果 17TRACK 已经进入您的集成候选名单，请以其 官方 Tracking API 页面 和 API 文档 作为需求核查的起点。在将任何通用跟踪集成视为海运货运解决方案之前，请确认应用所需的确切海运引用、集装箱事件、运输段和 ETA 字段。本指南并未证明 17TRACK 具备这些海运专属能力。
同样的验收标准也应适用于任何候选方案：使用具有代表性的货件演示所需数据，并解释其限制。更广泛的承运商跟踪工作流可能在供应链的其他环节有用，但不能替代专门的集装箱事件数据流。
围绕运营决策开展概念验证
最有力的概念验证应从团队需要做出的决策开始，而不是从仪表板演示开始。选择来自自身运营的代表性货件，包括简单航程和会产生人工工作的复杂案例。
- 定义验收标准。在测试前明确所需引用、事件、位置、时间戳语义以及对缺失数据的可接受处理方式。
- 验证身份。确认每个结果都属于目标货件和集装箱运输过程。在适用时纳入重复使用的设备和多集装箱订舱。
- 与源记录比较。将返回的里程碑与可获取的承运商或码头记录进行核对，同时考虑更新时间差异。
- 测试修订和故障。测试重复通知、乱序事件、更正后的时间戳、不可用的数据源和端点中断。
- 重现业务工作流。验证数据是否支持预期行动，例如审查延误的衔接或更新入库库存预估。
- 审查未解决的缺口。记录每个缺口来自底层数据源、供应商处理还是您的集成，并在扩大使用范围前就补救措施达成一致。
对于 ETA 测试，请保存每个到达的预测，并将其与同一里程碑最终发生的实际事件进行比较。不要将港口到达预测与仓库收货进行比较，也不要将提前期相差很大的预测合并为一个无法解释的评分。
选择规则很直接：选择能够通过可追溯事件、易于理解的预估和可恢复的交付行为，明确支持所需决策的集成方案。如果提货规划还需要码头可用性、放行状态或预约信息，请单独验证这些输入，而不要从船舶到达推断它们。
常见问题
只使用集装箱编号可以跟踪海运货件吗？
这取决于数据源和 API。某些工作流可能还需要承运商标识符、订舱编号或运输单据编号。由于设备会被重复使用，请确认返回的事件属于目标运输过程，而不要只依赖集装箱编号。
船舶实际到达是否意味着我的集装箱可以提取？
不意味着。船舶到达、集装箱卸船、货物可用和允许提取是不同的运营事实。根据货件情况，提取还可能需要放行信息和码头预约。请与负责这些事项的相关方确认适用条件。
AIS 船舶跟踪能否替代集装箱跟踪？
不能。AIS 涉及船舶识别和移动信息；它本身不能证明单个集装箱的装船、卸船、放行或出闸状态。船舶移动可以提供上下文，但仍需确认集装箱与航次之间的关联。
海运跟踪 API 应多久更新一次？
不存在适用于所有工作流的单一理想间隔。应根据相关源信息可用后团队需要多快采取行动来设定要求。将数据源延迟与 API 交付延迟分开测量，并确认数据源不发布新事件时会发生什么。
跟踪事件可以计算滞期费或 detention 费用吗？
事件可以支持时间线，但不能确定完整的费用计算。您还需要适用的合同条款、免费期规则、日历处理方式以及权威的起止条件。不要仅根据通用里程碑推导应付金额。
来源
- DCSA：Track & Trace 标准 — 集装箱运输中货件、运输和设备事件的参考框架。
- DCSA：OpenAPI 规范代码库 — DCSA API 定义和事件结构的技术参考。设计集成时请检查适用的规范版本。
- 国际海事组织：自动识别系统 — AIS 及其提供的船舶信息背景资料。
- 17TRACK：Tracking API 和 官方 API 文档 — 用于验证产品适配性的起点；本文并不以此证明其支持海运集装箱事件或预测性 ETA。
