# @aftership/tracking-sdk 中文文档

规范地址：https://npmcn.com/package/%40aftership/tracking-sdk/

版本：17\.0\.0
npm 元数据更新时间：2026-07-13T08:31:05.107Z
中文译文更新时间：2026-11-05T18:38:41.966Z
软件包许可：ISC

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40aftership/tracking-sdk
原文对照：https://npmcn.com/package/%40aftership/tracking-sdk/?lang=original
项目主页：https://github.com/aftership/tracking-sdk-nodejs/README.md
源码仓库：https://github.com/aftership/tracking-sdk-nodejs

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：316 kB，479 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=16\.20\.0
- 运行依赖：1 个
- 首次发布：2024-06-20T06:19:31.054Z
- 最新版本发布：2026-07-13T08:31:04.992Z
- 近 30 天下载量：60375（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：16（近 12 个月 3 个）

## 中文简介

跟踪节点JS SDK

## 安装

```sh
npm install @aftership/tracking-sdk
```

也可以使用：`pnpm add @aftership/tracking-sdk`、`yarn add @aftership/tracking-sdk`、`bun add @aftership/tracking-sdk`

## README

# 为 Node.js 的 Ship 跟踪 API 库之后

这个库允许您通过Node.js快速并方便地使用AfterShip跟踪API.

