运输承运商 API 详解：UPS、FedEx、USPS、DHL 及更多
运输承运商 API 是一种软件连接，使商店、仓库系统、订单管理平台或客户服务工具能够与 UPS、FedEx、USPS 和 DHL 等承运商交换运输数据。它们可以支持费率请求、面单创建、货件预订、跟踪更新、地址检查和配送事件通知等任务。正确的 API 方案与其说取决于承运商名称，不如说取决于你需要自动化的工作流、服务的国家/地区以及已经使用的系统。
当你的运输量和服务区域较为稳定时，单一承运商集成可以很好地发挥作用。当运营需要比较服务、开展国际运输，或需要在多个承运商之间采用统一的跟踪格式时，多承运商 API 通常更加实用。本指南将介绍主要的 API 类型，概括比较主要承运商之间的差异，并说明在构建或购买集成之前需要确认的事项。
运输承运商 API 的作用
API，即应用程序编程接口，规定了两个软件系统交换请求和响应的方式。在运输场景中，你的应用程序可能会发送包裹信息、发件地址和收件地址、服务偏好以及海关信息。随后，承运商或运输平台会返回运输费率、面单数据、跟踪号码或错误消息等响应。
承运商 API 通常提供多项独立功能：
- 计费：请求包裹和服务的预估运费或基于合同的运费。
- 创建货件：发送货件详情并接收跟踪号码或货件确认信息。
- 生成面单：生成可打印的面单，通常为 PDF、图像或文档数据。
- 跟踪：在可用的情况下，获取货件事件、状态、位置和配送信息。
- 地址服务：根据承运商和目的地的不同，对地址信息进行验证、标准化或补充。
- 取件和货件清单：在账户和服务允许的情况下，支持取件请求或日终货件文件。
- 通知：通过轮询、webhook、电子邮件功能或其他事件机制传递状态信息。
并非每个承运商 API 账户都会自动包含这些功能。承运商可能将服务拆分为不同产品，要求账户审批，或根据国家/地区、服务类型、客户协议或技术环境限制访问权限。应将每项功能视为需要在承运商当前文档中确认的内容，而不是根据存在 API 就自行推断其具备的功能。
直接承运商 API 与多承运商 API
实际应用中有两种集成模式。直接承运商集成是将你的软件连接到某一家承运商的开发者平台。多承运商集成则是将你的软件连接到一个中间平台，由该平台通过一个接口对多个承运商进行标准化处理。
| 模式 | 优势 | 权衡 | 最适合 |
|---|---|---|---|
| 直接承运商 API | 直接访问承运商自身的服务、账户规则和货件数据 | 每个承运商都需要分别处理凭证、格式、测试、错误处理和维护 | 拥有主要承运商或专门承运商工作流的企业 |
| 多承运商 API | 一次集成即可简化跟踪、承运商选择和标准化状态处理 | 覆盖范围、功能深度、账户要求和商业条款因供应商而异 | 多承运商电子商务、市场平台、3PL 和跨境运营 |
多承运商 API 不一定会取代与承运商的直接合作关系。某些运输功能可能仍然需要承运商账户、协商费率、审批或直接配置。还应确认中间平台是创建面单、仅跟踪现有货件，还是两者都支持。
主要承运商 API 的比较
UPS API
UPS 提供用于将企业应用程序连接到 UPS 服务的开发者资源。根据账户、地区和产品的不同，开发者可以通过官方 UPS 开发者环境了解计费、运输、跟踪、地址相关服务和取件工作流等功能。
对于包裹业务量较大、需要使用 UPS 特定服务，或已经管理 UPS 账户和合同的企业而言，UPS 通常是一个考虑对象。实际问题并不只是 UPS 是否拥有 API，而是你的账户可用的 API 产品是否支持特定的 UPS 服务、计费安排、目的地和包裹特征。
在实施之前，请确认当前的身份验证流程、沙盒可用性、支持的请求格式、面单输出、费率适用条件、跟踪事件行为和迁移要求。UPS 的文档和产品名称可能会发生变化，因此请以官方 UPS 开发者门户为起点。
FedEx API
FedEx 为需要使用 FedEx 运输和配送服务的应用程序提供开发者平台。其文档是检查可用 API、凭证、测试环境、货件工作流、跟踪和特定服务要求的适当来源。
当运营依赖 FedEx 服务，或需要对运输和跟踪工作流进行承运商特定控制时，FedEx 可能非常合适。集成工作可能不只是发送地址并接收面单。包裹尺寸、服务选择、账户详情、海关信息、危险品规则和国际文件都可能影响请求和响应。
团队应测试成功和失败的请求。例如，应用程序应知道如何处理无效地址、不受支持的服务、重复货件请求、缺少海关字段以及临时承运商中断。请参阅 FedEx Developer Portal，获取当前文档和访问要求。
USPS API
USPS 为使用 USPS 服务的应用程序提供在线业务和开发者资源。USPS 尤其适用于美国境内的包裹和邮件工作流，但具体 API 产品和访问条件应以当前官方文档为准。
USPS 集成需要进行仔细测试，因为企业可能需要区分邮件产品、包裹服务、跟踪事件、地址数据以及面单或邮资工作流。仅跟踪的需求与必须购买邮资或生成运输面单的应用程序有本质区别。
不要假设 USPS API 与 UPS 或 FedEx 具有相同的请求结构、事件词汇、服务可用性或账户模式。请查看 USPS developer resources，并确认哪些产品适用于你的使用场景、地理范围和账户安排。如果你的企业只需要在多个承运商之间提供一致的跟踪视图，那么以跟踪为重点的多承运商 API 可能比多个直接集成需要更少的定制承运商逻辑。
DHL API
DHL 是由不同物流和包裹服务组成的企业集团，因此“DHL API”并不是适用于每种货件的单一通用产品。DHL 的开发者资源涵盖与其服务相关的 API 和工具，但具体适用的产品取决于 DHL 业务部门、目的地、货件类型和账户关系。
DHL 是国际运输、快递服务和跨境运营的自然选择，但正确的集成仍需与所购买的服务相匹配。在设计工作流之前，请确认文档适用于 DHL Express、电子商务包裹服务、货运还是其他 DHL 产品。
请在 DHL Developer Portal 中检查支持的国家/地区、海关和商业发票字段、服务代码、跟踪行为、面单格式以及账户开通要求。对于国际实施，应包含处理海关异常和文件不完整的流程，而不要将跟踪视为完整的货件生命周期。
其他承运商
企业还可能需要 Canada Post、Royal Mail、Australia Post、DPD、GLS 或 Japan Post 等区域性或全国性承运商。它们的 API 在覆盖范围、开通流程、服务名称、跟踪事件详细程度、面单格式和国际货件支持方面各不相同。因此，“承运商越多”并不一定越好。覆盖范围应根据你实际使用的运输线路、服务和货件类型进行衡量。
对于对运营很重要的承运商，应首先查看其自身的开发者文档。如果该承运商通过第三方平台获得支持，请确认集成是否为直接集成、是否需要提供自己的承运商凭证，以及有哪些功能可用。支持跟踪并不能证明同时支持计费、面单创建或货件取消。
跟踪 API 还是完整运输 API？
许多项目使用“运输 API”一词，但实际上需要的是货件跟踪。这两者的范围不同。跟踪 API 通常接受跟踪号码和承运商，然后返回标准化事件或当前状态。完整运输 API 可能涵盖费率、面单、货件创建、海关文件和跟踪。
如果你的主要目标是在电子商务网站、客户门户或支持工具中展示配送进度，那么以跟踪为重点的集成可能已经足够。17TRACK 的 Tracking API 就是多承运商跟踪产品的一个示例；在采用之前，应使用其文档确认当前承运商覆盖范围、请求格式、身份验证和事件行为。
如果你需要购买邮资或创建面单，仅有跟踪无法完成整个工作流。你可能需要直接承运商账户、运输平台，或具备已记录面单功能的多承运商运输 API。尽早区分这些要求，可以避免常见的实施错误：选择跟踪产品后才发现它无法创建仓库所需的货件。
选择 API 前需要检查的事项
1. 定义业务工作流
写下系统必须执行的确切操作。例如：“订单发货后显示跟踪事件”“选择符合条件的最低价服务”“在仓库中创建面单”或“配送延迟时通知客户”。每项操作都有不同的数据、错误处理和运营要求。
2. 将承运商映射到运输线路和服务
列出始发国家/地区、目的地国家/地区、包裹类型、服务级别、退货流程以及任何受限制的货物。某个承运商在技术上受到支持，并不意味着它适合某条运输线路或某项服务。对于国际货件，请将海关数据、关税、税费和商业文件纳入需求。
3. 确认访问权限和商业前提
检查 API 是否需要承运商账户、计费设置、审批、协商费率、应用程序令牌或生产环境审核。测试凭证和生产凭证可能不同。切勿将生产机密放入浏览器代码或公共代码仓库；应使用安全的服务器端集成，并根据安全策略轮换凭证。
4. 比较数据质量，而不只是端点数量
了解 API 如何表示货件状态、预计配送时间、配送异常、签收证明、扫描记录、退货和多包裹货件。端点列表很长并不保证事件细节有用。确定应用程序将如何标准化“已创建面单”“运输中”“派送中”“已送达”“异常”和“已退回”等状态。
5. 测试失败和变更场景
可用于生产的集成必须处理超时、速率限制、重复请求、无效地址、缺少扫描记录、承运商中断、跟踪号码变更以及延迟或乱序事件。在 API 支持的情况下使用幂等性，记录请求标识符，并确保重试安全。跟踪系统还应容忍一段时间没有新扫描记录，而不是将每个无更新时段都视为失败。
6. 评估维护成本
承运商 API 会发生变化。版本更新、证书变更、服务代码变更、新增海关字段以及废弃端点都可能影响运营。了解谁负责监控文档变更、谁负责事故响应，以及集成可以多快更新。多承运商供应商可能减少团队需要维护的集成数量，但也会引入一项依赖，应从服务连续性和支持质量方面进行评估。
实用的决策框架
当一家承运商占据你的大部分货件、你需要承运商特定功能且团队能够维护集成时，选择直接承运商 API。当你需要通过一个工作流在多个承运商之间完成费率、面单和货件创建时，选择多承运商运输 API，但前提是所需服务确实受到支持。
当主要需求是在多个承运商、渠道或国家/地区之间提供一致的跟踪体验时，选择多承运商跟踪 API。对于希望使用统一售后状态模型、而不想为每个承运商构建独立跟踪解析器的电子商务团队而言，这可能很有用。如果你同时需要面单创建和跟踪，请确认一个供应商是否同时支持两者，或者规划双部分架构。
对于新项目，应从小规模概念验证开始。测试一件国内货件、一件国际货件（如适用）、一个失败请求、一个异常事件以及退货或取消场景。将返回的数据与承运商面向客户的跟踪页面和你的运营预期进行比较。只有这样，才应决定是否扩大部署范围。
常见问题
一个承运商 API 可以同时提供费率、面单和跟踪吗？
有时可以，但不应想当然。这些功能可能属于不同产品，或需要不同的账户权限。请在承运商当前文档中确认每项功能、服务、国家/地区和凭证要求。
多承运商 API 总是比直接集成更好吗？
不是。当你需要在多个承运商之间使用通用工作流时，多承运商 API 可以减少工程工作，但直接集成可能更好地访问承运商特定功能或账户控制。更好的选择取决于你需要的功能以及能够承担的维护成本。
使用运输 API 需要承运商账户吗？
通常需要，尤其是在创建面单、购买邮资、计费或使用协商费率时。要求因承运商、产品、国家/地区和供应商而异。在构建集成之前，请确认商业和技术开通规则。
跟踪号码和货件 ID 有什么区别？
跟踪号码是用于通过承运商网络跟踪包裹的标识符。货件 ID 可能用于标识交易、包裹组、面单请求或内部记录。一件货件可以包含多个包裹，因此你的数据模型不应假设一个订单始终对应一个跟踪号码。
团队应如何在 UPS、FedEx、USPS 和 DHL 之间进行选择？
应从运输线路、服务、包裹特征、账户条款和所需 API 功能开始，而不是仅根据品牌进行选择。然后针对最常见的国内和国际场景，测试承运商的文档和实际响应。
