会员接口文档

会员接口

按业务对象聚合展示会员相关接口。会员分类跟会员等级在银豹是一个意思，只是不同行业的叫法不同而已

查询会员等级

POST

/openapi/v3/customer/category/list

查询当前会员归属账号下的会员等级。连锁场景下，会员等级使用总部 userId 查询，规则与 customer.userId 一致。

Token 消耗 固定 100 token/次

请求参数

参数	类型	必填	说明
`account`	string	是	目标门店账号。用于鉴权后解析会员归属账号。
`enable`	int	否	等级状态。不传默认查询 `enable != -1`；传 `1` 只查启用，传 `0` 只查停用。

请求示例

{
  "account": "store001",
  "enable": 1
}

返回示例

{
  "status": "success",
  "errorCode": 0,
  "result": [
    {
      "uid": "10000",
      "name": "普通会员",
      "discount": "100",
      "enable": 1,
      "isPoint": 1,
      "sortValue": 1
    }
  ]
}

添加会员

POST

/openapi/v3/customer/add

新增会员基础资料，可选写入会员扩展表的性别、昵称、阴历生日。

Token 消耗 固定 100 token/次

请求参数

参数	类型	必填	说明
`account`	string	是	开卡门店。
`number`	string	是	会员编号，长度不超过 32；同一连锁下唯一。
`tel`	string	是	手机号，长度不超过 32。
`customerCategoryUid`	long	否	会员等级 UID。不传或传 `0` 时落库 `0`；传大于 0 的值时校验总部会员等级存在且未删除。
`validateTelUnique`	boolean	否	是否校验手机号唯一。`true` 时同一 `customer.userId` 下不可存在相同手机号且 `enable != -1` 的会员；默认 `false`。
`name`	string	否	会员姓名，长度不超过 128；不传默认使用 `tel`。
`point`	decimal	否	积分，默认 0，范围 -1000000.00 到 1000000.00。
`discount`	decimal	否	折扣，默认 100。
`money`	decimal	否	储值余额，默认 0。
`giftMoney`	decimal	否	赠送余额，默认 0；该金额包含在 `money` 中。
`credit`	int	否	是否允许赊账，默认 0；大于等于 1 按 1 落库，否则按 0 落库。
`enable`	int	否	会员状态，只允许 `0`/`1`，默认 1。
`birthday`	string	否	公历生日，支持 `yyyy-MM-dd` 或 `yyyy-MM-dd HH:mm:ss`。
`qq`	string	否	QQ，长度不超过 16。
`email`	string	否	邮箱，长度不超过 64。
`address`	string	否	地址，长度不超过 255。
`remarks`	string	否	备注，长度不超过 255。
`expiryDate`	string	否	过期时间，支持 `yyyy-MM-dd` 或 `yyyy-MM-dd HH:mm:ss`。
`customerExt`	object	否	会员扩展资料；首期只支持 `sex`、`nickName`、`lunarBirthday`。

customerExt 字段

字段	类型	必填	说明
`sex`	int	否	性别：`1` 男，`0` 女。
`nickName`	string	否	会员昵称，长度不超过 64。
`lunarBirthday`	string	否	阴历生日，支持 `yyyy-MM-dd` 或 `yyyy-MM-dd HH:mm:ss`，会同步写入 `lunarYear`、`lunarMonthDay`。

请求示例

{
  "account": "store001",
  "number": "VIP0001",
  "tel": "13800138000",
  "name": "张三",
  "customerCategoryUid": 0,
  "validateTelUnique": true,
  "point": 0,
  "discount": 100,
  "money": 0,
  "giftMoney": 0,
  "credit": 0,
  "enable": 1,
  "birthday": "1995-08-15",
  "qq": "123456",
  "email": "test@example.com",
  "address": "厦门市",
  "remarks": "开放平台新增",
  "expiryDate": "2030-12-31 23:59:59",
  "customerExt": {
    "sex": 1,
    "nickName": "小张",
    "lunarBirthday": "1995-07-20"
  }
}

