@qzsy/kd100-sdk

Bun + TypeScript 7 SDK for 快递100企业版“订单导入”接口。运行时零依赖，支持 Node.js 22+ 和 Bun 1.4+，表单请求使用 application/x-www-form-urlencoded。

官方订单导入文档的六个章节均有对应能力：

| 官方接口 | SDK 方法 | | --- | --- | | /ent/shop/authorize 获取店铺授权链接 | authorizeShop | | /ent/order/task 提交销售订单任务 | submitOrderTask | | 销售订单结果推送回调 | parseOrderCallback | | /ent/refundOrder/task 提交售后订单任务 | submitRefundOrderTask | | 售后订单结果推送回调 | parseRefundCallback | | /ent/logistics/send 回传快递单号并更新发货状态 | sendLogistics | | /label/order?method=order 电子面单下单 | createLabel | | /label/order?method=printOld 电子面单复打 | reprintLabel | | /label/order?method=cancel 电子面单取消 | cancelLabel | | https://poll.kuaidi100.com/poll 物流订阅 | subscribeTracking |

使用

import { createClient } from "@qzsy/kd100-sdk";

const kd100 = createClient({
  key: process.env.KD100_KEY!,
  secret: process.env.KD100_SECRET!,
});

const tasks = await kd100.submitOrderTask({
  shopType: "TAOBAO",
  shopId: "shop-id",
  orderStatus: "UNSHIP",
  updateAtMin: "2026-09-30 00:00:00",
  updateAtMax: "2026-09-30 01:00:00",
  callbackUrl: "https://erp.example.com/kd100/orders",
  salt: process.env.KD100_CALLBACK_SALT!,
});
console.log(tasks.data?.tasks);

请求签名严格按 MD5(param + key + secret) 计算并转大写；param 只序列化一次，签名和发送使用同一字符串。回调验签严格按收到的原始 param 字符串计算 MD5(param + salt)，解析器在验签后才进行 JSON 解析：

const callback = kd100.parseOrderCallback(
  { param: req.body.param, sign: req.body.sign, taskId: req.body.taskId },
  process.env.KD100_CALLBACK_SALT!,
);
// 先将 callback.param 持久化，再异步匹配商品、库存和履约状态。
const orders = callback.payload.orders;

电子面单 V2 使用另一套响应和签名：MD5(param + t + key + secret)，SDK 会在 createLabel、reprintLabel、cancelLabel 中生成毫秒时间戳并提交同一份原始 JSON 字符串。面单响应采用官方的 success/code/message/data envelope：

const label = await kd100.createLabel({
  printType: "IMAGE",
  partnerId: process.env.KD100_PARTNER_ID!,
  kuaidicom: "shunfeng",
  recMan: { name: "收件人", mobile: "13800000000", printAddr: "广东省深圳市" },
  sendMan: { name: "寄件人", mobile: "13900000000", printAddr: "广东省广州市" },
  cargo: "文件",
  count: 1,
});
console.log(label.data?.kuaidinum, label.data?.label);

subscribeTracking 调用物流订阅接口并将企业 key 放在 param.key，物流推送和面单 打印状态推送都可用 parseTrackingCallback / parsePrintCallback 验签。解析器会先对 收到的原始 param 验签，再解析 JSON；传入空字符串 salt 时可以选择跳过签名校验。

默认要求回调签名；仅在你已通过其他通道完成认证时，才传入第三个参数 false 接受无签名回调。授权成功推送可用额外的 parseShopAuthorizeCallback 解析。

开发

bun install
bun run typecheck
bun test tests
bun run build

build 输出 ESM、CommonJS 和 .d.ts 到 dist/。密钥只应放在服务端环境变量中；Next.js 对接建议在 Route Handler/Server Action 中调用，浏览器端不要打包企业 secret。