Skip to main content
首页博客指南你的第一个追踪 API 请求:使用 Postman 和 Curl 的 REST 客户端操作指南

你的第一个追踪 API 请求:使用 Postman 和 Curl 的 REST 客户端操作指南

17TRACK

要发出您的第一个 tracking API 请求,请在 REST 客户端中配置端点、身份验证标头和 JSON 请求体,发送请求,并检查 HTTP 状态和响应正文。本教程使用 17TRACK 的 Tracking API,在 Postman 和 curl 中演示相同的工作流程:注册货件、请求其跟踪信息,并检查结果是否已准备好供您的应用程序使用。

您的第一个 Tracking API 请求:REST 客户端操作指南

目标是进行一个小型、可复现的集成测试,而不是部署到生产环境。您需要 API 凭证以及一个您获授权处理的跟踪号码。以下命令使用 v2.2 端点模式;运行前,请在 17TRACK API 文档中确认端点版本和帐户特定要求。

了解您的第一个请求应完成什么

货件跟踪集成包含两个独立事项:告知服务要跟踪哪个货件,以及获取与该货件相关的跟踪信息。在此演示的工作流程中,这些是两个独立的请求。注册并不意味着包裹已经在运输中,注册成功也不保证承运商事件会立即可用。

首次测试时,请使用一个货件,而不是批量货件。这样更容易单独排查身份验证错误、无效跟踪号码和响应解读问题。第一个有用的里程碑并不只是“我收到了 HTTP 200”。而是“API 接受了我预期的操作,并且我能够解释货件级别的结果”。

Postman 为编辑请求和检查响应提供可视化界面。curl 可让您从终端复现相同的 HTTP 交换过程。两者都不会改变 API 的身份验证规则、货件数据或处理行为。请选择有助于您更清晰地调查请求的工具,然后在另一个工具中复现可用配置。

准备凭证、货件和请求详细信息

打开任一客户端前,请准备以下内容:

  • 已授权的 API 凭证:通过您的 17TRACK API 帐户设置获取。消费者跟踪会话不能替代 API 凭证。
  • 真实的跟踪号码:使用您拥有或获准访问的货件。测试实际跟踪数据时,近期活跃的货件通常比虚构号码更有用。
  • 承运商(如已知):保留承运商名称以便诊断。如果您的情况需要承运商标识符,请使用 API 文档中定义的值和字段,不要猜测。
  • 当前请求约定:确认 API 版本、身份验证标头、请求架构以及任何帐户限制。
  • 安全的工作区:避免将凭证、客户详细信息或完整跟踪响应放入公共代码仓库、截图或共享的支持消息中。

最小请求示例使用以下设置:

设置示例配置
基础 URLhttps://api.17track.net/track/v2.2
注册操作POST /register
跟踪信息操作POST /gettrackinfo
身份验证标头17token: YOUR_API_TOKEN
请求体格式Content-Type: application/json,以及包含货件对象的 JSON 数组

请将跟踪号码保留为字符串。将其转换为数字类型可能会删除前导零或以其他方式改变其值。下面的占位符 YOUR_TRACKING_NUMBER 必须替换为您的实际测试货件;它不是可用的示例号码。

在 Postman 中发出注册请求

1. 创建小型测试环境

在 Postman 中创建一个包含三个变量的环境:base_url、tracking_token 和 tracking_number。将 base_url 设置为上面的基础 URL,并在其他两个变量中输入您的凭证和货件号码。发送请求前选择该环境。

使用 Postman 提供的机密处理控件来保护令牌,并检查您的工作区会共享或同步哪些内容。在界面中隐藏值并不能替代控制访问权限。不要将已填充的凭证与用于同事或公开文档的集合一起导出。

2. 配置方法、URL 和标头

创建 HTTP 请求,选择 POST,并将 {{base_url}}/register 作为 URL。在 Headers 选项卡中添加:

17token: {{tracking_token}}
Content-Type: application/json

