FedEx API集成最佳实践

这是一份快速参考指南，旨在帮助API用户了解如何提升与FedEx的集成体验，并确保集成解决方案在设计、速度和安全方面的质量。

为了与FedEx API高效集成，开发者应遵循以下集成最佳实践：

API URI

  • 测试和正式的API URI不一样。
  • 开发者应使用测试URI进行开发和集成测试，并将生产URI用于生产环境。

下面列出API URI：

测试：https://apis-sandbox.fedex.com/

正式：https://apis.fedex.com/

凭据管理

  • API密钥和秘密密钥

  • 您的API密钥和秘密密钥用于识别您的应用程序，在OAuth令牌请求中需要用到它们。
  1. 您的API密钥和秘密密钥应妥善保管。请不要通过电子邮件或包含客户端JavaScript的配送代码配送API密钥或秘密密钥。
  2. 如果您的API密钥或秘密密钥被窃，会让您的应用程序遭受入侵。如果您怀疑凭据被窃或遭到入侵，请立即重新创建秘密密钥。
  3. 避免记录秘密密钥之类的敏感信息。
  • 不要对API密钥和秘密密钥进行硬编码。
  • 您的应用程序应能动态更新API密钥和秘密密钥。
  • 客户端凭据应存储在安全的位置，以免遭受入侵。

  • OAuth令牌

  • 访问令牌仅应存储在Web应用程序服务器上，请千万不要在浏览器中暴露。
  • 不要在您的应用程序中对令牌进行硬编码。
  • 保护访问令牌的安全避免遭受入侵。
  • 避免为获得新的访问令牌而多次调用OAuth令牌API。建议缓存访问令牌，直到出现HTTP错误码401。出现该错误时，重新生成OAuth令牌。
  • 不要将令牌暴露给最终用户或应用程序。
  • 为所有API交易使用HTTPS。

编码实践

  • 为了保持遵循最新和最安全的数据加密通信协议，建议使用传输层安全性(TLS) 1.2或更高版本。
  • 请务必为每个API请求设置所需的正确API标题。您将在每个API文档页面下找到该标题信息。
  • HTTP POST中的“Content-Type”应为“application/json”。
  • 请从参考示例代码开始使用每个API。每个API端点都随附有多个示例，可帮助您了解必要元素、格式及其他详细信息。
  • 当用户或开发者发送的值包含太多小数位时，可能会导致奇校验错误。对于重量和货币值/金额，只允许两位小数位数。尺寸（如长度、宽度和高度）不支持小数。

    • 示例：重量：45.26，货币值/金额：100.52，长度：10，宽度：25，高度：15。

  • 避免发送空元素。

    • 示例：“Streetlines”:””

  • 仅发送处理请求所需的必要数据。

    • 例如，对于美国国内货件，避免发送商业发票和货品数据，只有国际货件才需要这些信息。

  • 开发时，请确定如果费率等非必要回复元素未返回，该如何反应。使用数据前，请评估缺失元素的交易回复。

    • 例如，如果费率不正常，仍可托运包裹。使用数据前，请测试缺失元素的交易回复。

  • 通常，应避免对FedEx API集成的硬依赖关系（如果适用）。
  • 为了缩短延迟时间并获取准确的结果，应使用以下各项：
    • 过滤 - 使用此功能缩小所要寻找参数的搜索范围。
    • 排序 - 使用此功能可按某个参数的递增或递减顺序排序结果。
  • 验证必要字段（如收件人邮政编码和包裹重量），发送交易前应提供这些数据。验证上述字段的数据是否恰当。如此可确保将交易错误减至最低。

    • 例如，对于美国邮政编码，请验证字段是否全为数字，且采用5位或ZIP+4邮政编码格式。

  • 为了避免对FedEx系统可用性和可靠性造成不良影响：
    • 请勿在测试或生产环境中运行性能测试。
    • 设置恰当的编码逻辑，以避免相同交易一再失败。
  • 设置限制，每 10 秒 1400 个交易。如果前几秒即达到此限制，将返回 HTTP 错误码 429 Too many requests（请求太多），且交易将受限，直到 10 秒过后；此后将再次恢复交易。

    • 例如，如果我们在前 4 秒就收到 1400 个请求，将返回 HTTP 错误码 429 Too many requests（请求太多） - “我们短期内收到了太多请求。请过一段时间再来尝试。”交易将在接下来的 6 秒内受限，限制期过后会再次恢复。

  • 请勿对服务类型、包裹类型、重量限制等业务规则进行硬编码，因为这些规则随时会发生变化。

错误处理

每个API响应都将包含HTTP状态码和响应负载。某些响应伴有错误、警告或注意（如果适用）。警告和注意不代表失败；但应记录并检查错误或警告消息。正确的错误处理将确保与FedEx的集成顺畅，并能避免中断。

HTTP状态码

200 OK（正常）
已成功处理您的请求。此为成功HTTP请求的标准响应。

  • 注意：API响应中可能包含会提供信息性内容的注意和警告。请务必记录并分析消息。