返回示例

{
  "status": "success",
  "errorCode": 0,
  "result": {
    "id": "27051829",
    "uid": "3002001001",
    "number": "VIP0001",
    "name": "张三",
    "tel": "13800138000",
    "customerCategoryUid": "0",
    "createUserId": 10001,
    "sysUpdateTime": "2026-07-23 10:00:00"
  }
}

查询会员

POST

/openapi/v3/customer/increment-page

用于按主键游标分页查询会员基础信息，可按需返回扩展资料、分类、标签。

连锁规则：如果调用方是总部 appId，传总部 account 表示查询全部会员，传子门店 account 表示只查询该子门店创建的会员；如果调用方是子门店 appId，则只能传自己的 account，且只查询自己创建的会员。

Token 消耗 基础 100 token/次每开启一个扩展返回开关，额外 +20 token

请求参数

参数	类型	必填	说明
`account`	string	是	查询范围账号。非连锁门店传当前门店账号；连锁门店中，总部 `appId` 传总部账号查全部会员、传子门店账号查该门店创建的会员；子门店 `appId` 只能传自己的账号。
`uid`	long	否	按会员 UID 精确查询。
`number`	string	否	按会员编号精确查询。
`name`	string	否	按会员名称精确查询。
`tel`	string	否	按手机号精确查询。
`customerCategoryUid`	long	否	按会员分类 UID 精确查询。
`customerCategoryName`	string	否	按会员分类名称精确查询。
`lastId`	long	否	翻页游标。首次传 `0` 或不传；后续传上一次响应中的 `nextLastId`。
`order`	string	否	排序方向，仅支持 `asc`、`desc`，默认 `asc`。
`limit`	int	否	分页大小，默认 `100`，最大 `100`，超过按 `100` 处理。
`needCustomerExt`	boolean	否	传 `true` 时返回会员扩展资料。
`needCustomerCategory`	boolean	否	传 `true` 时返回会员分类对象。
`needCustomerTag`	boolean	否	传 `true` 时返回会员标签列表。
`needShoppingCard`	boolean	否	传 `true` 时返回会员购物卡列表。

请求示例

{
  "account": "store001",
  "uid": 3002001001,
  "number": "VIP0001",
  "name": "张三",
  "tel": "13800138000",
  "customerCategoryUid": 6001,
  "customerCategoryName": "金卡会员",
  "lastId": 0,
  "order": "asc",
  "limit": 100,
  "needCustomerExt": true,
  "needCustomerCategory": true,
  "needCustomerTag": false,
  "needShoppingCard": true
}

返回示例

{
  "status": "success",
  "errorCode": 0,
  "result": {
    "list": [
      {
        "id": "201",
        "uid": "3002001001",
        "customerCategoryUid": "6001",
        "number": "VIP0001",
        "name": "张三",
        "point": "1200",
        "discount": "85",
        "money": "88.60",
        "tel": "13800138000",
        "birthday": "1990-05-20",
        "qq": "12345678",
        "email": "vip001@example.com",
        "address": "上海市浦东新区世纪大道100号",
        "remarks": "高频到店会员",
        "createdDate": "2025-01-10 12:00:00",
        "credit": 1000,
        "enable": 1,
        "account": "vip001",
        "active": 0,
        "isLoss": 0,
        "expiryDate": "2026-12-31 23:59:59",
        "guiderUid": "8001001",
        "importDate": "2025-01-10 12:00:00.0000",
        "giftMoney": 20.00,
        "isPayMember": 1,
        "birthYear": 1990,
        "birthMonthDay": 520,
        "lunarYear": 1990,
        "lunarMonthDay": 426,
        "sysUpdateTime": "2026-04-01 10:20:00",
        "createUserAccount": "store001",
        "customerExt": {
          "sex": 1,
          "photoPath": "https://cdn.example.com/customer/3002001001/avatar.jpg",
          "nickName": "三哥",
          "totalPoint": 3200,
          "totalTicketAmount": 5680.50,
          "totalRechargeAmount": 2000.00,
          "totalTicketNum": 36,
          "creditLimit": 1000.00,
          "creditPeriod": 30,
          "creditType": 1,
          "amountInArrear": 0.00,
          "contactName": "张三",
          "vipCompany": "示例商贸有限公司"
        },
        "customerCategory": {
          "uid": "6001",
          "name": "金卡会员",
          "discount": "85",
          "enable": 1,
          "isPoint": 1,
          "sortValue": 10
        },
        "customerTags": [
          "高净值",
          "常购饮料"
        ],
        "shoppingCards": [
          {
            "uid": "7001001",
            "name": "通用购物卡",
            "balance": 100.00,
            "giftBalance": 20.00,
            "cardType": 1,
            "purchaseDateTime": "2026-01-01 10:00:00",
            "startUseDateTime": "2026-01-01 10:00:00",
            "expireDateTime": "2026-12-31 23:59:59",
            "enable": 1,
            "isWaitToActive": 0,
            "chargeAccount": "store001"
          }
        ]
      }
    ],
    "hasMore": false,
    "nextLastId": "201"
  }
}

