Fedex Tracking Api：如何逐步追踪包裹

要通过应用程序跟踪 FedEx 包裹，请创建 FedEx Developer 账户，获取 API 凭证，请求 OAuth 访问令牌，提交跟踪请求，然后将响应映射到您的订单或货件工作流中。FedEx Tracking API 面向需要货件状态数据的软件系统，而 FedEx 网站通常更适合手动快速查询单个包裹。

本指南将说明集成流程、需要验证的信息、常见实现错误，以及当企业需要多承运商跟踪而不仅是 FedEx 连接时的替代方案。在部署到生产环境之前，应始终根据最新的 FedEx 文档确认确切的请求字段、身份验证规则、环境和服务可用性。

首先选择正确的跟踪方式

最佳方式取决于由谁执行操作，以及需要监控多少件货物。

• 一次性查询：当客户或客服人员只需查询单个货件时，使用 FedEx 跟踪页面。
• 内部应用程序：当订单管理系统、仓库应用程序、客户门户或客服工具需要以编程方式获取状态数据时，使用 FedEx Tracking API。
• 多承运商运营：当企业接收来自 FedEx 及其他承运商的货件，并希望使用一个标准化集成、一套状态模型或一个面向客户的跟踪体验时，可以考虑使用跟踪平台。

仅针对 FedEx 的 API 集成可以提供直接控制，对于围绕 FedEx 货件构建的系统可能非常合适。但这也意味着您的团队必须自行管理身份验证、请求限制、响应变化、承运商特定的状态逻辑、错误处理以及其他承运商集成。

使用 FedEx Tracking API 前需要准备什么

在编写集成代码之前准备以下事项：

• 一个 FedEx Developer 账户，以及 FedEx 开发者门户的访问权限。
• 所选 FedEx 环境所需的 API 凭证。FedEx 文档可能会提到客户端 ID 和客户端密钥等凭证。
• 如果所选 API 操作需要，还需准备 FedEx 账户关系或其他账户信息。
• 用于存储凭证的安全服务器端位置。不要在浏览器 JavaScript、移动应用程序或公共代码仓库中暴露客户端密钥。
• 至少一个用于测试的有效货件标识符，例如 FedEx 跟踪号码。测试数据应代表您的应用程序将处理的货件类型和服务。
• 一套用于存储最近已知状态、事件时间戳、位置信息和最近一次成功查询时间的方案。

FedEx 将开发者访问、身份验证、API 环境和运营要求分开管理。成功登录开发者门户本身并不能证明生产请求已经准备就绪。请查看当前产品文档，了解账户前置条件、审批要求、环境 URL 以及任何使用限制。

步骤 1：在 FedEx 开发者门户中创建应用程序

从官方 FedEx Developer Portal 开始，并找到 Track API 产品。创建或选择一个应用程序，然后记录计划使用的环境所提供的凭证。开发环境和生产环境的凭证应分开保存。

在此阶段确认以下四项内容：

1. 包含您所需跟踪操作的 API 产品。
2. 测试环境或生产环境对应的基础 URL。
3. 所需的身份验证方法和作用域（如有）。
4. 请求是否需要 FedEx 账户号码或其他账户级字段。

在检查当前文档之前，不要直接复制旧代码示例中的 URL 或字段名称。承运商 API 可能会更改端点版本、必需请求头、响应结构或接入规则。

步骤 2：请求 OAuth 访问令牌

FedEx API 通常使用 OAuth 2.0 客户端凭证进行身份验证。您的应用程序将客户端凭证发送到 FedEx 授权端点，并接收一个短期访问令牌。随后，应用程序会在跟踪请求的 Authorization 请求头中发送该令牌。

简化的命令行示例如下：

curl -X POST "<FEDEX_OAUTH_URL>" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=<CLIENT_ID>" \
  -d "client_secret=<CLIENT_SECRET>"

应将其视为一种实现模式，而不是替代当前 FedEx 身份验证文档的方案。生产代码应读取令牌过期时间值，安全地缓存令牌，并在令牌过期或 API 返回身份验证失败时请求新令牌。除非官方限制和您的流量模式确有必要，否则应避免为每个跟踪号码都请求新令牌。

