@qzsy/qimen-sdk

奇门仓储 TypeScript SDK。用于 ERP 系统经奇门对接万里牛、聚水潭等 WMS。

你的系统 (ERP)  --taobao.qimen.*-->  奇门  ---->  WMS
你的系统 (ERP)  <--confirm/report--  奇门  <----  WMS

协议依据奇门仓储接入说明与白皮书 V3.9.5：仅 POST、仅 XML、系统参数放 query、业务报文放 body、v=2.0、customerId 必填。

安装

npm i @qzsy/qimen-sdk

也可以 bun add @qzsy/qimen-sdk。本地未发布时：bun add ../taobao-qimen。

Client（ERP → 奇门 → WMS）

import { QimenClient } from "@qzsy/qimen-sdk";

const client = new QimenClient({
  appKey: process.env.QIMEN_APP_KEY!,
  appSecret: process.env.QIMEN_APP_SECRET!,
  customerId: process.env.QIMEN_CUSTOMER_ID!, // WMS 分配的货主 ID
  env: "test", // test | prod
  signMethod: "hmac-sha256",
});

const res = await client.deliveryorder.create({
  deliveryOrder: {
    deliveryOrderCode: "TB1234",
    orderType: "JYCK",
    warehouseCode: "OTHER",
    createTime: "2026-08-27 12:00:00",
    placeOrderTime: "2026-08-27 12:00:00",
    operateTime: "2026-08-27 12:00:00",
    shopNick: "店铺",
    logisticsCode: "OTHER",
    senderInfo: { name: "仓库", mobile: "13800000000", province: "浙江", city: "杭州", detailAddress: "..." },
    receiverInfo: { name: "张三", mobile: "13900000000", province: "上海", city: "上海", detailAddress: "..." },
  },
  orderLines: [{ ownerCode: "OW1", itemCode: "I1234", planQty: 1, actualPrice: "0" }],
});

通用调用：client.execute("taobao.qimen.stock.query", { warehouseCode: "WH1", page: 1, pageSize: 20 })。

环境地址：

| 环境 | URL | | --- | --- | | 测试 | https://qimen.api.taobao.com/router/qmtest | | 正式 | https://qimen.api.taobao.com/router/qimen/service |

可用 endpoint 覆盖。对接万里牛/聚水潭需要三方：appKey、appSecret（开放平台应用）、customerId（WMS 给商家的货主账号）。

SPI（WMS → 奇门 → ERP）

发货确认、入库确认、库存异动由 WMS 经奇门回推到你的 HTTP 服务，需验签后返回 XML。

import { QimenSpi } from "@qzsy/qimen-sdk";

const spi = new QimenSpi({
  appSecret: process.env.QIMEN_APP_SECRET!,
  signMethod: "hmac-sha256",
});

spi.on("deliveryorder.confirm", async (req) => {
  // 处理发货确认
  void req.deliveryOrder?.deliveryOrderCode;
  return { flag: "success", code: "0", message: "success" };
});

spi.on("stockchange.report", async () => ({ flag: "success", code: "0", message: "success" }));

// 任意 HTTP 框架
export async function POST(request: Request) {
  const xml = await spi.handle({
    query: Object.fromEntries(new URL(request.url).searchParams),
    body: await request.text(),
  });
  return new Response(xml, { headers: { "Content-Type": "text/xml; charset=utf-8" } });
}

接口一览

正向（client.deliveryorder.create 等）与反向（spi.on("deliveryorder.confirm")）覆盖白皮书仓储接口，包括商品、入库、退货、出库、发货、库存、仓内加工、调拨、心跳等。方法名与奇门一致，去掉 taobao.qimen. 前缀即为 SPI method。

开发

bun install
bun test
bun run build

示例

# 发货单创建（需配置环境变量）
bun examples/client.ts

# 本地 SPI 服务，监听 /qimen
bun examples/spi.ts

观测台

Bun.serve 直接导入 HTML，打包 React，并提供签名/XML/SPI 观测 API：

bun run dev

打开 http://127.0.0.1:3456 。顶部填写 appKey / appSecret / customerId（存在浏览器 localStorage）。左侧选接口，可：

1. 生成 XML / 签名：看 SDK 真正产出的 body 与 query，不发网
2. 真实调用奇门：用当前凭据打测试/正式网关
3. 填入 SPI 入站样例 再 验签并模拟应答：观察 WMS 回推链路