返回字段说明

status、errorCode 及分页公共字段请参考“公共响应格式”，此处仅补充 result.list[] 及扩展对象。

字段	类型	说明
`id`	string	会员主键 ID。
`uid`	string	会员业务 UID。
`customerCategoryUid`	string	会员分类UID。
`number`	string	会员编号。
`name`	string	会员名称。
`point`	string	当前积分。
`discount`	string	分类折扣。85表示85折
`money`	string	储值余额。
`tel`	string	手机号。
`birthday`	string	生日。
`qq`	string	QQ。
`email`	string	邮箱地址。
`address`	string	联系地址。
`remarks`	string	备注信息。
`createdDate`	string	业务创建时间，按表字段原样返回。
`credit`	int	是否允许赊账 `1` 允许 `0/null` 不允许。
`enable`	int	会员状态，`1` 可用，`0` 禁用，`-1` 删除；接口仅返回 `enable != -1` 的会员。
`account`	string	会员账号。
`active`	int	会员状态，`0` 为正常，`-10` 为挂失。
`isLoss`	int	是否挂失，`0`/`null` 否，`1` 是。
`expiryDate`	string	会员到期时间。
`guiderUid`	string	导购员 UID。
`importDate`	string	导入时间。
`giftMoney`	decimal	剩余赠送金额，该金额已包含在 `money` 中。
`isPayMember`	int	是否付费会员，`0`/`null` 否，`1` 是。
`birthYear`	int	公历生日年份。
`birthMonthDay`	int	公历生日月日，例如 5 月 20 日返回 `520`。
`lunarYear`	int	农历生日年份。
`lunarMonthDay`	int	农历生日月日。
`sysUpdateTime`	string	系统更新时间。
`createUserAccount`	string	创建该会员的门店账号。
`customerExt`	object	会员扩展资料，需传 `needCustomerExt=true`。
`customerCategory`	object	会员分类对象，需传 `needCustomerCategory=true`。
`customerTags`	array<string>	会员标签列表，需传 `needCustomerTag=true`。
`shoppingCards`	array<object>	会员购物卡列表，需传 `needShoppingCard=true`。

扩展对象字段

