@qzsy/jushuitan

聚水潭开放平台 TypeScript SDK，完整封装文档中的 169 个 API（19 个分类）。

安装

npm install @qzsy/jushuitan

字段级 TypeScript 类型（v1.1+）

每个接口从官方 reqJsonSchema / respJsonSchema 自动生成类型，IDE 可补全 biz 入参 与 响应 data 字段：

import { JushuitanSdk, type ShopsQueryBiz, type ShopsQueryData } from "@qzsy/jushuitan";

const sdk = new JushuitanSdk({ appKey, appSecret, accessToken });

// 入参、返回值均有字段提示
const res = await sdk.basic.shopsQuery({
  page_index: 1,
  page_size: 10,
  shop_ids: [10178845],
});

const shops = res.data.datas; // ShopsQueryData['datas']

类型命名规则：{MethodName}Biz / {MethodName}Data，例如 shopsQuery → ShopsQueryBiz、ShopsQueryData。

也可按需单独导入：

import type { JushuitanOrdersUploadBiz, JushuitanOrdersUploadData } from "@qzsy/jushuitan";

更新 schema 缓存并重新生成：

npm run fetch-schemas   # 从官方拉取最新 JSON Schema
npm run generate        # 重新生成 API + 类型

import { JushuitanSdk, JushuitanAuthClient } from "@qzsy/jushuitan";

// 1. 获取 token（授权接口）
const auth = new JushuitanAuthClient({
  appKey: "your-app-key",
  appSecret: "your-app-secret",
  environment: "sandbox", // 或 "production"
});

const tokenRes = await auth.getInitToken("随机6位code");
const { access_token } = tokenRes.data;

// 2. 创建 SDK 客户端
const sdk = new JushuitanSdk({
  appKey: "your-app-key",
  appSecret: "your-app-secret",
  accessToken: access_token,
  environment: "sandbox",
});

// 3. 调用 API
const shops = await sdk.basic.shopsQuery({ page_index: 1, page_size: 10 });
console.log(shops.data);

API 分类

| 属性 | 分类 | 接口数 | |------|------|--------| | sdk.basic | 基础API | 6 | | sdk.product | 商品API | 20 | | sdk.inventory | 库存API | 5 | | sdk.order | 订单API | 16 | | sdk.logistics | 物流API | 4 | | sdk.purchase | 采购API | 12 | | sdk.inbound | 入库API | 7 | | sdk.outbound | 出库API | 5 | | sdk.aftersale | 售后API | 10 | | sdk.otherInout | 其它出入库API | 3 | | sdk.allocate | 调拨API | 6 | | sdk.crossBorder | 跨境API | 10 | | sdk.invoice | 票聚API | 4 | | sdk.workOrder | 聚工单开放API | 3 | | sdk.finance | 财务API | 5 | | sdk.seeding | 播种API | 8 | | sdk.virtualWarehouse | 虚拟仓API | 8 | | sdk.shengsuan | 胜算API | 15 | | sdk.wms | WMS API | 22 |

底层客户端

如需直接按路径调用：

import { JushuitanClient } from "@qzsy/jushuitan";

const client = new JushuitanClient({ appKey, appSecret, accessToken });
await client.request("/open/shops/query", { page_index: 1 });

开发

cd packages/jushuitan
npm install
npm run generate   # 从 docs/_meta.json 重新生成 API
npm test
npm run build

发布

npm publish --access public