有用的身份验证安全措施包括：

• 将密钥存储在服务器端密钥管理器或受保护的环境变量中。
• 绝不要将访问令牌或客户端密钥写入应用程序日志。
• 如果平台支持，应为开发环境和生产环境使用不同的凭证。
• 身份验证失败时向用户返回受控错误；不要暴露原始承运商响应。
• 将令牌失败与跟踪号码无效失败分开监控。

步骤 3：构建跟踪请求

获取有效令牌后，根据当前 FedEx Track API 文档构建请求。请求通常会标识一个或多个货件记录，并可以包含影响返回详细程度的选项。确切的 JSON 属性名称和必填字段必须以您所使用的 FedEx 端点版本为准。

一个具有代表性的请求模式可能如下所示：

curl -X POST "<FEDEX_TRACK_BASE_URL>/track/v1/trackingnumbers" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "trackingInfo": [
      {
        "trackingNumberInfo": {
          "trackingNumber": "<FEDEX_TRACKING_NUMBER>"
        }
      }
    ],
    "includeDetailedScans": true
  }'

使用前应根据实时 FedEx 文档检查上述端点路径和字段名称。某些集成可能需要不同的请求结构、账户号码、基于参考信息的查询方式，或用于详细扫描信息的其他选项。不要假设属于其他承运商的跟踪号码可以发送到仅支持 FedEx 的端点。

步骤 4：将响应解析为业务字段

不要将完整的承运商响应直接传递到面向客户的页面。应先将其映射为稳定的内部模型。实际的货件记录可以包含：

• 承运商：FedEx。
• 跟踪标识符：提交给 API 的标识符。
• 当前状态：您标准化后的状态，例如已创建标签、运输中、派送中、已送达、异常或未知。
• 承运商状态：原始 FedEx 状态或代码，用于客服支持和调试。
• 最新事件：FedEx 返回的最新事件描述和时间戳。
• 预计送达时间：仅在响应提供时存储，并应作为预计时间而非保证时间展示。
• 送达确认：使用承运商响应确定是否已报告送达。
• 最后查询时间：由您的系统记录的时间戳，这与 FedEx 报告的事件时间不同。

状态标准化需要结合编辑和运营判断。例如，异常不应自动显示为配送失败，而“已创建标签”事件也不一定意味着包裹正在网络中运输。请在保留标准化状态的同时保存原始承运商事件，以便客服人员调查差异。

步骤 5：处理错误和不完整信息

生产环境中的跟踪集成必须区分不同的失败类型。请求格式错误、令牌过期、跟踪号码无效、承运商暂时中断，以及成功响应但没有有用事件，并不是同一种情况。

情况	建议处理方式
身份验证失败	刷新凭证或令牌处理逻辑；如果问题持续存在，则提醒集成负责人。
请求无效	重试前验证请求负载、必需请求头、标识符格式和环境。
未找到跟踪号码	显示未解决或不可用状态；没有其他证据时，不要告诉客户包裹已丢失。
临时超时或服务器错误	使用有上限的重试和退避策略，并保留最近已知状态。
没有最新扫描记录	显示最近确认的事件及其时间间隔，而不是编造当前所在地。

重试逻辑应保持谨慎。重复请求可能增加负载、产生大量告警，或触发 API 限制。请使用超时、指数退避、幂等处理，并监控重复失败。确切的速率限制和服务承诺应以您的 FedEx 协议或当前文档为准，而不是根据示例应用程序自行假设。

步骤 6：安排更新，避免造成糟糕的客户体验

大多数货件系统不需要每隔几秒请求一次最新结果。应根据货件状态制定更新策略。新货件在创建标签后可能需要更频繁地查询，而已送达货件通常应停止轮询。异常情况可能需要单独的客服流程，而不是加快自动轮询。

向客户展示结果时，应包含最近承运商事件的时间，并明确说明送达日期是否为预计日期。如果 API 暂时不可用，应保留最近验证过的结果，并说明状态尚未刷新。这比用通用错误替换已知状态更有用。

步骤 7：测试完整工作流

测试内容不应仅限于成功响应。实际的测试计划应覆盖：

