Express Delivery API SDK

快递100 API 的 TypeScript SDK，提供完整的类型定义和便捷的接口封装。

功能特性

• 实时快递查询 - 查询快递单号的实时物流轨迹
• 地图轨迹查询 - 获取带地图轨迹的物流信息
• 快递订阅 - 订阅快递单号，接收物流状态推送
• Webhook 支持 - 解析和验证快递100推送的回调数据
• 自动限流 - 内置固定窗口限流器，防止请求过载
• 自动重试 - 支持可配置的重试机制
• 完整类型 - 全面的 TypeScript 类型定义，提供良好的开发体验

安装

npm install @be-link/express-delivery-api-sdk
# 或
pnpm add @be-link/express-delivery-api-sdk
# 或
yarn add @be-link/express-delivery-api-sdk

快速开始

初始化客户端

import { ExpressDeliveryClient } from '@be-link/express-delivery-api-sdk';

const client = new ExpressDeliveryClient({
  customer: 'YOUR_CUSTOMER_ID',  // 快递100 企业编号
  key: 'YOUR_API_KEY',           // 授权 key
  baseURL: 'https://poll.kuaidi100.com', // 可选，默认值
  timeoutMs: 5000,               // 可选，默认 5000ms
});

实时快递查询

import { ExpressDeliveryClient } from '@be-link/express-delivery-api-sdk';

const client = new ExpressDeliveryClient({
  customer: 'YOUR_CUSTOMER_ID',
  key: 'YOUR_API_KEY',
});

const result = await client.realTimeQuery({
  com: 'yuantong',              // 快递公司编码
  num: 'YT25569986666541',      // 快递单号
  phone: '13800138000',         // 可选，收寄件人电话
  from: '安徽省六安市霍邱县',    // 可选，出发地
  to: '江苏省苏州市昆山市',      // 可选，目的地
  resultv2: 1,                  // 可选，返回详细结果
  order: 'desc',                // 可选，排序方式
});

if (result.ok) {
  console.log('快递状态:', result.data?.state);
  console.log('轨迹信息:', result.data?.data);
} else {
  console.error('查询失败:', result.infoMessage);
}

地图轨迹查询

const result = await client.mapTrackQuery({
  com: 'yuantong',
  num: 'YT25569986666541',
  from: '广东省深圳市南山区',
  to: '江苏省南京市玄武区',
  resultv2: '7',                // 可选，返回 AI 时效预测
  needCourierInfo: true,        // 可选，返回快递员信息
});

if (result.ok) {
  console.log('地图轨迹链接:', result.data?.trailUrl);
  console.log('快递员信息:', result.data?.courierInfo);
}

快递订阅

const result = await client.subscribeTracking({
  company: 'yuantong',
  number: 'YT6186594166532',
  from: '广东省深圳市南山区',
  to: '江苏省南京市玄武区',
  parameters: {
    callbackUrl: 'https://your-domain.com/webhook/kuaidi',
    salt: 'YOUR_SALT',          // 可选，用于签名验证
    resultv2: '4',              // 可选，返回详细结果
    autoCom: '0',               // 可选，是否开启智能识别
  },
});

if (result.ok) {
  console.log('订阅成功');
}

Webhook 回调处理

import {
  parseExpressDeliveryPush,
  verifyExpressDeliveryPushSignature,
} from '@be-link/express-delivery-api-sdk';

// Express 示例
app.post('/webhook/kuaidi', express.urlencoded({ extended: true }), (req, res) => {
  try {
    // 解析推送数据
    const { request, payload } = parseExpressDeliveryPush(req.body);
    
    // 验证签名（如果订阅时提供了 salt）
    const salt = 'YOUR_SALT'; // 从数据库或其他地方获取
    if (!verifyExpressDeliveryPushSignature(request.param, salt, request.sign)) {
      return res.status(401).send('Invalid signature');
    }
    
    // 处理推送数据
    console.log('任务状态:', payload.status);
    console.log('运单状态:', payload.billstatus);
    console.log('最新轨迹:', payload.lastResult);
    
    res.status(200).send('ok');
  } catch (error) {
    console.error('处理推送失败:', error);
    res.status(500).send('Internal error');
  }
});

高级配置

自定义限流器

import { ExpressDeliveryClient, FixedWindowRateLimiter } from '@be-link/express-delivery-api-sdk';

const client = new ExpressDeliveryClient({
  customer: 'YOUR_CUSTOMER_ID',
  key: 'YOUR_API_KEY',
  rateLimiter: new FixedWindowRateLimiter({
    maxRequests: 20,    // 每个窗口最大请求数
    windowMs: 1000,     // 时间窗口（毫秒）
  }),
});

自定义重试配置

const client = new ExpressDeliveryClient({
  customer: 'YOUR_CUSTOMER_ID',
  key: 'YOUR_API_KEY',
  retry: {
    maxRetries: 5,      // 最大重试次数
    baseDelayMs: 1000,  // 基础延迟时间（毫秒）
  },
});

通用请求方法

// 使用通用 request 方法调用其他 API
const result = await client.request({
  path: '/custom/endpoint',
  method: 'POST',
  payload: { /* 你的参数 */ },
  contentType: 'form',  // 或 'json'
  needSign: true,       // 是否需要签名
});

API 参考

ExpressDeliveryClient

构造函数选项

• customer (string, 必需) - 快递100 企业编号
• key (string, 必需) - 授权 key
• baseURL (string, 可选) - API 根地址，默认 https://poll.kuaidi100.com
• timeoutMs (number, 可选) - 请求超时时间，默认 5000
• rateLimiter (RateLimiter, 可选) - 自定义限流器
• retry (Partial, 可选) - 重试配置

方法

• realTimeQuery(payload: RealTimeQueryPayload) - 实时快递查询
• mapTrackQuery(payload: MapTrackQueryPayload) - 地图轨迹查询
• subscribeTracking(payload: SubscribeTrackingPayload) - 快递订阅
• request<TPayload, TData>(options: ExpressDeliveryRequestOptions) - 通用请求方法

枚举类型

• ExpressDeliveryInfoCode - API 响应状态码
• ExpressDeliveryShipmentState - 物流状态
• ExpressDeliveryPushTaskStatus - 推送任务状态
• ExpressDeliveryBillStatus - 运单业务状态

Webhook 工具

• parseExpressDeliveryPush(body) - 解析推送数据
• verifyExpressDeliveryPushSignature(param, salt, sign) - 验证签名

开发

# 安装依赖
pnpm install

# 运行测试
pnpm test

# 监听模式运行测试
pnpm test:watch

# 生成测试覆盖率报告
pnpm test:coverage

# 构建项目
pnpm build

相关文档

• 快递100 API 文档

作者

[email protected]