欲知此库的更新情况,请参见: [GitHub 发布页面](https://github.com/AfterShip/tracking-sdk-nodejs/releases)。 。 。 .

如果您需要使用 AfterShip 产品支持,请联系 [支持@aftership.com](mailto:support@aftership.com)。 。 。 .

## 目录

-   [为 Node.js 的 Ship 跟踪 API 库之后](https://npmcn.com/package/%40aftership/tracking-sdk/#readme-aftership-tracking-api-library-for-nodejs)
    -   [目录](https://npmcn.com/package/%40aftership/tracking-sdk/#readme-table-of-contents)
    -   [在你开始之前](https://npmcn.com/package/%40aftership/tracking-sdk/#readme-before-you-begin)
        -   [API 和 SDK 版本](https://npmcn.com/package/%40aftership/tracking-sdk/#readme-api-and-sdk-version)
    -   [快速启动](https://npmcn.com/package/%40aftership/tracking-sdk/#readme-quick-start)
        -   [安装](https://npmcn.com/package/%40aftership/tracking-sdk/#readme-installation)
    -   [构造器](https://npmcn.com/package/%40aftership/tracking-sdk/#readme-constructor)
        -   [示例](https://npmcn.com/package/%40aftership/tracking-sdk/#readme-example)
    -   [限制费率](https://npmcn.com/package/%40aftership/tracking-sdk/#readme-rate-limiter)
    -   [处理错误](https://npmcn.com/package/%40aftership/tracking-sdk/#readme-error-handling)
        -   [错误列表](https://npmcn.com/package/%40aftership/tracking-sdk/#readme-error-list)
    -   [终点](https://npmcn.com/package/%40aftership/tracking-sdk/#readme-endpoints)
        -   [/跟踪](https://npmcn.com/package/%40aftership/tracking-sdk/#readme-trackings)
        -   [警车](https://npmcn.com/package/%40aftership/tracking-sdk/#readme-couriers)
        -   [/ cour- 连接](https://npmcn.com/package/%40aftership/tracking-sdk/#readme-courier-connections)
        -   [/估计交付日期](https://npmcn.com/package/%40aftership/tracking-sdk/#readme-estimated-delivery-date)
    -   [帮助](https://npmcn.com/package/%40aftership/tracking-sdk/#readme-help)
    -   [许可证](https://npmcn.com/package/%40aftership/tracking-sdk/#readme-license)

## 在你开始之前

在开始整合之前:

-   [创建 AfterShip 账户](https://admin.aftership.com/)。 。 。 .
-   [创建 API 密钥](https://organization.automizely.com/api-keys)。 。 。 .
-   [安装节点.js](https://nodejs.org/en/download/) 16版或稍后版本.

### API 和 SDK 版本

-   SDK版本: 17.0
-   API 版本: 2026-07

## 快速启动

### 安装

```bash
npm install --save @aftership/tracking-sdk
```

## 构造器

使用选项创建 Ship 后实例

| 名称 | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| 键 | 字符串 | ✔ | 您的 IP API 密钥后 |
| 认证类型( a) | 语句 |  | 默认值 : `AuthType.API_KEY`  
AES 认证 : `AuthType.AES`  
RSA 认证 : `AuthType.RSA` |
| 密语( s) | 字符串 |  | 如果认证类型是 `AuthType.AES` 或者说 `AuthType.RSA` |
| 域名 | 字符串 |  | 在Ship API域名之后. 默认值 : [https://api.aftership.com (中文(简体) )](https://api.aftership.com/) |
| 用户代理( a) | 字符串 |  | 用户定义的用户代理字符串, 请遵循 [RFC9110 (法语)](https://www.rfc-editor.org/rfc/rfc9110#field.user-agent) 格式标准. |
| 代理服务器 | 字符串 |  | 用于请求的 HTTP 代理 URL .  
默认值 : `null`  
示例 `http://192.168.0.100:8888` |
| 最大重试( r) | 编号 |  | 每个请求的重试次数 。 默认值: 2. min为0, Max为10. |
| 超时 | 编号 |  | 每个请求的超时, 以毫秒计 . |

### 示例

```javascript
// Step 1: Import the AfterShip client
import { AfterShip } from "@aftership/tracking-sdk";
// or
// const { AfterShip } = require('@aftership/tracking-sdk');

// Step 2: Initialize the client object
const aftership = new AfterShip({ api_key: "YOUR_API_KEY" });

// Step 3: Create the query object
const query = {};

// Step 4: Make the request
aftership.tracking
  .getTrackingById(
    "valid_value",

    query,
  )
  .then((result) => console.log(result))
  .catch((e) => console.log(e));
```

## 限制费率

见 [费率限制](https://www.aftership.com/docs/tracking/quickstart/rate-limit) 以了解AfterShip利率限制政策.

API返回其在每个响应头的当前速率限制状态,SDK在成功响应和速率限制错误上都会暴露出这些头,这样您就可以主动地监视您的消费,而不是等待 `429` 错误.

| 页眉 | 说明 |
| --- | --- |
| `X-RateLimit-Limit` | 当前终点每秒的费率上限 |
| `X-RateLimit-Remaining` | 1秒窗口所剩请求数 |
| `X-RateLimit-Reset` | 重置速度限制时的 Unix 时间戳 |

每一次成功的对策都表明 `response_headers` 对象并列 `data` (标题名称为小写). 以上面的快速启动为例:

```javascript
const remaining = Number(result.response_headers["x-ratelimit-remaining"]);
const resetAt = Number(result.response_headers["x-ratelimit-reset"]);

if (remaining <= 1) {
  // Throttle or defer lower-priority requests until `resetAt`
}
```

当超过费率限制时,请求失败 `429` 带有相同信头的错误——见 [处理错误](https://npmcn.com/package/%40aftership/tracking-sdk/#readme-error-handling)。 。 。 .

## 处理错误

SDK会在请求中出现出错时返回出错对象,其规格如下:

| 名称 | 类型 | 说明 |
| --- | --- | --- |
| 消息 | 字符串 | 错误的详细信息 |
| 代码 | 语句 | API 错误代码enum 错误 . |
| 元码 | 编号 | API响应元码. |
| 状态( c) | 编号 | HTTP状态代码. |
| 响应( b) | 字符串 | API反应机体. |
| 响应( h) | 对象 | API响应头. |

### 错误列表

| 代码 | 元码 | 状态( c) | 消息 |
| --- | --- | --- | --- |
| 申请 | 400个 | 400个 | 请求无效或无法以其他方式送达. |
| 参赛者( J) | 4001 (英语) | 400个 | 无效的JSON数据 . |
| 跟踪( A) | 4003 (英语) | 400个 | 跟踪已经存在. |
| 跟踪( D) | 4004 (中文(简体) ) | 404 (韩语) | 追踪不存在. |
| 跟踪( N) | 4005 (英语) | 400个 | 跟踪 数字的值无效 . |
| 跟踪( R) | 4006号 | 400个 | 需要跟踪对象. |
| 跟踪( N) | 4007 (英语) | 400个 | 需要跟踪 数字. |
| VALUE 评价 | 第4008号 | 400个 | \[field name\] 的值无效. |
| 数值( REQ) | 4009 (英语) | 400个 | \[域名\]是需要的. |
| (原始内容存档于2018-09-21) (英语). SLUG IVALID | 第40条 | 400个 | 弹片的值无效 . |
| 错过 OR 评估 REQUID FIELD | 第4011号 | 400个 | 该信使所需的字段缺少或无效值 。 除了跟踪 数字,还需要: \[字段 名称\] |
| 糟糕的学校 | 第4012号 | 400个 | 错误消息将是以下之一: 1. 无法进口货运,因为承运人不在贵国核准的承运人自动检测清单中。 在此添加载体 : [https://admin.aftership.com/ settings/couriers2 (中文(简体) )](https://admin.aftership.com/settings/couriers2)无法进口货物,因为我们无法从这个追踪号码中识别到承运人。 3个 无法导入货运, 因为跟踪号格式无效 。 4.四. 由于该承运人不再得到支持,无法进口货运。 5 (韩语). 无法进口货运,因为追踪号不属于该组中的承运人. |
| 缩略语 RETRACK 注: | 第4013号 | 400个 | 不允许重新追踪 。 您只能重新追踪不活动跟踪 . |
| 通知 已撤销 | 第4014条 | 400个 | 需要通知对象. |
| 识别( I) | 第4015号 | 400个 | Id的值无效. |
| 重新开放 | 第4016号 | 400个 | 不允许重新追踪 。 只能重新追踪一次. |
| 跟踪( N) 格式 估价 | 第4017号 | 400个 | 跟踪 数字的格式无效 . |
| API KEY 评估 | 401 (中文(简体) ) | 401 (中文(简体) ) | API 密钥无效 . |
| 请求( N) | 403 (韩语) | 403 (韩语) | 请求是可以理解的,但被拒绝或不允许访问. |
| 无 | 404 (韩语) | 404 (韩语) | 请求的 URI 无效或请求的资源不存在 . |
| (原始内容存档于2018-07-26) (英语). TOO MANY REQUEST | 429个 | 429个 | 您已超过 API 的呼叫率限制 。 默认限制为每秒10个请求. |
| 内部错误 | 500个 | 500个 | Ship死后出了点事. |
| 内部错误 | 502 (中文(简体) ) | 502 (中文(简体) ) | Ship死后出了点事. |
| 内部错误 | 第503条 | 第503条 | Ship死后出了点事. |
| 内部错误 | 504 (中文(简体) ) | 504 (中文(简体) ) | Ship死后出了点事. |

```
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
```

## 终点

AfterShip 实例的属性与 API 端点完全相同 :

-   跟踪
    -   获取跟踪
    -   创建跟踪
    -   通过身份追踪
    -   以 ID 更新跟踪
    -   以 ID 删除跟踪
    -   以 ID 重追踪已过期的跟踪
    -   标记跟踪由 ID 完成
-   邮递员
    -   找快递员
    -   侦测信使
-   信使连接
    -   获取信使连接
    -   创建信使连接
    -   通过 id 获取快递连接
    -   通过 id 更新快递连接
    -   以 id 删除信使连接
-   估计交付日期
    -   估计交付日期的预测
    -   估计交付日期批次预测

### /跟踪

**获取** /跟踪

```javascript
const query = {};

aftership.tracking
  .getTrackings(query)
  .then((result) => console.log(result))
  .catch((e) => console.log(e));
```

**邮政** /跟踪

```javascript
const createTrackingRequestBody = {
  tracking_number: "valid_value",
};

aftership.tracking
  .createTracking(createTrackingRequestBody)
  .then((result) => console.log(result))
  .catch((e) => console.log(e));
```

**获取** /跟踪/{id}

```javascript
const query = {};

aftership.tracking
  .getTrackingById(
    "valid_value",

    query,
  )
  .then((result) => console.log(result))
  .catch((e) => console.log(e));
```

**点** /跟踪/{id}

```javascript
const updateTrackingByIdRequestBody = {};

aftership.tracking
  .updateTrackingById("valid_value", updateTrackingByIdRequestBody)
  .then((result) => console.log(result))
  .catch((e) => console.log(e));
```

**迪莱特** /跟踪/{id}

```javascript
aftership.tracking
  .deleteTrackingById("valid_value")
  .then((result) => console.log(result))
  .catch((e) => console.log(e));
```

**邮政** /跟踪/{id}/再跟踪

```javascript
aftership.tracking
  .retrackTrackingById("valid_value")
  .then((result) => console.log(result))
  .catch((e) => console.log(e));
```

**邮政** /跟踪/{id}/标记-已完成

```javascript
const markTrackingCompletedByIdRequestBody = {};

aftership.tracking
  .markTrackingCompletedById(
    "valid_value",
    markTrackingCompletedByIdRequestBody,
  )
  .then((result) => console.log(result))
  .catch((e) => console.log(e));
```

### 警车

**获取** 警车

```javascript
const query = {};

aftership.courier
  .getCouriers(query)
  .then((result) => console.log(result))
  .catch((e) => console.log(e));
```

**邮政** 警监/侦察员

```javascript
const detectCourierRequestBody = {
  tracking_number: "valid_value",
};

aftership.courier
  .detectCourier(detectCourierRequestBody)
  .then((result) => console.log(result))
  .catch((e) => console.log(e));
```

### / cour- 连接

**获取** / cour- 连接

```javascript
const query = {};

aftership.courierConnection
  .getCourierConnections(query)
  .then((result) => console.log(result))
  .catch((e) => console.log(e));
```

**邮政** / cour- 连接

```javascript
const postCourierConnectionsRequestBody = {
  courier_slug: "valid_value",
  credentials: {},
};

aftership.courierConnection
  .postCourierConnections(postCourierConnectionsRequestBody)
  .then((result) => console.log(result))
  .catch((e) => console.log(e));
```

**获取** /courier-连接/{id}

```javascript
aftership.courierConnection
  .getCourierConnectionsById("valid_value")
  .then((result) => console.log(result))
  .catch((e) => console.log(e));
```

**帕齐** /courier-连接/{id}

```javascript
const putCourierConnectionsByIdRequestBody = {
  credentials: {},
};

aftership.courierConnection
  .putCourierConnectionsById(
    "valid_value",
    putCourierConnectionsByIdRequestBody,
  )
  .then((result) => console.log(result))
  .catch((e) => console.log(e));
```

**迪莱特** /courier-连接/{id}

```javascript
aftership.courierConnection
  .deleteCourierConnectionsById("valid_value")
  .then((result) => console.log(result))
  .catch((e) => console.log(e));
```

### /估计交付日期

**邮政** /估计交付日期/预测

```javascript
const predictRequestBody = {
  slug: "valid_value",
  origin_address: {}, // EstimatedDeliveryDateRequestOriginAddress
  destination_address: {}, // EstimatedDeliveryDateRequestDestinationAddress
};

aftership.estimatedDeliveryDate
  .predict(predictRequestBody)
  .then((result) => console.log(result))
  .catch((e) => console.log(e));
```

**邮政** 估计交付日期/预期批次

```javascript
const predictBatchRequestBody = {};

aftership.estimatedDeliveryDate
  .predictBatch(predictBatchRequestBody)
  .then((result) => console.log(result))
  .catch((e) => console.log(e));
```

## 帮助

如果你被卡住,我们在这里帮助:

-   [问题跟踪器](https://github.com/AfterShip/tracking-sdk-nodejs/issues) 对于与本套件相关的问题、特性请求、错误报告和一般性讨论。 在创建新问题之前尝试搜索 .
-   通过Ship 正式支持后联系 [支持@aftership.com](mailto:support@aftership.com)

## 许可证

版权 (c) 2025 Sip之后

持有麻省理工学院执照.

## 常见问题

### @aftership/tracking-sdk 是什么？

跟踪节点JS SDK

### 如何安装 @aftership/tracking-sdk？

在项目目录运行 npm install @aftership/tracking-sdk，或使用 pnpm add / yarn add / bun add。

### @aftership/tracking-sdk 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @aftership/tracking-sdk 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @aftership/tracking-sdk 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=16\.20\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @aftership/tracking-sdk 可以商用吗？

@aftership/tracking-sdk 使用 ISC 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @aftership/tracking-sdk 的下载量有多少？

根据 npm 官方下载统计，@aftership/tracking-sdk 在 2026/10/05 – 2026/11/03 这 30 天内被下载 60,375 次，日均约 2,013 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @aftership/tracking-sdk 还在维护吗？

最新版本 17\.0\.0 发布于 2026/07/13（3 个月前）；至今共发布 16 个版本，其中过去 12 个月发布了 3 个；首次发布于 2024/06/20。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。