对象	字段	类型	说明
`customerExt`	`sex`	int	性别 1-男，0-女，NULL未填写。
`customerExt`	`photoPath`	string	头像地址。
`customerExt`	`nickName`	string	昵称。
`customerExt`	`totalPoint`	decimal	累计积分。
`customerExt`	`totalTicketAmount`	decimal	累计消费金额。
`customerExt`	`totalRechargeAmount`	decimal	累计充值金额。
`customerExt`	`totalTicketNum`	int	累计消费次数。
`customerExt`	`creditLimit`	decimal	赊账额度。
`customerExt`	`creditPeriod`	int	账期天数。
`customerExt`	`creditType`	int	赊账类型。
`customerExt`	`amountInArrear`	decimal	欠款金额。
`customerExt`	`contactName`	string	联系人姓名。
`customerExt`	`vipCompany`	string	所属公司/单位。
`customerCategory`	`uid`	string	会员分类UID。
`customerCategory`	`name`	string	会员分类名称。
`customerCategory`	`discount`	string	分类折扣。85表示85折
`customerCategory`	`enable`	int	分类启用状态。
`customerCategory`	`isPoint`	int	是否参与积分。
`customerCategory`	`sortValue`	int	分类排序值。
`shoppingCards`	`uid`	string	购物卡 UID。
`shoppingCards`	`name`	string	购物卡名称。
`shoppingCards`	`balance`	decimal	购物卡余额。
`shoppingCards`	`giftBalance`	decimal	购物卡剩余赠送余额。
`shoppingCards`	`cardType`	int	卡类型，1-通用卡，2-分期返还旧卡。
`shoppingCards`	`purchaseDateTime`	string	购买时间。
`shoppingCards`	`startUseDateTime`	string	开始使用时间。
`shoppingCards`	`expireDateTime`	string	过期时间。
`shoppingCards`	`enable`	int	购物卡状态。
`shoppingCards`	`isWaitToActive`	int	是否待激活，0-已激活，1-待激活。
`shoppingCards`	`chargeAccount`	string	购物卡开卡门店账号。

会员余额积分接口

会员余额积分调整

POST

/openapi/v3/customer/balance-point/adjust

用于按增量调整会员储值余额和积分。余额扣减时先扣本金，再扣赠送金额，最后允许按会员赊账额度扣成负数；幂等继续复用请求头 X-Request-Id，同时按 dataChangeTime + timeSeq 做业务防重。

Token 消耗 固定 100 token/次

请求参数

参数	类型	必填	说明
`account`	string	是	操作门店账号。
`customerUid`	long	否	会员 UID，与 `customerNumber` 二选一。
`customerNumber`	string	否	会员编号，与 `customerUid` 二选一。
`balanceIncrement`	decimal	否	余额增量，正数增加，负数扣减。与 `pointIncrement` 至少传一个非 0 值。
`pointIncrement`	decimal	否	积分增量，正数增加，负数扣减。与 `balanceIncrement` 至少传一个非 0 值。
`validateBalance`	int	否	传 `1` 时，扣余额会校验扣减后余额不能低于负的赊账额度。
`validatePoint`	int	否	传 `1` 时，扣积分会校验积分余额不能小于 0。
`dataChangeTime`	string	是	业务变动时间，格式 `yyyy-MM-dd HH:mm:ss`。
`timeSeq`	int	否	业务时间序号，默认 `0`。同一会员同一 `dataChangeTime + timeSeq` 不允许重复提交。
`remark`	string	否	备注，最多 255 字符。

业务说明

customer.money 是会员总余额，customer.giftMoney 是总余额中剩余的赠送金额。
余额增加时默认增加本金，只更新 money，不增加 giftMoney。
余额扣减时按本金、赠送金额、赊账额度的顺序处理，giftMoney 不会扣成负数。
接口会更新 customer，并写入 customerbalnacepointchangelog、entitypropertychangelog；如有备注，还会写入 entitypropertychangelogext。

请求示例

{
  "account": "store001",
  "customerUid": 3002001001,
  "balanceIncrement": -10.00,
  "pointIncrement": -5.00,
  "validateBalance": 1,
  "validatePoint": 1,
  "dataChangeTime": "2026-06-12 16:30:00",
  "timeSeq": 0,
  "remark": "开放接口调整"
}

返回示例