• 包含多个扫描事件的有效跟踪号码。
• 跟踪历史有限的新创建货件。
• 已送达货件。
• 异常或延迟货件（如果有具有代表性的测试数据）。
• 无效或不完整的跟踪号码。
• 过期或已撤销的凭证。
• 超时、速率限制响应和临时服务器错误。
• 重复事件以及乱序到达的事件。
• 不同时区和夏令时转换。
• 对日志中的凭证、令牌、个人数据和完整承运商负载进行脱敏。

上线前，使用受控样本将标准化状态与 FedEx 跟踪页面进行比较。两种视图的更新时间可能并不完全一致，因此目标是确认您的解析器能够正确解释响应，而不会将缺失数据转化为确定性结论。

什么时候多承运商跟踪 API 更合适

当 FedEx 是主要承运商且您的团队希望自行掌控完整的应用程序逻辑时，直接集成 FedEx 是合理的。当订单可能经过多个承运商、市场平台、邮政运营商或区域配送服务时，这种方式的效率会降低。在这种情况下，企业可能需要承运商识别、通用状态模型、Webhook 或轮询编排、品牌化跟踪页面以及统一的客服视图。

17TRACK 提供独立的 Tracking API，并在 api.17track.net 发布开发者文档。当需求不只是跟踪 FedEx，而是需要更广泛的多承运商跟踪时，可以将其作为多承运商选项进行评估。正确的选择取决于您的项目在测试期间能够验证的承运商、国家/地区、事件详细程度、集成模式、商业条款和运营控制。多承运商服务并不能免除测试承运商特定异常，或验证事件对于您自己的货件组合的准确性和时间性的必要。

实际实施检查清单

• 确认 FedEx API 产品与您需要的查询类型相匹配。
• 验证当前的身份验证端点、基础 URL、请求结构和必需请求头。
• 将客户端密钥和访问令牌保存在服务器端。
• 安全地缓存和刷新 OAuth 令牌。
• 发送请求前验证跟踪标识符。
• 同时保存原始承运商状态和标准化状态。
• 将承运商事件时间与系统检索时间分开记录。
• 使用有上限的重试，并分别监控身份验证、验证、超时和承运商错误。
• 进入终止状态后停止常规轮询，但应遵循您的运营规则。
• 在向客户展示状态消息前测试真实的响应变化。
• 更改 API 版本或扩展货件类型时重新检查 FedEx 文档。

常见问题

我可以使用 FedEx 网站而不是 API 吗？

可以。对于手动查询，FedEx 网站通常是最简单的选择。当软件必须自动获取跟踪数据、将状态事件与订单关联，或在其他应用程序中展示跟踪信息时，API 会更有用。

每次跟踪请求都需要 OAuth 令牌吗？

通常，应用程序会获取一个访问令牌，并在令牌过期前将其用于后续 API 请求。请安全地缓存令牌，并遵循当前 FedEx 身份验证文档中关于过期和刷新行为的说明。不要将令牌暴露给浏览器或客户。

API 能告诉我包裹的确切位置吗？

它可以返回 FedEx 为该货件提供的跟踪事件和其他信息。结果可能会显示扫描位置或设施，但不应将其理解为持续的实时 GPS 定位。只展示实际返回的位置和事件详细信息。

为什么跟踪号码有时没有更新？

货件可能已创建但近期没有扫描记录，标识符可能不正确，事件可能尚未出现在响应中，或者承运商服务可能暂时不可用。请保留最近确认的结果，显示查询时间，并调查重复失败，而不是直接宣布货件丢失。

电商企业是否应该为每个承运商分别构建 API？

对于专注于 FedEx 且拥有强大工程资源的运营来说，这可能是合理的选择。通过多个承运商发货的企业可能更倾向于使用多承运商跟踪层，以减少集成工作并统一事件。在选择之前，请比较承运商覆盖范围、数据详细程度、可靠性、文档、成本以及对面向客户体验的控制力。

来源

• FedEx Developer Portal: Track API
• FedEx Developer Portal: Authorization API
• FedEx Developer Portal
• 17TRACK Tracking API
• 17TRACK API Documentation