如何使用 UPS Tracking API：分步设置指南

要使用 UPS Tracking API，请创建 UPS Developer 账户、注册应用、获取 OAuth 2.0 凭据、请求访问令牌，然后使用有效的 UPS 跟踪号码发送经过身份验证的跟踪请求。具体的门户标签、审批步骤和 API 要求可能会发生变化，因此在正式启用生产集成之前，请先在官方 UPS Developer Portal 中确认当前说明。

本指南面向需要在网店、订单管理系统、仓库工作流、客户服务工具或内部仪表板中显示货件状态的开发者和电商运营团队。本文重点介绍集成流程、影响可靠性的决策，以及防止常见跟踪失败的检查。

UPS Tracking API 的作用

API 集成允许软件从 UPS 请求货件信息，而不需要员工或客户手动打开承运商的跟踪页面。您的应用可以使用响应来显示最新已知状态、识别配送事件、支持客户服务调查，或触发内部工作流。

API 与跟踪页面并不相同。跟踪页面是为人类阅读而设计的，而 API 响应是软件必须解析、存储和呈现的结构化数据。您的系统仍需负责身份验证、错误处理、轮询或事件收集、数据保留、用户界面设计，以及围绕配送事件建立的任何业务规则。

开始之前

打开开发者门户之前，请准备以下项目：

• UPS Developer 账户，或当前 UPS 开通流程所要求的账户类型。
• 已注册的应用，以及为该应用签发的凭据。
• 测试跟踪号码或其他获批准的测试方法。如果 UPS 文档提供了单独的测试环境或测试流程，请不要从真实客户数据开始。
• 明确决定由哪个系统负责保存货件记录、跟踪事件和面向客户的状态消息。
• 用于安全存储客户端凭据和访问令牌的位置。切勿将密钥放入浏览器代码、公共代码仓库、截图或用户可以检查的移动应用中。

您还应决定应用是否只需要跟踪功能，还是需要更广泛的 UPS 集成。跟踪、计费、运输、地址验证和单据服务可能具有不同的产品、权限、请求格式和运营要求。

第 1 步：打开 UPS Developer Portal

从官方 UPS Developer Portal开始。查看当前的 API 目录、身份验证指南、开通要求、条款和环境信息。请专门查找 Tracking API 文档，不要假设其他 UPS 服务的说明同样适用于跟踪功能。

门户是获取当前请求字段、授权范围、响应定义、速率限制、错误代码和环境详情的适当来源。这些细节可能发生变化，第三方代码示例可能使用较旧的 UPS 接口或过时的身份验证方法。

第 2 步：注册应用

在开发者门户中创建应用，并选择应用实际需要的 UPS API。对于仅跟踪项目，除非工作流需要其他服务，否则只请求跟踪功能。限制权限可以降低配置复杂性，并使后续故障排查更容易。

将应用标识符和密钥记录在服务器端密钥管理器或受保护的环境变量系统中。将密钥视同密码处理。如果密钥泄露，请通过 UPS 提供的流程进行轮换，并检查日志中是否存在未经授权的使用。

如果门户要求提供账户、账单、业务或应用信息，请提供准确的信息。不要为了完成测试而虚构生产用途或使用他人的账户信息。能否访问服务可能取决于账户配置和当前 UPS 审批流程。

第 3 步：实现 OAuth 2.0 身份验证

当前 UPS 开发者文档对其 API 使用基于 OAuth 的身份验证。您的服务器通常会通过文档规定的令牌流程交换应用凭据并接收访问令牌，然后在 API 请求的授权标头中包含该令牌。

请将身份验证与跟踪逻辑分离。实际设计中，可以由一个组件获取并缓存有效令牌，由另一个组件调用跟踪端点。令牌组件应：

• 仅向文档规定的 UPS 授权端点发送凭据。
• 使用当前 UPS 文档规定的内容类型和授权参数。
• 临时存储令牌，并在令牌过期前重复使用，而不是为每个跟踪号码请求新令牌。
• 在文档规定的过期条件发生时刷新或重新获取令牌。
• 从应用日志、错误报告和支持工单中删除凭据和令牌。

不要将浏览器会话中的令牌复制到永久集成中。后端服务通常是管理凭据更安全的位置，因为它可以使密钥远离公开的客户端代码。

第 4 步：构建跟踪请求

使用官方 Tracking API 参考文档中所示的请求格式。典型请求包括路径或请求参数中的跟踪号码、授权标头中的访问令牌，以及 UPS API 所要求的标头。不要假设跟踪号码是唯一必需的值：当前参考文档可能还规定版本、事务、内容类型或关联标头。

简化的请求模式如下：

GET [UPS tracking endpoint]/[tracking-number]
Authorization: Bearer [access-token]
Accept: application/json

这只是结构示例，不是可直接复制粘贴的端点。请根据应用情况，使用 UPS 文档发布的端点、版本、标头和参数名称。请按照您自己的订单数据规则规范化跟踪号码，但除非承运商文档确认这样做是安全的，否则不要删除任何字符。

第 5 步：将事件解析到数据模型中

承运商响应通常包含比单个状态标签更多的信息。在编写面向客户的页面之前，请将响应映射到内部模型，例如货件标识符、承运商、最新状态、事件代码、事件描述、事件时间戳、位置、预计配送信息，以及可用时的送达时间戳。

在保留和隐私政策允许的情况下，请保留原始承运商响应。原始响应有助于诊断映射错误，或解释规范化状态为何与承运商的表述不同。同时，不要在没有易懂说明的情况下向客户显示技术事件代码。

不要将每个状态都视为最终配送结果。例如，在途事件、异常、尝试配送和已送达事件不应被合并为同一条客户消息。请创建明确的映射，并定义当 UPS 添加代码无法识别的事件值时应如何处理。