400 Bad request（错误请求）
 我们收到了无法处理的错误请求。请修改您的请求后重试。

  • 注意：请查看错误码和消息，以修复请求并重试。仅对错误码进行了编码，而未对错误消息编码，因为消息会动态变化。

401 Unauthorized（未授权）
我们无法验证您的凭据。请务必交叉检查您的API密钥，然后重试。

403 Forbidden（禁止）
我们无法授权您的凭据。请检查您的权限后重试。

404 Not found（未找到）
 您请求的资源不再可用。请修改您的请求后重试。

405 Method not allowed（不允许的方法）
我们收到的请求方法不受支持。您只能使用为每个端点提供的方法。

例如，要创建货件，您必须使用如API文档中所述的POST方法。

409 Conflict（冲突）
{provide reason of conflict}。请修改您的请求后重试。

415 Unsupported media type（不支持的媒体类型）
我们不支持您请求中的内容类型。请修改格式后重试。

422 Unprocessable entity（无法处理的实体）
我们能理解您请求的格式，但无法处理实体。请修改您的请求后重试。

429 Too many requests（太多请求）
 我们短期内收到了太多请求。请务必查看交易配额和费率限制。

500 Failure（失败）
我们遇到意外错误，正在解决该问题。不便之处，敬请谅解。请稍后再来查看，并留意来自FedEx的通信。

503 Service unavailable（服务不可用）
服务目前不可用，我们正在解决该问题。不便之处，敬请谅解。请稍后再来查看，并留意来自FedEx的通信。

费率

  • 有两种方法可获取费率报价：
    • 特定serviceType的费率 - 结果将按指定的serviceType值进行过滤。这将会减小回复大小并缩短交易响应时间。

      示例：STANDARD_OVERNIGHT

    • 费率工场 – 如果未指定serviceType，则将返回所有适用的服务及对应的费率。
  • 使用服务可用性API来确定对于指定的始发地/目的地组合，有哪些服务、包裹选项及特殊服务可用，并在费率请求中传递serviceType和包裹选项。

    例如，在所有邮政编码之间STANDARD_OVERNIGHT（及其他）不可用。

  • 对于货件要应用的特殊服务，必须包含特殊服务类型及其详细信息。
    • 注意：某些特殊服务没有详细信息。
  • 查看费率API文档。

寄件

  • 使用服务可用性API来确定对于指定的始发地/目的地组合，有哪些服务可用，并在托运请求中传递serviceType和包裹选项。
  • 对于货件要应用的特殊服务，必须包含特殊服务类型及其详细信息。
    • 注意：某些特殊服务没有详细信息。
  • 在取件之前，于托运日期结束时执行FedEx Ground的关闭操作。
  • 查看寄件API文档。

查询货件

  • 将单次追踪请求中的追踪号码数量上限设为30个。如此会减小回复的大小，并缩短交易响应时间。
  • 将同一包裹的追踪次数限制为公司所需的必要次数。
  • 对于批量追踪，请从批量追踪中删除返回的追踪状态为“已送达”的所有包裹。
  • 查看追踪API文档。

地址验证

  • FedEx的地址验证仅作为建议提供，而非最终决定。需要由最终用户来最终决定所提供数据中的地址是否可用以及是否符合其公司需求。必须设置适当的流程来处理无法验证的地址，以使订单仍可进行处理。
  • 要确保更好的托运体验，请不要根据可选服务（如地址验证）设置托运流程。

    • 例如，如果地址验证API在订单输入或托运时不可用，必须设置应变措施来完成货件托运。

  • 查看地址验证API文档。

FedEx服务站搜索

  • 通过提供特定属性（如服务站类型、提供的服务等）缩小您的搜索范围，以获得更适合的服务站选项及更快的响应时间。
  • 查看 FedEx 服务站搜索 API 文档。

取件请求

  • 安排取件时，不要输入过去的就绪时间、过去的日期或太久远的未来日期。
  • 不允许匿名取件。
  • 查看取件请求API文档。

服务可用性

  • 要获取多个运营公司（如 FedEx Express (FDXE)、FedEx Ground (FDXG)、FedEx Freight (FXFR) 和 FedEx Ground® Economy）的结果，可省略 carrierCodes 元素或发送单独的服务可用性请求，因为无法指定多个承运人代码。
  • 请确保您已预先审批单个重量为151磅或以上的垫木以及总重量超过2,200磅的垫木。
  • 如果为变量选项指定了SATURDAY_DELIVERY，则您会获得“星期六递送”选项，以及可以选择星期六递送的所有服务的常规选项。请不要为特殊服务指定SATURDAY_DELIVERY，否则只会返回所有适用的“星期六递送”选项。
  • 查看服务可用性API文档。

客户支持

如果您有疑问或需要协助，我们随时乐意为您提供帮助！请转到我们的支持页面获取资源及如何联系我们的信息。