你的第一个追踪 API 请求:使用 Postman 和 Curl 的 REST 客户端操作指南
要发出您的第一个 tracking API 请求,请在 REST 客户端中配置端点、身份验证标头和 JSON 请求体,发送请求,并检查 HTTP 状态和响应正文。本教程使用 17TRACK 的 Tracking API,在 Postman 和 curl 中演示相同的工作流程:注册货件、请求其跟踪信息,并检查结果是否已准备好供您的应用程序使用。
目标是进行一个小型、可复现的集成测试,而不是部署到生产环境。您需要 API 凭证以及一个您获授权处理的跟踪号码。以下命令使用 v2.2 端点模式;运行前,请在 17TRACK API 文档中确认端点版本和帐户特定要求。
了解您的第一个请求应完成什么
货件跟踪集成包含两个独立事项:告知服务要跟踪哪个货件,以及获取与该货件相关的跟踪信息。在此演示的工作流程中,这些是两个独立的请求。注册并不意味着包裹已经在运输中,注册成功也不保证承运商事件会立即可用。
首次测试时,请使用一个货件,而不是批量货件。这样更容易单独排查身份验证错误、无效跟踪号码和响应解读问题。第一个有用的里程碑并不只是“我收到了 HTTP 200”。而是“API 接受了我预期的操作,并且我能够解释货件级别的结果”。
Postman 为编辑请求和检查响应提供可视化界面。curl 可让您从终端复现相同的 HTTP 交换过程。两者都不会改变 API 的身份验证规则、货件数据或处理行为。请选择有助于您更清晰地调查请求的工具,然后在另一个工具中复现可用配置。
准备凭证、货件和请求详细信息
打开任一客户端前,请准备以下内容:
- 已授权的 API 凭证:通过您的 17TRACK API 帐户设置获取。消费者跟踪会话不能替代 API 凭证。
- 真实的跟踪号码:使用您拥有或获准访问的货件。测试实际跟踪数据时,近期活跃的货件通常比虚构号码更有用。
- 承运商(如已知):保留承运商名称以便诊断。如果您的情况需要承运商标识符,请使用 API 文档中定义的值和字段,不要猜测。
- 当前请求约定:确认 API 版本、身份验证标头、请求架构以及任何帐户限制。
- 安全的工作区:避免将凭证、客户详细信息或完整跟踪响应放入公共代码仓库、截图或共享的支持消息中。
最小请求示例使用以下设置:
| 设置 | 示例配置 |
|---|---|
| 基础 URL | https://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'
不要假设新注册的货件会立即返回完整的事件历史记录。数据可用性取决于货件和服务的处理情况。如果信息尚不可用,请遵循文档中的获取和更新指导,而不是反复注册同一个号码或进行高频轮询。
分三个层面读取响应
- 传输:客户端是否连接并收到 HTTP 响应?
- 操作:API 是否接受了请求,单个货件是否成功?
- 货件信息:返回的数据是否标识了预期包裹?其状态或事件历史实际上说明了什么?
使用官方响应架构查找状态、承运商和事件字段。请区分标准化货件状态与承运商的原始事件描述。查询成功并不证明已送达,缺少事件也不证明包裹丢失。
存储时间戳时,请保留提供的时区或偏移信息。避免对不同格式的原始日期字符串进行排序,并假设它们代表正确的时间顺序。同时区分应用程序获取记录的时间与货件事件发生的时间。
逐项排查问题,不要一次改变所有内容
- 没有响应:检查主机名、网络访问、代理设置、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 命令作为可复现参考,但不要包含有效令牌或不必要的客户数据。
来源
- 17TRACK API 文档 — 用于了解身份验证、端点约定、请求字段、响应解读和集成要求。
- Postman 文档:发送 API 请求 — 请求配置和响应检查。
- Postman 文档:变量 — 基于变量的请求配置。
- curl 手册 — 用于标头、请求体、超时、保存响应和输出 HTTP 状态的命令选项。