第 6 步：添加重试、验证和监控

生产集成需要的不只是开发控制台中的一次成功请求。请添加验证和运营保护措施：

• 输入验证：在发送请求之前，拒绝空白、格式错误或明显不完整的跟踪号码。
• 超时：防止缓慢的承运商响应阻塞整个结账、支持或仓库工作流。
• 重试规则：谨慎重试临时网络或服务故障，并使用退避机制。不要反复重试身份验证错误或无效跟踪号码。
• 关注速率：遵守 UPS 文档中的限制和使用规则。在业务流程允许的情况下缓存近期结果。
• 未知状态：保留无法识别的事件以供审核，而不是错误地将其标记为已送达或丢失。
• 可观测性：记录请求耗时、响应类别和关联信息，但不要记录密钥或不必要的个人数据。

跟踪系统还应定义刷新货件的频率。过于频繁的轮询会造成可避免的负载，并且可能无法产生新信息。轮询过少则可能使面向客户的页面显得陈旧。请根据货件量、运营紧迫性、承运商规则和用户实际需要的新鲜度选择间隔。

第 7 步：使用真实场景进行测试

测试内容不应只有成功送达的货件。请包括未知跟踪号码、在途货件、异常、多事件货件、过期令牌、超时、授权失败，以及包含解析器未预期字段的响应。如果 UPS 提供单独的测试环境或测试凭据，请先遵循该流程。

检查从请求到用户界面的完整路径。确认正确的订单收到正确的货件，时间戳按照预期时区显示，重复事件不会生成重复的客户消息，并且承运商中断不会用误导性文本覆盖之前有效的状态。

何时多承运商跟踪 API 更适合

当您的业务主要使用 UPS 发货，并且需要对承运商工作流进行精细控制时，直接集成 UPS 可能很合适。当订单可能经过多个承运商、市场平台、邮政运营商或区域配送公司时，直接集成就不太方便。在这种情况下，不同的凭据、响应格式、状态词汇和重试规则可能会增加维护工作。

对于需要跨多个承运商进行跟踪的应用，诸如 17TRACK Tracking API 这样的多承运商服务可以提供另一种集成模式。应直接查阅其开发者文档，了解支持的承运商、请求格式、身份验证、使用条款和可用功能。这并不意味着它自动优于直接连接 UPS：正确的选择取决于承运商组合、数据要求、对集成的控制程度，以及商业或合规限制。

如果只是面向消费者的查询，而不是开发者集成，那么 17TRACK’s tracking page 可能比构建 API 连接更合适。对于需要品牌化售后更新的网店，请单独查看相关平台集成，而不是增加网店并不需要的 API 工作。

常见实现错误

• 使用旧示例：代码示例可能引用已停用的版本、旧的身份验证方法或其他 UPS 服务。
• 将密钥放入前端代码：发送到浏览器的任何内容都应视为可被检查。
• 认为空结果意味着没有货件：在得出业务结论之前，请核实跟踪号码、账户权限、环境和响应消息。
• 只映射文本：状态描述可能有所不同。请使用文档规定的代码，并保留未知值以供审核。
• 忽略账户和使用要求：技术代码可能正确，但应用未针对所请求的服务完成配置。
• 在没有业务规则的情况下刷新：不必要的轮询可能增加成本、负载和运营噪声，却无法改善客户体验。

实用的正式上线检查清单

1. 确认应用使用的是当前 UPS 文档和获批准的环境。
2. 确认凭据存储在服务器端，并且可以进行轮换。
3. 测试身份验证失败、承运商错误、格式错误的输入和超时。
4. 将规范化状态与代表性货件的原始响应进行比较。
5. 设置刷新策略并监控请求量。
6. 明确未识别事件、更新延迟和客户升级问题的负责人。
7. 记录集成信息，以便其他开发者能够安全地更新凭据、端点版本和状态映射。

常见问题

使用 Tracking API 是否需要 UPS 账户？

您应在 Developer Portal 中查看当前 UPS 开通和访问要求。API 访问权限可能取决于应用注册、凭据、账户配置和所请求的具体服务。不要假设公共跟踪页面登录与开发者 API 访问可以互换。

UPS Tracking API 是免费的吗？

不要假设 API 访问不存在商业或使用条件。UPS 会通过官方渠道发布当前的服务和账户信息，某些要求可能取决于产品、账户或协议。在制定生产预算之前，请直接确认适用条款。

可以直接从浏览器中的 JavaScript 调用 UPS API 吗？

基于浏览器的调用可能暴露应用凭据，并产生跨域、安全和使用控制问题。服务器端集成通常是更安全的模式，可用于存储密钥、获取令牌、应用重试规则，以及限制对货件数据的访问。

应用应多久请求一次跟踪更新？

请根据承运商规定的限制、货件量、运营紧迫性和用户所需的新鲜度制定刷新策略。在适当情况下缓存近期结果，在临时失败后使用退避机制，并避免将重复轮询当作文档规定的事件或通知功能的替代方案。

应该使用直接 UPS 集成还是多承运商 API？

对于需要承运商特定控制的 UPS 核心工作流，直接集成 UPS 可能更合适。当货件使用多个承运商时，多承运商 API 可能减少集成数量。在选择之前，请比较支持的承运商、身份验证、数据字段、可靠性要求、使用条款和实现工作量。

来源

• UPS Developer Portal — 官方 API 目录、应用访问、身份验证和开发者文档。
• UPS Technology Integration — 关于将 UPS 技术与业务系统集成的官方信息。
• 17TRACK Tracking API — 多承运商跟踪的官方产品和开发者入口。
• 17TRACK API Documentation — 关于身份验证、请求和响应处理的官方 API 文档。