{
  "status": "success",
  "errorCode": 0,
  "result": {
    "customerUid": "3002001001",
    "balanceBeforeUpdate": 100.00,
    "balanceAfterUpdate": 90.00,
    "balanceIncrement": -10.00,
    "giftMoneyBeforeUpdate": 20.00,
    "giftMoneyAfterUpdate": 18.00,
    "pointBeforeUpdate": 50.00,
    "pointAfterUpdate": 45.00,
    "pointIncrement": -5.00,
    "dataChangeTime": "2026-06-12 16:30:00",
    "timeSeq": 0,
    "updateCustomerTime": "2026-06-12 16:31:02"
  }
}

返回字段说明

字段	类型	说明
`customerUid`	string	会员 UID。
`balanceBeforeUpdate`	decimal	调整前会员总余额。
`balanceAfterUpdate`	decimal	调整后会员总余额。
`balanceIncrement`	decimal	本次余额增量。
`giftMoneyBeforeUpdate`	decimal	调整前剩余赠送金额。
`giftMoneyAfterUpdate`	decimal	调整后剩余赠送金额。
`pointBeforeUpdate`	decimal	调整前积分。
`pointAfterUpdate`	decimal	调整后积分。
`pointIncrement`	decimal	本次积分增量。
`dataChangeTime`	string	业务变动时间。
`timeSeq`	int	业务时间序号。
`updateCustomerTime`	string	实际更新时间。

会员购物卡接口

购物卡余额调整

POST

/openapi/v3/customer/shopping-card/adjust-balance

用于按购物卡 UID 调整余额。当前仅支持负数扣减，扣减时先扣本金，再扣赠送金额；幂等继续复用请求头 X-Request-Id。

Token 消耗 固定 100 token/次

请求参数

参数	类型	必填	说明
`account`	string	是	操作门店账号。
`shoppingCardUid`	long	是	购物卡 UID。
`balance`	decimal	是	调整金额，不能等于 `0`。当前仅支持小于 `0` 的扣减，例如 `-3.00` 表示扣减 3 元。

业务说明

仅允许扣减 enable=1 且 delDateTime IS NULL 的购物卡。
接口会按 customerUserId 和 shoppingCardUid 锁定购物卡并在同一事务内更新余额、写入 shoppingcardusage。
写入流水时固定 ticketId=0、operateType=1755。
useBalance 返回并写入本次扣减总金额，useGiftBalance 返回并写入其中的赠送金额部分，均为正数。

请求示例

{
  "account": "store001",
  "shoppingCardUid": 1781245872443715380,
  "balance": -3.00
}

返回示例

{
  "status": "success",
  "errorCode": 0,
  "result": {
    "shoppingCardUid": "1781245872443715380",
    "adjustAmount": -3.00,
    "useBalance": 3.00,
    "useGiftBalance": 0.00,
    "afterUsedBalance": 7.00,
    "afterUsedGiftBalance": 4.00
  }
}

返回字段说明

字段	类型	说明
`shoppingCardUid`	string	购物卡 UID。
`adjustAmount`	decimal	本次调整金额，负数表示扣减。
`useBalance`	decimal	本次扣减总金额。
`useGiftBalance`	decimal	本次扣减赠送金额。
`afterUsedBalance`	decimal	扣减后购物卡总余额。
`afterUsedGiftBalance`	decimal	扣减后购物卡赠送余额。

会员充值记录接口

查询会员充值记录

POST

/openapi/v3/customer/recharge-log/page

用于按会员 UID、会员编号和充值时间范围查询会员充值流水。

连锁规则：请求体 account 传总部账号时，返回总部及全部子门店充值记录；传子门店或独立门店账号时，只返回该门店充值记录。响应字段 account 表示该条充值实际发生的门店账号。

请求参数