在此示例中,凭证应放在自定义 17token 标头中。不要仅因为其他 API 使用了 Bearer token 模式,就将其替换为 Bearer token 配置。同时检查继承的集合设置是否意外引入了 Authorization 标头。

3. 添加 JSON 请求体

打开 Body,选择 raw,然后选择 JSON。输入:

[
  {
    "number": "{{tracking_number}}"
  }
]

外层方括号很重要:此请求使用数组,即使其中只有一个货件。使用双引号,删除末尾逗号,并确保 JSON 中不包含注释。如果文档要求针对您的承运商或货件提供额外信息,请在发送前添加文档中规定的字段。

4. 发送并检查结果

点击 Send。首先检查是否确实收到了 HTTP 响应。DNS 失败、TLS 错误、代理问题或超时,与收到说明请求无效的响应不同。接着检查响应正文中的操作结果,以及任何货件级别的接受或拒绝信息。

将请求保存为“注册测试货件”。记录 HTTP 状态、API 结果和任何错误消息,但不要复制令牌。如果注册失败,请先解决该问题再继续。反复提交未改变的请求会增加诊断难度,并可能消耗帐户资源。

使用 curl 复现请求

以下命令使用 POSIX 风格的 shell,例如 Bash 或 Zsh。PowerShell 和 Windows Command Prompt 使用不同的引号和变量规则。在 PowerShell 中,如有必要,请使用 curl.exe 调用 curl 可执行文件,而不是 shell 专用的命令别名。

设置基础 URL,并通过您常用的机密处理流程将凭证加载到环境变量中:

export TRACKING_BASE_URL='https://api.17track.net/track/v2.2'
# 在继续之前安全地设置 TRACKING_API_TOKEN。

环境变量可以避免凭证出现在可复用示例中,但它不是完整的机密管理系统。在本地测试时,避免将真实令牌输入到 shell 历史记录会保留的命令中。对于自动化,请使用平台的机密存储并限制日志输出。

创建名为 shipment.json 的文件,并将占位符替换为您的测试跟踪号码:

[
  {
    "number": "YOUR_TRACKING_NUMBER"
  }
]

发送注册请求:

curl --request POST \
  --url "$TRACKING_BASE_URL/register" \
  --header "17token: $TRACKING_API_TOKEN" \
  --header 'Content-Type: application/json' \
  --data-binary @shipment.json \
  --connect-timeout 10 \
  --max-time 30 \
  --silent --show-error \
  --output register-response.json \
  --write-out 'HTTP status: %{http_code}\n'

这会将响应正文保存到 register-response.json,并单独打印 HTTP 状态。连接超时和总超时是本地测试选择,并非 17TRACK 服务的保证。打开保存的文件以检查 API 结果;仅凭状态行是不够的。

即使服务器返回 HTTP 错误响应,curl 也可能成功完成传输。相反,传输失败可能导致无法收到任何可用的 API 响应。编写脚本时,请将 curl 的退出状态、HTTP 状态和应用程序级结果作为不同信号分别处理。

请求货件的跟踪信息

确认注册后,复制 Postman 请求并将 URL 更改为 {{base_url}}/gettrackinfo。保留 POST 方法、身份验证标头、内容类型和货件请求体。将其单独保存,以免在本想获取数据时意外重新注册货件。

对应的 curl 请求为:

curl --request POST \
  --url "$TRACKING_BASE_URL/gettrackinfo" \
  --header "17token: $TRACKING_API_TOKEN" \
  --header 'Content-Type: application/json' \
  --data-binary @shipment.json \
  --connect-timeout 10 \
  --max-time 30 \
  --silent --show-error \
  --output tracking-response.json \
  --write-out 'HTTP status: %{http_code}\n'

不要假设新注册的货件会立即返回完整的事件历史记录。数据可用性取决于货件和服务的处理情况。如果信息尚不可用,请遵循文档中的获取和更新指导,而不是反复注册同一个号码或进行高频轮询。

