@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。问题请提给支付网关仓库。
