npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@qzsy/group-sdk

v0.1.6

Published

群兴云集团 SaaS 对接统一支付网关的 TypeScript SDK:集团凭据、多主体/多应用管理、门店账单与佣金付款

Readme

@qzsy/group-sdk

群兴云集团 SaaS 对接统一支付网关的官方 SDK:集团凭据一次接入,管理多个营业执照主体、每执照一个小程序应用,并读取门店账单、发起佣金转账。

底层 HTTP、OAuth 令牌缓存、错误模型全部复用 @qzsy/unipay-sdk,所以集团侧只需要安装这一个包:应用维度(下单、收银台、退款、付款)的能力也一并可用。

  • Node.js ≥ 20.19(原生 fetch 与 require(esm);无运行时依赖)
  • ESM / CJS / TypeScript 类型三者齐全(CJS 依赖 Node ≥ 20.19 的 require(esm);更早版本请用 ESM 入口)
  • 金额一律「分」为单位,时间一律 ISO 8601 字符串

安装

npm install @qzsy/group-sdk
# 或 pnpm add @qzsy/group-sdk / yarn add @qzsy/group-sdk

快速开始

import { createGroupClient } from '@qzsy/group-sdk'

const group = createGroupClient({
  baseUrl: 'https://pay.example.com',       // 网关根地址,不要带 /api
  clientId: process.env.GROUP_CLIENT_ID!,   // 运营签发的集团凭据
  clientSecret: process.env.GROUP_CLIENT_SECRET!,
  // 集团总管理员代门店操作时上报,网关写入审计
  operator: { id: 'manager_1', name: 'Group Admin' },
})

// G-1 概览:主体数 / 应用数 / 已完成进件的账户数
const overview = await group.getOverview()

// G-2 主体列表:含每个主体的支付账户与应用
const { items: entities } = await group.listEntities()

典型流程

1. 开通一个门店(营业执照主体)

const { entity } = await group.createEntity({
  name: '杭州西湖店',
  legal_name: '杭州西湖咖啡有限公司',
  license_no: '91330100MA2H8XK21P',
  license_address: '杭州市西湖区文三路 100 号',
  contact_name: '沈亦然',
  contact_phone: '13800001234',
})

// W-2 建 LIVE 应用并签发应用凭据(client_secret 只返回这一次)
const { application, credential } = await group.createApplication({
  entity_id: entity.id,
  name: '西湖店小程序',
  slug: 'xihu-mini', // 组织内唯一;留空会按名称生成,生成不出合法 slug 时必填
  wechat_app_id: 'wx1234567890abcdef',
})

// W-4 提交微信进件(platform_channel_id 省略时按 provider 自动选唯一的 LIVE 通道)
await group.createMerchantAccount({
  provider: 'WECHAT',
  merchant_entity_id: entity.id,
  materials: { /* 见《业务对接》5.2 进件资料 */ },
})

集团 API 目前没有「进件查询」接口:进件进度看商户控制台,或订阅 com.unifiedpay.onboarding.* 回调(submitted / needs_verification / needs_sign / finished / rejected / canceled)。

2. 门店账单(按主体 + 站点)

// 门店账单由日结任务按 (主体, 站点) 生成,scope=STORE 必须带 store_code
const { items } = await group.listStatements({
  scope: 'STORE',
  entity_id: entity.id,
  store_code: 'store-hz-01',
  period_key: '2026-11-16',
})

const detail = await group.getStatement(items[0].id)   // 含明细行
const csv = await group.downloadStatementCsv(items[0].id) // 直接落盘即可

3. 佣金转账(分销分佣)

import { UnifiedPay } from '@qzsy/group-sdk'

// 付款主体 = 收这笔钱的应用所属主体,用它的应用凭据发起付款
const pay = new UnifiedPay({ baseUrl, clientId: APP_CLIENT_ID, clientSecret: APP_CLIENT_SECRET })

await pay.createPayout({
  scene_key: 'commission',
  merchant_payout_no: `DIST-${distributorId}-${periodKey}`,
  amount: { value: 1280, currency: 'CNY' },
  payee: { type: 'WECHAT_OPENID', id: distributorOpenId, app_id: appId },
  remark: '11 月分销佣金',
  site_code: 'store-hz-01',
  source_order_nos: ['ORD-1001', 'ORD-1002'],
})