参数	类型	必填	说明
`account`	string	是	查询范围账号。总部账号查总部及子门店；子门店或独立门店只查本店。
`customerUid`	long	否	按会员 UID 精确查询。
`customerNumber`	string	否	按会员编号精确查询，对应 `customer.number`。
`datetimeBegin`	string	否	充值开始时间，格式 `yyyy-MM-dd HH:mm:ss`，包含该时间。
`datetimeEnd`	string	否	充值结束时间，格式 `yyyy-MM-dd HH:mm:ss`，不包含该时间，必须大于 `datetimeBegin`。
`lastId`	long	否	翻页游标。首次传 `0` 或不传；后续传响应中的 `nextLastId`。
`order`	string	否	排序方向，支持 `desc`、`asc`，默认 `desc`。
`limit`	int	否	分页大小，默认 `100`，最大 `100`。

业务说明

传 customerUid 或 customerNumber 时，按会员精确查询计费，100 token。
未传 customerUid 和 customerNumber 时，即使传了充值时间范围，也按范围查询计费，500 token。
默认按充值时间倒序返回；同一充值时间内按 id 排序，保证游标分页稳定。
响应字段 account 是充值发生门店账号，不一定等于请求体中的查询范围账号。

请求示例

{
  "account": "head001",
  "customerUid": 3002001001,
  "customerNumber": "VIP0001",
  "datetimeBegin": "2026-04-01 00:00:00",
  "datetimeEnd": "2026-04-02 00:00:00",
  "lastId": 0,
  "order": "desc",
  "limit": 100
}

返回示例

{
  "status": "success",
  "errorCode": 0,
  "result": {
    "list": [
      {
        "id": "1102747",
        "userId": 10002,
        "account": "store002",
        "customerUid": "3002001001",
        "customerNumber": "VIP0001",
        "cashierUid": "9001001",
        "rechargeLogId": 12345,
        "rechargeMoney": 100.00,
        "giftMoney": 10.00,
        "datetime": "2026-04-01 12:30:00",
        "uid": "20260401123000001",
        "payMethod": "现金",
        "customerMoneyAfterRecharge": 188.60,
        "guiderUid": "8001001",
        "fromOrToCustomerUid": null,
        "rechargeType": 0,
        "remark": "会员充值",
        "externalOrderNo": "PAY202604010001",
        "rechargeRuleUid": "6001001",
        "rechargeRuleDesc": "充100送10",
        "payMethodCode": 1,
        "rechargeChannelCode": 1
      }
    ],
    "hasMore": false,
    "nextLastId": "1102747"
  }
}

返回字段说明

字段	类型	说明
`id`	string	充值记录主键 ID。
`userId`	int	充值发生门店 ID。
`account`	string	充值发生门店账号。
`customerUid`	string	会员 UID。
`customerNumber`	string	会员编号。
`cashierUid`	string	收银员 UID。
`rechargeLogId`	int	业务充值记录 ID。
`rechargeMoney`	decimal	充值金额。
`giftMoney`	decimal	赠送金额。
`datetime`	string	充值时间。
`uid`	string	充值业务 UID。
`payMethod`	string	支付方式名称。
`customerMoneyAfterRecharge`	decimal	会员充值后的储值余额。
`guiderUid`	string	导购 UID。
`fromOrToCustomerUid`	string	转账关联会员 UID。
`rechargeType`	int	充值方式。
`remark`	string	备注。
`externalOrderNo`	string	外部订单号。
`rechargeRuleUid`	string	充值规则 UID。
`rechargeRuleDesc`	string	充值规则描述。
`payMethodCode`	int	支付方式代码。
`rechargeChannelCode`	int	充值通道代码。

会员接口

查询会员等级

请求参数

请求示例

返回示例

添加会员

请求参数

customerExt 字段

请求示例

返回示例

查询会员

请求参数

请求示例

返回示例

返回字段说明

扩展对象字段

会员余额积分接口

会员余额积分调整

请求参数

业务说明

请求示例

返回示例

返回字段说明

会员购物卡接口

购物卡余额调整

请求参数

业务说明

请求示例

返回示例

返回字段说明

会员充值记录接口

查询会员充值记录

请求参数

业务说明

请求示例

返回示例

返回字段说明

相关页面