17Track API SDK

基于 TypeScript 的 17Track API SDK，提供完整的类型定义和易用的接口封装。

安装

npm install @be-link/17trak-api-sdk
# 或
pnpm install @be-link/17trak-api-sdk
# 或
yarn add @be-link/17trak-api-sdk

快速开始

初始化 SDK

import { TrackSDK } from '@be-link/17trak-api-sdk';

const sdk = new TrackSDK({
  apiKey: 'your-api-key-here',
  timeout: 30000, // 可选，默认 30 秒
  enableRateLimit: true, // 可选，默认启用限流（3 req/s）
  rateLimitOptions: {
    windowMs: 1000, // 1秒
    maxRequests: 3, // 最大 3 个请求/秒
  },
});

注册追踪单号

const response = await sdk.registerTracking([
  {
    number: 'RR123456789CN',
    carrier: 3011, // 中国邮政
    lang: 'zh-hans', // 简体中文
    tag: '我的订单ID',
  },
]);

console.log('注册成功:', response.data.accepted);
console.log('注册失败:', response.data.rejected);

获取追踪详情

const response = await sdk.getTrackingInfo([
  {
    number: 'RR123456789CN',
    carrier: 3011,
  },
]);

const trackInfo = response.data.accepted[0];
console.log('最新状态:', trackInfo.track_info.latest_status.status);
console.log('运输天数:', trackInfo.track_info.time_metrics.days_of_transit);

获取实时追踪详情

const response = await sdk.getRealTimeTrackingInfo([
  {
    number: 'RR123456789CN',
    carrier: 3011,
    cacheLevel: 1, // 立即获取最新信息（消耗10配额）
  },
]);

搜索追踪列表

const response = await sdk.searchTrackingList({
  package_status: 'Delivered',
  register_time_from: '2024-01-01',
  register_time_to: '2024-12-31',
  page_no: 1,
});

console.log('总数据量:', response.page.data_total);

获取配额信息

const response = await sdk.getQuota();
console.log('剩余配额:', response.data.quota_remain);

Webhook 处理

Express.js 示例

import express from 'express';
import { createExpressWebhookMiddleware } from '@be-link/17trak-api-sdk';

const app = express();
app.use(express.json());

app.post('/webhook', createExpressWebhookMiddleware('your-api-key'));

app.listen(3000);

自定义 Webhook 处理

import { WebhookHandler, WebhookEvent } from '@be-link/17trak-api-sdk';

const handler = new WebhookHandler({ apiKey: 'your-api-key' });

// 处理 Webhook 消息
const message = handler.handleWebhook(requestBody, signature);

if (message.event === WebhookEvent.TRACKING_UPDATED) {
  console.log('追踪已更新:', message.data);
}

API 接口

追踪管理

• registerTracking() - 注册追踪单号
• changeCarrier() - 更改运输商
• changeInfo() - 更改注册信息
• stopTracking() - 停止追踪
• retrack() - 重新追踪
• deleteTracking() - 删除追踪单号

查询接口

• getTrackingInfo() - 获取追踪详情
• getRealTimeTrackingInfo() - 获取实时追踪详情
• searchTrackingList() - 搜索追踪列表
• getQuota() - 获取配额信息

推送接口

• manualPush() - 手动推送

错误处理

import { TrackAPIError, ErrorCode } from '@be-link/17trak-api-sdk';

try {
  await sdk.registerTracking([...]);
} catch (error) {
  if (error instanceof TrackAPIError) {
    console.error('错误代码:', error.code);
    console.error('错误信息:', error.message);
    console.error('HTTP状态码:', error.statusCode);
  }
}

类型定义

SDK 提供完整的 TypeScript 类型定义，包括：

• 请求参数类型
• 响应数据类型
• 枚举类型（状态码、错误码、包裹状态等）
• Webhook 消息类型

限流管理

SDK 内置请求限流功能，默认限制为 3 req/s，防止超过 API 限制：

// 检查限流器状态
const status = sdk.getRateLimiterStatus();
console.log('当前请求数:', status.currentRequests);

// 重置限流器
sdk.resetRateLimiter();

签名验证

用于验证 Webhook 推送消息的签名：

import { verifySignature } from '@be-link/17trak-api-sdk';

const isValid = verifySignature(requestBody, apiKey, signature);

常量定义

import {
  HttpStatusCode,
  ErrorCode,
  PackageStatus,
  LanguageCode,
} from '@be-link/17trak-api-sdk';

更多示例

查看 src/examples 目录获取更多使用示例。

官方文档

17Track API 官方文档