分三个层面读取响应

  1. 传输:客户端是否连接并收到 HTTP 响应?
  2. 操作:API 是否接受了请求,单个货件是否成功?
  3. 货件信息:返回的数据是否标识了预期包裹?其状态或事件历史实际上说明了什么?

使用官方响应架构查找状态、承运商和事件字段。请区分标准化货件状态与承运商的原始事件描述。查询成功并不证明已送达,缺少事件也不证明包裹丢失。

存储时间戳时,请保留提供的时区或偏移信息。避免对不同格式的原始日期字符串进行排序,并假设它们代表正确的时间顺序。同时区分应用程序获取记录的时间与货件事件发生的时间。

逐项排查问题,不要一次改变所有内容

  • 没有响应:检查主机名、网络访问、代理设置、TLS 配置和本地超时。不要将禁用证书验证作为常规解决方法。
  • 身份验证失败:确认令牌处于激活状态、存在 17token 标头,并且所选 Postman 环境正确解析变量。检查是否意外包含空格。
  • 请求无效:根据文档检查 API 版本、操作路径、POST 方法、内容类型和 JSON 数组结构。
  • 货件被拒绝:读取货件特定的错误。检查号码和任何必需的承运商信息,不要将每次拒绝都视为身份验证问题。
  • 没有跟踪事件:确认注册和预期货件身份。检查是否需要承运商信息,以及更新是否可用,再进行重试。
  • Postman 有效但 curl 失败:比较解析后的 URL、实际标头和请求体字节。shell 引号和未设置的环境变量是导致请求出现差异的常见原因。

每次测试只更改一个变量,并简要记录结果。如果检查 Postman 控制台或使用 curl 的详细输出,请将输出视为敏感信息:请求标头可能暴露凭证。共享诊断信息前,请编辑掉机密和客户信息。

了解何时完成本教程

当两个客户端都发送了预期请求、您理解了注册过程、获取操作返回了可解释的结果,并且能够区分 API 失败与货件没有新信息时,您就完成了一次有意义的首次集成测试。仅匹配 HTTP 状态代码,并不能证明两个客户端的行为完全相同。

将工作流程移入应用程序之前,请将凭证保存在服务器端、验证输入,并使用结构化错误处理。了解帐户适用的文档化速率限制、批量限制、重试指导和更新传递选项。不要假设超时后可以盲目安全地重试注册:即使客户端没有收到响应,服务器也可能已经处理了请求。

为无效凭证、格式错误的 JSON、无效货件号码、已注册货件、不可用的跟踪数据和网络超时添加测试。每种情况都应导向明确的应用程序结果,而不是未处理的异常或误导客户的状态。

常见问题

没有真实跟踪号码可以测试吗?

您可以使用无效值测试某些请求验证行为,但这无法验证货件跟踪。要测试真实事件,请使用获授权的货件,或在服务提供测试装置时使用文档化的测试装置。不要假设任意示例号码属于沙盒环境。

为什么 HTTP 200 响应仍然包含失败信息?

HTTP 状态和应用程序结果描述的是不同层面。服务器可以成功接收并处理请求,同时报告某个货件被拒绝。请读取响应正文和文档化的货件级结果,而不仅仅是 HTTP 状态。

为什么使用 POST 获取跟踪信息?

请使用端点约定规定的方法。此获取示例通过 POST 接受 JSON 请求体中的货件标识符。不要因为该操作读取数据就将其改为 GET;这样无法保留文档规定的请求。

应该将 API 令牌放在浏览器 JavaScript 中吗?

不要将私有 API 凭证嵌入公开交付的前端代码中。请通过受授权的后端转发请求,由后端保护凭证、验证输入,并控制每个用户可以访问的货件信息。

生产环境需要同时使用 Postman 和 curl 吗?

不需要。它们是有用的测试和诊断工具。您的生产应用程序可以使用合适的 HTTP 客户端。保留经过清理的 Postman 请求或 curl 命令作为可复现参考,但不要包含有效令牌或不必要的客户数据。

来源