// G-9 查集团范围内所有付款
const { items: payouts, next_cursor } = await group.listGroupPayouts({
  site_code: 'store-hz-01',
  status: 'SUCCEEDED',
})

接口对照

| 方法 | 网关接口 | 说明 | | --- | --- | --- | | getOverview() | G-1 /v1/group/overview | 主体 / 应用 / 可用账户计数 | | listEntities(query?) | G-2 /v1/group/entities | 支持 updated_since、limit | | listApplications(query?) | G-3 /v1/group/applications | 可按 entity_id 过滤 | | listChannelAccounts(query?) | G-4 /v1/group/channel-accounts | 平台镜像 / 直连 | | listSplitRules(accountId) | G-5 /v1/group/split-rules | 分账接收方 | | listStatements(query?) | G-6 /v1/group/statements | scope=STORE 需 store_code | | getStatement(id) | G-6 /v1/group/statements/:id | 含明细行 | | downloadStatementCsv(id) | G-6 …/download | 返回 CSV 文本 | | listPaymentIntents(query?) | G-7 /v1/group/payment-intents | 订单汇总 | | getSnapshot() | G-8 /v1/group/snapshot | 五个维度一次取回 | | listGroupPayouts(query?) | G-9 /v1/group/payouts | 游标翻页 | | getGroupPayout(id) | G-10 /v1/group/payouts/:id | 单笔详情 | | createEntity(input) | W-1 /v1/group/entities | 按 license_no 幂等 | | createApplication(input) | W-2 /v1/group/applications | 首次返回一次性凭据 | | bindApplicationChannel(input) | W-3 /v1/group/application-channels | 复用控制台校验 | | createMerchantAccount(input) | W-4 /v1/group/merchant-accounts | 代门店进件 | | applyEscrowPermission(accountId, options?) | W-5 /v1/group/escrow-applications | 申请担保+分账 | | getEscrowApplication(id) | W-6 /v1/group/escrow-applications/:id | 查审批进度 |

应用维度接口(下单、收银台、退款、付款、对账)由 UnifiedPay 提供,与 @qzsy/unipay-sdk 完全一致。

操作人(审计)

写接口会带上 X-Operator-Id / Name / Site 三个请求头。两种用法:

// 方式一:构造时设置默认操作人,后续所有写操作自动携带
const group = createGroupClient({ baseUrl, clientId, clientSecret, operator })

// 方式二:换一个身份(复用同一套凭据)
const asStoreManager = group.withOperator({ id: 'store_1_manager', name: 'Store Manager' })

// 单次覆盖
await group.createEntity(input, { operator: { id: 'manager_2', name: 'Ops' } })

三个字段都会进 HTTP 头,只能使用 ASCII 可见字符(中文名会被 SDK 在发请求前拒绝,报「只能使用 ASCII 可见字符」)。操作人只随写请求(同时带幂等键)发送,读请求不带。 withOperator() 复用同一套凭据,但令牌缓存是实例级的 —— 换身份后的第一个请求会重新取一次令牌。

幂等

所有写接口自动携带 Idempotency-Key(每次调用生成;401 刷新令牌后的自动重试会复用同一把键)。网络超时后请自行重试并显式传 { idempotencyKey } 复用,否则会生成新键。注意:网关的集团路由当前不读取该头,幂等靠下面的自然键;该头仅用于观测与重试标记。业务侧更应依赖自然幂等键:

  • W-1 建主体:license_no 相同 → 返回已有主体
  • W-2 建应用:(entity_id, slug, LIVE) 相同 → 返回已有应用,credential 为 null
  • W-5 申请分账:同账户已有 PENDING → 返回同一张申请单

错误处理

import { describeGroupError, isGatewayError } from '@qzsy/group-sdk'

try {
  await group.createEntity(input)
} catch (error) {
  if (isGatewayError(error)) {
    console.error(error.status, error.problem?.code, describeGroupError(error))
  }
  throw error
}

常见错误:GROUP_CONTEXT_REQUIRED(用了应用凭据调集团接口,403)、STORE_CODE_REQUIRED(scope=STORE 缺 store_code,400);主体/应用/账户不属于本集团统一返回 404(不泄露存在性)。

类型

import type {
  GroupEntity,
  GroupApplication,
  GroupStatement,
  GroupPayout,
  GroupEscrowApplication,
} from '@qzsy/group-sdk'

许可

MIT。问题请提给支付网关仓库。